Full tBB reference¶
This section of tBB documentation is dedicated to documenting the internals of tBB.
tBB.async_stdio module¶
tBB.builtin_configuration module¶
tBB’s builtin configuration.
This is what tBB will fall back to if the user doesn’t specify differently.
tBB.discoveries module¶
Discovery methods implementations.
Library asyncio.subprocess
is used to implement these methods.
-
class
tBB.discoveries.
ARPDiscovery
(count, interface, timeout, quit_on_first=True, enabled=True)[source]¶ Bases:
tBB.discoveries.DiscoveryMethod
ARP discovery method. Uses system’s
arping
to perform requests.
-
class
tBB.discoveries.
DiscoveryMethod
(short_name, enabled=True)[source]¶ Bases:
object
Base-abstract class for all discovery methods.
-
class
tBB.discoveries.
ICMPDiscovery
(count, timeout, flood=False, enabled=True)[source]¶ Bases:
tBB.discoveries.DiscoveryMethod
ICMP discovery method. Uses system’s
ping
to perform requests.
-
class
tBB.discoveries.
SYNDiscovery
(ports, timeout, enabled=True)[source]¶ Bases:
tBB.discoveries.DiscoveryMethod
SYN discovery method. Uses system’s
nc
to perform requests.
tBB.frontends module¶
This module helps handling tBB front-ends.
-
class
tBB.frontends.
FrontendsHandler
(tracker, password, config, loop=None)[source]¶ Bases:
object
tBB.net_elements module¶
Network elements representations for Python.
-
class
tBB.net_elements.
IPElement
(*args, **kwargs)[source]¶ Bases:
object
IP node object representation for Python. This object responds to the following interfaces:
- addition (and subtraction)
- equality (and inequality)
- hashable
-
ip
¶
-
is_broadcast
()[source]¶ Returns
True
ifself.ip
is a broadcast IP in accordance toself.mask
.Returns: bool
-
is_network
()[source]¶ Returns
True
ifself.ip
is a network IP in accordance toself.mask
.Returns: bool
-
mask
¶
-
static
parse_ip
(string)[source]¶ Parses a string and checks if it is a valid IP.
Returns: string, list
-
class
tBB.net_elements.
IPHost
(ip)[source]¶ Bases:
object
-
ago
¶
-
ip
¶
-
is_up
¶
-
last_discovery_method
¶
-
mac
¶
-
name
¶
-
second_last_mac
¶
-
second_last_name
¶
-
-
class
tBB.net_elements.
Network
(*args, **kwargs)[source]¶ Bases:
tBB.net_elements.IPElement
IP network object representation for Python. This object responds to the following interfaces (inherited from IPElement):
- addition (and subtraction)
- equality (and inequality)
- hashable
- In addition, also responds to the following:
- iterable
- sliceable
-
ip
¶
tBB.paths module¶
This module contains various utilities for finding correct paths for tBB.
tBB.serialization module¶
Serialization module for tBB.
tBB.settings module¶
This module takes care of representing and handling settings throughout tBB.
-
exception
tBB.settings.
InconsistentSettingTypeException
(setting_path, should_be, got)[source]¶ Bases:
Exception
tBB.tracker module¶
Tracker implementation.
-
class
tBB.tracker.
Tracker
(network)[source]¶ Bases:
object
-
changes
(hosts, from_, to, json_compatible=False)[source]¶ This function returns changes occurred to given hosts within the given time period. If argument json_compatible evaluates to True, in the returned dict there will be no objects as defined in net_elements. Instead they will be converted into builtin types as follows:
IPElement("192.168.0.0/24") -> "192.168.0.0" # str
MACElement("a0:ff:e4:bc:66:70") -> "a0:ff:e4:bc:66:70" # str
datetime() -> datetime().timestamp() # float
The returned dict will be in the following form:
{ IPElement("...") : { 'discovery_history': { datetime(...): 'icmp', # or 'syn' ... }, 'is_up_history': { datetime(...): True, # or False ... }, 'mac_history': { datetime(...): MACElement("..."), ... } }, MACElement("..."): { 'history': { datetime(...): [IPElement("..."), ...], ... } 'is_up_history': { datetime(...): True, # or False ... } } IPElement("..."): { ... }, ... }
Since this function may do some heavy calculations and therefore block, it had been designed to be a coroutine, in order to prevent blocking. For filtering results to
IPHosts
only orMACHosts
only, seeTracker.ip_changes
andTracker.mac_changes
.Parameters: - hosts – IPHost,MACHost[]
- from – datetime.datetime
- to – datetime.datetime
- json_compatible – bool
Returns: dict
-
do_complete_network_scan
()[source]¶ Runs complete network scan. Similarly to
Track.do_partial_scan
, this does not useself.highest_priority_host
internally; iterates overself.network
instead.
-
do_partial_scan
(start, hosts)[source]¶ Runs partial scan of the network. Starting from argument start for so many hosts as defined in argument
hosts
. Similarly toTrack.do_complete_network_scan
, this does not use self.highest_priority_host internally; iterates overself.network
instead.Parameters: - start (int) – integer to add to
self.network
to get first ip to scan. - hosts (int) – number of ips to scan.
Returns: number of up hosts
Return type: int
- start (int) – integer to add to
-
do_single_scan
(ip)[source]¶ Runs a scan to the specified ip. Uses discovery methods found in
self.discoveries
. You can enable/disable each one of them by settingself.discoveries[x].enable
to whatever suits you. This function takes care of detecting whether the host changed its status and if so it callsself.fire_notifiers
. If one discovery method results positive others won’t be run. Returns whether or not the host was found to be up.Note
in order to provide the mac address of the scanning host, ARP will be run even if it had been disabled, but it won’t be tracked as the discovery method used when executed for this purpose.
Parameters: ip (IPElement()) – ip to scan. Return type: bool
-
highest_priority_host
()[source]¶ Returns the host that has the highest priority in this moment. The calculation is made so that there can be no hosts with the same priority. It takes in account per-host set priorities in self.priorities. The calculation is done as follows:
priority = host_priority + time_since_last_check|IP
As shown, the IP added at the end prevents two hosts from having the same priority. Seen how the calculation is performed, priorities set in self.priorities should consider that if, for instance, the priority for host A is set to 10, every call within 10 seconds since last scan will return host A.
Return type: IPElement
-
ip_changes
(hosts, from_, to, json_compatible=False)[source]¶ Similar to
Tracker.changes
, but only iterates overIPHosts
.
-
keep_network_tracked
(initial_sleep=0)[source]¶ Keeps the given network (
self.network
) tracked. Differently fromTracker.do_complete_network_scan
andTracker.do_partial_scan
, this function doesn’t iterate overself.network
to keep it tracked. Instead it callsself.highest_priority_host
each time it has to scan a new host. Again, differently fromTracker.do_complete_network_scan
andTracker.do_partial_scan
, this function implements a sleeping mechanisms between scans in order to reduce its weight on the network. The time it takes for sleeping can be set usingTrack.time_between_scans
andTrack. maximum_seconds_randomly_added
, calculated as follows:sleep = time_between_scans + randint(0, maximum_seconds_randomly_added)
randint being the
random.randint
function included in the Python’s standard library.
-
mac_changes
(hosts, from_, to, json_compatible=False)[source]¶ Similar to
Tracker.changes
, but only iterates overMACHosts
.
-
name_changes
(hosts, from_, to, json_compatible=False)[source]¶ Similar to
Tracker.changes
, but only iterates overNameHosts
.
-
outer_status
¶ Used to supply information to front-ends.
-
status
¶ Used to supply information to front-ends.
-
up_hosts
¶ Number of IP hosts currently up.
-
up_ip_hosts
¶ IPHosts currently up. Result is a dictionary
{IPElement: IPHost}
.Return type: dict[IPElement, IPHost]
-
up_mac_hosts
¶ MACHost``s currently up. Result is a dictionary ``{MACElement: MACHost}
. Determining how a MACHost is up is a little bit different from an IPHost. Since a MACHost doesn’t hold any up state, a MACHost is considered up when any of the IPHosts related to it (found inMACHost.ip
) is up. Therefore even if only one of the (possibly) many IPHosts is up, the MACHost is considered up.Return type: dict[MACElement: MACHost]
-
up_name_hosts
¶ Similar to
Tracker.up_mac_hosts
.
-
-
class
tBB.tracker.
TrackersHandler
(network, hosts=16)[source]¶ Bases:
object
This is capable of handling different
Tracker
instances at the same time. For methods and attributes documentation you may refer toTracker
‘s documentation, since this class mimics most of its behaviour. Please, note that this is not a subclass ofTracker
, though. In most casesTracker
‘s attributes are mapped to properties in order to provide the attributes of allTracker
s this object is currently handling. Usually, setting one of these properties reflects the change to allTracker
s objects currently handled.-
arp
¶
-
auto_ignore_broadcasts
¶
-
discoveries
¶
-
force_notify
¶
-
ignore
¶
-
ignore_mac
¶
-
ignore_name
¶
-
ip_hosts
¶
-
maximum_seconds_randomly_added
¶
-
name_discovery
¶
-
outer_status
¶
-
priorities
¶
-
serializer
¶
-
status
¶
-
time_between_checks
¶
-
up_hosts
¶
-
up_ip_hosts
¶
-
up_mac_hosts
¶
-
up_name_hosts
¶
-
warn_parsing_exception
¶
-
Module contents¶
tBB - The Big Brother.
An open-source Intrusion Detection System written in Python: keeps track of connections, disconnections and changes in the specified network.
For further information open tBB/docs/
.