Configuring tBB¶

If you wish to configure tBB settings, you can use the configuration files tBB is instructed to look for. These files are always located in the ~/.tBB/configs/ folder. Please check where this folder is located before continuing reading.

Configuration files are in the standard JSON format. If you’re unfamiliar with such format, please refer to RFC 7159, or other documentation on the Internet.

Note

You’re free to change settings in these files at any time, but if you want your changes to take effect you’ll to have to restart tBB.

How configuration works in tBB¶

Configuration in tBB works like the way cascade sheets work. There are 3 levels of configuration:

BUILTIN configuration
        ^
        |
        |
DEFAULT configuration
        ^
        |
        |
SPECIFIC configuration

The first level is the built-in configuration that comes with tBB: this cannot be changed and acts as a fallback for tBB.

The second level is the default configuration which is stored in ~/.tBB/configs/config_default.json: you can set this and will be applied to every network your tBB installation will monitor.

The third level is the network-specific configuration which is stored in ~/.tBB/configs/config_{NETWORK}.json: this configuration will only be applied if tBB is asked to monitor the {NETWORK} network. On network-specific filename syntax please refer to the below section.

Each new level overrides the configurations of the previous one.

Note

There are many configuration files you may want to add to your tBB installation, but tBB is capable of running without any configuration file, falling back to the built-in configuration.

Network-specific configuration files naming conventions¶

Specific configuration files naming conventions follow the scans naming conventions, and is as follows:

~/.tBB/configs/config_{NETWORK IP}\{NETMASK (cidr)}-{NETWORK LENGTH}.json

This rigid naming conventions allow tBB to use the correct configuration file for every network you may want to monitor.

For instance, if you want to create a configuration file for network 192.168.100.0/24 you’re going to need to create a file named config_192.168.100.0\24-256.json.

Note

Please note the backslash \ replacing the forward slash / (forward slash is invalid for the Unix file name conventions). Also note the given network length in the filename after the dash - sign.

Examples¶

These examples may be applied to both a default or a network-specific configuration file.

Do not sleep between checks:

{
    "monitoring": {
        "time_between_checks": "00:00",
        "maximum_seconds_randomly_added": 0
    }
}

Change time format and enable syslog:

{
    "logging": {
        "default_time_format": "%m-%d-%Y, %H.%M.%S"  # <-- time format
        "handlers": {
            "syslog": {                   # <-- configure syslog
                "address": {              #
                    "ip": "192.168.0.1",  #
                    "port": 666           #
                },
                "socktype": "DATAGRAM"
            },
            "enable": ["console", "file", "syslog"]  # <-- enable logging handlers here
    }
}

Bind tBB server to a non-loopback interface and disable SSL:

{
    "frontends": {
        "host": "192.168.100.15",
        "ssl": {
            "enable": false
        }
    }
}

Configuration fields¶

The various fields configurable in tBB are divided in logical sections, so that they can be easier to understand and recognize.

What follows are tables of the available configurable fields.

Default values are the values specified in the built-in configuration.

Root-level

Field name	Description	Example values	Default value
`monitoring`	Section dedicated to the monitoring machinery	is section, see below	...
`frontends`	Section dedicated to frontends communication	is section, see below	...
`serialization`	Section dedicated to scans storage handling	is section, see below	...
`logging`	Section dedicated to the logging facilities	is section, see below	...

monitoring

Field name	Description	Example values	Default value
`discoveries`	Section dedicated to the discovery methods	is section, see below	...
`least_record_update`	Maximum amount of time for which tBB will not re-perform a complete scan on startup (format: `minutes:seconds`).	`'00:00'`	`'30:00'`
`enable_notifiers`	Tell notifiers about detected changes.	`false`	`true`
`time_between_checks`	Amount of time to wait before proceeding to check the next host [1] (format: `minutes:seconds`).	`'00:00'`	`'00:02'`
`maximum_seconds_randomly_added`	Maximum amount of time to add randomly [2] to `time_between_checks` (in seconds). Must be a positive integer.	`10`	`2`
`auto_ignore_broadcasts`	Enable/disable automatic broadcasts ignore. If enabled, when a broadcast is detected during a scan, it will be ignored in the next ones.	`false`	`true`
`hosts`	Number of hosts sub-networks will be divided into. Must be a valid network length (aka, power of 2).	`64`	`16`
`ignore`	List of IPs to ignore.	`['192.168.100.1']`	`[]`
`ignore_mac`	List of MACs to ignore.	`['00:...:00']` `[]`
`ignore_name`	List of host names to ignore.	`['donald.duck']`	`[]`

monitoring → discoveries

Field name	Description	Example values	Default value
`arp`	Section dedicated to the ARP discovery method	is section, see below	...
`icmp`	Section dedicated to the ICMP discovery method	is section, see below	...
`syn`	Section dedicated to the SYN discovery method	is section, see below	...

monitoring → discoveries → arp

Field name	Description	Example values	Default value
`count`	Number of ARP broadcasts to emit.	`1`	`3`
`timeout`	Maximum amount of time in which to wait for a response (in seconds). Must be a positive integer. A higher value in this field represent a more reliable check, but also a slower one.
`quit_on_first`	Stop listening for responses at first response.	`false`	`true`

monitoring → discoveries → icmp

Field name	Description	Example values	Default value
`count`	Number of requests to send. If `flood` is enabled, it represents the number of responses to receive before returning.	`4`	`1`
`timeout`	Maximum amount of time in which to wait for a response (in seconds). Must be a positive integer. A higher value in this field represent a more reliable check, but also a slower one.	`1`	`4`
`flood`	Enable/disable flood ping mode.	`false`	`true`
`enable`	Enable/disable discovery method.	`false`	`true`

monitoring → discoveries → syn

Field name	Description	Example values	Default value
`ports`	Ports to check. Must be of string type.	`'80'`	`'2'`
`timeout`	Maximum amount of time in which to wait for a response (in seconds). Must be a positive integer. A higher value in this field represent a more reliable check, but also a slower one.	`1`	`4`
`enable`	Enable/disable discovery method.	`false`	`true`

frontends

Field name	Description	Example values	Default value
`host`	IP address for the frontends socket.	`192.168.1.10`	`localhost`
`port`	Port number for the frontends socket.	`2000`	`1984`
`maximum_port_lookup`	Maximum number of times tBB will look for the next available port if the previous one is busy.	`1`	`20`
`ssl`	Section dedicated to securing communications with SSL/TLS.	is section, see below	...

frontends → ssl

Field name	Description	Example values	Default value
`enable`	Enable/disable SSL encryption. tBB will fall back to HTTP communication.	`false`	`true`
`check_hostname`	Enable/disable certificate checking, must agree with frontends on this field for correct SSL handshake.	`true`	`false`

serialization

Field name	Description	Example values	Default value
`indent`	Number of spaces with which indent the scan storages (json.dump(indent) ext. docs).	`0`	`4`
`do_sort`	Enable/disable sorting of scan storages (json.dump(sort_keys) ext. docs).	`false`	`true`

logging

Field name	Description	Example values	Default value
`default_time_format`	Default format for datetimes in log files. [3]	`'%d-%m-%Y %H.%M.%S'`	`'%Y-%m-%d %H.%M.%S'`
`level`	Minimum logging level. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	`DEBUG`	`INFO`
`formatters`	Section dedicated to loggers formatters.	is section, see below	...
`handlers`	Section dedicated to loggers handlers.	is section, see below	...

logging → formatters

Field name	Description	Example values	Default value
`complete`	Section dedicated to the complete formatter.	is section, see below	...
`brief`	Section dedicated to the brief formatter.	is section, see below	...
`syslog`	Section dedicated to the syslog formatter.	is section, see below	...
`custom_1`	Section dedicated to the custom_1 formatter.	is section, see below	...
`custom_2`	Section dedicated to the custom_2 formatter.	is section, see below	...
`custom_3`	Section dedicated to the custom_3 formatter.	is section, see below	...

logging → formatters → complete/brief/syslog/custom_1/custom_2/custom_3

All formatters share the same configuration skeleton.

Field name	Description	Example values	Default value
`format`	String to format logging upon. [4]	...	...
`datefmt`	String to format datetimes upon. [3] Macro `{default_time_format}` points to `logging` → `default_time_format`.	`'%d-%m-%Y %H.%M.%S'`	`{default_time_format}`

logging → handlers

Field name	Description	Example values	Default value
`console`	Section dedicated to the complete handler.	is section, see below	...
`syslog`	Section dedicated to the syslog handler.	is section, see below	...
`file`	Section dedicated to the file handler.	is section, see below	...
`enable`	List of enabled logging handlers: handlers found in this list will be triggered when logging.	`[]`	`['console', 'file']`

logging → handlers → console

Field name	Description	Example values	Default value
`level`	Minimum logging level for this handler. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	`DEBUG`	`INFO`
`formatter`	Formatter chosen for this handler, as defined in `logging` → `formatters`.	`custom_1`	`brief`

logging → handlers → syslog

Field name	Description	Example values	Default value
`level`	Minimum logging level for this handler. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	`DEBUG`	`INFO`
`formatter`	Formatter chosen for this handler, as defined in `logging` → `formatters`.	`custom_2`	`syslog`
`address`	Section dedicated to the syslog host address.	is section, see below	...
`socktype`	ISO/OSI level 4 protocol chosen by the syslog server. One of UDP: `DATAGRAM`, TCP: `STREAM`.	`STREAM`	`DATAGRAM`

logging → handlers → syslog → address

Field name	Description	Example values	Default value
`ip`	Syslog host IP.	`'192.168.100.20'`	`''`
`port`	Syslog server port.	`514`	`''`

logging → handlers → file

Field name	Description	Example values	Default value
`level`	Minimum logging level for this handler. One of `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.	`WARNING`	`DEBUG`
`formatter`	Formatter chosen for this handler, as defined in `logging` → `formatters`.	`syslog`	`complete`
`max_bytes`	Maximum size for log file (in bytes).	`1000`	`10000000` (`10 MB`)
`backup_count`	Maximum number of log files (of at most `max_bytes` size) to keep.	`1`	`4`
`filename`	Log file name.	`definetelynota logfile.log`	`tBB.log`

[1]	Determined by Tracker.highest_priority_host.

[2]	See Tracker.keep_network_tracked for further details.

[3]	(1, 2) Python logging library date format documentation https://docs.python.org/3/library/logging.html#logging.Formatter.formatTime

[4]	Python logging library log records documentation https://docs.python.org/3/library/logging.html#logrecord-attributes

Configuring tBB¶

How configuration works in tBB¶

Network-specific configuration files naming conventions¶

Examples¶

Configuration fields¶

Table Of Contents

Related Topics

This Page