base/frameworks/software/main.bro

Software

This script provides the framework for software version detection and parsing but doesn’t actually do any detection on it’s own. It relies on other protocol specific scripts to parse out software from the protocols that they analyze. The entry point for providing new software detections to this framework is through the Software::found function.

Namespace:Software
Imports:base/utils/directions-and-hosts.bro, base/utils/numbers.bro
Source File:/scripts/base/frameworks/software/main.bro

Summary

Options

Software::asset_tracking: Host &redef Hosts whose software should be detected and tracked.

State Variables

Software::tracked: table &create_expire = 1.0 day &synchronized &redef The set of software associated with an address.

Types

Software::Info: record The record type that is used for representing and logging software.
Software::SoftwareSet: table Type to represent a collection of Software::Info records.
Software::Type: enum Scripts detecting new types of software need to redef this enum to add their own specific software types which would then be used when they create Software::Info records.
Software::Version: record &log A structure to represent the numeric version of software.

Redefinitions

Log::ID: enum The software logging stream identifier.

Events

Software::log_software: event This event can be handled to access the Software::Info record as it is sent on to the logging framework.

Functions

Software::cmp_versions: function Compare two version records.
Software::found: function Other scripts should call this function when they detect software.

Detailed Interface

Options

Software::asset_tracking
Type:Host
Attributes:&redef
Default:ALL_HOSTS

Hosts whose software should be detected and tracked. Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.

State Variables

Software::tracked
Type:table [addr] of Software::SoftwareSet
Attributes:&create_expire = 1.0 day &synchronized &redef
Default:{}

The set of software associated with an address. Data expires from this table after one day by default so that a detected piece of software will be logged once each day.

Types

Software::Info
Type:

record

ts: time &log &optional

The time at which the software was detected.

host: addr &log

The IP address detected running the software.

host_p: port &log &optional

The port on which the software is running. Only sensible for server software.

software_type: Software::Type &log &default = Software::UNKNOWN &optional

The type of software detected (e.g. HTTP::SERVER).

name: string &log &optional

Name of the software (e.g. Apache).

version: Software::Version &log &optional

Version of the software.

unparsed_version: string &log &optional

The full unparsed version string found because the version parsing doesn’t always work reliably in all cases and this acts as a fallback in the logs.

force_log: bool &default = F &optional

This can indicate that this software being detected should definitely be sent onward to the logging framework. By default, only software that is “interesting” due to a change in version or it being currently unknown is sent to the logging framework. This can be set to T to force the record to be sent to the logging framework if some amount of this tracking needs to happen in a specific way to the software.

url: string &optional &log

(present if policy/protocols/http/detect-webapps.bro is loaded)

Most root URL where the software was discovered.

The record type that is used for representing and logging software.

Software::SoftwareSet
Type:table [string] of Software::Info

Type to represent a collection of Software::Info records. It’s indexed with the name of a piece of software such as “Firefox” and it yields a Software::Info record with more information about the software.

Software::Type
Type:

enum

Software::UNKNOWN

A placeholder type for when the type of software is not known.

OS::WINDOWS

(present if policy/frameworks/software/windows-version-detection.bro is loaded)

Identifier for Windows operating system versions

FTP::CLIENT

(present if policy/protocols/ftp/software.bro is loaded)

Identifier for FTP clients in the software framework.

FTP::SERVER

(present if policy/protocols/ftp/software.bro is loaded)

Not currently implemented.

HTTP::WEB_APPLICATION

(present if policy/protocols/http/detect-webapps.bro is loaded)

Identifier for web applications in the software framework.

HTTP::BROWSER_PLUGIN

(present if policy/protocols/http/software-browser-plugins.bro is loaded)

Identifier for browser plugins in the software framework.

HTTP::SERVER

(present if policy/protocols/http/software.bro is loaded)

Identifier for web servers in the software framework.

HTTP::APPSERVER

(present if policy/protocols/http/software.bro is loaded)

Identifier for app servers in the software framework.

HTTP::BROWSER

(present if policy/protocols/http/software.bro is loaded)

Identifier for web browsers in the software framework.

MySQL::SERVER

(present if policy/protocols/mysql/software.bro is loaded)

Identifier for MySQL servers in the software framework.

SMTP::MAIL_CLIENT

(present if policy/protocols/smtp/software.bro is loaded)

SMTP::MAIL_SERVER

(present if policy/protocols/smtp/software.bro is loaded)

SMTP::WEBMAIL_SERVER

(present if policy/protocols/smtp/software.bro is loaded)

SSH::SERVER

(present if policy/protocols/ssh/software.bro is loaded)

Identifier for SSH clients in the software framework.

SSH::CLIENT

(present if policy/protocols/ssh/software.bro is loaded)

Identifier for SSH servers in the software framework.

Scripts detecting new types of software need to redef this enum to add their own specific software types which would then be used when they create Software::Info records.

Software::Version
Type:

record

major: count &optional &log

Major version number.

minor: count &optional &log

Minor version number.

minor2: count &optional &log

Minor subversion number.

minor3: count &optional &log

Minor updates number.

addl: string &optional &log

Additional version string (e.g. “beta42”).

Attributes:

&log

A structure to represent the numeric version of software.

Events

Software::log_software
Type:event (rec: Software::Info)

This event can be handled to access the Software::Info record as it is sent on to the logging framework.

Functions

Software::cmp_versions
Type:function (v1: Software::Version, v2: Software::Version) : int

Compare two version records.

Returns:-1 for v1 < v2, 0 for v1 == v2, 1 for v1 > v2. If the numerical version numbers match, the addl string is compared lexicographically.
Software::found
Type:function (id: conn_id, info: Software::Info) : bool

Other scripts should call this function when they detect software.

Id:The connection id where the software was discovered.
Info:A record representing the software discovered.
Returns:T if the software was logged, F otherwise.
Copyright 2016, The Bro Project. Last updated on October 17, 2017. Created using Sphinx 1.5.2.