19.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.

19.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.

19.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 five big decisions you need to make before running the deployer script:

Where the collected data will be sent
If the script needs to download a Collector configuration file
What kinds of data should be collected
If you will be using custom file collector rules
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.

19.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:

Cyber Triage Server: You can have the collector send data to a waiting Cyber Triage Team Server. You need to specify server information.
Cloud (S3 or Azure): You can have the collector upload data to an S3 bucket or Azure blob. You then download the file from there. You need to specify the cloud credentials.
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.

19.4.1.2.1.1. Sending to a Cyber Triage Server¶

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")

19.4.1.2.1.2. Sending to Cloud Storage¶

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.

There are two ways to get the account information to the Collector:

You can specify the information as command line arguments
You can copy a configuration file onto the target host and the Collector will read it

Our advice is:

If have created the cloud credentials such that you have an account that can only write (and cannot read), then you should store those credentials in the Deployer script and have them passed in as an argument.
If you want to more frequently update credentials, then having them in a separate configuration file could be easier so that you do not update the script each time.

If you are going to pass in the credentials as an argument, then go to the line in the Deployer script and uncomment the ‘config_output’ line that refers to S3 regions and update appropriately. It should end up looking like this:

#   1c) Upload to S3 based on arguments. Update based on your bucket info.
$config_output = @("--s3_Region", "us-east-2", "--s3_Bucket", "xyz", "--s3_AccessKeyID", "IWLAS383819AWAQ", "--s3_AccessKey", "s8li209sjha33au34y3u4ysuyds7")

If you want to use a configuration file, then:

Get the configuration file by extracting the Collector. You can find those instructions in Extracting the Collector. This will produce a folder with a ‘CollectorConfig.cfg’ file.
Decide how that configuration file will get onto the host. You have two options:
- Have the script download it from a URLs (an S3 bucket for example) specified in the script
- Have the script download it from a URL you specify on the deployer command line
- You will push it to the host each time you do a collection.
Edit the Deployer script so that config_output is an empty string. It should look something like this:

#   1d) Upload to cloud based on the CollectorConfig.yaml file. You need to either configure that file to be
$config_output = ""

If you want the script to download the file using a URL in the script, then take care of that in Step 2. Otherwise, refer to your specific EDR section in this doc about how to push the configuration file into its library (if it supports that).

NOTE: Data uploaded to S3 will be broken up into 2GB or less chunks.

19.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.

19.4.1.2.2. Downloading a Configuration File¶

The Collector can use a configuration file that, when present, will overrule settings supplied by the command line. You can use the configuration file for:

Cloud storage information
Public encryption keys

By default, the Collector does not need or use the configuration file. You can always push the configuration file via your EDR.

If you want the script to download the file from one of your URLs, then uncomment the line in the script like the one below and edit with your URL:

# Step 2
# Uncomment below if you need to download a configuration file from your server.
# [string]$ct_cfg_download = "\\server\share\ct\CollectorConfig.yaml"

19.4.1.2.3. 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.

19.4.1.2.4. 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:

Have your EDR copy the configuration file.
Configure the script to download the file.
Specify the file as an argument.

To use custom rules, you must enable this line:

$config_use_filesets = $true

19.4.1.2.5. 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:

Have the Powershell script download the EXE from a Cyber Triage site. This is the default behavior. This of course requires internet access.
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
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).

19.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.

19.4.1.4. Recommendations¶

Here is our advice for getting this script working:

You should start by manually launching this script (with no setting changes) on a computer and not involve the EDR. To do that:
- Open an admin command prompt.
- Type in ‘powershell -File deploy_cyber_triage_collector.ps1’ and it should download the collector and run.
- Verify you see results in c:\windows\temp\file.json.gz
Start to make changes and test them locally as you go. This is useful for testing S3 and server output settings. Ensure the Collector configuration file is in the same folder as the deployer script.
- To save time between tests, 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.
Then you can involve the EDR after you are sure the script works on your local machine as expected.

19.4.1.5. Troubleshooting¶

Look at the c:\windows\temp\file.log file on the target system for any error messages.

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.