18.4.1. Configure the Collector Deployer Powershell Script

The Cyber Triage Collector Deployment Script is a Powershell script that can be used within EDRs and other Windows-based infrastructure to launch the Cyber Triage Collector program and collect endpoint data.

If you need a copy of the Deployer script, you can get it here.

This page talks about the general script. Other pages focus on how to integrate the script within your EDR.

18.4.1.1. Deployer Script Basics

The basic concept of the Deployer script is that it will:

  • Run on the target system

  • Will download a copy of the Cyber Triage Collector (or find an existing copy)

  • Run the Collector

  • Send the data to a specified location

The script has several options that you can override, by either:

  • Editing the script itself

  • Supplying command line arguments (which will override the script settings)

You will need to get the deployment script onto the endpoint. You can often do that with some form of script library in your EDR.

18.4.1.2. Configuration Topics

The script will “work” right away, but it may not send data to a place that you can access. This section defines what you can change and what to expected.

There are three big decisions you need to make before running the deployer script:

  1. Where the collected data will be sent

  2. What kinds of data should be collected

  3. If you will be using custom file collector rules

  4. How the Cyber Triage Collector will get on the host.

Each of these are settings in the script. To edit them, open the .PS1 file in a text editor and scroll down to the text that starts with:

######## Configuration  ##########

Below that are four sections that mirror the three topics listed above. For each section, you’ll need to either uncomment a line (by removing the “#”) or change the value in between the quotes.

You should read this section in this doc to understand what approach you want and then go to the script and follow its instructions.

Let’s review each concept in more detail.

18.4.1.2.1. Configuring Where to Send Data

Cyber Triage needs to know where to send the collected data. There are three main options:

  1. Cyber Triage Server: You can have the collector send data to a waiting Cyber Triage Team Server. You need to specify server information.

  2. Cloud (S3 or Azure): You can have the collector upload data to an S3 bucket or Azure blob. You then copy the file from there. You need to specify the cloud credentials.

  3. File: You can have the collector send the data to a file and then you can copy it off. The file can be local or on a network share. Note that many EDRs have a maximum file size that you can copy from a host. This is the default.

Each approach has its own section below to provide details about how to get the needed configuration settings.

18.4.1.2.1.1. Configuring Cyber Triage Server Information

If you are running a Cyber Triage Team server and the endpoint has access to it, you can have the Collector send data back to the server.

Refer to the instructions in Collect with EDR about how to enable the streaming mode and where to find the server name, certificate hash, and server key.

Edit the script to uncomment the config_output line that mentions servers and edit it appropriately. An example is:

$config_output = @("--serverkey", "12345678", "--server", "cybertriage.acme.com", "--cert_hash", "a1b2c3d4")

18.4.1.2.1.2. Configuring Cloud Storage Information

You can also have the endpoint upload to S3 or Azure if it has access and you have configured a bucket.

To do this, you need to first configure Cyber Triage to use cloud storage, as outlined in Cloud Storage Services.

The Collector needs a configuration file with the bucket information. You can get this configuration file by using the Extract Collector feature from within Cyber Triage. You can find those instructions in Extracting the Collector.

The above process will give you a folder with an CloudConfig.cfg file (it was called S3Config.cfg in versions before 3.10).

If you are using cloud storage, you will need to edit the Deployer script so that this line is uncommented:

$config_output = "S3"

Some S3 providers have max file sizes, so the output will be broken up into 2GB or less chunks.

You now have two options to get that configuration file onto the endpoint when it comes time to run the Deployer script:

  1. Have your EDR copy the configuration file to the endpoint by putting it into the script library. Each EDR is different about this, so refer to the appropriate section in this document about how to do this with your EDR.

  2. Or you can have the deployer script download the file from a URL that you have uploaded the configuration file to (such as an S3 bucket). To do this, edit the config_cloud_cfg_download variable and supply the path you want to use:

[string]$config_cloud_cfg_download = "\\server\share\ct\CloudConfig.cfg"

The cloud configuration URL can also be specified as a command line argument.

18.4.1.2.1.3. Saving To File

The default behavior (because it requires no other setup) is to save the results to a file. You can edit the path in the script if you want to choose a new location.

Because most EDRs will limit the size of files that you copy, the script will automatically specify that the output should be broken up.

If your collection is too big, you can either upload it to S3 or use a collection setting such as --skip_file_contents to not collect file content.

18.4.1.2.2. Specifying What Data To Collect

By default, all of the relevant Cyber Triage data is collected. You can use any of the usual Collector settings to reduce the amount of data, such as:

  • --fast to skip the full file system scan

  • --skip_file_contents to keep file contents out of the output and report only hashes

  • --dtypes to specify specific data types

For example, specify --fast --skip_file_contents to focus on data from the registry and other source files and keep exes out of the output. Note that the arguments must be in a Powershell array.

To see all of the argument options, refer to Collector Command Line Arguments.

You can specify these settings as the config_collect_args variable in the script.

18.4.1.2.3. Using Custom File Collector Sets

If you want the Collector to collect custom files, you should configure them within Cyber Triage using the steps as outlined in Customize File Collection.

Those rules will be saved in a configuration file for the Collector. You can get the configuration file by using the Extract Collector feature from within Cyber Triage after you make the rules. You can find those instructions in Extracting the Collector. That folder will then have the filesets.yaml configuration file.

Like the cloud storage settings, you then have three options for getting that file to the endpoint. Refer the that section for details and links:

  1. Have your EDR copy the configuration file.

  2. Configure the script to download the file.

  3. Specify the file as an argument.

To use custom rules, you must enable this line:

$config_use_filesets = $true

18.4.1.2.4. Getting the Collector To The Target Host

The deployer script is a Powershell wrapper to launch CyberTriageCollector.exe, which does the actual collecting. You have three options to get the Collector onto the host:

  1. Have the Powershell script download the EXE from a Cyber Triage site. This is the default behavior. This of course requires internet access.

  2. Have the Powershell script download the EXE from YOUR site or file share. You can do this two ways:

    • Edit the script and specify the URL or UNC path

    • Or, specify the path as a -collector_download argument

  3. Have your EDR or other IT infrastructure copy the exe file over to the target host. To to this:

    • Edit the script so that the download argument is an empty string (i.e. “”)

    • Have your EDR copy the EXE into the same folder that the Deployer Powershell script will be run from. Some EDRs run the script from the folder the script is copied into. Others run from a different folder. Refer to the EDR’s specific page for our experiences.

Options 2 and 3 require that you have a copy of CyberTriageCollector.exe. You get that from within Cyber Triage (see Extracting the Collector).

18.4.1.3. Running and Checking Status

Once configured, you simply need to run the script and optionally provide command line arguments.

Many EDRs will kill long running processes and therefore the deployer script will launch the Collector as a background process. Then, even if the EDR kills the deployer script, then the Collector will keep on running.

You can check if the Collector is still running, by running the deployer script again with the --status argument. That will look for an existing Collector process or show you the final status.

18.4.1.4. Recommendations

Here is our advice for getting this script working:

  • You should first start with the default settings and prove that the output is written to the JSON file in the temp folder. If this happens, this proves that the script can run, access the Collector, and it can run. Then move on to testing sending the data to S3 or the server.

  • If you make any changes to the script, you can locally run it to make sure you have no syntax errors. You can open a command prompt, navigate to the file, and run something like:

powershell -File deploy_cyber_triage_collector.ps1

  • You can also use the local launch method to test sending data to S3 or a server. Ensure the cloud configuration file is in the same folder as the deployer script.

  • As you are testing how to send data to different places, you can minimize the mount of data that the Collector saves. The options in the script for config_collect_args to specify fast and skip file contents will certainly help. But, you can also use something like @("--dtypes", "nc"), which will just collect network caches.

18.4.1.5. Troubleshooting

Error messages will be written to a file named ct_err.txt in the directory where the program was run from. Though, finding this file can be challenging because it requires you to know where your EDR will launch programs from.

Key things to remember:

  • The EXE needs to create some temporary files and output files. Make sure the Collector has permissions run from where it runs from. Do not run things from c:\\windows\\system32 (that is where some EDRs copy the program to).

  • Using network shares is often tricky because the EDR service may not have permissions on them.