base/frameworks/intel/main.bro

Intel

The intelligence framework provides a way to store and query IP addresses, and strings (with a str_type). Metadata can also be associated with the intelligence, like for making more informed decisions about matching and handling of intelligence.

Namespace:Intel
Imports:base/frameworks/notice
Source File:/scripts/base/frameworks/intel/main.bro

Summary

Types

Intel::Info: record Record used for the logging framework representing a positive hit within the intelligence framework.
Intel::Item: record Represents a piece of intelligence.
Intel::MetaData: record Data about an Intel::Item.
Intel::Seen: record Information about a piece of “seen” data.
Intel::Type: enum Enum type to represent various types of intelligence data.
Intel::Where: enum Enum to represent where data came from when it was discovered.

Redefinitions

Log::ID: enum  

Events

Intel::log_intel: event  
Intel::match: event Event to represent a match in the intelligence data from data that was seen.

Functions

Intel::insert: function Intelligence data manipulation function.
Intel::seen: function Function to declare discovery of a piece of data in order to check it against known intelligence for matches.

Detailed Interface

Types

Intel::Info
Type:

record

ts: time &log

Timestamp when the data was discovered.

uid: string &log &optional

If a connection was associated with this intelligence hit, this is the uid for the connection

id: conn_id &log &optional

If a connection was associated with this intelligence hit, this is the conn_id for the connection.

fuid: string &log &optional

If a file was associated with this intelligence hit, this is the uid for the file.

file_mime_type: string &log &optional

A mime type if the intelligence hit is related to a file. If the $f field is provided this will be automatically filled out.

file_desc: string &log &optional

Frequently files can be “described” to give a bit more context. If the $f field is provided this field will be automatically filled out.

seen: Intel::Seen &log

Where the data was seen.

sources: set [string] &log &default = {  } &optional

Sources which supplied data that resulted in this match.

Record used for the logging framework representing a positive hit within the intelligence framework.

Intel::Item
Type:

record

indicator: string

The intelligence indicator.

indicator_type: Intel::Type

The type of data that the indicator field represents.

meta: Intel::MetaData

Metadata for the item. Typically represents more deeply descriptive data for a piece of intelligence.

Represents a piece of intelligence.

Intel::MetaData
Type:

record

source: string

An arbitrary string value representing the data source. Typically, the convention for this field will be the source name and feed name separated by a hyphen. For example: “source1-c&c”.

desc: string &optional

A freeform description for the data.

url: string &optional

A URL for more information about the data.

do_notice: bool &default = F &optional

(present if policy/frameworks/intel/do_notice.bro is loaded)

A boolean value to allow the data itself to represent if the indicator that this metadata is attached to is notice worthy.

if_in: Intel::Where &optional

(present if policy/frameworks/intel/do_notice.bro is loaded)

Restrictions on when notices are created to only create them if the do_notice field is T and the notice was seen in the indicated location.

cif_impact: string &optional

(present if policy/integration/collective-intel/main.bro is loaded)

Maps to the Impact field in the Collective Intelligence Framework.

cif_severity: string &optional

(present if policy/integration/collective-intel/main.bro is loaded)

Maps to the Severity field in the Collective Intelligence Framework.

cif_confidence: double &optional

(present if policy/integration/collective-intel/main.bro is loaded)

Maps to the Confidence field in the Collective Intelligence Framework.

Data about an Intel::Item.

Intel::Seen
Type:

record

indicator: string &log &optional

The string if the data is about a string.

indicator_type: Intel::Type &log &optional

The type of data that the indicator represents.

host: addr &optional

If the indicator type was Intel::ADDR, then this field will be present.

where: Intel::Where &log

Where the data was discovered.

node: string &optional &log

The name of the node where the match was discovered.

conn: connection &optional

If the data was discovered within a connection, the connection record should go here to give context to the data.

f: fa_file &optional

If the data was discovered within a file, the file record should go here to provide context to the data.

Information about a piece of “seen” data.

Intel::Type
Type:

enum

Intel::ADDR

An IP address.

Intel::URL

A complete URL without the prefix "http://".

Intel::SOFTWARE

Software name.

Intel::EMAIL

Email address.

Intel::DOMAIN

DNS domain name.

Intel::USER_NAME

A user name.

Intel::FILE_HASH

File hash which is non-hash type specific. It’s up to the user to query for any relevant hash types.

Intel::FILE_NAME

File name. Typically with protocols with definite indications of a file name.

Intel::CERT_HASH

Certificate SHA-1 hash.

Intel::PUBKEY_HASH

Public key MD5 hash. (SSH server host keys are a good example.)

Enum type to represent various types of intelligence data.

Intel::Where
Type:

enum

Intel::IN_ANYWHERE

A catchall value to represent data of unknown provenance.

Conn::IN_ORIG

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

Conn::IN_RESP

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

Files::IN_HASH

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

Files::IN_NAME

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

DNS::IN_REQUEST

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

DNS::IN_RESPONSE

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

HTTP::IN_HOST_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

HTTP::IN_REFERRER_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

HTTP::IN_USER_AGENT_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

HTTP::IN_X_FORWARDED_FOR_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

HTTP::IN_URL

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_MAIL_FROM

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_RCPT_TO

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_FROM

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_TO

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_RECEIVED_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_REPLY_TO

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_X_ORIGINATING_IP_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_MESSAGE

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SSH::IN_SERVER_HOST_KEY

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SSL::IN_SERVER_NAME

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SMTP::IN_HEADER

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

X509::IN_CERT

(present if policy/frameworks/intel/seen/where-locations.bro is loaded)

SSH::SUCCESSFUL_LOGIN

(present if policy/protocols/ssh/detect-bruteforcing.bro is loaded)

An indicator of the login for the intel framework.

Enum to represent where data came from when it was discovered. The convention is to prefix the name with IN_.

Events

Intel::log_intel
Type:event (rec: Intel::Info)
Intel::match
Type:event (s: Intel::Seen, items: set [Intel::Item])

Event to represent a match in the intelligence data from data that was seen. On clusters there is no assurance as to where this event will be generated so do not assume that arbitrary global state beyond the given data will be available.

This is the primary mechanism where a user will take actions based on data within the intelligence framework.

Functions

Intel::insert
Type:function (item: Intel::Item) : void

Intelligence data manipulation function.

Intel::seen
Type:function (s: Intel::Seen) : void

Function to declare discovery of a piece of data in order to check it against known intelligence for matches.

Copyright 2013, The Bro Project. Last updated on July 19, 2016. Created using Sphinx 1.4.4.