4. Configure

Warning

The configuration values shown here are intended to demonstrate how to configure PEAT. We STRONGLY recommend customizing the settings for your use case and environment. The best example of this is limiting the PEAT device modules used to only those present in the environment, e.g. -d sel if using PEAT with SEL-manufactured devices.

4.1. Configuring PEAT

PEAT has a number of global settings that are configurable via several methods, including command line arguments, environment variables, and a YAML file.

If a value is configured via multiple methods, the order of precedence determines what value is actually used.

4.1.1. Order of precedence for configuration

  1. Command line arguments (example: -VV)

  2. Environment variables (example: export PEAT_DEBUG=2)

  3. Configuration file (example: -c peat-config.yaml)

  4. Default values

If using the Python API, e.g. config.DEBUG=1 or values passed to initialize_peat(...), those are applied at the same level as command line arguments and override environment variables and the config file.

4.2. YAML configuration file

PEAT can be configured using a YAML file. This file can be provided on the CLI using the -c argument, for example peat scan -c peat-config.yaml.

Values loaded from the file override the default values, but can be overridden by environment variables and command line arguments. In other words, options set in a config file have lower precedence than those set via command line args or environment variables.

Refer to YAML config reference for the available configuration options.

4.2.1. Config file usage examples

peat scan -c ./examples/peat-config.yaml -d clx -i 192.0.2.0/24
peat pull -c ./examples/peat-config.yaml -d ion sel -i 192.0.2.0/24
peat push -c ./examples/peat-config.yaml -d selrelay -i 192.0.2.1 -- ./SET_1.TXT
peat parse -c ./examples/peat-config.yaml -d selrelay ./SET_ALL.TXT

4.3. Walkthrough of the YAML config

The file starts with a metadata section. This is metadata about the config file itself, including the name of the config, a human-readable description, the name of the original author, timestamp of when it was created, and timestamp of when it was updated. name should be set, the others are optional but recommended.

Metadata example
metadata:
  name: "simple-peat-config"
  description: "Simplified PEAT configuration with all comments removed"
  author: "cegoes"
  created: "May 22nd, 2024"
  updated: ""

Most of the top-level keys are standard config options, and most can be specified via command line args or environment variables, with a few exceptions (notable example are a lot of the elastic options aren’t CLI-configurable to reduce complexity and size of --help). Examples include resolve_ip, no_print_results, elastic_server, debug, and others.

Examples of standard config options
verbose: false
quiet: false
no_print_results: false
no_color: false
no_logo: false
assume_online: false
max_threads: 260
default_timeout: 5.0

The pillage section is the configuration for PEAT Pillage, refer to Pillage config reference.

The device_options section are settings for modules or protocols that are applied to everything in this PEAT run. In other words, it’s global/universal, it’s not on a per-host basis. Generally speaking, module/vendor specified methods have a dedicated key, e.g. sel for SEL devices (SELRelay and SELRTAC modules), sage for the Sage module, etc. Then, there are protocol-specific options, e.g. telnet, ssh, etc. The protocol-specific options are usually port, timeout, login credentials, and any other protocol-specific options (such as SSH key paths).

Simple example forcing telnet to be used for pulls from any SEL devices.
device_options:
sel:
   pull_methods:
      - telnet

The hosts section is a list of hosts that will be scanned/pulled/interrogated by PEAT. Think of it as a inventory of devices. PEAT will use the information about these those to tune it’s scanning parameters. Additionally, this is where per-host configurations are set, notably login credentials, as well as any other settings that need to be set for a particular host.

Example of the hosts section
hosts:
- label: "SEL-351S"
  comment: "SEL-351S Protection System in building XXX"
  identifiers:
    ip: 192.0.0.220
    mac: 00:30:A7:11:12:13
    serial_port: /dev/ttyUSB0
  peat_module: "SELRelay"
  options:
    ftp:
      user: "FTPUSER"
      pass: "TAIL"
- label: "SEL-351"
  comment: "SEL-351 Protection System in building XXX"
  identifiers:
    ip: 192.0.0.221
    mac: 00:30:A7:11:12:14
  peat_module: "SELRelay"
  options:
    ftp:
      user: "FTP"
      pass: "TAIL"
    sel:
      never_download_dirs:
        - EVENTS

It’s important to keep in mind that config options are not consistent. PEAT modules have evolved over time and they don’t always follow the same way of doing things as other modules, especially those modules that existed before the YAML config was a thing (YAML config was introduced in late 2021). If you’re uncertain of a option’s behavior, refer to the reference config, and the module’s class definition if needed.

4.4. Environment variables

Configuration options can be set via system environment variables that are prefixed with PEAT_. For example, to change the debugging level to 1, set the environment variable PEAT_DEBUG to 1, such as with export PEAT_DEBUG=1 on Linux. Environment variables will override default settings and settings loaded from a configuration file, and are overridden by command line arguments. For example, if the environment variable PEAT_DEBUG is set to 1, and peat is run with peat scan -VV, then the value of DEBUG for that run of PEAT will be 2.

Linux environment variable configuration example
# Set variables via export
export PEAT_DEBUG=1
export PEAT_VERBOSE=true
peat parse examples/
peat scan -i localhost

# Modify only for this command execution
PEAT_DEBUG=2 peat parse examples/
Windows environment variable configuration example
setx PEAT_DEBUG 1
setx PEAT_VERBOSE true
peat parse examples/
peat scan -i localhost

4.5. Additional topics

4.5.1. Disabling file output

Setting directory-related configuration options (e.g. SUMMARIES_DIR) to an empty string will disable any output to that directory. For example, setting LOG_DIR to an empty string (e.g. LOG_DIR="") will disable writing of logging data to files, including PEAT’s logging and any protocols that log to a file (such as Telnet).

This feature is works well for most of the general options, such as SUMMARIES_DIR or ELASTIC_DIR. Be warned, however, that mileage may vary for heavily used output dirs, such as DEVICE_DIR and OUT_DIR. They should work fine, but there have been regressions in the past where files have been written when OUT_DIR was disabled (in one case). If disabling file output is critical to your use case, we recommend testing locally before executing in the field.

4.5.2. Auto-generated configs

Every run of PEAT generates a YAML file with the configuration values from the run in the path set by META_DIR, which by default is ./peat_results/*/peat_metadata/. This contains values for all configurations, regardless of their source, and is the single source of truth for how PEAT was configured at the end of a run. Note that if you used a config file for the run the auto-generated config may not match the config file you specified exactly.

These auto-generated configuration files can also be safely re-used in a future run without modification. For example, peat scan -c ./peat_results/*/peat_metadata/peat_configuration.yaml -i 192.0.2.0/24. This can help ensure consistency between runs, simplifies the process of reproducibility (redoing the same run in the same manner at a later date), and saves typing.

4.5.3. JSON file

PEAT will also accept configuration files in JSON format. This is provided for flexibility and to provide backward compatibility. However, it’s more limited than the YAML, and harder to write. The YAML format is preferred.

4.6. YAML config 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: {...}
# -----------------------------------------------------------------------------

4.7. Pillage config reference

  • auto_copy [True or False] If True automatically copy a file to the results directory. If False ask for permission to copy first. This can be helpful in the case when there may be lot of false positives and the user wants to verify prior to copying. For example if you are searching for xml files.

  • recursive [True of False] If True search in the source parent directory and all sub directories. If False only search in the source parent directory and ignore all sub directories.

  • Default/Brand specific search criteria:

    • locations [List of strings, each one should be a directory path] If empty search through all directories. If directories exist only files in those directories will be considered. Not yet implemented, Pillage currently searches through all directories regardless of what is listed here.

    • filenames [List of strings] A list of filenames to search for. When searching filenames take precedence over extensions and will be used first to determine the validity of a file. No wildcards are accepted. Must be the full filename with extension. Example ['set_all.txt', '700g_001.rdb']

    • extensions [List of strings] A list of extensions to search for. No wildcards are accepted. Example ['txt', 'rdb', 'xml']