main.zeek

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/frameworks/cluster, base/utils/directions-and-hosts.zeek, base/utils/numbers.zeek

Summary

Runtime Options

Software::asset_tracking: Host &redef

Hosts whose software should be detected and tracked.

Redefinable Options

`Software::found_cache_interval`: `interval` `&redef`	The framework maintains a redundancy cache in each worker that deduplicates their version reporting in `Software::found`.
`Software::max_software_cache_size`: `count` `&redef`	For each software, each proxy maintains a per-host deduplication cache of known versions that refreshes daily.
`Software::parse_cache_interval`: `interval` `&redef`	The framework maintains per-node caches that map unparsed version strings to `Software::Version` instances.

State Variables

`Software::alternate_names`: `table` `&default` = `function`	Sometimes software will expose itself on the network with slight naming variations.
`Software::tracked`: `table` `&create_expire` = `1.0 day` `&deprecated` = …
`Software::tracked_software`: `table` `&create_expire` = `1.0 day`	The set of software associated with an address.

Types

`Software::Info`: `record`	The record type that is used for representing and logging software.
`Software::Set`: `record`	Type to represent a set of software versions of the same name, tracking the most recent version explicitly.
`Software::SoftwareSet`: `table` `&deprecated` = …
`Software::SoftwareSets`: `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.

Software::LOG

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.
`Software::register`: `event`	This event is raised when software is about to be registered for tracking in `Software::tracked_software`.
`Software::version_change`: `event`	This event can be handled to access software information whenever it’s version is found to have changed.

Hooks

Software::log_policy: Log::PolicyHook

A default logging policy hook for the stream.

Functions

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

Detailed Interface

Runtime Options

Software::asset_tracking 

Type:

Host

Attributes:

&redef

Default:

LOCAL_HOSTS

Redefinition:

from policy/tuning/track-all-assets.zeek

=:

``ALL_HOSTS``

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

Redefinable Options

Software::found_cache_interval 

Type:: interval
Attributes:: &redef
Default:: 10.0 mins

The framework maintains a redundancy cache in each worker that deduplicates their version reporting in Software::found. This is its expiration interval. Setting to 0secs disables this cache.

Software::max_software_cache_size 

Type:: count
Attributes:: &redef
Default:: 20

For each software, each proxy maintains a per-host deduplication cache of known versions that refreshes daily. This setting caps the size of each of these caches. Exceeding the cap leads to a reset of the cache, and to redundant software.log writes. 0 disables the cap.

Software::parse_cache_interval 

Type:: interval
Attributes:: &redef
Default:: 1.0 min 5.0 secs

The framework maintains per-node caches that map unparsed version strings to Software::Version instances. This is its expiration interval.

State Variables

Software::alternate_names 

Type:

table [string] of string

Attributes:

&default = function

Default:

{
   ["Flash Player"] = "Flash"
}

Sometimes software will expose itself on the network with slight naming variations. This table provides a mechanism for a piece of software to be renamed to a single name even if it exposes itself with an alternate name. The yielded string is the name that will be logged and generally used for everything.

Software::tracked 

Type:: table [addr] of Software::SoftwareSet
Attributes:: &create_expire = 1.0 day &deprecated = “Remove in v9.1. Unused. Use tracked_software instead.”
Default:: {}

Software::tracked_software 

Type:: table [addr] of Software::SoftwareSets
Attributes:: &create_expire = 1.0 day
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. In a cluster, this table is uniformly distributed among proxy nodes.

Types

Software::Info 

Type:

record

Fields:

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.zeek is loaded)

Most root URL where the software was discovered.

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

Software::Set 

Type:

record

Fields:

versions: set [string]: Set of version strings, unparsed when available (for full detail) or based on a Software::Version record.

last: Software::Info &optional: The most recent software info record for this set.

Type to represent a set of software versions of the same name, tracking the most recent version explicitly.

Software::SoftwareSet 

Type:: table [string] of Software::Info
Attributes:: &deprecated = “Remove in v9.1. Use SoftwareSets instead.”

Software::SoftwareSets 

Type:: table [string] of Software::Set

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::Set with specific versions of 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.zeek is loaded)

Identifier for Windows operating system versions

DHCP::SERVER

(present if policy/protocols/dhcp/software.zeek is loaded)

Identifier for web servers in the software framework.

DHCP::CLIENT

(present if policy/protocols/dhcp/software.zeek is loaded)

Identifier for web browsers in the software framework.

FTP::CLIENT

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

Identifier for FTP clients in the software framework.

FTP::SERVER

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

Not currently implemented.

HTTP::WEB_APPLICATION

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

Identifier for web applications in the software framework.

HTTP::BROWSER_PLUGIN

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

Identifier for browser plugins in the software framework.

HTTP::SERVER

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

Identifier for web servers in the software framework.

HTTP::APPSERVER

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

Identifier for app servers in the software framework.

HTTP::BROWSER

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

Identifier for web browsers in the software framework.

MySQL::SERVER

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

Identifier for MySQL servers in the software framework.

SMTP::MAIL_CLIENT: (present if policy/protocols/smtp/software.zeek is loaded)

SMTP::MAIL_SERVER: (present if policy/protocols/smtp/software.zeek is loaded)

SMTP::WEBMAIL_SERVER: (present if policy/protocols/smtp/software.zeek is loaded)

SSH::SERVER

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

Identifier for SSH clients in the software framework.

SSH::CLIENT

(present if policy/protocols/ssh/software.zeek 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

Fields: