Skip to content

Moduleconfiguration

Nick Brown edited this page Nov 27, 2018 · 14 revisions

Vermont Module Configuration

Table of Contents

CryptoPanPrefix

This module is a submodule for the RecordAnonymizer mentioned above. It implements a modified version of the CryptoPan anonymization method. The following only applies if the IP address passing through the module matches a subnet configured in the configuration file - elsewise the address is skipped: The IP address is split into a network and host identifier according to the specified CIDR, i.e. the CIDR represents the number of bits belonging to the network part. After this splitting is done, only the host part of the IP address is anonymized with the basic CryptoPan algorithm. In a second step, the network part is replaced with the preconfigured subnet given in the configuration file in the to field. As seen below, multiple mappings are possible.

  • Input type: IpfixRecord
  • Output type: IpfixRecord

Example configuration

<anonRecord id="3">
    <anonField>
        <anonMethod>CryptoPanPrefix</anonMethod>
        <anonIE>
            <ieName>destinationIPv4Address</ieName>
        </anonIE>
       <anonParam>12345678901234567890123456789013</anonParam>
       <mappingList>
           <subnet cidr="24">
                <from>192.44.88.0</from>
                <to>222.222.222.0</to>
           </subnet>
           <subnet cidr="16">
                <from>119.152.0.0</from>
                <to>111.111.0.0</to>
           </subnet>
       </mappingList>
    </anonField>
    <copyMode>false</copyMode>
    <next>5</next>
</anonRecord>

Parameters:

Element name Default value Description
subnet none The element subnet must include the attribute cidr
from none Subnet to be anonymized
to none Assigned Subnet ID

FpaPcapExporter

Expects IPFIX data records with FPA (Front Payload Aggregation, field IPFIX_ETYPE_frontPayload) or DPA (Dialog-based Payload Aggregation) data elements. This module then creates one/two packet per flow (unidirectional/bidirectional flow) and writes the packets into a PCAP file.

  • Input type: IpfixRecord
  • Output type: none

Example configuration: pcap.dump 2048

Parameters:

Element name Default value Description
filename none Filename of PCAP file that is to be created.
snaplen PCAP_MAX_CAPTURE_LENGTH Maximum packet size in PCAP file. Default value is specified at compile time.

FpaPacketGenerator

Expects IPFIX data records with FPA (Front Payload Aggregation, field IPFIX_ETYPE_frontPayload) or DPA (Dialog-based Payload Aggregation) data elements. This module then creates one/two packet per flow (unidirectional/bidirectional flow) and forwards raw packets to the next module.

  • Input type: IpfixRecord
  • Output type: Packet

Example configuration: 6

Parameters: There are no parameters available!

FrontPayloadSigMatcher

Matches flow records containing a front payload field (IPFIX_ETYPE_frontPayload) to signature files in the specified directory. Each signature file includes the tokens (or signature substrings) the payload is searched for. Each token is associated with a support value. The support values of all matching tokens are summed up and the result is compared against a threshold. The module reports a matching signature if the sum of the support values is equal or larger than the threshold.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<frontPayloadSigMatcher id="9">
    <signaturedir>./signatures</signaturedir>
</frontPayloadSigMatcher>

Parameters:

Element name Default value Description
signaturedir none Directory that contains signature rule files.

Example signature file matching FTP traffic

SIGNATUREID
FTP
TOKEN
FTP
SUPPORT
0.50000
TOKEN
220
SUPPORT
0.50000
THRESHOLD
1.0

Signature file keywords:

Keyword The line(s) following this keyword are interpreted as...
SIGNATUREID string which identifies the signature. If omitted, the name of the signature file is used as identifier.
TOKEN signature substring to be matched. The substring may span multiple lines. Lines must not start with any keyword.
SUPPORT decimal support value of the preceding token.
THRESHOLD decimal threshold value of the signature.

HostStatistics

Receives flow records and counts all bytes that were transferred by all hosts in the specified subnet. On reconfiguration, the byte sums and corresponding IP addresses are written to the file specified in element 'logPath'. Attention: This code is alpha status and may be quite slow.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<hostStatistics id="9">
    <subnet>192.168.0.0/16</subnet>
    <addrFilter>src</addrFilter>
    <logPath>hoststats.log</logPath>
    <logInterval>10</logInterval>
</frontPayloadSigMatcher>

Parameters:

Element name Default value Description
subnet none IP subnet with all hosts that need to be analyzed. IP 4-tuple notation with subnet mask specified in bits.
addrFilter none Specifies which IP address fields are used for the IP filter (specified in element 'subnet'). 'src' for the source IP, 'dst' for the destination IP, 'both' for both IP addresses.
logPath none File, where statistics are saved.
logInterval 10 Interval in seconds, when statistics are exported. ATTENTION: currently not in use.

IdmefExporter

Exports incoming IDMEF messages to the external perl script idmefsender.pl which sends it over the network to a specified URL.

  • Input type: IdmefMessage
  • Output type: none

Example configuration:

<idmefExporter id="9">
    <sendurl>http://localhost</sendurl>
    <destdir>idmef_work</destdir>
</idmefExporter>

Parameters:

Element name Default value Description
sendurl none Destination URL where IDMEF messages must sent to.
destdir idmef_work Directory, where IDMEF messages are temporary stored. There they are picked up by the external perl script ''idmefsender.pl'' in directory ''/tools''.

IpfixAggregator

Aggregates incoming IPFIX flows according to specified parameters. Configuration is similar to module PacketAggregator.

  • Input type: IpfixRecord
  • Output type: IpfixRecord

Example configuration:

<ipfixAggregator id="6">
<rule>
	<templateId>998</templateId>
	<biflowAggregation>1</biflowAggregation>				
	<flowKey>
		<ieName>sourceIPv4Address</ieName>
	</flowKey>
	<flowKey>
		<ieName>destinationIPv4Address</ieName>
	</flowKey>
	<flowKey>
		<ieName>protocolIdentifier</ieName>
	</flowKey>
	<flowKey>
		<ieName>sourceTransportPort</ieName>
	</flowKey>
	<flowKey>
		<ieName>destinationTransportPort</ieName>
	</flowKey>
	<nonFlowKey>
		<ieName>flowStartMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>flowEndMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>octetDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>packetDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>tcpControlBits</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>revflowStartMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>revflowEndMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>revoctetDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>revpacketDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>revtcpControlBits</ieName>
	</nonFlowKey>			
</rule>
<expiration>
	<inactiveTimeout unit="sec">1</inactiveTimeout>
	<activeTimeout unit="sec">1</activeTimeout>
</expiration>
<pollInterval unit="msec">1000</pollInterval>
<next>4</next>
</ipfixAggregator>				

Parameters:

Element name Default value Description
rule none Specifies a rule according to which is aggregated. More than one rule may be specified per aggregator.
biflowAggregation 0 Specifies if biflow aggregation is to be performed (0=no biflow, 1=biflow). Only valid in IpfixAggregator. To accomodate biflow information elements, Vermont-specific enterprise type ids were specified: revFlowStartMilliSeconds, revFlowEndMilliSeconds, revFlowStartSeconds, revFlowEndSeconds, revOctetDeltaCount, revPacketDeltaCount and revTcpControlBits.
templateId none Template ID (optional).
flowKey none Flow key information element - flows are aggregated according to those keys.
nonFlowKey none Non-flow key information element - those IEs are aggregated.
ieName none name of the IE.
modifier none Optional field modifier for flow key IEs ("discard", "mask/X").
match 0 Optional flow key filter for protocol identifier ("TCP", "UDP", "ICMP", or IANA number), IP addresses ("A.B.C.D/M"), port numbers (separated by ",", port range "A:B"), TCP control bits ("FIN", "SYN", "RST", "PSH", "ACK", "URG", separated by ",").
inactiveTimeout 0 Expiration timeout for idle/inactive flows.
activeTimeout 0 Periodic expiration timeout for long-lasting flows (typically larger than inactiveTimeout).
pollInterval 10s Length of interval when flows should be exported to next module.
hashtableBits 17 Length of hashtable used for aggregation in bits. The resulting hashtable will have a size of ''2^hashtableBits''.

IpfixCollector

Receives IPFIX records from the network and imports them into Vermont.

  • Input type: none
  • Output type: IpfixRecord

Example configuration:

<ipfixCollector>
<cert>configs/example_certs/collector_cert.pem</cert>
<key>configs/example_certs/collector_key.pem</key>
<CAfile>configs/example_certs/vermontCA.pem</CAfile>
<CApath>/etc/ssl/certs</CApath>

<listener>
	<ipAddress>0.0.0.0</ipAddress>
	<transportProtocol>DTLS_OVER_UDP</transportProtocol>
	<port>4740</port>
	<peerFqdn>exporter.example.com</peerFqdn>
</listener>
<udpTemplateLifetime>300</udpTemplateLifetime>
</ipfixCollector>

**Parameters: **

Element name Default value Description
listener none Specifies a port on which to listen on for IPFIX data.
ipAddress none IP address at which collector receives IPFIX Messages. If not given, collector receives at all local addresses.
transportProtocol none SCTP, UDP, DTLS_OVER_SCTP or DTLS_OVER_UDP
port 4739 for insecure, 4740 for secure connections i.e. DTLS Port on which Vermont listenes for incoming IPFIX flows.
UDP specific
udpTemplateLifetime 70 Seconds after which templates received from UDP exporters are expired. A value of 0 means that templates never expire.
DTLS specific
cert (none) See IpfixExporter for details.
key (none) See IpfixExporter for details.
CAfile (none) See IpfixExporter for details.
CApath (none) See IpfixExporter for details.
peerFqdn (none) See IpfixExporter for details.

IpfixCsExporter

Writes IPFIX data records to a local disk using the CarmentiS file format. The module recieves Ipfix packets, caches them and writes them as a chunk to disk.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixCsExporter id="27">
   <filenamePrefix>carmentis_</filenamePrefix>
   <destinationPath>/tmp/carmentis</destinationPath>
   <maxFileSize>20480</maxFileSize>
   <maxChunkBufferTime>300</maxChunkBufferTime>
   <maxChunkBufferRecords>50000</maxChunkBufferRecords>  
   <maxFileCreationInterval>1500</maxFileCreationInterval>
   <exportMode>1</exportMode>
</ipfixCsExporter>

Parameters:

Element name Default value Description
filenamePrefix none Prefix to each file.
destinationPath none Output directory for data files.
maxFileSize none Maximum size of one exported file.
maxChunkBufferTime none Maximum time in seconds until a chunk will be written.
maxChunkBufferRecords none Maximum records per chunk.
maxFileCreationInterval none Maximum time in seconds until the currently opened file will be written and a new one opened.
exportMode none Sets a flag inside the exported data which privacy level the packets have. 0=plain; 1=anonymized; 2=pseudonymized

IpfixExporter

Exports internal IPFIX records to the network. The transport protocols UDP and SCTP including their secure counterparts i.e. DTLS over UDP and DTLS over SCTP are supported. The OpenSSL library is required for DTLS. At the time of writing, DTLS over SCTP is only available on the FreeBSD platform. To make DTLS over SCTP work, you have to apply the patches from http://sctp.fh-muenster.de/ to OpenSSL.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixExporter id="7">
    <templateRefreshInterval>10</templateRefreshInterval>
    <maxRecordRate>5000</maxRecordRate>
    <sctpDataLifetime unit="msec">10000</sctpDataLifetime>
    <sctpReconnectInterval unit="sec">30</sctpReconnectInterval>
    <cert>configs/example_certs/exporter_cert.pem</cert>
    <key>configs/example_certs/exporter_key.pem</key>
    <CAfile>configs/example_certs/vermontCA.pem</CAfile>
    <CApath>/etc/ssl/certs</CApath>
    <dtlsMaxConnectionLifetime unit="sec">10</dtlsMaxConnectionLifetime>

    <collector>
        <ipAddressType>4</ipAddressType>
        <ipAddress>127.0.0.1</ipAddress>
        <port>1500</port>
        <transportProtocol>DTLS_OVER_UDP</transportProtocol>
        <peerFqdn>collector.example.com</peerFqdn>
        <mtu>1492</mtu>
    </collector>
</ipfixExporter>

Parameters:

Element name Default value Description
observationDomainId 0 Observation Domain ID of the exporter.
templateRefreshInteval 20s Interval for periodic sending of templates. Applies only to UDP.
ipAddress none The collector's IPv4 or IPv6 address. Host names i.e. FQDNs are not accepted.
transportProtocol none SCTP, UDP, DTLS_OVER_SCTP or DTLS_OVER_UDP
port 4739 for insecure, 4740 for secure connections i.e. DTLS Port number of the collector.
maxRecordRate 0 Maximum number of flow records per second sent to collector. A value of 0 disables record sending limitations. The Exporter will then send records at maximum speed.
UDP specific
mtu 0 (PMTU discovery) The Path Maximum Transmission Unit (PMTU) that should be assumed when creating IPFIX Messages. If set to 0, PMTU discovery will be used to determine a PMTU estimate. This works currently only on Linux. In case the platform does not provide comprehensive PMTU discovery support (e.g., FreeBSD), a conservative default value (1400) is used, which might lead to suboptimal performance. You should, therefore, manually set the PMTU if you are using a platform other than Linux.
SCTP specific
sctpDataLifetime 10000ms Lifetime of SCTP messages carrying Data Records. SCTP's partial reliablity (i.e. PR-SCTP) policy "timed reliability" as defined in RFC3758 is always turned on.
sctpReconnectInterval 30s Time that the Exporter waits before reestablishing a lost connection.
DTLS specific
cert (none) File containing the certificate chain used for authentication. Quote from OpenSSL manpage: "The certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA."
key (none) File containing the private key in PEM format corresponding to the certificate. If left empty, the file specified by the ''cert'' option will be searched for the private key. This allows for the private key to be stored in the same file as the certificate.
CAfile (none) A file containing one or more certificates of trusted CAs. This file has to be in PEM format.
CApath (none) A directory containing certificates of trusted CAs in PEM format. Quote from OpenSSL man page: "The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available."
peerFqdn (none) The expected Fully Qualified Domain Name (FQDN) of the Collector. If set, the Collector must present a certificate of which either the subject's Common Name (CN) or one of the subject alternative names matches this FQDN. There is no support for wildcard matching. For the certificate verification to work, ''CAfile'' or ''CApath'' or both must be set in order to specify the locations of the root CA certificates. If ''peerFqdn'' is not set, anonymous cipher suites will be added to the list of permissible cipher suites. The identity of the peer will not be verified then. Note, that no DNS queries will be performed. Technically, the FQDN specified by ''peerFqdn'' does not need to resolve to an IP address.
dtlsMaxConnectionLifetime 1 hour Lifetime of a DTLS over UDP connection. A new DTLS connection is initiated as soon as the lifetime is up. The old connection is replaced by the new one when the handshake is completed. This mechanism aims to overcome the dead peer problem.

IpfixDbReader

Imports IPFIX flows from a MYSQL database table.

  • Input type: none
  • Output type: IpfixRecord

Example configuration:

<ipfixDbReader id="10">
    <dbType>mysql</dbType>
    <host>127.0.0.1</host>
    <port>3306</port>
    <dbname>flows</dbname>
    <username>vermont</username>
    <password>v_password</password>
    <timeshift>true</timeshift>
    <next>12</next>
</ipfixDbReader>

Parameters:

Element name Default value Description
dbType none Type of database. Legal values are "mysql", "postgres", "oracle"
host none Host of database.
port 3306 Port number of database.
dbname none Database name.
username none Username for database access.
password none Password for database access.
timeshift false Shift time stamps to current time.
fullspeed false If true, tables are read at full speed. Timeshifts are disabled. Otherwise, records are read from table approximately at the same speed as they were originally exported.
observationDomainId 0 Observation Domain Id assigned to the records.

IpfixDbWriter

Exports IPFIX flows to a database table in a MySQL, PostgreSQL or Oracle database.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixDbWriter id="10">
	<dbType>mysql</dbType>
    <host>127.0.0.1</host>
    <port>3306</port>
    <dbname>flows</dbname>
    <username>vermont</username>
    <password>v_password</password>
    <bufferrecords>30</bufferrecords>
    <tablePrefix>f</tablePrefix>
    <columns>
        <name>flowStartSeconds</name>
        <name>flowEndSeconds</name>
        <name>sourceIPv4Address</name>
        <name>destinationIPv4Address</name>
        <name>octetDeltaCount</name>
        <name>packetDeltaCount</name>
    </columns>
</ipfixDbWriter>

Parameters:

Element name Default value Description
dbType none Type of database. Legal values are "mysql", "postgres", "oracle"
useLegacyNames false Enables/Disables the use of legacy VERMONT db names. The use of the old names is hihgly discouraged
host none Host of MySQL database.
port 3306 Port number of database.
dbname none Database name.
username none Username for database access.
password none Password for database access.
bufferrecords 30 Amount of flow records to buffer until they are written to the database.
tablePrefix f Prefix of flow tables created in the database.
observationDomainId none Observation Domain Id overriding the value to the records.
name none IPFIX IE name or legacy VERMONT column name (if useLegacyNames is set to true) (see IpfixDbCommon.hpp for leagcy names currently one of "srcIP", "dstIP", "srcPort", "dstPort", "proto", "dstTos", "bytes", "pkts", "firstSwitched", "lastSwitched", "firstSwitchedMillis", "lastSwitchedMillis", "exporterID", "tcpControlBits", "revbytes", "revpkts", "revFirstSwitched", "revLastSwitched", "revFirstSwitchedMillis", "revLastSwitchedMillis", "revTcpControlBits", "maxPacketGap")

IpfixFileWriter

Dumps ipfix messages into data files.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixFileWriter id="11">
	<observationDomainId>99</observationDomainId>
	<maximumFilesize>64 </maximumFilesize>
	<destinationPath>/home/test</destinationPath> 
	<filenamePrefix>my_dump</filenamePrefix> 
</ipfixFileWriter> 

Parameters:

Element name Default value Description
observationDomainId 0 Observation Domain Id assigned to the records.
maximumFilesize 2097152 maximum size for the date files in KiB (maximumFilesize*1024 == maxmimum filesize in bytes)
destinationPath ./ Output directory for the data files.
filenamePrefix ipfix.dump Basename of the generated filenames. Please note that every filename will be suffixed with a consecutive 10-digit number starting at 0.

IpfixNetflowExporter

Exports flows as Netflow.v5 records, filling non-existent fields with 0. Attention: do not send Biflows to this module, as Netflow.v5 only supports undirectional flows. The reverse direction will be ignored!

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixNetflowExporter id="11">
    <host>localhost</host>
    <port>9995</port>
    <maxRecordRate>500</maxRecordRate> 
</ipfixFileWriter> 

Parameters:

Element name Default value Description
host none Destination host name where Netflow packets should be sent to.
port none Destination port.
maxRecordRate 0 Maximum number of data/flow records to be sent to the receiving side. Higher flow rates will block the exporter, so maybe a buffer is required in front of the module. A value of 0 disables record sending limitations. The Exporter will then send records at maximum speed.
filenamePrefix ipfix.dump Basename of the generated filenames. Please note that every filename will be suffixed with a consecutive 10-digit number starting at 0.

IpfixReceiverFile

Reads ipfix message from data files generated with IpfixFileWriter.

  • Input type: none
  • Output type: IpfixRecord

Example configuration:

    <ipfixReceiverFile id="1">
	<packetFileDirectory>/home/test/</packetFileDirectory>
	<packetFileBasename>my_dump</packetFileBasename>
	<ignoreTimestamps>false</ignoreTimestamps>
	<offlineSpeed>2.0</offlineSpeed>
	<from>0</from>
	<to>5</to>
	<next>5</next>
</ipfixReceiverFile>

Parameters:

Element name Default value Description
packetFileDirectory ./ Standard directory to read files from.
packetFileBasename ipfix.dump Basename of the filenames, i.e. the filename without the suffixed number.
form 0 Suffix of the first file to read from.
to end Suffix of the last file to read from. If not specified, the suffix of the last file available will be used.
ignoreTimestamps true If set to false, the ipfix messages will be processed with the same delay as they were originally recorded by IpfixFileWriter
offlineSpeed 1.0 Sets the speed multiplier for file reading. A value %%<=%% 0 is equivalent to ignoreTimestamp=true. This value has no effect unless ignoreTimestamps is set to false.

IpfixPayloadWriter

Writes IPFIX records including front payload into files. Only the first N (to be set in parameters) flows in chronological order are regarded. It is expected, that incoming flows are biflows and include front payload. For each biflow, three files are generated: .info contains header information of the flow, two .payload files contain front payload in both directions.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixPayloadWriter id="5">
 <destPath>payload_work</destPath>
 <filenamePrefix>vfp</filenamePrefix>
 <connNumber>10</connNumber>
 <ignoreEmptyPayload>1</ignoreEmptyPayload>
</ipfixPayloadWriter>

Parameters:

Element name Default value Description
destPath none Relative path where output files are stored.
filenamePrefix none Prefix for generated filenames.
connNumber none Amount of connections that are recorded. If this parameter is set to 0, no sorting will be performed and all incoming flows will be directly written to filesystem.
ignoreEmptyPayload false Set to true if all connections/biflows with empty payload shoud be ignored.
ignoreIncompleteTCP false Set to true if all TCP biflows without SYN flags in both directions should be ignored.
password none Password for database access.
bufferrecords 30 Amount of flow records to buffer until they are written to the database.
startIndex 0 Start index of first flow written to disk. Useful if already partially written dump on disk needs to be completed.

IpfixPrinter

Prints incoming Ipfix flows to stdout for debugging purposes.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<ipfixPrinter id="8">
    <outputType>tree</outputType>
    <filename>output.log</filename>
</ipfixPrinter>

Parameters:

Element name Default value Description
outputType tree Determines the output format of IpfixPrinter. 'tree' constructs a tree of each incoming DataRecord with all values, 'table' constructs a table-like output format, 'line' produces one line of output per DataRecord, and 'none' does not output anything.
filename none Sets the name of the output file. If nothing is specified (which is the default), data is printed on STDOUT.

IpfixQueue

Caches IPFIX records in a queue until next module is ready to process them.

  • Input type: IpfixRecord
  • Output type: IpfixRecord

Example configuration:

<ipfixQueue id="3">
<maxSize>10</maxSize>
<next>6</next>
</ipfixQueue>			

Parameters:

Element name Default value Description
maxSize 1 Maximum number of items in queue. If queue is full, no new packets are accepted and preceding modules are paused.

IpfixSampler

Samples IPFIX records using a simple sampler based on modulo.

  • Input type: IpfixRecord
  • Output type: IpfixRecord

Example configuration:

<ipfixSampler id="3">
<flowRate>0.1</flowRate>
<next>6</next>
</ipfixSampler>			

Parameters:

Element name Default value Description
flowRate 1 Ratio of flows that should pass sampler. When set to 0.1, 10% of all flows pass the module. Attention: internally, after calculating the inverse, this value is converted to an integer for the modulo operation. So values close to 1 may not be reflected properly by the sampler. Values above 1 are not allowed.

Observer

Captures raw packets using the PCAP interface.

  • Input type: none
  • Output type: Packet

Example configuration:

<observer id="1">
<interface>eth1</interface>
<pcap_filter>ip</pcap_filter>
<next>2</next>
</observer>

Parameters:

Element name Default value Description
interface none Interface PCAP listens to. Do not use in combination with parameter filename.
captureLength 128 Sets the capture length of each packet. Packets bigger than that size are truncated. ATTENTION: if payload is analyzed in later modules, this parameter needs to be large enough!
filename none Must be specified if Vermont needs to read from file and contains its filename. Do not use in combination with parameter interface.
pcap_filter none Filter specification which is passed to PCAP (usually `ip' to only capture IP packets).
replaceTimestamps false If true, PCAP packet timestamps are replaced with current time. This parameter only applies to PCAP file reading.
offlineSpeed 1.0 Only applies to PCAP file reading. Sets the speed multiplier for offline PCAP file reading. A negative value means read as fast as you can.
offlineAutoExit true Only applies to PCAP file reading. Sets if Vermont should be shut down automatically after reading all PCAP file data.
maxPackets 0 Specifies a maximum number of packets to be processed by the Observer. After this number is reached, the Observer stops reading packets and may trigger the shutdown, if parameter 'offlineAutoExit' was specified. If this parameter is set to 0, the Observer may read an infinite amount of packets.

P2PDetector

Detects Peer-to-Peer Clients in a subnet. Attention: IPFIX flows must be aggregated to biflows.

  • Input type: IpfixRecord
  • Output type: IdmefMessage

Example configuration:

<p2pDetector id="5">
<analyzerid>P2PDetector</analyzerid>
<interval>300</interval>
<subnet>192.168.1.0/24</subnet>
<udpRateThreshold>0.013</udpRateThreshold>
<udpHostRateThreshold>0.0007</udpHostRateThreshold>
<tcpRateThreshold>0.082</tcpRateThreshold>
<coexistentTCPConsThreshold>2.9</coexistentTCPConsThreshold>
<rateLongTCPConsThreshold>0.018</rateLongTCPConsThreshold>
<tcpVarianceThreshold>0.068</tcpVarianceThreshold>
<failedConsPercentThreshold>4.8</failedConsPercentThreshold>
<tcpFailedRateThreshold>0.01</tcpFailedRateThreshold>
<tcpFailedVarianceThreshold>0.3</tcpFailedVarianceThreshold>
<next>6</next>
</p2pDetector>	

Parameters:

Element name Default value Description
analyzerid none Analyzer ID which is inserted into the generated IDMEF message.
interval 300 Interval in seconds for repeated computing of the criteria
subnet 0.0.0.0 Subnet to be researched
udpRateThreshold 0.013 Threshold for udp rate. Calculated criteria must be above this value to be detected as a peer
udpHostRateThreshold 0.0007 Threshold for udp host rate. Calculated criteria must be above this value to be detected as a peer
tcpRateThreshold 0.082 Threshold for tcp rate. Calculated criteria must be above this value to be detected as a peer
coexistentTCPConsThreshold 2.9 Threshold for coexistent TCP connections. Calculated criteria must be above this value to be detected as a peer
rateLongTCPConsThreshold 0.018 Threshold for rate of long TCP conncetions. Calculated criteria must be above this value to be detected as a peer
tcpVarianceThreshold 0.068 Threshold for variance of new TCP connections. Calculated criteria must be below this value to be detected as a peer
failedConsPercentThreshold 4.8 Threshold for percentage of failed TCP connections. Calculated criteria must be above this value to be detected as a peer
tcpFailedRateThreshold 0.01 Threshold for rate of failed TCP connections. Calculated criteria must be above this value to be detected as a peer
tcpFailedVarianceThreshold 0.3 Threshold for variance of failed TCP connections. Calculated criteria must be below this value to be detected as a peer

PacketFilter

Forwards packets which match specified filter configuration and drops non-matching packets.

  • Input type: Packet
  • Output type: Packet

Example configuration:

<filter id="2">
<countBased>
	<interval>4</interval>
	<spacing>2</spacing>
<countBased>
<timeBased>
	<interval>100</interval>
	<spacing>50</spacing>
</timeBased>
<stringBased>
	<is>bla</is>
	<isnot>blub</isnot>
	<is type="HEX">0xFF024F</is>
</stringBased>
<regexBased>
	<matchPattern>is\s*not</matchPattern>
</regexBased>
<hostBased>
	<addrFilter>src</addrFilter>
	<ip>1.2.3.4</ip>
	<ip>1.2.3.6</ip>
</hostBased>
<next>3</next>
</filter>

Parameters:

Element name Default value Description
countBased none Creates a count-based filter. Spacing defines the number of packets accepted at the beginning of the period, interval specifies the length of the period
timeBased none Creates a time-based filter. Spacing defines the number of milliseconds during which time all incoming packets are accepted at the beginning of the period, interval specifies the length of the period in milliseconds.
interval none Belongs to either countBased or timeBased filter. Specifies length of period.
spacing none Belongs to either countBased or timeBased filter. Specifies amount of time or number of packets accepted.
stringBased none Creates a string-based filter which scans for specified strings inside the packet payload. If more than one search element is specified, only packets will be forwarded which match **all** specifications.
is none Accepts packets which contain included ASCII string. If attribute "type" is set to "HEX", the tag's content MUST include a hexstring which specifies the binary data to be searched for.
isnot none Drops packets which contain included ASCII string. If attribute "type" is set to "HEX", the tag's content MUST include a hexstring which specifies the binary data to be searched for.
regexBased none Creates a regex-based filter which scans for specified regexes inside the packet payload. If more than one regex is specified, only packets will be forwarded which match *all* specifications.
matchPattern none Specifies a regular expression used by the regex-based filter.
stateConnectionBased none Creates a filter which searches for TCP connections and matches all packets that contain the first N payload bytes. It uses a determinstic algorithm that will consume all the memory necessary to store all seen TCP connections.
connectionBased none Same as stateConnectionBased filter, but uses a different algorithm for TCP connection tracking. The algorithm is probabilistic and uses a fixed amount of memory to store the TCP connections.
timeout 3 Belongs to either stateConnectionBased or connectionBased filter. Specifies the time in seconds a seen TCP connection request is valid, before it will time out.
bytes 100 Belongs to either stateConnectionBased or connectionBased filter. Specifies how much Payload should be exported in bytes.
hashFunctions 3 Belongs to connectionBased filter. Specifies the number of hash functions that are used to index the bloom filters.
filterSize 1000 Belongs to connectionBased filter. Specifies the size of the bloom filters that are used by the connection based filter.
exportControlPackets true Controls wether TCP control packets (SYN/FIN/RST) are exported by stateConnectionBased and connectionBased filter.
anonFilter none Specifies a filter that performs anonymization on captured network packets. Contains one or more anonFields. This tag can have several subtags. The subtags are the same ones that can be used in the RecordAnonymizer module
payloadFilter none Payload is dropped, when this filter is specified.
hostBased none Hostbased filter, which filters packets not belonging to any IPs listed in configuration.
addrFilter none Specifies if source IP address ('src'), destination IP address ('dst') or both IP addresses ('both') are used in the filter.
ip none IP address that is accepted by the filter. May appear multiple times.

PacketQueue

Caches packets in a queue until next module is ready to process them.

  • Input type: Packet
  • Output type: Packet

Example configuration:

<packetQueue id="3">
<maxSize>10</maxSize>
<next>6</next>
</packetQueue>	

Parameters:

Element name Default value Description
maxSize 0 Maximum number of items in queue. If queue is full, no new packets are accepted and preceding modules are paused.

PacketAggregator

Aggregates incoming raw packets to flows according to specified parameters.

  • Input type: Packet
  • Output type: IpfixRecord

Example configuration:

<packetAggregator id="6">
<rule>
	<templateId>998</templateId>
	<flowKey>
		<ieName>sourceIPv4Address</ieName>
	</flowKey>
	<flowKey>
		<ieName>destinationIPv4Address</ieName>
	</flowKey>
	<flowKey>
		<ieName>protocolIdentifier</ieName>
	</flowKey>
	<flowKey>
		<ieName>sourceTransportPort</ieName>
	</flowKey>
	<flowKey>
		<ieName>destinationTransportPort</ieName>
	</flowKey>
	<nonFlowKey>
		<ieName>flowStartMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>flowEndMilliSeconds</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>octetDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>packetDeltaCount</ieName>
	</nonFlowKey>
	<nonFlowKey>
		<ieName>tcpControlBits</ieName>
	</nonFlowKey>
</rule>
<expiration>
	<inactiveTimeout unit="sec">1</inactiveTimeout>
	<activeTimeout unit="sec">1</activeTimeout>
</expiration>
<pollInterval unit="msec">1000</pollInterval>
<next>4</next>
</packetAggregator>	

Parameters:

Element name Default value Description
templateId none Template ID (optional).
flowKey none Flow key information element - flows are aggregated according to those keys.
nonFlowKey none Non-flow key information element - those IEs are aggregated.
ieName none name of the IE.
modifier none Optional field modifier for flow key IEs ("discard", "mask/X").
match 0 Optional flow key filter for protocol identifier ("TCP", "UDP", "ICMP", or IANA number), IP addresses ("A.B.C.D/M"), port numbers (separated by ",", port range "A:B"), TCP control bits ("FIN", "SYN", "RST", "PSH", "ACK", "URG", separated by ",").
inactiveTimeout 0 Expiration timeout for idle/inactive flows.
activeTimeout 0 Periodic expiration timeout for long-lasting flows (typically larger than inactiveTimeout).
pollInterval 10s Length of interval when flows should be exported to next module.
hashtableBits 17 Length of hashtable used for aggregation in bits. The resulting hashtable will have a size of 2%%^%%{hashtableBits}.

PacketIdmefReporter

For each incoming packet an IDMEF message is generated. An extract of the packet payload called snapshot may be included in the IDMEF message.

  • Input type: Packet
  • Output type: IdmefMessage

Example configuration:

<packetIdmefReporter>
<snapshotoffset>12</snapshotoffset>
<snapshotlength>20</snapshotlength>
<analyzerid>idmefreporter</analyzerid>
<idmeftemplate>idmef/templates/idmefreporter_template.xml</idmeftemplate>
</packetIdmefReporter>				

Parameters:

Element name Default value Description
snapshotoffset 0 Byte offset from start of packet payload.
snapshotlength 0 Byte length of snapshot. If it exceeds packet length, snapshot will be truncated.
analyzerid none Analyzer ID that will be included in IDMEF message.
idmeftemplate none Path to template file for IDMEF message.

PcapExporterFile

Exports incoming packets into a file in PCAP format.

  • Input type: Packet
  • Output type: none

Example configuration:

<pcapExporterFile>
<filename>output.pcap</filename>
</pcapExporterFile>

Parameters:

Element name Default value Description
filename none Name of the output pcap file.
linkType EN10MB Data link type of the output file. Names are DLT_ names form the pcap man page with the DLT_ removed (see `man pcap')
snaplen PCAP_MAX_CAPTURE_LENGTH Snaplen for the pcap file

PcapExporterPipe

Writes packets in PCAP format into a pipe, allowing another process to read these packets via STDIN.

  • Input type: Packet
  • Output type: none

Example configuration:

<pcapExporterPipe>
<logfilebasename>/tmp/pcap_exporter_fifo</logfilebasename>
<snaplen>1512</snaplen>
<sigkilltimeout>4</sigkilltimeout>
<command>tcpdump -nr -</command>
<workingpath>/tmp</workingpath>
</pcapExporterPipe>

Parameters:

Element name Default value Description
logfilebasename none If specified, STDOUT and STDERR of fiforeadercmd will be redircted into this file.
command none A single (i.e. no shell) command, which must read PCAP files via STDIN.
workingpath none Working directory for the command to be executed.
sigkilltimeout 1 Maximum additional waiting time in seconds, until a SIGKILL is sent to the reader process on module shutdown.
appenddate false If set to true, the logfilename given as logfilebasename will be suffixed with the current time and date
restartonsignal false If set to true, the command specified as fiforedercmd will be restarted, when a SIGUSR2 is sent to vermont
linkType EN10MB Data link type of the output file. Names are DLT_ names form the pcap man page with the DLT_ removed (see `man pcap')
snaplen PCAP_MAX_CAPTURE_LEN Snaplen for the pcap file
restartInterval 0 If > 0, the process is restarted regularly every restartIntervall seconds, whereby the incoming packets' capture timestamp is used.

PsampExporter

Exports incoming packets as PSAMP records over the network.

  • Input type: Packet
  • Output type: none

Example configuration:

<psampExporter id="1">
<observationDomainId>123</observationDomainId>
<ipfixPacketRestrictions>
	<maxPacketSize>200</maxPacketSize>
	<maxExportDelay unit="msec">500</maxExportDelay>
</ipfixPacketRestrictions>
<packetReporting>
	<templateId>888</templateId>
	<reportedIE>
		<ieName>sourceIPv4Address</ieName>
	</reportedIE>
	<reportedIE>
		<ieName>destinationIPv4Address</ieName>
	</reportedIE>
	<reportedIE>
		<ieName>ipPayloadPacketSection</ieName>
		<ieLength>65535</ieLength>
	</reportedIE>
</packetReporting>
<collector>
	<ipAddress>127.0.0.1</ipAddress>
	<transportProtocol>UDP</transportProtocol>
	<port>4739</port>
</collector>
</psampExporter>			

Parameters:

Element name Default value Description
observationDomainId 0 Observation Domain ID of the exporter.
ipfixPacketRestrictions none Restrictions for IPFIX packets.
maxPacketSize none Maximum size of IPFIX packets.
maxExportDelay none Maximum delay until IPFIX packet is sent to destination.
packetReporting none Specifies elements to be exported for one template.
templateId 0 Specifies template ID.
reportedIE none Specifies one information element to be reported.
ieName none IPFIX type id of element to be exported.
ieLength none Optional specification of element length (usually only used by "ipPayloadPacketSection".
collector none Contains specification of one destination for PSAMP records.
idAddress none IP address of destination.
transportProtocol none Transport protocol to be used. Currently only "UDP" is supported.
port 4739 Port of destination.
templateRefreshRate 5000 Number of records, until template is resent.
templateRefreshInterval 30s Time, until template is resent.

RecordAnonymizer

This module is capable of anonymizing arbitary fields within IPFIX-Records using different anonymization methods.

  • Input type: IpfixRecord
  • Output type: IpfixRecord

Example configuration:

<anonRecord id="3">
<anonField>
	<anonIE>
		<ieName>sourceIPv4Address</ieName>
	</anonIE>
	<anonMethod>CryptoPan</anonMethod>
	<anonParam>insert key here</anonParam>
</anonField>
<anonField>
	<anonIE>
		<ieName>destinationIPv4Address</ieName>
		<ieLength>4</ieLength>
	</anonIE>
<anonMethod>CryptoPan</anonMethod>
	<anonParam>insert key here</anonParam>
</anonField>
<copyMode>false</copyMode>
<next>6</next>
</anonRecord>

Parameters:

Element name Default value Description
anonField none Specifies one field and an anonymization method for that field. Contains one anonIE, one anonMethod and an optional anonParam tag.
anonIE none Specifies the information element that needs to be anonymized. Belongs to anonField.
ieName none Specifies the name of the field that needs to be anonymized. Belongs to anonIE.
anonMethod none Specifies the anonymization method that is used to anonymize a given header field. Belongs to anonField. Possible values are: BytewiseHashHmacSha1, BytewiseHashSha1, ConstOverwrite, ContinuousChar, HashHmacSha1, HashSha1, Randomize, Shuffle, Whitenoise, CryptoPan
anonParam none Specifies an optional parameter to the anonymization method. Different methods need different params. ByteWiseHashHmacSha1, HashHmacSha1 need an variable sized key. ConstOverwrite needs one character as parameter. CryptoPan needs an 32 bytes long parameter (16 bytes key, 16 bytes pad). For CryptoPan and ConstOverwrite, keys can be specified as normal text, or as hexadecimal string starting with '0x'.
copyMode false If true, the Record Anonymizer creates a copy of the incoming record and leaves the original record unchanged. Copy mode should be turned on if the original records are processed by other moduls as well.

SensorManager

Module which controls all sensors ("Messfühle") inside Vermont. It does not have any in- or output types and must not be connected to any other module. It is recommended to set its ID to 99 to express its special role. If this module is specified in the configuration, available sensors are activated and polled regularly. It may only be specified once.

  • Input type: none
  • Output type: none

Example configuration:

<sensorManager id="99">
<checkinterval>2</checkinterval>
<outputfile>sensor_output.xml</outputfile>
</sensorManager>	

Parameters:

Element name Default value Description
checkinterval 2 Interval in seconds, when all sensors are polled and the output file is written to.
outputfile ''sensor_output.xml'' Path to file, where sensor data is stored.
append 0 Set to 1 if output file should be appended to, and not overwritten.

TrwPortscanDetector

Detects horizontal portscans in incoming IPFIX flows. Attention: IPFIX flows must be aggregated to biflows. To achieve best results, flows should contain the following IEs:

sourceIPv4Address
destinationIPv4Address
sourceTransportPort
destinationTransportPort
protocolIdentifier
flowStartMilliSeconds
flowEndMilliSeconds
revFlowStartMilliSeconds
revFlowEndMilliSeconds
octetDeltaCount
revOctetDeltaCount
packetDeltaCount
revPacketDeltaCount
tcpControlBits
revTcpControlBits
  • Input type: IpfixRecord
  • Output type: IdmefMessage

Example configuration:

<trwPortscanDetector id="8">
<analyzerid>trwportscandetector</analyzerid>
<idmeftemplate>idmef/templates/trwportscan_template.xml</idmeftemplate>
<hashbits>20</hashbits>
<timeexpirepending>86400</timeexpirepending>
<timeexpirescanner>1800</timeexpirescanner>
<timeexpirebenign>1800</timeexpirebenign>
<timecleanupinterval>10</timecleanupinterval>
<next>9</next>
</trwPortscanDetector>	

Parameters:

Element name Default value Description
analyzerid none Analyzer ID which is inserted into the generated IDMEF message.
idmeftemplate none Path to IDMEF template which is used to generate the IDMEF message.
hashbits 20 Amount of bits used for hashtable to contain watched IP addresses.
timeexpirepending 86400 Seconds, until non-classified inactive IP addresses are purged from table.
timeexpirescanner 1800 Seconds, until as portscanner classified IP addresses are purged from table.
timeexpirebenign 1800 Seconds, until as benign classified IP addresses are purged from table.
timecleanupinterval 10 Interval length in seconds, when IP address table is scanned for entries to be purged.

FlowLenAnalyzer

Output statistics on the observed flow lenghts. Usefull for getting data for flow len distributions from the network.

  • Input type: IpfixRecord
  • Output type: none

Example configuration:

<flowLenAnalyzer id="10">
     <flowFilename>biflowlens.txt</flowFilename>
     <binFilename>bins.txt</binFilename>
     <bins>100,1000,10000,100000,1000000,10000000,100000000,1000000000,10000000000</bins>
</flowLenAnalyzer> 

Parameters:

Element name Default value Description
flowFileName none Output file for flowlen information.
binFileName none Output file for binned flow len information
bins none Comma separated list of bins that are used to group flow lens

NetflowV9Converter

Converts NetflowV9Records into IpfixRecords. The main difference between both type of records are their notion of times. IPFIX uses timestamps that are based on the current time encoded in unix timestamps (relative to 1/1/1970) while NetflowV9 uses timestamps that are relative to the uptime of the flow monitor. The module converts the NetflowV9 timestamps into IPFIX timestamps and generates IPFIX compliant records.

  • Input type: NetFlowRecords
  • Output type: IpfixRecords

Example configuration:

<netflowV9Converter id="2">
    <keepFlowSysUpTime>true</keepFlowSysUpTime>
    <next>3</next>
</netflowV9Converter> 

Parameters:

Element name Default value Description
copyMode true Defines whether a record is modified in-place or if a modified copy is created and passed to the other modules.
keepFlowSysUpTime false Defines if old NetFlowV9 timestamps are replaced by the new timestamps or if the new timestamps are added to the flow record. If this configuration is true, the old timestamps will be preserved. If set to false, then the old timestamps will be replaced.