Configuration

Kestrel loads user-defined configurations to override default values when the runtimes start. Thus you can customize your Kestrel runtime by putting configuration values in ~/.config/kestrel/kestrel.yaml or any YAML file with path specified in the environment variable KESTREL_CONFIG.

Note: the Kestrel main config should not be confused with configurations for data sources. In Kestrel, data sources are defined/grouped by each Kestrel Data Source Interface. Each data source interface is a Python package and has its own configuration file. For example, STIX-shifter Data Source Interface describes the use and configuration of STIX-shifter data sources.

Default Kestrel Configuration

# syntax default values
language:
  default_variable: "_"
  default_sort_order: "desc"
  default_datasource_schema: "stixshifter"
  default_analytics_schema: "python"

# Kestrel session execution
session:
  cache_directory_prefix: "kestrel-session-" # under system temp directory
  local_database_path: "local.db"
  log_path: "session.log"
  show_execution_summary: true

# whether/how to prefetch all records/observations for entities
prefetch:

  # enable/disable prefetch for command
  #
  # If prefetch is enabled, Kestrel will send additional queries to the data
  # source to search for related records regarding entities retrieved from the
  # user-specified pattern, collecting more complete information (attributes,
  # connections to other entities) of the entities from different records.
  switch_per_command:
    get: true
    find: true

  # declare the list of entity types to not prefetch
  #
  # This can be used when a user finds prefetch hinders the performance with
  # large amount of results for one or more generic type of entities. For
  # example, the data source may have millions of records containing
  # `C:\Windows\SYSTEM32\ntdll.dll` touched by all Windows processes in a short
  # amount of time. Executing a Kestrel command `f = FIND file LINKED p` will
  # retrieve the file from a process and then start prefetch to gain
  # information/connections of the file from all processes. Retrieval of
  # millions records will likely result in a performance issue, thus the user
  # can put `file` in this list to disable prefetch for it.
  excluded_entities:
    # By default, Kestrel disables prefetch for the 3 entities, which are
    # shared by large amount of logs
    - file
    - user-account
    - x-oca-asset

  # Detailed logic to identify the same process from different records is more
  # complex than many data source query language can express, so Kestrel
  # retrieves potential same process candidate records and perform fine-grained
  # process identification in Kestrel with these parameters.
  process_identification:
    pid_but_name_changed_time_begin_offset: -5 # seconds
    pid_but_name_changed_time_end_offset: 5 # seconds
    pid_and_name_time_begin_offset: -3600 # seconds
    pid_and_name_time_end_offset: 3600 # seconds
    pid_and_ppid_time_begin_offset: -3600 # seconds
    pid_and_ppid_time_end_offset: 3600 # seconds
    pid_and_name_and_ppid_time_begin_offset: -86400 # seconds
    pid_and_name_and_ppid_time_end_offset: 86400 # seconds

# option when generating STIX query
stixquery:
  timerange_start_offset: -300 # seconds
  timerange_stop_offset: 300 # seconds
  support_id: false # STIX 2.0 does not support unique ID

# debug options
debug:
  env_var: "KESTREL_DEBUG" # debug mode if the environment variable exists
  cache_directory_prefix: "kestrel-" # under system temp directory
  session_exit_marker: "session.exited"
  maximum_exited_session: 3

Example of User-Defined Configurations

You can disable prefetch by creating ~/.config/kestrel/kestrel.yaml with the following:

prefetch:
  switch_per_command:
    get: false
    find: false

Kestrel will then not proactively search for logs/records for entities extracted from the return of GET/FIND, which will largely disable followup FIND commands/steps.

Kestrel config supports expansion of environment variables, e.g., if a value in the YAML file is $ENVX, then the value is fetched from environment variable $ENVX Kestrel loads the config file.