6. Reference Documents

6.3. PEAT Elasticsearch indices reference

Index name

Description

Index name configuration option

vedar-logs

PEAT logging events.

ELASTIC_LOG_INDEX

peat-scan-summaries

Scan result summaries.

ELASTIC_SCAN_INDEX

peat-pull-summaries

Pull result summaries.

ELASTIC_PULL_INDEX

peat-parse-summaries

Parse result summaries.

ELASTIC_PARSE_INDEX

peat-configs

PEAT configurations.

ELASTIC_CONFIG_INDEX

peat-state

Dumps of PEAT’s internal state during a run.

ELASTIC_STATE_INDEX

ot-device-hosts-timeseries

Information collected by PEAT from field devices or parsed files. A new Elasticsearch document is created for every pull of data from a device (the data is ‘timeseries’, with differences visible between pulls over time).

ELASTIC_HOSTS_INDEX

ot-device-files

Information about files present on the device, or that were present on the device at one point in time.

ELASTIC_FILES_INDEX

ot-device-registers

Information about individual communication ‘registers’ (e.g. Modbus registers/coils, DNP3 data points, BACNet objects, etc.) that are configured on devices, as extracted from device configuration information.

ELASTIC_REGISTERS_INDEX

ot-device-tags

Information about tag variables that are configured on devices, as extracted from device configuration information.

ELASTIC_TAGS_INDEX

ot-device-io

Information about I/O (Input/Output) available and/or configured on a device, as extracted from device configuration information.

ELASTIC_IO_INDEX

ot-device-events

Logging and other event history as extracted from devices. Examples include access logs, system logs, or protection history.

ELASTIC_EVENTS_INDEX

ot-device-memory

Memory reads from devices, including address in memory, the value read, and information about where it came from and when the read occurred.

ELASTIC_MEMORY_INDEX

6.4. Command Line Interface (CLI) usage reference

PEAT: Process Extraction and Analysis Tool

peat [-h] [--version] {parse,pull,scan,push,pillage,heat,config-builder,encrypt,decrypt} ...

6. peat options

  • -h, --help - show this help message and exit

  • --version - show program’s version number and exit

6. peat parse

Parse and extract data from project files, device configs, and PEAT pulls

peat parse [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
           [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
           [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs] [-d TYPES]
           [--list-all] [--list-modules] [--list-aliases] [--list-alias-mappings]
           [--examples] [--all-examples]
           [input_source ...]

6. peat parse positional arguments

  • input_source - Paths of files and/or directories to parse. If nothing or a "-" is specified, then stdin (piped input) is used. (default: ['-'])

6. peat parse options

  • -h, --help - show this help message and exit

  • -d TYPES, --device TYPES, --device-types TYPES, --peat-modules TYPES - The type of the device(s) to parse using from. These can be the name of a PEAT module, device vendor, device type (e.g. "plc"), or other aliases. This can be a single string or a space-separated list of strings. Input from stdin (pipe/redirect) must be a single device type. (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat parse general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat parse development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat parse elasticsearch arguments

6. peat pull

Pull and extract firmware, configs, logic, and/or logs from devices

peat pull [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
          [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
          [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs]
          [-d TYPE [TYPE ...]] [-T DEFAULT_TIMEOUT] [--baudrates BAUDRATES [BAUDRATES ...]]
          [-Y] [--intensive-scan]
          (-i HOSTS [HOSTS ...] | -s PORTS [PORTS ...] | -f FILE | -b TARGETS [TARGETS ...] | --list-all | --list-modules | --list-aliases | --list-alias-mappings | --examples | --all-examples)

6. peat pull options

  • -h, --help - show this help message and exit

  • -d TYPE, --device TYPE, --device-types TYPE, --peat-modules TYPE - The type of the device(s) to pull from. This can be the name of a PEAT module, device vendor, device type (e.g. "plc"), or other aliases. This can be a single string or a space-separated list of strings. (default: ['all'])

  • -T DEFAULT_TIMEOUT, --timeout DEFAULT_TIMEOUT - Number of seconds to wait for responses. WARNING: if using a YAML config file, setting this argument will override ANY AND ALL timeouts configured in that file, including protocol-specific timeouts! (default: None)

  • --baudrates BAUDRATES - Serial baud rate(s) to try. Use a single number to specify a single rate, or dash-separated numbers to specify a range of rates. (default: ['9600-115200'])

  • -Y, --assume-online - Assume all hosts are online. Skips the host online status checks (TCP SYN, ICMP, or ARP requests).

  • --intensive-scan - Force identification checks of all ports during scanning. Normally PEAT will only perform identification on ports that are open. This option overrides that behavior and forces every potential service be checked. The services and ports checked vary based on the imported modules and other information sources, such as imported scan results.

  • -i HOSTS, --ip HOSTS, --hosts HOSTS - Network hosts to target or filenames with hosts to target. IPv4 addresses and hostnames can be used, as well as CIDR "/" notation to specify subnet ranges. Nmap-style host and network ranges are accepted, e.g. "192.0.2.20-40" or "192.168.0-4.0". If a file or set of files is specified, they will be read and the hosts will be added to the list Host strings in files can be space, tab, or newline-separated. Basically, PEAT will call .split() on whatever is in the file. (default: None)

  • -s PORTS, --serial-ports PORTS - Serial port(s) to target. Use a single number to specify a single port (0), or numbers separated by a - to specify a range of ports (e.g. 0-4). Alternatively, platform-specific port names can be used (e.g. /dev/ttyUSB0). (default: None)

  • -f FILE, --host-file FILE - JSON PEAT scan result file with hosts to scan/pull. This will override the --hosts argument. (default: None)

  • -b TARGETS, --broadcast-targets TARGETS - Network broadcast targets to use for scanning. Targets can be IP subnet broadcast addresses ("192.0.2.255"), MAC broadcast addresses ("ff:ff:ff:ff:ff:ff") or local system network interfaces ("eth0"). (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat pull general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat pull development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat pull elasticsearch arguments

6. peat scan

Scan the network for devices

peat scan [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
          [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
          [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs]
          [-d TYPES [TYPES ...]] [--sweep] [-T DEFAULT_TIMEOUT]
          [--baudrates BAUDRATES [BAUDRATES ...]] [-Y] [--intensive-scan]
          (-i HOSTS [HOSTS ...] | -s PORTS [PORTS ...] | -f FILE | -b TARGETS [TARGETS ...] | --list-all | --list-modules | --list-aliases | --list-alias-mappings | --examples | --all-examples)

6. peat scan options

  • -h, --help - show this help message and exit

  • -d TYPES, --device TYPES, --device-types TYPES, --peat-modules TYPES - Limit scan to a specific device type. This can be the name of a PEAT module, device vendor, device type (e.g. "plc"), or other aliases. This can be a single string or a space-separated list of strings. (default: ['all'])

  • --sweep, --enumerate - Check what hosts are online using the standard methods (TCP SYN, ARP, or ICMP) and exit. If serial ports are targeted, this will enumerate the active serial ports on the host.

  • -T DEFAULT_TIMEOUT, --timeout DEFAULT_TIMEOUT - Number of seconds to wait for responses. WARNING: if using a YAML config file, setting this argument will override ANY AND ALL timeouts configured in that file, including protocol-specific timeouts! (default: None)

  • --baudrates BAUDRATES - Serial baud rate(s) to try. Use a single number to specify a single rate, or dash-separated numbers to specify a range of rates. (default: ['9600-115200'])

  • -Y, --assume-online - Assume all hosts are online. Skips the host online status checks (TCP SYN, ICMP, or ARP requests).

  • --intensive-scan - Force identification checks of all ports during scanning. Normally PEAT will only perform identification on ports that are open. This option overrides that behavior and forces every potential service be checked. The services and ports checked vary based on the imported modules and other information sources, such as imported scan results.

  • -i HOSTS, --ip HOSTS, --hosts HOSTS - Network hosts to target or filenames with hosts to target. IPv4 addresses and hostnames can be used, as well as CIDR "/" notation to specify subnet ranges. Nmap-style host and network ranges are accepted, e.g. "192.0.2.20-40" or "192.168.0-4.0". If a file or set of files is specified, they will be read and the hosts will be added to the list Host strings in files can be space, tab, or newline-separated. Basically, PEAT will call .split() on whatever is in the file. (default: None)

  • -s PORTS, --serial-ports PORTS - Serial port(s) to target. Use a single number to specify a single port (0), or numbers separated by a - to specify a range of ports (e.g. 0-4). Alternatively, platform-specific port names can be used (e.g. /dev/ttyUSB0). (default: None)

  • -f FILE, --host-file FILE - JSON PEAT scan result file with hosts to scan/pull. This will override the --hosts argument. (default: None)

  • -b TARGETS, --broadcast-targets TARGETS - Network broadcast targets to use for scanning. Targets can be IP subnet broadcast addresses ("192.0.2.255"), MAC broadcast addresses ("ff:ff:ff:ff:ff:ff") or local system network interfaces ("eth0"). (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat scan general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat scan development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat scan elasticsearch arguments

6. peat push

Push firmware, configuration, or logic to a device

peat push [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
          [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
          [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs]
          [-T DEFAULT_TIMEOUT] [--baudrates BAUDRATES [BAUDRATES ...]] [-Y]
          [--intensive-scan]
          (-i HOSTS [HOSTS ...] | -s PORTS [PORTS ...] | -f FILE | -b TARGETS [TARGETS ...] | --list-all | --list-modules | --list-aliases | --list-alias-mappings | --examples | --all-examples)
          [-d DEVICE [DEVICE ...]] [-t PUSH-TYPE] [--push-skip-scan]
          [input_source]

6. peat push positional arguments

  • input_source - Path to file or a directory containing files to push to the device. If nothing or a "-" is specified, then stdin (piped input) is used. (default: -)

6. peat push options

  • -h, --help - show this help message and exit

  • -T DEFAULT_TIMEOUT, --timeout DEFAULT_TIMEOUT - Number of seconds to wait for responses. WARNING: if using a YAML config file, setting this argument will override ANY AND ALL timeouts configured in that file, including protocol-specific timeouts! (default: None)

  • --baudrates BAUDRATES - Serial baud rate(s) to try. Use a single number to specify a single rate, or dash-separated numbers to specify a range of rates. (default: ['9600-115200'])

  • -Y, --assume-online - Assume all hosts are online. Skips the host online status checks (TCP SYN, ICMP, or ARP requests).

  • --intensive-scan - Force identification checks of all ports during scanning. Normally PEAT will only perform identification on ports that are open. This option overrides that behavior and forces every potential service be checked. The services and ports checked vary based on the imported modules and other information sources, such as imported scan results.

  • -i HOSTS, --ip HOSTS, --hosts HOSTS - Network hosts to target or filenames with hosts to target. IPv4 addresses and hostnames can be used, as well as CIDR "/" notation to specify subnet ranges. Nmap-style host and network ranges are accepted, e.g. "192.0.2.20-40" or "192.168.0-4.0". If a file or set of files is specified, they will be read and the hosts will be added to the list Host strings in files can be space, tab, or newline-separated. Basically, PEAT will call .split() on whatever is in the file. (default: None)

  • -s PORTS, --serial-ports PORTS - Serial port(s) to target. Use a single number to specify a single port (0), or numbers separated by a - to specify a range of ports (e.g. 0-4). Alternatively, platform-specific port names can be used (e.g. /dev/ttyUSB0). (default: None)

  • -f FILE, --host-file FILE - JSON PEAT scan result file with hosts to scan/pull. This will override the --hosts argument. (default: None)

  • -b TARGETS, --broadcast-targets TARGETS - Network broadcast targets to use for scanning. Targets can be IP subnet broadcast addresses ("192.0.2.255"), MAC broadcast addresses ("ff:ff:ff:ff:ff:ff") or local system network interfaces ("eth0"). (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

  • -d DEVICE, --device DEVICE, --device-types DEVICE, --peat-modules DEVICE - The type of device to push to (default: None)

  • -t PUSH-TYPE, --push-type PUSH-TYPE - What type of information to push, either 'config' or 'firmware' (default: config)

  • --push-skip-scan - Skip scanning and verification of hosts being pushed to, and assume all hosts are online and valid devices. NOTE: this requires a single device type to be specified.

6. peat push general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat push development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat push elasticsearch arguments

6. peat pillage

Find and parse firmware, configuration, and logic from a disk image

peat pillage [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
             [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
             [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs]
             [-P SOURCE] [--list-all] [--list-modules] [--list-aliases]
             [--list-alias-mappings] [--examples] [--all-examples]

6. peat pillage options

  • -h, --help - show this help message and exit

  • -P SOURCE, --pillage-source SOURCE - Source to pillage either a raw image file or directory location. Defaults to local directory if nothing specified. If the source is a "split" VMware VMDK disk (e.g. multiple VMDK files that make up a single disk), use the file without the "-sXXX" in the name as the source. (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat pillage general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat pillage development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat pillage elasticsearch arguments

6. peat heat

HEAT (High-fidelity Extraction of Artifacts from Traffic). This feature finds file artifacts in network traffic parsed using Vedizar’s elastic-utils and stored in Elasticsearch. Examples of file artifacts include device firmware images, configuration files, and other files PEAT knows how to parse.

peat heat [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
          [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
          [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs] [--list-all]
          [--list-modules] [--list-aliases] [--list-alias-mappings] [--examples]
          [--all-examples] [--list-heat-protocols] [--heat-elastic-server ELASTIC_URL]
          [--heat-index-names INDEX_NAMES] [--heat-date-range DATE_RANGE]
          [--heat-exclude-ips IP_ADDRESSES [IP_ADDRESSES ...]]
          [--heat-only-ips IP_ADDRESSES [IP_ADDRESSES ...]] [--heat-file-only]
          [--heat-artifacts-dir PATH] [--heat-protocols PROTOCOLS [PROTOCOLS ...]]
          [--pcaps PCAPS] [--no-run-zeek] [--zeek-dir ZEEKDIR]

6. peat heat options

  • -h, --help - show this help message and exit

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat heat general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat heat development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat heat elasticsearch arguments

6. peat heat HEAT arguments

  • --list-heat-protocols - List the available HEAT protocol extractors

  • --heat-elastic-server ELASTIC_URL - Elasticsearch server to query for Packetbeat data for use with artifact extraction (HEAT). If this argument isn’t specified, then the value of --elastic-server will be used instead. This argument is distinct from --elastic-server and the values of the two are allowed to differ, e.g. extract from data on one server and put the results into a different server. URL format: http://user:password@hostname-or-ip:9200/ (default: None)

  • --heat-index-names INDEX_NAMES - Elasticsearch index names or patterns with the Packetbeat datato use for extraction. This can be multiple index names and/or patterns, comma-separated. Same format as Elasticsearch’s API. Example: "packetbeat-2021.05.03,packetbeat-2021.05.04,packetbeat-2021.04.*" (default: None)

  • --heat-date-range DATE_RANGE - Date range to limit extraction to. Format: "<timestamp> - <timestamp>". Example: "2021-07-15T00:00:00.000 - 2021-07-16T12:34:12.143" (default: None)

  • --heat-exclude-ips IP_ADDRESSES - IP addresses or subnets to exclude from search (source and/or destination IP). Example: 192.0.2.33 192.0.0.0/24 (default: None)

  • --heat-only-ips IP_ADDRESSES - IP addresses or subnets to limit search to (source and/or destination IP). Example: 192.0.2.33 192.0.0.0/24 (default: None)

  • --heat-file-only - Skip parsing of extracted files using PEAT (just extract the files)

  • --heat-artifacts-dir PATH - Output directory for artifacts extracted by HEAT. Defaults to "./peat_results/<run-dir>/heat_artifacts/". (default: None)

  • --heat-protocols PROTOCOLS - Protocols for HEAT to use. Defaults to All (default: None)

  • --pcaps PCAPS - Filepath to folder containing PCAPs for processing (default: None)

  • --no-run-zeek - Flag to tell PEAT not to run zeek and instead run on existing Zeek output (on the directory specified with --zeek-dir)

  • --zeek-dir ZEEKDIR - Filepath to direct PEAT to a zeek output directory (default: None)

6. peat config-builder

PEAT Configuration Builder - Textual in-console GUI for generating template YAML configuration files to use with PEAT.

peat config-builder [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
                    [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb]
                    [--repl] [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT]
                    [--elastic-save-blobs]

6. peat config-builder options

  • -h, --help - show this help message and exit

6. peat config-builder general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat config-builder development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat config-builder elasticsearch arguments

6. peat encrypt

Encrypt a config file using PEAT’s built in encryption capability. Must specify the file path to the config file using the -f flag. The encrypted file will be saved to the same directory as the original unencrypted config. The new file will be named the same as the unencrypted file, but will have ‘encrypted_’ added to the beginning of the filename. WARNING: PEAT will not save the encrypted file’s password for you, it is up to you to remember it

peat encrypt [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
             [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
             [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs] [-f FILE]
             [-p USER_PASS] [--list-all] [--list-modules] [--list-aliases]
             [--list-alias-mappings] [--examples] [--all-examples]

6. peat encrypt options

  • -h, --help - show this help message and exit

  • -f FILE, --file-path FILE - File path for config file to encrypt (default: None)

  • -p USER_PASS, --password USER_PASS - Specify password to use to encrypt/decrypt file (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat encrypt general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat encrypt development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat encrypt elasticsearch arguments

6. peat decrypt

Decrypt a config file using PEAT’s built in decryption capability. Must specify the file path to the config file. The decrypted file will be saved to the same directory as the original encrypted config. IMPORTANT: PEAT will only decrypt configs that have previously been encrypted by PEAT, and upon receiving the correct password

peat decrypt [-h] [-c FILE] [-I PATH [PATH ...]] [--no-color] [--no-logo] [-o PATH]
             [--run-dir PATH] [-R NAME] [-q] [-Q] [-E] [-v] [-V] [--dry-run] [--pdb] [--repl]
             [-e [URL]] [--elastic-timeout ELASTIC_TIMEOUT] [--elastic-save-blobs] [-f FILE]
             [-w DIR] [-p USER_PASS] [--list-all] [--list-modules] [--list-aliases]
             [--list-alias-mappings] [--examples] [--all-examples]

6. peat decrypt options

  • -h, --help - show this help message and exit

  • -f FILE, --file-path FILE - File path for config file to decrypt (default: None)

  • -w DIR, --write-file DIR - File path to save decrypted file to (default: None)

  • -p USER_PASS, --password USER_PASS - Specify password to use to encrypt/decrypt file (default: None)

  • --list-all - List the currently imported device modules, their aliases, and alias mappings, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --list-modules - Print the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-aliases - Print aliases for the currently imported device modules, then exit. This includes modules imported with "-I".

  • --list-alias-mappings - Print alias mappings for the currently imported device modules, then exit. This includes modules imported with "-I". WARNING: this has a LOT of output, do not run if you are using a screen reader.

  • --examples - Print examples for the current command, then exit.

  • --all-examples - Print examples for all commands, then exit.

6. peat decrypt general arguments

  • -c FILE, --config-file FILE - Load PEAT configuration from a file (YAML or JSON) (default: None)

  • -I PATH, --import-modules PATH - Director(ies) or file(s) containing 3rd-party PEAT device module(s) to import and use. Modules are Python code (.py files) that subclass and implement "peat.DeviceModule". (default: None)

  • --no-color - Do not color terminal output

  • -o PATH, --out-dir PATH - Output directory for all runs of PEAT. Defaults to "peat_results" in the current directory. (default: None)

  • --run-dir PATH - Directory to use for output for this run. Defaults to a directory in peat_results with either a auto-generated name or the value of --run-name. (default: None)

  • -R NAME, --run-name NAME - Name of the run to use for creating the run directory, instead of auto-generating the name (default: None)

  • -q, --quiet, --silent - Do not output logging messages to the terminal (stdout)

  • -Q, --no-print-results - DEPRECATED. Setting this no longer has any effect, as it’s now the default behavior.

  • -E, --print-results, --json - Print JSON-formatted results from the operation to the terminal (stdout). Note that log messages will still be printed unless '--quiet' is specified.

  • -v, --verbose - Print DEBUG-level messages to terminal (they are still logged to a file even if this option isn’t enabled)

  • -V, --debug - Enable debugging mode. Verbosity can be increased by adding more V’s, e.g. "-VVV". Detailed protocol output generally starts at level 2 ("-VV"). (default: None)

  • --dry-run - Dry run with no actions executed (e.g. scanning for peat scan)

6. peat decrypt development/debugging arguments

  • --pdb, --launch-debugger - Launch the Python debugger (pdb) after initialization and before executing commands. A REPL interface can also be accessed by running "interact" after launching pdb. (WARNING: this will NOT exit cleanly or safely!)

  • --repl, --launch-interpreter - Launch the Python interactive interpreter, aka the Read-Eval-Print-Loop (REPL). Note that this will not necessarily include all of the global state. If you need to do in-depth debugging, use "--pdb", and run "interact".

6. peat decrypt elasticsearch arguments


To get help for a command, run "peat <command> --help" (example: "peat scan --help").

To get examples of how to use a command, run "peat <command> --examples" (example: "peat parse --examples"). Alternatively, to list examples for all commands, run "peat scan --all-examples".

To list modules currently imported by PEAT: "peat scan --list-modules" (or other --list-* arguments, as detailed above in the "optional arguments" section).

Data collected by PEAT is written to files in "./peat_results/" in the current directory (by default). Data can also be saved to Elasticsearch. See the help for specific sub-commands for details.

Refer to the PEAT documentation for a list of supported devices.
You can also run --list-modules or --list-all to get a list of the currently included device modules (e.g., "peat scan --list-modules").

On Linux, the man page may be available: "man peat"

Refer to the PEAT documentation for further information about PEAT's usage.

To report bugs or get help please contact peat@sandia.gov

6.5. PEAT configuration reference

# Configuration file for PEAT (the Process Extraction and Analysis Tool)
#
# PEAT uses PyYAML (https://pyyaml.org/) for YAML parsing, so anything
# that works for PyYAML will work here. YAML version 1.2 is used.
#
# Resources
# - Introduction to YAML: https://learnxinyminutes.com/docs/yaml/
# - YAML 1.2 specification: https://yaml.org/spec/1.2.2/
# - YAML anchors (&) and aliases (*): https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet
#
# Refer to the PEAT Configure section in the VEDAR documentation for further
# details on using the config files and configuring PEAT.
#
# -----------------------------------------------------------------------------

# --- Information about this configuration, such as who created it and what it's for ---

metadata:
  name: "reference-peat-config"
  description: "Reference PEAT configuration with all possible options listed"
  author: "cegoes"
  created: "August 5th, 2021"
  updated: ""

# -----------------------------------------------------------------------------

# --- General configuration options ---

# File paths to external/third-party PEAT device modules to import.
# These can be the path to a .py file with a DeviceModule subclass or a
# path to a folder with an __init__.py file and any number of .py
# files containing DeviceModule subclasses to import.
additional_modules: []

# DEBUG level (higher = more output, 0 = disabled)
debug: 0

# Prefix used for PEAT environment variables
env_prefix: "PEAT_CONFIG_"

# Hash algorithms to use wherever hashes are calculated.
#
# Available algorithms are any of the algorithms provided
# by Python's built-in "hashlib" library.
# https://docs.python.org/3/library/hashlib.html
hash_algorithms:
- md5
- sha1
- sha256
- sha512

# -----------------------------------------------------------------------------

# --- Options for configuring PEAT's Command Line Interface (CLI) output ---

# Include DEBUG-level messages in the terminal output
verbose: false

# Don't write log messages to the terminal
quiet: false

# DEPRECATED. Setting this no longer has any effect, as it's now the default behavior.
no_print_results: false

# Print JSON-formatted results from the operation to
# the terminal (stdout). Note that log messages will still
# be printed unless 'quiet' is true.
print_results: false

# Don't color log messages in the terminal
no_color: false

# Don't print the PEAT logo at startup
no_logo: false

# "Dry run" when running on the CLI, do everything except running commands or
# connecting to servers. Actions won't be executed, but logs and state will
# still be written to files and saved to Elasticsearch (if enabled).
# This includes loading and verifying configuration and importing modules.

# Useful for verifying a YAML config file or other settings are correct,
# or that a third-party PEAT module is imported correctly.
dry_run: false

# Skip the host online check before scan/pull/push
assume_online: false

# Maximum number of threads for any concurrent operations (scanning, etc.)
max_threads: 260

# Default timeout for sockets and potentially other things
default_timeout: 5.0

# -----------------------------------------------------------------------------

# --- Options for controlling lookups of addresses ---

# If PEAT should attempt to resolve device IP address from a hostname or MAC address
resolve_ip: true

# If PEAT should attempt to resolve device MAC address from its IP address
resolve_mac: true

# If PEAT should attempt to resolve device hostname from its IP address
resolve_hostname: true

# -----------------------------------------------------------------------------

# --- Options for controlling how PEAT finds active hosts on a network ---

# Force ARP and ICMP requests to be used to check if a host is online,
# even if the system running PEAT isn't able to use them
force_online_method_ping: false

# Force TCP SYNs to be used to check if a host is online,
# even if the system running PEAT is able to use ARP/ICMP to perform the checks.
force_online_method_tcp: false

# In the case of a ICMP failure, fallback to attempting a
# TCP SYN RST to check if the host is online. If false,
# then ICMP failures will result in the host being marked
# as down, even if they're blocked by a firewall or gateway.
icmp_fallback_tcp_syn: true

# Default port used for basic TCP SYN online checks
# The default HTTP (web) port 80 is generally safe to check
syn_port: 80

# Skip scanning and verification of hosts being pushed to and assume
# all hosts are online and valid devices. NOTE: requires a single
# device type to be specified.
push_skip_scan: false

# Simple host up/down check (equivalent to "nmap -Pn <hosts>").
# If serial ports are targeted, this will enumerate the active
# serial ports on the host.
scan_sweep: false

# Force identification checks of all ports during scanning
intensive_scan: false

# -----------------------------------------------------------------------------

# --- Options for configuring where PEAT saves files ---
# Note: "!JOIN" is a custom YAML construct to join variables
# and static strings into a single value.

# Default directory for all file output
# Note: changing this option will change the base directory for all other
# "*_dir" options, unless they're set to a non-default value.
out_dir: &OUTDIR "./peat_results/"

# Output directory for all files associated with a single run of PEAT.
#
# The name of this directory is automatically generated.
# This can be overridden by manual configuration,
# just be aware of the consequences when doing so.
#
# Name format: <command>_<config-name>_<timestamp>_<run-id>
# - <command> : PEAT command, e.g. "scan", "pull", "parse", etc.
# - <config-name> : name of YAML config file, set in metadata: name: "name".
#     If no config name is specified, then the string default-config is used.
# - <timestamp> : start time of the PEAT run, e.g. 2022-06-15_13-08-59.
#     This value is retrieved from consts.START_TIME.
# - <run-id> : Run ID, aka agent.id, e.g. 165532013980.
#     This value is retrieved from consts.RUN_ID.
#
# Examples:
# - pull_sceptre-test-config_2022-06-17_165532013980
# - scan_default-config_2022-09-27_165532013980
run_dir: &RUNDIR !JOIN [*OUTDIR, "default_run_dir/"]

# Output of device modules (pulled configuration files, firmware images, etc.)
# This is the most relevant directory for the majority of PEAT users
#
# Device file output can be disabled entirely by setting this to an empty string
# or null. This can be useful for low-footprint use cases.
device_dir: !JOIN [*RUNDIR, "devices/"]

# High-level API file output (scan API, parse API, etc.)
summaries_dir: !JOIN [*RUNDIR, "summaries/"]

# Directory where raw documents pushed to Elasticsearch are saved in JSON format.
# These can be used to rebuild the Elasticsearch indices if needed
# To disable this functionality, set this field to 'null' or empty string.
elastic_dir: !JOIN [*RUNDIR, "elastic_data/"]

# Directory for PEAT's run metadata (PEAT's configs and internal state)
meta_dir: !JOIN [*RUNDIR, "peat_metadata/"]

# Directory for PEAT's log files, including:
# - Human-readable PEAT log file
# - Human-readable Elasticsearch log file
# - JSON files for rebulding "vedar-logs" index in Elasticsearch
# - Various other log files generated by specific modules, e.g. Telnet
log_dir: !JOIN [*RUNDIR, "logs/"]

# Working directory for file artifacts. May be cleaned up on exit.
temp_dir: !JOIN [*RUNDIR, "temp/"]

# Directory where Zeek logs will be saved
# Also contains Zeek artifacts
zeek_logdir: !JOIN [*RUNDIR, "zeek_logs/"]


# -----------------------------------------------------------------------------

# --- Options for configuring Elasticsearch or OpenSearch ---
# PEAT is compatible with Elasticsearch 7.x and 8.x, and OpenSearch 2.6+,
# and can be used with Malcolm's OpenSearch instance via '/mapi/opensearch'.
# At runtime, PEAT will determine if the server is running OpenSearch, and
# automatically use the appropriate API. All "elastic_*" options apply to
# OpenSearch as well.

# URL of the Elasticsearch or OpenSearch server.
# Elasticsearch exporting is disabled if this value is null or empty.
# Elasticsearch example: "http://localhost:9200/"
# Malcolm example: "https://user:pass@localhost/mapi/opensearch"
elastic_server: null

# Control what PEAT metadata is automatically saved to Elasticsearch.
# The relevant indices are configurable via ELASTIC_*_INDEX,
# e.g. ELASTIC_CONFIG_INDEX for PEAT configs.
elastic_save_logs: true  # If PEAT logs should be sent to Elasticsearch
elastic_save_config: true  # PEAT's configuration
elastic_save_state: true  # PEAT's state

# If large binary blobs should be stored in Elasticsearch (e.g. firmware images)
elastic_save_blobs: false

# Timeout to connect to the Elasticsearch server
elastic_timeout: 10.0

# Append the current date to Elasticsearch index names.
# Example: when enabled, a push to "ot-device-hosts-timeseries" on April 29 2022
# will actually push to an index named "ot-device-hosts-timeseries-2022.04.29".
# When disabled, the push will go to "ot-device-hosts-timeseries", without the date.
elastic_disable_dated_indices: false

# Additional tag strings to add to each document pushed to Elasticsearch
elastic_additional_tags: []

# -- Elasticsearch index base names --
# NOTE: a date will be automatically appended to the name if
# ELASTIC_DISABLE_DATED_INDICES is false (the default).

# Base name of Elasticsearch index to use PEAT logging events.
elastic_log_index: "vedar-logs"

# Base name of Elasticsearch index to use for scan result summaries,
# e.g. what normally gets written in peat_results/scan_results/.
elastic_scan_index: "scan-summaries"

# Base name of Elasticsearch index to use for pull result summaries,
# e.g. what normally gets written in peat_results/pull_results/
elastic_pull_index: "peat-pull-summaries"

# Base name of Elasticsearch index to use for parse result summaries,
# e.g. what normally gets written in peat_results/parse_results/
elastic_parse_index: "peat-parse-summaries"

# Base name of Elasticsearch index to use for PEAT configuration dumps
# from runs of PEAT, e.g. what normally gets written in
# peat_results/metadata/configs/
elastic_config_index: "peat-configs"

# Base name of Elasticsearch index to use for PEAT state dumps
# from runs of PEAT, e.g. what normally gets written in
# peat_results/metadata/state/
elastic_state_index: "peat-state"

# Information collected by PEAT from field devices or parsed files.
# A new Elasticsearch document is created for every pull of data
# from a device (the data is 'timeseries', with differences visible
# between pulls over time).
elastic_hosts_index: "ot-device-hosts-timeseries"

# Information about files present on the device, or that were present
# on the device at one point in time.
elastic_files_index: "ot-device-files"

# Information about individual communication 'registers'
# (e.g. Modbus registers/coils, DNP3 data points, BACNet objects, etc.)
# that are configured on devices, as extracted from device
# configuration information.
elastic_registers_index: "ot-device-registers"

# Information about tag variables that are configured on devices,
# as extracted from device configuration information.
elastic_tags_index: "ot-device-tags"

# Information about I/O (Input/Output) available and/or configured
# on a device, as extracted from device configuration information.
elastic_io_index: "ot-device-io"

# Logging and other event history as extracted from devices.
# Examples include access logs, system logs, or protection history.
elastic_events_index: "ot-device-events"

# Memory reads from devices, including address in memory,
# the value read, and information about where it came
# from and when the read occurred.
elastic_memory_index: "ot-device-memory"

# Specific UEFI file index that includes the CRC32 of files
# from a UEFI System and paths of files from an SPI dump
elastic_uefi_files_index: "uefi-files"

# Specific UEFI Hash index that includes the hash of files
# from a UEFI System and files.
elastic_uefi_hashes_index: "uefi-hashes"

# -----------------------------------------------------------------------------

# --- HEAT (High-fidelity Extraction of Artifacts from Traffic) ---
# Refer to the HEAT section in the VEDAR documentation for details.

# Elasticsearch server to pull HEAT data from
heat_elastic_server: null

# Names and/or patterns of Elasticsearch indices with Packetbeat data
heat_index_names: "packetbeat-*"

# Date range to filter HEAT extraction to
heat_date_range: null

# IP addresses to exclude from packetbeat search (source and/or destination IP)
heat_exclude_ips: []

# IP address to limit packetbeat search to (source or destination IP)
heat_only_ips: []

# Extract the file(s) but don't parse them using PEAT
heat_file_only: false

# Directory where HEAT artifacts should be saved
heat_artifacts_dir: !JOIN [*RUNDIR, "heat_artifacts/"]

# List of HEAT protocol extractors to run.
# Defaults to all available protocols if empty or unspecified.
#
# Available HEAT protocol extractors:
# - UmasExtractor : UMAS protocol for Schneider Modicon PLCs
# - TelnetExtractor : Telnet protocol for SEL relays
# - FTPExtractor : FTP protocol for SEL relays
heat_protocols: []

# Specify folder that contains PCAPS for processing by HEAT.
pcaps: null

# Don't have PEAT run Zeek on a PCAP, instead run it
# on a PCAP file, then process the output of the PCAP.
# NOTE: zeek_dir must be specified if no_run_zeek is true.
no_run_zeek: false

# Directory with existing Zeek output to use as input
# This is an alternative to PEAT running Zeek on the PCAPs itself
# NOTE: This argument is required if no_run_zeek is true.
zeek_dir: null

# -----------------------------------------------------------------------------

# --- Configuration for "peat pillage" ---
# Refer to the Pillage section in the VEDAR documentation for details.
# Filenames and extensions are matched case-insensitively.
# For example, "set_all.txt" will also match "SET_ALL.TXT".

pillage:
  auto_copy: true
  recursive: true
  default:
    locations: []
    filenames: []
    extensions: []
  brands:
    Siemens:
      locations: []
      filenames: []
      extensions:
        - mc7
    SEL:
      locations: []
      filenames:
        - set_all.txt
        - cfg.txt
        - ser.txt
        - history.txt
        - cser.txt
        - chistory.txt
      extensions:
        - rdb
        - cid
    Modicon:
      extensions:
        - apx
    # Rockwell Studio5000
    L5X:
      extensions:
        - l5x
    ION:
      filenames:
        - DEVINFO.DAT
        - SITEINFO.DAT
        - 61850_log.txt
      extensions:
        - upg
    Woodward:
      extensions:
        - wset
        - tc

# -----------------------------------------------------------------------------

# --- Protocol and module configuration options that apply to all hosts ---
# Note: these options will be overridden by values configured in the "hosts" section.

device_options:
  # Serial baud rates to use when scanning/pulling a serial device (e.g. RS-232)
  # Example: [9600, 57600]
  baudrates: []

  # Default timeout for all protocols
  timeout: 5.0

  # Configuration specific to the Fortinet FortiGate firewalls
  fortigate:
    # Select what protocols PEAT is allowed to use
    # for pulling data from FortiGate devices.
    pull_methods:
      - ssh
      - https

    # How long to wait before timing out when pulling log files.
    # This may need to be increased for very large log files.
    log_pull_timeout: 30.0

  # Enable SCEPTRE/OpenPLC compatibility changes to Structured Text logic output
  sceptre_plc_compatible_st_logic: false

  # Configuration specific to the SCEPTRE module
  sceptre:
    # Enable local development of SCEPTRE module using Twisted
    # (refer to SCEPTRE module docstring for details)
    ftp_testing: false

    # Name of bennu firmware file.
    # This will be auto-determined if a scan is performed.
    bennu_filename: "bennu-field-deviced.firmware"

  # Configuration specific to the SEL modules (SELRelay and SELRTAC)
  sel:
    # Select what protocols PEAT is allowed to use
    # for pulling data from SEL relays.
    pull_methods:
      - http
      - ftp
      - telnet

    # Run a variety of SEL terminal commands that PEAT knows.
    # This can provide information that are not in config files, or
    # provide an alternate source of data to config files when they
    # aren't able to be retrieved for whatever reason.
    # This is disabled by default as it is relatively untested and
    # can potentially be very slow.
    attempt_more_commands: false

    # Enable PEAT to attempt to download files via Telnet, if able to,
    # and if the files haven't already been downloaded via FTP.
    allow_telnet_file_download: true

    # Force files to be downloaded via Telnet,
    # even downloading via FTP is successful.
    force_telnet_file_download: false

    # Force serial to be used for the pull, instead
    # of auto-determining if it should be used.
    force_serial_pull: false

    # Use YMODEM rz/sz (from lrzsz package) to perform file transfers
    # instead of using the ASCII interface.
    #
    # NOTE: this ONLY works on Linux, and requires "lrzsz" package
    # to be installed ("sudo apt install lrzsz").
    force_ymodem: false

    # Restrict the files/directories downloaded to only those in these lists
    # Note: files in "only_*" lists will OVERRIDE any values
    #   specified in the "never_*" lists
    only_download_files: []  # Example: ["SET_6.TXT"]
    only_download_dirs: []  # Example: ["SETTINGS", "EVENTS"]

    # Never download the files/directories in these lists
    never_download_files: []  # Example: ["CFG.XML", "SWCFG.ZIP"]
    never_download_dirs: []  # Example: ["EVENTS", "HMI"]

    # If the relay should be restarted (rebooted) after pushing updated configs ("peat push").
    restart_after_push: false

    # Alternate method of FTP pulls that may work on older devices.
    # Only enable this if debugging issues with FTP downloads.
    old_ftp: false

    # If exceptions during file downloads should be caught and logged.
    # Set this to false if debugging issues with downloads.
    handle_download_errors: true

    # Credentials for standard SEL accounts, e.g. "acc" and "2ac".
    # This applies to Telnet, Serial, and HTTP communication methods,
    # and also applies to FTP in many cases (but not all).
    #
    # NOTE: these are available in SEL's documentation for each relay model,
    # For further information about featured available at each level,
    # consult the SEL documentation for the relay model of interest.
    creds:
      # Access level 1 ("acc"). Provides access to status and listing commands,
      # including "fil show" and "fil dir" commands for reading
      # files and directories.
      acc: "OTTER"
      # Access level 2 ("2ac"). Provides access to more commands,
      # including the ability to reboot the relay.
      2ac: "TAIL"
      # bac: "BREAKER" access level (present on 351S and others)
      #
      # "bac" isn't currently used by PEAT, but is left here
      # for future compatibility and documentation/reference.
      bac: "EDITH"
      # cal: "CALIBRATION" access level. This provides access to advanced
      # commands intended for use by SEL employees, such as the ability
      # to read and write arbitrary memory and many other functions.
      #
      # PEAT uses cal when performing memory reads.
      #
      # SEL-451 "cal" default: "Sel-1"
      cal: "CLARKE"

    # SELRTAC: If the pull should collect data via HTTP
    pull_http: true

    # SELRTAC: If the pull should collect data via Postgres
    pull_postgres: true

    # SELRTAC: enable "monitoring"
    # This regularly pulls device data and compares the pulls over time
    # NOTE: this feature was a initial proof of concept and may not work anymore
    rtac_monitor_enable: false

    # Number of pulls to do before finishing monitoring
    rtac_monitor_count: 3

    # How long to wait between each pull during monitoring, in seconds
    rtac_monitor_pause_for: 4.0

  # Configuration specific to the M340 module
  m340:
    # Pull only the project file from a M340 via Modbus,
    # don't use network services to pull additional information (SNMP, FTP, etc.)
    use_network_for_config: true

    # Generate a OpenPLC project with generated TC6 XML from the results of
    # parsing the project from the M340. If a directory path is provided
    # (e.g. "~/project_dir/"), then the project files will be created in
    # that directory. If the string "dev_out_dir" is specified, then the
    # files will be created in a project-named directory in the device's
    # output directory.
    generate_openplc_project: null

  # Configuration specific to the GE modules (GERTU and GERelay)
  ge:
    # GERTU: How long to sleep between selecting menu options over
    # Telnet on the GE D25 RTU.
    menu_sleep_seconds: 5.0

  # Configuration specific to the ControlLogix module
  rockwell:
    # What protocols to use for pulling from Rockwell devices
    # Available methods: cip, ftp, http, snmp
    pull_methods:
      - cip
      - ftp
      - http
      - snmp
    # NOTE: the "ftp" option (below) should be used to specify custom
    # login credentials for FTP server on the ControlLogix.
    #
    # NOTE: the "web" option (below) should be used to configure custom
    # login credentials used for the HTTP server on the ControlLogix.

  # ion:
  #   # Select what protocols PEAT is allowed to use
  #   # for pulling data from ION meters.
  #   pull_methods:
  #     - ssh
  #     - ion_protocol
  #     - telnet
  #     - http

  # Configuration specific to the Sage module
  sage:
    # Available methods: telnet, ftp, ssl, ssh
    pull_methods:
      - telnet
      - ftp
      - ssl
      - ssh
      - sftp
      - http
      - https
    # Filesystems on the device that will be enumerated via FTP
    ftp_filesystems:
      - /ata0a
      - /ramDrv
    ssh_filepaths:
      - /ata0a/scripts/vxworks_start.scp
      - /ata0a/scripts/startup.scp

  # Configuration for iDirect devices
  #
  # "idirect" is used by the following modules: Idirect
  idirect:
    # Available methods: ssh, ssl
    pull_methods:
      - ssh
      - ssl

  # Configuration for Woodward modules
  #
  # "woodward" is used by the following modules: MicroNet, Easygen3500XT, WDW2301E
  woodward:
    # Available methods: servlink_tcp, ftp
    pull_methods:
      - servlink_tcp
      - ftp

  # Combination of HTTP and HTTPS configurations into a single option
  #
  # "web" is used by the following modules: ControlLogix, SELRelay, SELRTAC
  web:
    user: ""
    pass: ""
    timeout: 30.0  # Used by Sage
    users: []  # Used by SELRTAC
    passwords: []  # Used by SELRTAC

  # File Transfer Protocol (FTP)
  #
  # "ftp" is used by the following modules:
  #   Sage, SCEPTRE, SELRelay, M340, Micronet, Easygen3500XT
  ftp:
    port: 21
    timeout: 5.0
    user: ""
    pass: ""
    creds: []
    pull_delay: 0.5  # Used by SELRelay

  # Telnet protocol
  #
  # "telnet" is used by the following modules: GERTU, ION, SELRelay, Sage
  telnet:
    port: 23
    timeout: 5.0
    # NOTE: for SELRelay, configure "creds" under "sel" instead
    user: ""
    pass: ""
    # ION specific option for advanced security mode
    meter_pass: "0"
    # ION specific options for network latency adjustments
    pull_delay: 0

  # SSH protocol
  #
  # "ssh" is used by the following modules: Sage
  ssh:
    port: 22
    timeout: 5.0          # Timeout (seconds) before timing out
    user: ""              # Login username
    pass: ""              # Login password
    passphrase: ""        # Pem key_file passphrase
    key_filename: ""      # Location of pem key (must be openssh)
    look_for_keys: false  # Don't look for ssh keys

  # Hyper-Text Transfer Protocol (HTTP)
  #
  # "http" is used by the following modules:
  #   ControlLogix, GERelay, ION, Totus, M340, Sage, SELRelay, SELRTAC, Siprotec
  #
  # NOTE: ControlLogix only uses "http" for port/timeout, use
  # "web" to configure credentials (user/pass).
  http:
    port: 80
    timeout: 5.0
    user: ""
    pass: ""

  # HTTPS (encrypted HTTP)
  #
  # "https" is used by the following modules: Sage, SELRelay, SELRTAC, Siprotec
  https:
    port: 443
    timeout: 5.0

  # Simple Network Management Protocol (SNMP)
  #
  # "snmp" is used by the following modules: ControlLogix, M340, Siprotec
  snmp:
    port: 161
    timeout: 5.0
    community: public
    communities:
      - public
      - private

  # Serial connection options (RS-232, etc.)
  #
  # NOTE: PEAT uses "8N1" for all serial connections.
  # This is not configurable currently.
  serial:
    baudrate: 0
    timeout: 5.0

  # Modbus/TCP protocol
  #
  # "modbus_tcp" is used by the following modules: M340
  modbus_tcp:
    port: 502
    timeout: 5.0

  # ServLink/TCP protocol
  #
  # "servlink_tcp" is used by the following modules: Easygen3500XT
  servlink_tcp:
    port: 666
    timeout: 5.0

  # ServLink protocol (for serial links)
  #
  # "servlink_serial" is used by the following modules: Easygen3500XT, WDW2301E
  servlink_serial:
    timeout: 5.0

  # PostgreSQL protocol (used for communicating with PostgreSQL databases)
  #
  # "postgres" is used by the following modules: SELRTAC
  postgres:
    port: 5432
    timeout: 5.0
    user: ""
    pass: ""
    users: []  # Used by SELRTAC
    passwords: []  # Used by SELRTAC

  # Common Industrial Protocol (CIP)
  #
  # "cip" is used by the following modules: ControlLogix
  cip:
    port: 44818
    timeout: 5.0

  # Siemens SIPROTEC DIGSI protocol
  #
  # "digsi" is used by the following modules: Siprotec
  digsi:
    port: 50000
    timeout: 5.0

  ion_protocol:
    port: 7700
    timeout: 5.0
    pull_ion_log: true
    pull_ion_config: true
    authenticated: false
    advanced_security: false
    user: "0"
    pass: "0"

# -----------------------------------------------------------------------------

# --- Specify or override options for specific hosts ---
# For example, if login credentials are known for specific hosts,
# then those can be specified here.
# Note: these will override values specified in the "device_options" section above.
#
# If you have a network inventory, such as a spreadsheet or network diagram,
# this section ("hosts") is where you would enter the information from that
# inventory.

hosts:
  # The Label can be used to reference the host in commands, e.g. "peat scan -i example-host"
  # Labels are case-insensitive, e.g. "example-host" and "Example-Host" are considored the same
  # IMPORTANT: Labels MUST be unique, and must not match any other device.
  - label: "example-host"
    comment: "User-specified text that may be included in results or other output (e.g. log messages)"

    # Identifying information for the host.
    # NOTE: At least ONE identifier value must be set.
    identifiers:
      ip: "192.168.0.1"
      mac: "00:00:00:00:00:00"
      serial_port: "COM0"
      name: "some-device-name"
      hostname: "a-hostname"

    # This option forces a specific PEAT module to be used for this host.
    # No other modules will be attempted or otherwise used for this host.
    # For example, if "ION" is specified, then only the ION module will
    # be used for fingerprinting and pulling from this host.
    peat_module: "AwesomeModule"

    # Options for this specific device.
    # These options will override any values specified in the
    # "device_options" section above for this host only. They
    # will also override any default values.
    options: {...}
# -----------------------------------------------------------------------------