471 lines
22 KiB
Plaintext
471 lines
22 KiB
Plaintext
/**
|
|
* This file is part of Rubanetra.
|
|
* Copyright (C) 2013,2014 Stefan Swerk (stefan_rubanetra@swerk.priv.at)
|
|
*
|
|
* This program is free software: you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation, either version 3 of the License, or
|
|
* (at your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
*/
|
|
/**
|
|
* This file serves as the Rubanetra configuration entry point and will be looked up by the main executable jar.
|
|
* Therefore this file must be either directly available via classpath entry, or the file-path has to be passed via
|
|
* command line argument (for further details refer to the README file).
|
|
*
|
|
* While this file must contain all configuration sections, i.e. 'general', 'protocols', 'input' and 'output'
|
|
* at once, one may prefer to split certain dynamically changing configuration sections into separate and therefore
|
|
* replaceable files. However, please note that the general section must reside in a statically known location to the
|
|
* Rubanetra executable and the paths to the dynamically changed files must be defined in the appropriate sections.
|
|
*
|
|
* Since all configuration files will be parsed by ANTLRv4, the corresponding grammar defining the exact syntax
|
|
* is available in the source archive, see 'src/main/antlr4/.../RubanetraSystemConfiguration.g4'.
|
|
*/
|
|
|
|
/**
|
|
* #########################
|
|
* # General Configuration #
|
|
* #########################
|
|
*/
|
|
general {
|
|
/**
|
|
* Defines the base directory containing the Drools knowledge-base configuration.
|
|
* Currently this directory must contain:
|
|
* - 'META-INF' as subdirectory, containing:
|
|
* ~ 'kmodule.xml', the Drools configuration file, i.e. 'META-INF/kmodule.xml'
|
|
* ~ the subsequent Apache Maven configuration structure, i.e.:
|
|
* + 'maven/at.jku.fim/rubanetra/' sub-directories
|
|
* + 'maven/at.jku.fim/rubanetra/pom.xml' the project's Maven configuration file
|
|
* + 'maven/at.jku.fim/rubanetra/pom.properties' Maven-generated properties
|
|
*
|
|
* If this setting is changed, the default 'META-INF' directory should be removed either from the classpath
|
|
* or directly from the configuration directory (since this directory is by default in the classpath).
|
|
*
|
|
* Default value "./conf", this setting is mandatory.
|
|
*/
|
|
drools_configuration_directory = "./conf";
|
|
|
|
/**
|
|
* Defines the name of the Drools knowledge base to use for the reasoning process.
|
|
* This knowledge base name must be listed in the Drools knowledge base descriptor file 'kmodule.xml'.
|
|
* If this setting is not specified the default knowledge base as specified in the Drools descriptor file will
|
|
* be compiled and used.
|
|
*
|
|
* Default value "DefaultKnowledgeBase", this setting is optional.
|
|
*/
|
|
drools_base_model_name = "DefaultKnowledgeBase";
|
|
|
|
/**
|
|
* Defines the name of the Drools session to use for the reasoning process.
|
|
* This session name must be listed in the Drools knowledge base descriptor file 'kmodule.xml' as session entry
|
|
* under the specified (or the default) 'drools_base_model_name'.
|
|
* If this setting is not specified the default session name as specified in the Drools descriptor file will be
|
|
* used instead.
|
|
*
|
|
* Default value "DefaultSession", this setting is optional.
|
|
*/
|
|
drools_session_model_name = "DefaultSession";
|
|
};
|
|
|
|
/**
|
|
* ##########################
|
|
* # Protocol Configuration #
|
|
* # (Application Layer) #
|
|
* ##########################
|
|
*
|
|
* This section should be filled with application layer specific protocol settings, i.e. underlying lower layer
|
|
* protocol parser bindings and potential port filters, if applicable. The listed application layer parser settings
|
|
* also serve as a vital tool of directing the output generation engine. By default, any parser output below the
|
|
* application layer will be suppressed due to verboseness, however, this behaviour may be overturned by appropriate
|
|
* rule definitions inside the used Knowledge Base. For further information on how to achieve this, please refer to
|
|
* the documentation of Activity#setExcludedFromOutput(boolean).
|
|
* Additional Notes: An application layer parser will only produce output if all of the following conditions are met:
|
|
* - A protocol decoder pipeline has been setup, including all lower layer protocols,
|
|
* e.g.: L2 -> L3 -> L4 -> <application_layer_parser>
|
|
* - The destination port restriction may not be 'None' and has to include the relevant port(s).
|
|
* - The PCAP file actually contains relevant packets applicable to <application_layer_parser> and defined port(s).
|
|
*
|
|
* Furthermore, it is recommended to specify one protocol identifier per application layer protocol parser, however,
|
|
* remember that there must be a 1:1 mapping between a transport layer parser and an application layer parser, therefore
|
|
* the following example will not work:
|
|
* [HTTPandDNSoverTCP]:
|
|
* port = ALL;
|
|
* protocol_binding = Ethernet -> Ipv4;
|
|
* protocol_binding = Ipv4 -> Tcp;
|
|
* protocol_binding = Tcp -> Http;
|
|
* protocol_binding = Tcp -> Dns;
|
|
*
|
|
* In general, the following implementation constraints may be observed:
|
|
* - 1:n mapping between Layer1 (Pcap) and Layer2 (link) parsers
|
|
* - n:m mapping between Layer2 (link) and Layer3 (IP), Layer3 and Layer4 (transport) parsers
|
|
* - 1:1 mapping between Layer4 (transport) and application layer parsers
|
|
*
|
|
* On the other hand, if extremely fine grained control over the actual PCAP data is required, see the BPF setting
|
|
* in the 'input' configuration section.
|
|
*
|
|
* If the Drools knowledge base contains rules that require certain protocol parsers, those parsers must be referenced
|
|
* at least one time in this configuration section. However, rule based parsers must be configured entirely in the
|
|
* Drools rule files.
|
|
*/
|
|
protocols {
|
|
/**
|
|
* If a 'protocol_configuration_file' setting is specified all remaining protocol specific settings will be looked
|
|
* up in the referenced file. This file must exist and be readable for the invoking process.
|
|
* Note, however, that there will be no explicit checks against configuration file dereferencing chains, i.e.
|
|
* it should be ensured that there is no 'protocol_configuration_file' setting in the referenced file again.
|
|
* The referenced file must contain a "protocols {};" section containing the entire protocol specific configuration.
|
|
*
|
|
* This setting is optional, but if it is specified all remaining protocol specific settings in the
|
|
* main configuration file will be ignored.
|
|
*/
|
|
//protocol_configuration_file = "/path/to/protocol.conf";
|
|
|
|
/**
|
|
* An unique protocol id should be defined for each application layer protocol parser that should be used, i.e.
|
|
* by default the name of an application layer protocol should suffice.
|
|
* Syntax: '[ Protocol_ID ]:', where Protocol_ID represents an unique protocol identifier conforming
|
|
* to ([a-zA-Z]+ DIGIT*)+.
|
|
* A number of protocol specific settings may be specified subsequently.
|
|
* This setting may be repeated multiple times for configuring different protocol parsers.
|
|
*
|
|
* Constraints: It is currently not defined what will happen in the case of multiple different protocol ids that
|
|
* contain exactly the same protocol bindings. Consider for instance:
|
|
* [HTTP]: ... as below ...
|
|
* [HTTP1]: ... as [HTTP] ...
|
|
*
|
|
* The rule engine will probably receive double notifications for all HTTP related events in this case and this
|
|
* could lead to severe issues during the reasoning process and the corresponding output (two identical frame numbers
|
|
* for two different parser instances).
|
|
*/
|
|
[HTTP]:
|
|
/**
|
|
* The strategy to use for mapping Kraken's transport layer parsers to the application layer parsers.
|
|
* Currently only the destination port strategy has been implemented, i.e. an application layer parser receives
|
|
* packets that match the specified destination port number(s) defined by the "port" setting.
|
|
*
|
|
* Default value "destination_port", this setting is required.
|
|
*/
|
|
transport_layer_mapping_strategy = destination_port;
|
|
|
|
/**
|
|
* Restricts the transport layer parser (UDP/TCP) to the specified destination ports and/or port-ranges.
|
|
* A similar result could be achieved globally (and more efficiently) via the input BPF filter setting.
|
|
*
|
|
* Default value "80", this setting is required if the mapping strategy used is "destination_port".
|
|
* Exemplary values:
|
|
* - ALL or ANY, i.e. do not apply any port based restriction to the parser (matches all ports)
|
|
* - NONE, i.e. disable this protocol since no ports will be allowed (matches no ports)
|
|
* - 80, i.e. match only packets with destination port 80, any valid port numbers are allowed
|
|
* - 80,8080,8081 matches packets with destination port 80 or 8080 or 8081
|
|
* - 80,8080-8088 matches packets with destination port 80 or the destination port range 8080-8088
|
|
* Warning: A setting of ALL should be used with care, as it may cause a library decoder to crash and
|
|
* prevent the continued parsing process of valid HTTP data.
|
|
*/
|
|
port = 80;
|
|
|
|
/**
|
|
* The "protocol_binding" setting binds an available protocol parser to another protocol parser that is capable
|
|
* of decoding the previously "unwrapped/decoded" content. Usually this setting should be used to define
|
|
* the network layer decoding pipeline. The lowest network layer parser available is currently a
|
|
* layer 2 parser, e.g. ethernet. Layer 1 (basically PCAP-entries) may be implicitly assumed to be always
|
|
* provided in decoded form.
|
|
* A network layer protocol parser is always identified by the unique protocol identifier that this parser is
|
|
* advertising as capable of decoding. Unless custom protocol parsers have been registered, the following parsers
|
|
* should be available:
|
|
* Ethernet, Arp,
|
|
* Ipv4, Ipv6, Icmpv4, Icmpv6,
|
|
* Tcp, Udp,
|
|
* Telnet, Snmp, Netbios, Dhcp, Pop3, Msn, Ftp, Dns, Smtp, Http
|
|
*
|
|
* This setting is not required, however, if no bindings are specified no parsers will be setup.
|
|
* This setting must be specified multiple times in case of different bindings for the same higher layer protocol
|
|
* parser, i.e. the entire network layer stack below the highest defined protocol parser layer must be bound.
|
|
* For instance, if the highest network layer protocol specified is TCP (layer 4), a layer 2 parser
|
|
* must be bound to layer 3 and a layer 3 parser must be bound to tcp. If the parsers are incompatible or the
|
|
* pipeline is not complete, the parser of the highest layer will not receive any decoded data.
|
|
* Multiple lower layer parsers leading to a common higher layer parser are nevertheless allowed, e.g.
|
|
* ethernet -> ipv4, ethernet -> ipv6,
|
|
* ipv4 -> tcp, ipv6 -> tcp,
|
|
* tcp -> http
|
|
*
|
|
* In general, the following implementation constraints may be observed:
|
|
* - 1:n mapping between Layer1 (Pcap) and Layer2 (link) parsers
|
|
* - n:m mapping between Layer2 (link) and Layer3 (IP), Layer3 and Layer4 (transport) parsers
|
|
* - 1:1 mapping between Layer4 (transport) and application layer parsers
|
|
*
|
|
* Note: Not all theoretically possible bindings are implemented, e.g. a binding from ethernet -> http will
|
|
* cause a runtime exception because the Http-parser handles decoded TCP/IP-data only.
|
|
* It is also discouraged to bind a higher layer parser to a lower layer, e.g. http -> tcp, since this will
|
|
* depend solely on the individual parser implementation on how this case is handled and should therefore
|
|
* be avoided.
|
|
*/
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Http;
|
|
|
|
/**
|
|
* Example of a possible DNS protocol parser pipeline setup. Note that larger DNS messages are sent via
|
|
* the TCP transport layer instead of UDP. This pipeline is capable of handling Ethernet, IPv4/IPv6, UDP/TCP and
|
|
* the DNS parsers. however, the TCP -> DNS parser is currently considered experimental.
|
|
*/
|
|
[DNS]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = Any;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv4 -> Udp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Ipv6 -> Udp;
|
|
protocol_binding = Tcp -> Dns;
|
|
protocol_binding = Udp -> Dns;
|
|
|
|
/**
|
|
* Exemplary SNMP v1/v2 Pipeline configuration.
|
|
* (default: disabled)
|
|
*/
|
|
[SNMPv1v2]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = None;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Udp;
|
|
protocol_binding = Ipv6 -> Udp;
|
|
protocol_binding = Udp -> Snmp;
|
|
|
|
/**
|
|
* Exemplary DHCP Pipeline configuration.
|
|
* (default: enabled for port 67,68)
|
|
*/
|
|
[DHCP]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = 67,68;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Udp;
|
|
protocol_binding = Ipv6 -> Udp;
|
|
protocol_binding = Udp -> Dhcp;
|
|
|
|
/**
|
|
* Exemplary Netbios Pipeline configuration.
|
|
* (default: disabled)
|
|
*/
|
|
[Netbios]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = None;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Udp;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Udp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Udp -> Netbios;
|
|
protocol_binding = Tcp -> Netbios;
|
|
|
|
/**
|
|
* Exemplary Msn Pipeline configuration.
|
|
* (default: disabled)
|
|
*/
|
|
[MSN]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = None;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Msn;
|
|
|
|
/**
|
|
* Exemplary Ftp Pipeline configuration.
|
|
* (default: disabled)
|
|
*/
|
|
[FTP]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = None;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Ftp;
|
|
|
|
/**
|
|
* Exemplary Pop3 Pipeline configuration.
|
|
* (default: enabled for ports 110, 995)
|
|
*/
|
|
[Pop3]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = 110, 995;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Pop3;
|
|
|
|
/**
|
|
* Exemplary Telnet Pipeline configuration.
|
|
* (default: enabled for port 23)
|
|
*/
|
|
[Telnet]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = 23;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Telnet;
|
|
|
|
/**
|
|
* Exemplary Smtp Pipeline configuration.
|
|
* (default: enabled for ports 25, 587, 465)
|
|
*/
|
|
[SMTP]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = 25, 587, 465;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Tcp;
|
|
protocol_binding = Ipv6 -> Tcp;
|
|
protocol_binding = Tcp -> Smtp;
|
|
|
|
/**
|
|
* Exemplary ICMPv4/v6 Pipeline configuration.
|
|
* (default: enabled, a port based restriction is not possible)
|
|
*/
|
|
[ICMP]:
|
|
transport_layer_mapping_strategy = destination_port;
|
|
port = None;
|
|
protocol_binding = Ethernet -> Ipv4;
|
|
protocol_binding = Ethernet -> Ipv6;
|
|
protocol_binding = Ipv4 -> Icmpv4;
|
|
protocol_binding = Ipv6 -> Icmpv6;
|
|
};
|
|
|
|
/**
|
|
* #######################
|
|
* # Input Configuration #
|
|
* #######################
|
|
*/
|
|
input {
|
|
/**
|
|
* If a 'input_configuration_file' setting is specified, all remaining input specific settings will be looked
|
|
* up in the referenced file. This file must exist and be readable for the invoking process.
|
|
* Note, however, that there will be no explicit checks against configuration file dereferencing chains, i.e.
|
|
* it should be ensured that there is no 'input_configuration_file' setting in the referenced file again.
|
|
* The referenced file must contain a "input {};" section containing the entire input specific configuration.
|
|
*
|
|
* This setting is optional, but if it is specified all remaining input specific settings in the
|
|
* main configuration file will be ignored.
|
|
*/
|
|
//input_configuration_file = "path/to/input.conf";
|
|
|
|
/**
|
|
* The path to the input files to parse. All specified files must adhere to the format specified by
|
|
* the "input_format" setting.
|
|
*
|
|
* This setting is required, syntax (curly braces indicate arbitrary repetitions and must not be included):
|
|
* input_file = "/path/to/file1" {, "/path/to/another/file"};
|
|
* This setting may be specified multiple times, all occurrences will be processed.
|
|
*
|
|
* Notes: Input files that were specified by using the command line interface will not replace the input_file
|
|
* specifications of this section, i.e. all sources will be combined and processed.
|
|
*/
|
|
//input_file = "path/to/input/file";
|
|
|
|
/**
|
|
* The format of the specified input files.
|
|
* Currently only a pcap parser has been implemented.
|
|
*
|
|
* This setting is required.
|
|
*/
|
|
input_format = pcap;
|
|
|
|
/**
|
|
* A Berkeley Packet Filter string to facilitate an efficient way to filter the entire PCAP-Stream before it is
|
|
* passed to the parsers. This string will be compiled and applied by the native PCAP-decoding library by the means
|
|
* of JNetPcap.
|
|
*
|
|
* This setting is optional.
|
|
* Syntax definition: <https://www.wireshark.org/docs/man-pages/pcap-filter.html>.
|
|
*/
|
|
bpf_filter = "";
|
|
|
|
/**
|
|
* The Berkeley Packet Filter optimization flag.
|
|
* This boolean value will be passed along the bpf_netmask and the bpf_filter string to the native PCAP decoding
|
|
* library and indicates whether or not the bpf_filter string should be optimized by the compiler.
|
|
*
|
|
* This setting is optional, default value = false.
|
|
*/
|
|
bpf_optimize = false;
|
|
|
|
/**
|
|
* If this setting is set to true, all specified input files will be opened and the first content entry will be
|
|
* parsed respectively, i.e. the timestamp of the first entry in each file will be analyzed and compared.
|
|
* The File-Handler will then try to sort all files chronologically according to this timestamp, so that
|
|
* the "real" parsing process provides all packet capture entries in the original order (the oldest entry will
|
|
* be parsed first).
|
|
* Because this process relies only on the first timestamp of each file, it cannot handle overlapping
|
|
* time-intervals.
|
|
*
|
|
* This setting is optional, default value: false
|
|
* Possible values:
|
|
* - false, i.e. parse in the order the files were specified in the configuration itself.
|
|
* - true, try to sort all files chronologically according to the timestamp of their first network capture entry.
|
|
*/
|
|
sort_by_first_timestamp = false;
|
|
};
|
|
|
|
/**
|
|
* ########################
|
|
* # Output Configuration #
|
|
* ########################
|
|
*/
|
|
output {
|
|
/**
|
|
* If a 'output_configuration_file' setting is specified, all remaining output specific settings will be looked
|
|
* up in the referenced file. This file must exist and be readable for the invoking process.
|
|
* Note, however, that there will be no explicit checks against configuration file dereferencing chains, i.e.
|
|
* it should be ensured that there is no 'output_configuration_file' setting in the referenced file again.
|
|
* The referenced file must contain a "output {};" section containing the entire output specific configuration.
|
|
*
|
|
* This setting is optional, but if it is specified all remaining output specific settings in the
|
|
* main configuration file will be ignored.
|
|
*/
|
|
//output_configuration_file = "path/to/output.conf";
|
|
|
|
/**
|
|
* The file descriptor to use for writing the derived information to. The information will be transformed
|
|
* according to the specified output_format before it is written to the output-stream.
|
|
*
|
|
* This setting is required, default value: stdout.
|
|
* The file or stream must be writable by the invoking process.
|
|
* Possible values:
|
|
* - STDOUT, the standard output stream
|
|
* - "path/to/a/file", a file-path
|
|
*/
|
|
output_file = stdout;
|
|
|
|
/**
|
|
* The output format that is used to transform the derived information to before writing it to "output_file".
|
|
*
|
|
* This setting is required, default value: plaso
|
|
* Possible values:
|
|
* - plaso, a format that can be parsed by the provided Plaso specific parser (currently XML)
|
|
* - xml, however, without a schema definition
|
|
* - json
|
|
* - csv, generic/limited comma separated value content will be produced
|
|
* If extended output for certain activities is desired, a custom CSV schema has to be provided first.
|
|
* - nop, does not write anything to "output_file".
|
|
* - callback, as 'nop', mainly interesting for developers/testing.
|
|
*/
|
|
output_format = plaso;
|
|
}; |