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.