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.
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
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:
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 \
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/.awsrepresents the directory in which the
credentialsfile is located. The data after the
:in this line is required by the Canary Exporter and should not be changed.
CUSTOMER_NAMEis 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_TYPEdefines whether you are subscribing to native or standardized data
SUBSCRIBE_TO_EVENTSdefines 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 -itwill 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 -ditwill 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
If you have questions while configuring the Canary Exporter, we've collected the frequently asked questions here.
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.