CoPAS Guide

In the following section, you will find everything you need to know about working with CoPAS.

Registry (Marketplace) Management

CoPAS Marketplaces are registries that contain a list of CoPAS modules that are available for download. You can add multiple registries through CoPAS CLI. For more information, visit CoPAS Marketplaces.

Adding Registries

To add a registry, you can use copas registry add. When prompted for which type of registry to add, select the registry type and press enter. For example, if you want to add the forensics registry, select harbor:

When prompted for the URL of the registry, enter the URL of the registry and press enter:

Finally, when prompted for the Harbor project, enter the project name and press enter:

Listing Added Registries

To list all added registries, use copas registry list:

This will list all added registries and their status. If the status is available, you can use the registry to download CoPAS modules.

Removing Registries

To remove a registry, use copas registry remove:

This will automatically remove the only available registry or prompt you to select a registry to remove if there are multiple registries. You can also be explicit and use copas registry remove <registry-url>/<registry-project> to remove a specific registry. For example, to remove the forensics registry, use copas registry remove https://copas-market.cerit-sc.cz/forensics:

Module Management

Listing Available Modules

Once you have successfully added at least one registry and its status is available, you can list all available CoPAS modules in added registries by using copas module avail:

You can now see the list of all available modules in all added registries. To get more information about a specific module, you can use copas module info <module-name>. For example, to get more information about the csv-elk` module, use copas module info csv-elk:

Adding Modules

Once you have decided which module you want to use, you can download it by using copas module add <module-name>. For example, to download the csv-elk module from forensics registry, use copas module add csv-elk:

CoPAS will automatically download the latest version of the module. If you want to download a specific version, use copas module add <module-name>:<version>:

You can also load a module from a tar image file by using copas module load <path-to-image-file>:

Listing Downloaded Modules

You can list all downloaded modules by using copas module list:

You can see that the csv-elk module is listed as the only added module and its version is 2.2.

Upgrading Modules

CoPAS modules are constantly being updated. To upgrade all modules to their latest version,
use copas module upgrade:

Removing Modules

To remove a specific module, you can use copas module remove <module-name>. For example, to remove the csv-elk module:

This will remove all versions of the module. If you want to remove a specific version of the module, use copas module remove <module-name>:<version>:

You can also remove all added modules by using copas module purge:

Container Management

To use CoPAS modules, you need to first create containers from them. Containers are isolated environments that contain all the necessary tools and services to run the module.

Creating Containers

If you want to create a container from a module, use copas create. You will be prompted to select a module to use and to enter a name for the container. For example, to create a container named csv from the csv-elk module:

Or you can be explicit and use copas create <container-name> -m <module-name>:

A container named csv was created from the csv-elk module. You can also load a container from an image file by using copas load <path-to-container-file>:

Additionally, you can specify the data file to be loaded into the container by using copas load <path-to-container-file> <path-to-data-file>:

Listing Containers

You can list all containers and their state by using copas list:

You can see one container named csv that was created from the csv-elk module. The container should be stopped.

Starting Containers

To start the container, use copas start:

This will automatically start the only stopped container or prompt you to select a container to start if there are multiple stopped containers. You can also be explicit and use copas start <container-name>. For example, to start the csv container:

After the container is started, you are provided with the URL of the container. You can use this URL to access the CoPAS UI and start with the analysis.

Monitoring Containers

If you have running containers, you can get information about them by using copas monitor:

Additionally, you can also access a running container by using copas enter:

This will automatically enter the only running container or prompt you to select a container to enter if there are multiple running containers. You can also be explicit and use copas enter <container-name>. For example, to enter the csv container:

Stopping Containers

Once you are done with the analysis, you can stop the container by using copas stop:

This will automatically stop the only running container or prompt you to select a container to stop if there are multiple running containers. You can also be explicit and use copas stop <container-name>`. For example, to stop the csv container:

Backing Up Containers

If you have stopped containers, you can back them up into a tar archive by using copas backup. You will be prompted to enter a backup name for the container or you can use the default:

This will automatically back up the only available stopped container or prompt you to select a container to back up if there are multiple stopped containers. You can also be explicit and use copas backup <container-name>. For example, to back up the csv container:

Removing Containers

If you want to remove a container, use copas destroy:

This will automatically try to remove the only stopped container or prompt you to select a container to remove if there are multiple stopped containers. You can also be explicit and use copas destroy <container-name>. For example, to remove the csv container:

You can also remove all stopped containers by using copas purge:

Working with CoPAS UI

CoPAS UI is configurable and each module can have a different UI. However, some parts of the UI are shared across all modules. This section will give you all the information you need about the shared parts of the UI and how to work with them. For more information about the specific modules, you can check out their documentation in the UI.

Home Page

The home page of CoPAS UI serves as the central hub, from where all the functionality is accessible. It is divided into multiple sections and can look a little bit different depending on the module. There are 5 main sections:

1. Module Title and Description Section: 
   
   • Configurable by the module author.

2. Navigation/Menu Section:

   • Three prominent links for essential analysis processes:
     • File manager for file uploads.
     • Data import to the Analysis API.
     • Analysis UI.
   • Three less prominent links for:
     • Analytical configuration management.
     • Watchdog management.
     • History of all imports.

3. Promotion Sections (Left and Right):

   • Configurable sections for promoting the module's author.
   • Logos, website links, and email contacts can be provided.

4. Information Section:

   • Link for additional information about module authors and CoPAS authors on hover.
   • Link to the Help page for learning more about the module.
5. Status Bar

Status Bar

The status bar is located at the bottom of the page and is visible on every page of the CoPAS UI. It consists of 4 parts:

1. Service Information:

• Located on the left side of the status bar.
• Indicates the availability of services (green for up, red for down).
• Hovering provides additional service details.

2. Analysis API Actions:

• Positioned to the right of service statuses.
• Defined by the module.
• A popup with available actions for the Analysis API. These serve to update the state of the container - e.g., delete the data of a service, restart the service, or similar.

3. Profile Selection:

• Next to API Actions.
• There is always one active profile, which can be updated using the selection list.
• Profile usually serves for setting the resource consumption by the module, but can be used for other purposes.

4. Additional Details:

• Displayed on the far right.
• Includes the name of the container, the module's name, and its version.

Information about service statuses, available actions, and active profiles is only shown if configured by the module author.

File Manager

The file manager can be accessed by clicking on the Files icon in the navigation section. It allows you to manage files inside the container. Currently, there is support for:

• uploading files - either upload button or drag and drop
• creating new directories using the new directory button
• deleting files - either the delete button or Del key on the keyboard
• copy/cut files functionality using Ctrl + C/X , Ctrl + V
• searching and filtering files using the search bar

There are two view modes for the contents of directories - list and grid mode. By default hidden files (beginning with a dot) remain hidden, but they can be shown using a radio button option.

Shared Folder

CoPAS containers have a shared folder named shared-data located in the /opt/copas/ directory on Linux machines. On Windows, the folder is located in the \\wsl.localhost\Copas\opt\copas directory. This folder is shared between the host and the container. This means that you can upload files into the container by simply copying them into the shared-data folder on the host. They will be automatically available in the container in the copas-data-shared folder.

Uploading Data Into the Container

CoPAS offers two ways of uploading data into the container. You can either take advantage of the File Manager or use the Shared Folder.

When uploading large amounts of data, we recommend using the Shared Folder approach.

Importing Data for Analysis

Once you have uploaded data into the container, you can start the import process. To start the import process, click on the Import icon in the navigation section. On the import page, you will encounter four sequential steps.

Step 1: Select Files for Analysis

Firstly, select files, directories, or contents of archives you want to analyze by clicking on the arrow button in the middle of the screen. Directories can be selected for watching which is explained further in the Watching Directories for New Files section. Once you have selected all the desired files, click the Confirm button in the bottom right to continue.

Step 2: Choose Analysis Configuration

Configuration for analysis can be either chosen directly, a new one can be created from scratch, or an existing configuration can be duplicated and modified.

Step 3: Modify or Create Configuration (Optional)

In the third step, modify an existing analytical configuration or create a new one. Additionally, if configured, utilize the support for generating an analytical configuration based on the selected files to streamline the process. Details about a particular set of options for the module are specified in the respective help section.

Step 4: View the Summary and Confirm the Import

A summary of selected files, configuration, and watched directories is displayed. If a new configuration is created or an existing modified, an option to save the configuration is shown, which will happen if the import is successful.

After confirming in the UI, all the files along with the analytical configuration will be sent to the Analysis API for processing. You can check if the import was successful on the History page. Once the import is finished, you can start the analysis by clicking on the Analysis button in the navigation section. This will open the Analysis page, which is different for each module.

Watching Directories for New Files

Directories can be selected for watching along with an assigned configuration. A watchdog checks on this directory and its subtree and when a new file appears in the subtree given by the directory, it is automatically imported.

Watchdogs can be either created during import when selecting a directory or separately in its dedicated UI, where all the watched directories can be viewed. To access the dedicated UI, click on the Watchdog icon in the navigation section.

Viewing Import History

To view import history, click on the History icon in the navigation section. The table displays information such as the time of completion, duration of the import process, status (success, failure, importing), origin (manual, watchdog), imported files along with their import status, and the analytical configuration used.

Many of the columns can be filtered or sorted. There is also a search input, which allows filtering through all the imported files.

When the import is in progress, history shows the importing status and the current duration since the start.

Help Page

A page with information about the module. The page is split into several sections describing different aspects of the module. The sections are fully customizable by the module’s author. Ideally, the help page should have at least the following sections:

• General: Describing the general usage of the module (which file types are supported, the installed software).
• Configurations: Describing the available analytical configurations.
• Analysis UI: Describing the UI for analyzing results.
• CopAS UI: Describing CopAS UI. This is similar across all modules (except the configured parts).