diff --git a/scripts/base/protocols/ssl/consts.bro b/scripts/base/protocols/ssl/consts.bro index b0656eab58..1568ff17d3 100644 --- a/scripts/base/protocols/ssl/consts.bro +++ b/scripts/base/protocols/ssl/consts.bro @@ -1,23 +1,27 @@ module SSL; export { - const SSLv2 = 0x0002; const SSLv3 = 0x0300; const TLSv10 = 0x0301; const TLSv11 = 0x0302; + ## Mapping between the constants and string values for SSL/TLS versions. const version_strings: table[count] of string = { [SSLv2] = "SSLv2", [SSLv3] = "SSLv3", [TLSv10] = "TLSv10", [TLSv11] = "TLSv11", } &default="UNKNOWN"; - + + ## Mapping between numeric codes and human readable strings for alert + ## levels. const alert_levels: table[count] of string = { [1] = "warning", [2] = "fatal", } &default=function(i: count):string { return fmt("unknown-%d", i); }; - + + ## Mapping between numeric codes and human readable strings for alert + ## descriptions.. const alert_descriptions: table[count] of string = { [0] = "close_notify", [10] = "unexpected_message", @@ -50,8 +54,11 @@ export { [114] = "bad_certificate_hash_value", [115] = "unknown_psk_identity", } &default=function(i: count):string { return fmt("unknown-%d", i); }; - - # http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml + + ## Mapping between numeric codes and human readable strings for SSL/TLS + ## extensions. + ## ..note: More information can be found here: + ## http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xml const extensions: table[count] of string = { [0] = "server_name", [1] = "max_fragment_length", @@ -299,11 +306,10 @@ export { const SSL_RSA_WITH_DES_CBC_MD5 = 0xFF82; const SSL_RSA_WITH_3DES_EDE_CBC_MD5 = 0xFF83; const TLS_EMPTY_RENEGOTIATION_INFO_SCSV = 0x00FF; - - # --- This is a table of all known cipher specs. - # --- It can be used for detecting unknown ciphers and for - # --- converting the cipher spec constants into a human readable format. - + + ## This is a table of all known cipher specs. It can be used for + ## detecting unknown ciphers and for converting the cipher spec constants + ## into a human readable format. const cipher_desc: table[count] of string = { # --- sslv20 --- [SSLv20_CK_RC4_128_EXPORT40_WITH_MD5] = @@ -530,7 +536,8 @@ export { [SSL_RSA_FIPS_WITH_DES_CBC_SHA_2] = "SSL_RSA_FIPS_WITH_DES_CBC_SHA_2", [SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA_2] = "SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA_2", } &default="UNKNOWN"; - + + ## Mapping between the constants and string values for SSL/TLS errors. const x509_errors: table[count] of string = { [0] = "ok", [1] = "unable to get issuer cert", diff --git a/scripts/base/protocols/ssl/main.bro b/scripts/base/protocols/ssl/main.bro index 4c6721fcd8..0b280a6bcf 100644 --- a/scripts/base/protocols/ssl/main.bro +++ b/scripts/base/protocols/ssl/main.bro @@ -1,4 +1,5 @@ -##! Base SSL analysis script. +##! Base SSL analysis script. This script logs information about the SSL/TLS +##! handshaking and encryption establishment process. @load ./consts @@ -12,44 +13,53 @@ export { ts: time &log; uid: string &log; id: conn_id &log; + ## SSL/TLS version the server offered. version: string &log &optional; + ## SSL/TLS cipher suite the server chose. cipher: string &log &optional; + ## Value of the Server Name Indicator SSL/TLS extension. It + ## indicates the server name that the client was requesting. server_name: string &log &optional; + ## Session ID offered by the client for session resumption. session_id: string &log &optional; + ## Subject of the X.509 certificate offered by the server. subject: string &log &optional; + ## NotValidBefore field value from the server certificate. not_valid_before: time &log &optional; + ## NotValidAfter field value from the serve certificate. not_valid_after: time &log &optional; + ## Last alert that was seen during the connection. last_alert: string &log &optional; - + + ## Full binary server certificate stored in DER format. cert: string &optional; + ## Chain of certificates offered by the server to validate its + ## complete signing chain. cert_chain: vector of string &optional; - ## This stores the analyzer id used for the analyzer instance attached + ## The analyzer ID used for the analyzer instance attached ## to each connection. It is not used for logging since it's a ## meaningless arbitrary number. analyzer_id: count &optional; }; - - ## This is where the default root CA bundle is defined. By loading the + + ## The default root CA bundle. By loading the ## mozilla-ca-list.bro script it will be set to Mozilla's root CA list. const root_certs: table[string] of string = {} &redef; - + ## If true, detach the SSL analyzer from the connection to prevent ## continuing to process encrypted traffic. Helps with performance ## (especially with large file transfers). const disable_analyzer_after_detection = T &redef; - + ## The openssl command line utility. If it's in the path the default ## value will work, otherwise a full path string can be supplied for the ## utility. const openssl_util = "openssl" &redef; - + + ## Event that can be handled to access the SSL + ## record as it is sent on to the logging framework. global log_ssl: event(rec: Info); - - const ports = { - 443/tcp, 563/tcp, 585/tcp, 614/tcp, 636/tcp, - 989/tcp, 990/tcp, 992/tcp, 993/tcp, 995/tcp, 5223/tcp - } &redef; } redef record connection += { @@ -76,6 +86,11 @@ redef capture_filters += { ["xmpps"] = "tcp port 5223", }; +const ports = { + 443/tcp, 563/tcp, 585/tcp, 614/tcp, 636/tcp, + 989/tcp, 990/tcp, 992/tcp, 993/tcp, 995/tcp, 5223/tcp +}; + redef dpd_config += { [[ANALYZER_SSL]] = [$ports = ports] }; diff --git a/scripts/base/protocols/syslog/consts.bro b/scripts/base/protocols/syslog/consts.bro index f08e7f71d7..dce1877ecf 100644 --- a/scripts/base/protocols/syslog/consts.bro +++ b/scripts/base/protocols/syslog/consts.bro @@ -1,6 +1,9 @@ +##! Constants definitions for syslog. + module Syslog; export { + ## Mapping between the constants and string values for syslog facilities. const facility_codes: table[count] of string = { [0] = "KERN", [1] = "USER", @@ -27,7 +30,8 @@ export { [22] = "LOCAL6", [23] = "LOCAL7", } &default=function(c: count): string { return fmt("?-%d", c); }; - + + ## Mapping between the constants and string values for syslog severities. const severity_codes: table[count] of string = { [0] = "EMERG", [1] = "ALERT", diff --git a/scripts/base/protocols/syslog/main.bro b/scripts/base/protocols/syslog/main.bro index f4afa6d34d..79f89d5e71 100644 --- a/scripts/base/protocols/syslog/main.bro +++ b/scripts/base/protocols/syslog/main.bro @@ -1,4 +1,5 @@ -##! Core script support for logging syslog messages. +##! Core script support for logging syslog messages. This script represents +##! one syslog message as one logged record. @load ./consts @@ -12,16 +13,19 @@ export { ts: time &log; uid: string &log; id: conn_id &log; + ## Protocol over which the message was seen. proto: transport_proto &log; + ## Syslog facility for the message. facility: string &log; + ## Syslog severity for the message. severity: string &log; + ## The plain text message. message: string &log; }; - - const ports = { 514/udp } &redef; } redef capture_filters += { ["syslog"] = "port 514" }; +const ports = { 514/udp } &redef; redef dpd_config += { [ANALYZER_SYSLOG_BINPAC] = [$ports = ports] }; redef likely_server_ports += { 514/udp }; diff --git a/scripts/policy/protocols/ssl/cert-hash.bro b/scripts/policy/protocols/ssl/cert-hash.bro index 1e47ccac2e..32a165a946 100644 --- a/scripts/policy/protocols/ssl/cert-hash.bro +++ b/scripts/policy/protocols/ssl/cert-hash.bro @@ -1,4 +1,4 @@ -##! This script calculates MD5 sums for server DER formatted certificates. +##! Calculate MD5 sums for server DER formatted certificates. @load base/protocols/ssl @@ -6,6 +6,7 @@ module SSL; export { redef record Info += { + ## MD5 sum of the raw server certificate. cert_hash: string &log &optional; }; } diff --git a/scripts/policy/protocols/ssl/expiring-certs.bro b/scripts/policy/protocols/ssl/expiring-certs.bro index 374065c286..80616e6a99 100644 --- a/scripts/policy/protocols/ssl/expiring-certs.bro +++ b/scripts/policy/protocols/ssl/expiring-certs.bro @@ -1,6 +1,6 @@ -##! This script can be used to generate notices when X.509 certificates over -##! SSL/TLS are expired or going to expire based on the date and time values -##! stored within the certificate. +##! Generate notices when X.509 certificates over SSL/TLS are expired or +##! going to expire soon based on the date and time values stored within the +##! certificate. @load base/protocols/ssl @load base/frameworks/notice @@ -24,7 +24,8 @@ export { ## The category of hosts you would like to be notified about which have ## certificates that are going to be expiring soon. By default, these - ## notices will be suppressed by the notice framework for 1 day. + ## notices will be suppressed by the notice framework for 1 day after + ## a particular certificate has had a notice generated. ## Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS const notify_certs_expiration = LOCAL_HOSTS &redef; diff --git a/scripts/policy/protocols/ssl/extract-certs-pem.bro b/scripts/policy/protocols/ssl/extract-certs-pem.bro index e6a740c215..420c60a4fd 100644 --- a/scripts/policy/protocols/ssl/extract-certs-pem.bro +++ b/scripts/policy/protocols/ssl/extract-certs-pem.bro @@ -2,7 +2,7 @@ ##! after being converted to PEM files. The certificates will be stored in ##! a single file, one for local certificates and one for remote certificates. ##! -##! A couple of things to think about with this script:: +##! ..note:: ##! ##! - It doesn't work well on a cluster because each worker will write its ##! own certificate files and no duplicate checking is done across @@ -20,15 +20,15 @@ module SSL; export { - ## Setting to control if host certificates offered by the defined hosts + ## Control if host certificates offered by the defined hosts ## will be written to the PEM certificates file. ## Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS const extract_certs_pem = LOCAL_HOSTS &redef; } -## This is an internally maintained variable to prevent relogging of -## certificates that have already been seen. It is indexed on an md5 sum of -## the certificate. +# This is an internally maintained variable to prevent relogging of +# certificates that have already been seen. It is indexed on an md5 sum of +# the certificate. global extracted_certs: set[string] = set() &read_expire=1hr &redef; event ssl_established(c: connection) &priority=5 diff --git a/scripts/policy/protocols/ssl/known-certs.bro b/scripts/policy/protocols/ssl/known-certs.bro index 669432e4d9..3986a9aa1e 100644 --- a/scripts/policy/protocols/ssl/known-certs.bro +++ b/scripts/policy/protocols/ssl/known-certs.bro @@ -1,5 +1,4 @@ -##! This script can be used to log information about certificates while -##! attempting to avoid duplicate logging. +##! Log information about certificates while attempting to avoid duplicate logging. @load base/utils/directions-and-hosts @load base/protocols/ssl @@ -36,6 +35,8 @@ export { ## in the set is for storing the DER formatted certificate's MD5 hash. global certs: set[addr, string] &create_expire=1day &synchronized &redef; + ## Event that can be handled to access the loggable record as it is sent + ## on to the logging framework. global log_known_certs: event(rec: CertsInfo); } diff --git a/scripts/policy/protocols/ssl/validate-certs.bro b/scripts/policy/protocols/ssl/validate-certs.bro index 5a663864d2..03624eac84 100644 --- a/scripts/policy/protocols/ssl/validate-certs.bro +++ b/scripts/policy/protocols/ssl/validate-certs.bro @@ -14,8 +14,7 @@ export { }; redef record Info += { - ## This stores and logs the result of certificate validation for - ## this connection. + ## Result of certificate validation for this connection. validation_status: string &log &optional; };