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.