Dettectinator as a CLI tool

You can use the command line tool to generate one of the following DeTT&CT YAML files:

A techniques administration YAML file based on detections including their ATT&CK mapping from your SIEM / EDR. We have multiple plugins available that get this information from an API, file or other source. We call that data import plugins. These plugins adds detections in the location field of a detection object for a specific ATT&CK technique (taking the applicable_to value into account). A default detection score of "1" is used for new techniques. When a technique was already present in a given YAML file, the score will be preserved, and a score logbook entry will be added with a "TODO" to let you know to review the score.

A data source administration YAML file based on data sources that are mapped to ATT&CK. We have multople plugins available that can import or map data sources. These plugins adds data sources and uses a default score of "1" for the data quality dimensions.

A groups administration YAML file based on attack groups that are mapped to ATT&CK. In general you have to create your own tailored plugin to ingest your CTI reports. Two example plugins have been supplied for reading from Excel and PDF files to get you started.

To run the CLI tool you need to install the required libraries first:

pip install -r requirements.txt

The command line tool requires a data import plugin parameter to be specified. To get a list of available plugins run dettectinator.py without any argument:

python dettectinator.py
Please specify a valid data import plugin using the "-p" argument:
 - GroupExcel
 - GroupPdf
 - DatasourceCsv
 - DatasourceDefenderEndpoints
 - DatasourceExcel
 - DatasourceWindowsSecurityAuditing
 - DatasourceWindowsSysmon
 - TechniqueCsv
 - TechniqueDefenderAlerts
 - TechniqueDefenderIdentityRules
 - TechniqueElasticSecurityRules
 - TechniqueExcel
 - TechniqueSentinelAlertRules
 - TechniqueSigmaRules
 - TechniqueSplunkConfigSearches
 - TechniqueSuricataRules
 - TechniqueSuricataRulesSummarized
 - TechniqueTaniumSignals

Select a data import plugin and specify it using the -p argument. To see a list of all parameters add the -h argument, for example:

python dettectinator.py -p TechniqueTaniumSignals -h
Plugin "TechniqueTaniumSignals" has been found.
usage: dettectinator.py [-h] [-c CONFIG] -p PLUGIN [-a APPLICABLE_TO] [-d {enterprise,ics,mobile}] [-i INPUT_FILE] [-o OUTPUT_FILE] [-n NAME] [-s STIX_LOCATION] [-lf LOG_FILE] [-lp] [-ch] [-cl] [-ri RE_INCLUDE] [-re RE_EXCLUDE]
                        [-l LOCATION_PREFIX] [-clp] --host HOST --user USER --password PASSWORD [--search_prefix SEARCH_PREFIX]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Configuration file location.
  -a APPLICABLE_TO, --applicable_to APPLICABLE_TO
                        Systems that the detections are applicable to (comma seperated list).
  -d {enterprise,ics,mobile}, --domain {enterprise,ics,mobile}
                        The ATT&CK domain (default = enterprise). This argument is ignored if a domain is specified in the YAML file.
  -i INPUT_FILE, --input_file INPUT_FILE
                        YAML filename for input.
  -o OUTPUT_FILE, --output_file OUTPUT_FILE
                        YAML filename for output.
  -n NAME, --name NAME  Value for the name attribute in the YAML file.
  -s STIX_LOCATION, --stix_location STIX_LOCATION
                        Local STIX repository location.
  -lf LOG_FILE, --log_file LOG_FILE
                        Log to write results and warnings to.
  -lp, --log_parameters
                        Add the configuration parameters to the log.
  -ch, --check_unused   Check unused detections.
  -cl, --clean_unused   Clean unused detections.

required arguments:
  -p PLUGIN, --plugin PLUGIN
                        Data import plugin name.

TechniqueTaniumSignals:
  -ri RE_INCLUDE, --re_include RE_INCLUDE
                        Regex for detection names that should be included.
  -re RE_EXCLUDE, --re_exclude RE_EXCLUDE
                        Regex for detection names that should be excluded.
  -l LOCATION_PREFIX, --location_prefix LOCATION_PREFIX
                        Location of the detection, will be prepended to the detection name.
  -clp, --clean_unused_location_prefix
                        Clean unused detections based on location_prefix.
  --host HOST           Tanium host
  --user USER           Tanium API username
  --password PASSWORD   Tanium API password
  --search_prefix SEARCH_PREFIX
                        Search prefix

The command line tool has default arguments and arguments that are data import plugin specific. The default arguments are described below, the arguments for the plugins are described here (TODO).

Configuration file location: -c, --config

You can optionally supply the location of a configuration file. All Dettectinator and data import plugin arguments can also be supplied in this configuration file. The config file is in JSON format, all arguments need to be defined in their 'long' format, for example:

{
  "plugin":  "ImportCsv",
  "applicable_to": "Windows servers, Windows desktops",
  "check_unused": 1,
  "file": "../examples/import.csv"
}

Any argument supplied on the command line will overrule the value supplied in the config file.

Data import plugin name (required): -p, --plugin

Dettectinator can import data from several sources by supplying a plugin name. To get a list of all available plugins, run dettectinator.py without any arguments.

Systems that the detections or data sources are applicable to: -a, --applicable_to

You can specify a comma separated list of types of systems that the imported detections are applicable to. For instance "Windows servers, Linux servers, Windows desktops" etc.

The ATT&CK domain: -d {enterprise,ics,mobile}, --domain {enterprise,ics,mobile}

You can optionally specify the ATT&CK domain: enterprise, ics or mobile. By default it will use enterprise. This argument is ignored if a domain is specified in the input YAML file.

YAML filename for input: -i, --input_file

You can optionally specify an input YAML file that will be updated with the imported data. If no file name is specified an empty file will be used.

YAML filename for output: -o, --output_file

You can optionally specify an output YAML file. If no file name is specified the results will be written to the input file. If an input file name also hasn't been specified a default name will be generated for the output file.

Name attribute in YAML: -n, --name

You can specify a value for the name attribute in the YAML file. If no value is specified, the existing value will be preserverd and for new files the value "new" will be used.

Local STIX repository location: -s, --stix_location

You can optionally specify a location for a local STIX repository containing the MITRE ATT&CK STIX objects. Dettectinator uses this repository to generate the YAML files. This repository can be cloned from here: https://github.com/mitre-attack/attack-stix-data. Set the argument to the location of the cloned repository to use it. If no location is specified, an attempt will be made to download the information via MITRE's TAXII server.

Location of log file: -lf, --log_file

You can optionally supply a location for a log file to write the results and warnings to. If omitted no log file will be used. If the file already exists the new results will be appended to it.

Log paramters: -lp, --log_parameters

Add the option if you want the configurations parameters of the plugin added to the log file.

Check/Clean unused detections: -ch, --check_unused, -cl, --clean_unused

When updating an existing YAML file you can choose to annotate or remove detections that are not present in the newly imported set of detections. The -ch/--check_unused option will only report the unused detections. The -cl/--clean_unused option will also remove the detections from the YAML file. Please note that when using -cl/--clean_unused you also need to include -ch/--check_unused.