Configurations

As discussed in previous sections, the BroAPT system is configurable in various ways. You can configure the outer system from the entry CLI of BroAPT-Daemon server, and the main framework through Docker Compose environment variables.

BroAPT-Daemon Server

Command Line Interface

usage: broaptd [-h] [-v] [-e ENV] [-s SIGNAL] [-t HOST] [-p PORT]
               [-f DOCKER_COMPOSE] [-d DUMP_PATH] [-l LOGS_PATH] [-r API_ROOT]
               [-a API_LOGS] [-i INTERVAL] [-m MAX_RETRY]

BroAPT Daemon

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit

environment arguments:
  -e ENV, --env ENV     path to dotenv file
  -s SIGNAL, --signal SIGNAL
                        daemon kill signal

server arguments:
  -t HOST, --host HOST  the hostname to listen on
  -p PORT, --port PORT  the port of the webserver

compose arguments:
  -f DOCKER_COMPOSE, --docker-compose DOCKER_COMPOSE
                        path to BroAPT's compose file
  -d DUMP_PATH, --dump-path DUMP_PATH
                        path to extracted files
  -l LOGS_PATH, --logs-path LOGS_PATH
                        path to log files

API arguments:
  -r API_ROOT, --api-root API_ROOT
                        path to detection APIs
  -a API_LOGS, --api-logs API_LOGS
                        path to API runtime logs

runtime arguments:
  -i INTERVAL, --interval INTERVAL
                        sleep interval
  -m MAX_RETRY, --max-retry MAX_RETRY
                        command retry

Environment Variables

As suggests in the --env option, you may provice a dotenv (.env) file for the BroAPT-Daemon server to configure itself.

Acceptable environment variables are as following:

BROAPT_KILL_SIGNAL
Type

int

Default

15 (SIGTERM)

CLI Option

-s / --signal

Daemon kill signal.

BROAPT_SERVER_HOST
Type

str (hostname)

Default

0.0.0.0

CLI Option

-t / --host

The hostname to listen on.

BROAPT_SERVER_PORT
Type

int (port number)

Default

5000

CLI Option

-p / --port

The port of the webserver.

BROAPT_DOCKER_COMPOSE
Type

str (path)

Default

docker-compose.yml

CLI Option

-f / --docker-compose

Path to BroAPT’s compose file.

BROAPT_DUMP_PATH
Type

str (path)

Default

None

CLI Option

-d / --dump-path

Path to extracted files.

BROAPT_LOGS_PATH
Type

str (path)

Default

None

CLI Option

-l / --logs-path

Path to log files.

BROAPT_API_ROOT
Type

str (path)

Default

None

CLI Option

-r / --api-root

Path to detection APIs.

BROAPT_API_LOGS
Type

str (path)

Default

None

CLI Option

-a / --api-logs

Path to API runtime logs.

BROAPT_INTERVAL
Type

float

Default

10

CLI Option

-i / --interval

Sleep interval.

BROAPT_MAX_RETRY
Type

int

Default

3

CLI Option

-m / --max-retry

Command retry.

Note

Environment variables of bool type will be translated through the following mapping table (case-insensitive):

True

False

1

0

yes

no

true

false

on

off

BroAPT-Core Framework

The BroAPT-Core framework only supports configuration through environment variables.

BROAPT_CPU
Type

int

Default

None

Availability

bundled implementation

Number of BroAPT concurrent processes for PCAP analysis. If not provided, then the number of system CPUs will be used.

BROAPT_CORE_CPU
Type

int

Default

None

Availability

cluster implementation

See also

BROAPT_CPU

BROAPT_INTERVAL
Type

float

Default

10

Availability

bundled implementation

Wait interval after processing current pool.

BROAPT_CORE_INTERVAL
Type

float

Default

10

Availability

cluster implementation

Wait interval after processing current pool of PCAP files.

BROAPT_DUMP_PATH
Type

str (path)

Default

FileExtract::prefix (Bro script)

Path to extracted files.

BROAPT_PCAP_PATH
Type

str (path)

Default

/pcap/

Path to source PCAP files.

BROAPT_LOGS_PATH
Type

str (path)

Default

/var/log/bro/

Path to system logs.

BROAPT_MIME_MODE
Type

bool

Default

True

If group extracted files by MIME type.

BROAPT_JSON_MODE
Type

bool

Default

LogAscii::use_json (Bro script)

Toggle Bro logs in JSON or ASCII format.

BROAPT_BARE_MODE
Type

bool

Default

False

Run Bro in bare mode (don’t load scripts from the base/ directory).

BROAPT_NO_CHKSUM
Type

bool

Default

True

Ignore checksums of packets in PCAP files when running Bro.

BROAPT_HASH_MD5
Type

bool

Default

False

Calculate MD5 hash of extracted files.

BROAPT_HASH_SHA1
Type

bool

Default

False

Calculate SHA1 hash of extracted files.

BROAPT_HASH_SHA256
Type

bool

Default

False

Calculate SHA256 hash of extracted files.

BROAPT_X509_MODE
Type

bool

Default

False

Include X509 information when running Bro.

BROAPT_ENTROPY_MODE
Type

bool

Default

False

Include file entropy information when running Bro.

BROAPT_LOAD_MIME
Type

List[str] (case-insensitive)

Default

None

A , or ; separated string of MIME types to be extracted.

BROAPT_LOAD_PROTOCOL
Type

List[str] (case-insensitive)

Default

None

A , or ; separated string of application layer protocols to be extracted, can be any of dtls, ftp, http, irc and smtp.

BROAPT_FILE_BUFFER
Type

int (uint64)

Default

Files::reassembly_buffer_size (Bro script)

Reassembly buffer size for file extraction.

BROAPT_SIZE_LIMIT
Type

int (uint64)

Default

FileExtract::default_limit (Bro script)

Size limit of extracted files.

BROAPT_HOOK_CPU
Type

int

Default

1

Number of BroAPT concurrent processes for Python hooks.

BroAPT-App Framework

The BroAPT-App framework only supports configuration through environment variables.

BROAPT_SCAN_CPU
Type

int

Default

None

Availability

bundled implementation

Number of BroAPT concurrent processes for extracted file analysis. If not provided, then the number of system CPUs will be used.

BROAPT_APP_CPU
Type

int

Default

None

Availability

cluster implementation

See also

BROAPT_SCAN_CPU

BROAPT_INTERVAL
Type

float

Default

10

Availability

bundled implementation

Wait interval after processing current pool.

BROAPT_APP_INTERVAL
Type

float

Default

10

Availability

cluster implementation

Wait interval after processing current pool of extracted files.

BROAPT_MAX_RETRY
Type

int

Default

3

Retry times for failed commands.

BROAPT_API_ROOT
Type

str (path)

Default

/api/

Path to the API root folder.

BROAPT_API_LOGS
Type

str (path)

Default

/var/log/bro/api/

Path to API detection logs.

BROAPT_NAME_HOST
Type

str (hostname)

Default

localhost

Hostname of BroAPT-Daemon server.

BROAPT_NAME_PORT
Type

int (port number)

Default

5000

Port number of BroAPT-Daemon server.