Validation tests focus on verifying the parsing capabilities of a probe. A validation test usually consists of a one or several packets which are sent to the probe and its output is compared with an expected result. Validation tests typically verify whether certain IPFIX fields are present and have correct values.
Every validation test consists of a PCAP file and an annotation file (yaml format).
When creating a new validation test, it is recommended that the annotation should be kept minimalistic, annotating only fields necessary to identify the flow ('key fields') and fields which must be verified to determine the validation test result.
Key fields directly influence how flow sources are differentiated during the validation, but do not affect probe behavior in any way.
For instance, annotation of a test designed to verify parsing of the TCP protocol should not include fields from other protocols e.g., MAC addresses, IP time-to-live value (except fields necessary for the flow identification) and should include data from the TCP header e.g., flags, window size, etc.
The required_protocols field in the annotation defines which protocols must the probe be able to parse (usually also export), so that the test can be executed and properly evaluated. The following protocols and fields are considered to be present by default and thus their respective protocol does not need to be stated in the required_protocols field.
| Protocol | Fields |
|---|---|
| ETH | - |
| IPv4 | src_ip, dst_ip, protocol |
| IPv6 | src_ip, dst_ip, protocol |
| TCP | src_port, dst_port |
| UDP | src_port, dst_port |
| - | bytes, packets, ip_version |
For instance, ethernet protocol does not need to be stated in the required_protocols field if only parsing is necessary, but must be stated if the test requires evaluating MAC addresses.
Conforming with this minimalistic approach ensures that any faults related to parsing a specific field affect only tests focusing on that functionality.
If possible, the annotation should be done in pairs - biflows, so that both directions of the network communication (forward and reverse) are kept together to increase the evaluation potential of the validation test. Especially, if the probe is capable of exporting biflows. For this reason, it is sometimes necessary to categorize which flow fields are supposed to be in which direction. Therefore, special sections _forward and _reverse should be utilized for this purpose.
The annotation format allows to define field alternatives (multiple possible values in a single field) and also group of fields (subfields) which can be useful if there are multiple possible values for the fields in the group. See examples below.
# Comment stating the purpose of this test
test:
name: Short name of the test
pcaps: List of PCAP files that should be used (the order of pcaps is respected)
required_protocols: List of protocols which must be supported by the probe so that this test can be evaluated
key: List of key fields (may be omitted, default - src_ip, dst_ip, protocol, src_port, dst_port)
# List of flows with their flow fields annotation. All fields need to be properly defined in the fields.yml
flows:
- flow1_field1: "..."
flow1_field2: "..."
- flow2_field1: "..."
flow2_field2: "..."# Check that TCP header is properly parsed
test:
name: Simple TCP traffic
pcaps: ["tcp.pcap"]
required_protocols: ["tcp"]
flows:
- src_ip: "192.168.56.101"
dst_ip: "192.168.56.102"
ip_version: 4
protocol: 6
bytes: 751
bytes@rev: 1900
packets: 6
packets@rev: 4
tcp_flags: 0x1a
tcp_flags@rev: 0x1a
src_port: 45422
dst_port: 443
tcp_options: 0x11e
tcp_options@rev: 0x11e
tcp_syn_size: 60
tcp_syn_ttl: 64# Check that ICMPv4 is properly parsed
test:
name: Simple ICMP traffic
pcaps: ["icmp.pcap"]
required_protocols: ["icmp"]
key: [src_ip, dst_ip, protocol]
flows:
- src_ip: "192.168.158.139"
dst_ip: "174.137.42.77"
ip_version: 4
protocol: 1
bytes: 240
bytes@rev: 240
packets: 4
packets@rev: 4
icmp_type: 8
icmp_type@rev: 0
icmp_code: 0
icmp_code@rev: 0
icmp_type_code: 2048
icmp_type_code@rev: 0This tests validates that MAC addresses and IP addresses were parsed properly after the VXLAN tunnel.
# Check that information from inner Ethernet and IP headers are exported
test:
name: Traffic in VXLAN tunnel
pcaps: ["vxlan.pcap"]
required_protocols: ["eth", "vxlan"]
flows:
- src_ip: "10.0.0.1"
dst_ip: "10.0.0.2"
ip_version: 4
protocol: 1
bytes: 336
bytes@rev: 336
bytes_outer: 536
bytes_outer@rev: 536
packets: 4
packets@rev: 4
src_mac: "ba:09:2b:6e:f8:be"
dst_mac: "4a:7f:01:3b:a2:71"
vxlan_id: 123In this example, the http_content_type field can contain any of the specified values.
# Check that HTTP 500 error response code is parsed properly
test:
name: HTTP Error 500
pcaps: ["http_500.pcap"]
required_protocols: ["http"]
flows:
- src_ip: "192.168.0.113"
dst_ip: "209.31.22.39"
ip_version: 4
protocol: 6
bytes: 931
bytes@rev: 4298
packets: 6
packets@rev: 6
src_port: 3541
dst_port: 80
http_host: "www.frys.com"
http_url: "/category/Outpost/Notebooks+&+Tablets/View+All+Notebooks?site=sa:Notebook%20Pod:Pod2"
http_method: "GET"
http_method_id: 1
http_status_code: 500
http_agent: "Mozilla/5.0 (Windows; U; Windows NT 6.0; en-US; rv:1.9.1.3) Gecko/20090824 Firefox/3.5.3 (.NET CLR 3.5.30729)"
http_content_type: ["text/html", "text/html;charset=UTF-8"]
http_referer: "http://www.frys.com/template/notebook/"# Check that at least one of the IPv4 addresses present in DNS response to type A request is present in the flow
test:
name: Simple DNS A Request
pcaps: ["dns_a.pcap"]
required_protocols: ["dns"]
flows:
- src_ip: "192.168.21.89"
dst_ip: "192.168.197.92"
ip_version: 4
protocol: 17
bytes: 67
bytes@rev: 99
packets: 1
packets@rev: 1
src_port: 40980
dst_port: 53
dns_id: 14402
_forward:
dns_flags: 0x0100
dns_req_query_type: 1
dns_req_query_class: 1
dns_req_query_name: "newportconceptsla.com"
_reverse:
dns_flags: 0x8180
dns_resp_rcode: 0
dns_resp_rr:
- name: "newportconceptsla.com"
type: 1
class: 1
ttl: 136
data: "192.168.73.162"
- name: "newportconceptsla.com"
type: 1
class: 1
ttl: 136
data: "192.168.215.181"