What is the Canary Exporter?

Canary Exporter is an application that allows you to subscribe to a feed of native or standardized data that we collect on your behalf. 

Prerequisites

The requirements for the Canary Exporter are simple:

  • Docker running on a system of your choice (the free Community Edition will work)
  • Amazon Web Services credentials provided by Red Canary during configuration

Configuration

The Canary Exporter settings can be accessed in your Portal via Administration > Integrations > Canary Exporter

Step 1: Choose your Preferred Data Format

You can subscribe to data in one of two formats:

  • Native: Data is formatted according to the vendor's specification. This format is ideal when using third-party applications that expect data from a specific product, such as Carbon Black Response or CrowdStrike Falcon. 
  • Standardized: Data is formatted according to Red Canary's standardized format. This format tends to be easier to read and parse, and is product-agnostic.

Note that you're not restricted to only one of these data formats. You can run multiple instances simultaneously, and each can be configured to collect unique data and/or formats.

Step 2: Generate AWS Credentials

Select the Generate Credentials button to dynamically assign your organization credentials to access your telemetry data. A few notes on these credentials:

  • Credentials are organization-wide, not specific to users: You will receive one AWS key pair for your organization, which should be documented and kept as safe as you would any other password. If you lose your key material, you will need to generate new keys.
  • Generating new credentials will destroy those previously generated: If your organization has multiple Administrators in the Red Canary Portal, please ensure only one generates key materials. Only the more recent set of keys generated will work!

Step 3: Create the AWS Credentials File

The AWS credential file is formatted as follows:

[Default]
AWS_ACCESS_KEY_ID=XXXXXXXXXXXXXXXXXXXX
AWS_SECRET_ACCESS_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The file, named credentials, can be placed anywhere on the filesystem, but a protected location and strong access controls are preferred. 

Running the Exporter

With Docker installed and your credentials created, you are ready to start consuming data!

Step 1: Review your Docker Run Statement

Based on the settings selected during configuration, a sample Docker run statement will be generated for you on the Canary Exporter configuration page. It will look something like this:

docker run -it \
      --volume $HOME/canary_exporter_staging:/tmp/canary_exporter_staging \
      --volume $HOME/.aws:/root/.aws \
      -e CUSTOMER_NAME=CustomerIdentifier \
      -e QUEUE_TYPE=standardized \
      -e SUBSCRIBE_TO_EVENTS=all \
      redcanary/canary-exporter

The following variables can be modified based on your requirements:

  • --volume $HOME/canary_exporter_staging: defines the local path where data will be downloaded, parsed, and output. Note that everything after the : on this line is required by the Exporter and should not be changed.
  • $HOME/.aws represents the directory in which the credentials file is located. The data after the :  in this line is required by the Canary Exporter and should not be changed.
  • CUSTOMER_NAME is your customer identifier, which will be provided to you as part of the configuration process. Note that this is not necessarily your Portal name.
  • QUEUE_TYPE defines whether you are subscribing to native or standardized data
  • SUBSCRIBE_TO_EVENTS defines the event types to which you are subscribing as a comma-delimited list (defaults to all). Please see the Event Types article for details.
  • docker run -it  will produce standard out to the screen and the process is tied to the logged in session. To maneuver around, you will need to kill the running Docker instance, perform activity, and restart it.
  • docker run -dit will run the container and output in the background continuously and is not tied to a session. 

Step 2: Execute and Collect!

Run your prepared Docker command and start collecting data! 

All data will be downloaded into your local path. The download subdirectory is used for temporary storage of files that need to be decompressed and/or combined. Event data matching your specifications will be written to the output subdirectory in a JSON-formatted file named canary_exporter_output.log.

Questions?

If you have questions while configuring the Canary Exporter, we've collected the frequently asked questions here

What Next?

Now that you have your raw telemetry data, it's time to leverage it! Use cases for Canary Exporter include integration with Security Information and Event Management (SIEM) systems, log aggregators, or even long-term storage.

Did this answer your question?