Skip to content

Orb Policy Reference

The policy model has seven top level sections: name, desciption, tags, backend, schema_version, policy and format.

{
    "name": "",
    "description" : "",
    "tags": {},
    "backend": "",
    "schema_version": "",
    "format": "",
    "policy": {}
}
Policy Sections Default Required
name -
backend -
policy -
description None
tags None
schema_version 1.0
format json
  • Name

    Policy name must be unique, must start with a letter and contain only letters, numbers, "-" or "_".

Examples

Success

"name": "my_policy"
"name": "MY-policy_2

Failure

"name": "1_policy"
"name": "MY-policy/2

  • Description

    Policy description is a free string. You can describe using spaces, letters, numbers and special characters.

  • Tags

    Tags are intended to facilitate organization and are a dict type.

The tags usage syntax is:

    "tags": {"key1":"value1", "key2":"value2", "key3":"value3"}
  • Backend

    Backend determine to which backend the policy will be attached. Check the available backends here.

  • Schema version

    Each backend supported on Orb must have a policy schema to be validated, parsed and applied. schema_version is the field responsible for allowing different schema versions and backward compatibility. Default should be "1.0".

  • Format

    The format specifies in which format the policy data will be written. The options are json and yaml. json is the default value.

  • Policy

    Each supported backend has specific structures for its policy data. Check the available options below.

Pktvisor policy

The policy data for pktvisor can be written in either YAML or JSON, and has four top level sections: “input”, “handlers”, "config" and “kind”.

input: ..
config: ...
kind: collection
handlers: ...
{
  "input": {       
   },
  "config": {
   },
  "kind": "collection"
   },
  "handlers": {        
}

Input section

The input section specifies what data streams the policy will be using for analysis, in other words, this specifies what data the agent should be listening in on, and is defined at the agent level.

Required fields:
input_type - the type of input. This field will be validated with the type of tap indicated by the tap parameter or by the tap selector . If the types are incompatible, the policy will fail.

tap - the name given to this input in the tap/agent configuration or tap_selector - tags to match existing agent taps. If tap_selector is used, it can be chosen whether taps with any of the tags or with all tags will be attached.

Optional fields:
filter - to specify what data to include from the input
config - how the input will be used

Note

Every configuration set at the input can be reset at the tap level, with the one set on the tap dominant over the one set on the input.

Default input structure

Using specific tap (check the application in a policy here):

input:
  tap: tap_name
  input_type: type_of_input
  filter:
    bpf: ...
  config:
    ...
{
  "input": {
    "tap": "tap_name",
    "input_type": "type_of_input",
    "filter": {
      "bpf": "..."
    },
    "config": "..."
  }
}

or using tap selector matching any (check the application in a policy here):

input:
  tap_selector:
    any:
      - key1: value1
      - key2: value2
  input_type: type_of_input
  filter:
    bpf: ...
  config:
    ...
{
  "input": {
    "tap_selector": {
      "any": [
        {
          "key1": "value1"
        },
        {
          "key2": "value2"
        }
      ]
    },
    "input_type": "type_of_input",
    "filter": {
      "bpf": "..."
    },
    "config": "..."
  }
}

or using tap selector matching all (check the application in a policy here):

input:
  tap_selector:
    all:
      - key1: value1
      - key2: value2
  input_type: type_of_input
  filter:
    bpf: ...
  config:
    ...
{
  "input": {
    "tap_selector": {
      "all": [
        {
          "key1": "value1"
        },
        {
          "key2": "value2"
        }
      ]
    },
    "input_type": "type_of_input",
    "filter": {
      "bpf": "..."
    },
    "config": "..."
  }
}

Config section

There is the possibility of defining settings on the policy level. Currently, the only configuration available is the merge_like_handlers.

Policy Configuration Type Default
merge_like_handlers bool false

merge_like_handlers

When merge_like_handlers config is true, metrics from all handlers of the same type are scraped together. This is useful when the tap_selector is used, as, by default, metrics are generated separately for each tap in the policy and this can be very expensive, depending on the number of taps.

The merge_like_handlers filter usage syntax is:

config:
  merge_like_handlers: true
{
  "config": {
    "merge_like_handlers": true
  }
}

Kind section

What kind of object you want to create The only option for now is "collection".

Handlers section (Analysis)

Handlers are the modules responsible for extracting metrics from inputs. For each handler type, specific configuration, filters and group of metrics can be defined, and there are also configs (abstract configuration) that can be applied to all handlers:

Default handler structure:

handlers:
  config:
    deep_sample_rate: 100
    num_periods: 5
    topn_count: 10
    topn_percentile_threshold: 0
  modules:
    tap_name:
      type: ...
      config: ...
      filter: ...
      metric_groups:
        enable:
          - ...
          - ....
        disable:
          - .....
          - ......     
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 5,
      "topn_count": 10,
      "topn_percentile_threshold": 0
    },
    "modules": {
      "tap_name": {
        "type": "...",
        "config": "...",
        "filter": "...",
        "metric_groups": {
          "enable": [
            "...",
            "...."
          ],
          "disable": [
            ".....",
            "......"
          ]
        }
      }
    }
  }
}


To enable any metric group use the syntax:

metric_groups:
  enable:
    - group_to_enable
{
  "metric_groups": {
    "enable": [
      "group_to_enable"
    ]
  }
}

To enable all available metric groups use the syntax:

metric_groups:
  enable:
    - all
{
  "metric_groups": {
    "enable": [
      "all"
    ]
  }
}

In order to disable any metric group use the syntax:

metric_groups:
  disable:
    - group_to_disable
{
  "metric_groups": {
    "disable": [
      "group_to_disable"
    ]
  }
}

To disable all metric groups use the syntax:

metric_groups:
  disable:
    - all
{
  "metric_groups": {
    "disable": [
      "all"
    ]
  }
}
  • Attention: enable is dominant over disable. So if both are passed, the metrics group will be enabled;

Abstract Configurations

There are general configurations, which can be applied to all handlers. These settings can be reset for each module, within the specific module configs. In this case, the configuration inside the module will override the configuration passed in general handler.

Abstract Configuration Type Default
deep_sample_rate int 100 (per second)
num_periods int 5
topn_count int 10
topn_percentile_threshold int 0

deep_sample_rate

deep_sample_rate determines the number of data packets that will be analyzed deeply per second. Some metrics are operationally expensive to generate, such as metrics that require string parsing (qname2, qtype, etc.). For this reason, a maximum number of packets per second to be analyzed is determined. If in one second fewer packages than the maximum amount are transacted, all packages will compose the deep metrics sample, if there are more packages than the established one, the value of the variable will be used. Allowed values are in the range [1,100]. Default value is 100.

Note

If a value less than 1 is passed, the deep_sample_rate will be 1. If the value passed is more than 100, deep_sample_rate will be 100.

The deep_sample_rate usage syntax is:

deep_sample_rate: int
{
  "deep_sample_rate": int
}

num_periods

num_periods determines the amount of minutes of data that will be available on the metrics endpoint. Allowed values are in the range [2,10]. Default value is 5.

The num_periods usage syntax is:

num_periods: int
{
"num_periods": int
}

topn_count

topn_count sets the maximum amount of elements displayed in top metrics. If there is less quantity than the configured value, the composite metrics will have the existing value. But if there are more metrics than the configured value, the variable will be actively limiting. Any positive integer is valid and the default value is 10.

The topn_count usage syntax is:

topn_count: int
{
"topn_count": int
}

topn_percentile_threshold

topn_percentile_threshold sets the threshold of data to be considered based on the percentiles, so allowed values are in the range [0,100]. The default value is 0, that is, all data is considered. If, for example, the value 10 is set, scraped topn metrics will only consider data from the 10th percentile, that is, data between the highest 90%.

The topn_percentile_threshold usage syntax is:

topn_percentile_threshold: int
{
"topn_percentile_threshold": int
}

DNS Analyzer (dns)

Example of policy with input pcap and handler DNS
handlers:
  config:
    deep_sample_rate: 100
    num_periods: 5
    topn_count: 10
  modules:
    default_dns:
      type: dns
      config:
        public_suffix_list: true
        deep_sample_rate: 50
        num_periods: 2
        topn_count: 25
        topn_percentile_threshold: 10
      filter:
        only_rcode: 0
        only_dnssec_response: true
        answer_count: 1
        only_qtype: [1, 2]
        only_qname_suffix: [".google.com", ".orb.live"]
        geoloc_notfound: false
        asn_notfound: false
        dnstap_msg_type: "auth"
      metric_groups:
        enable:
          - top_ecs
          - top_qnames_details
        disable:
          - cardinality
          - counters
          - dns_transaction
          - top_qnames
          - top_ports
input:
  input_type: pcap
  tap: default_pcap
  filter:
    bpf: udp port 53
  config:
    iface: wlo1
    host_spec: 192.168.1.167/24
    pcap_source: libpcap
    debug: true
config:
    merge_like_handlers: true
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 5,
      "topn_count": 10
    },
    "modules": {
      "default_dns": {
        "type": "dns",
        "config": {
          "public_suffix_list": true,
          "deep_sample_rate": 50,
          "num_periods": 2,
          "topn_count": 25,
          "topn_percentile_threshold": 10
        },
        "filter": {
          "only_rcode": 0,
          "only_dnssec_response": true,
          "answer_count": 1,
          "only_qtype": [
            1,
            2
          ],
          "only_qname_suffix": [
            ".google.com",
            ".orb.live"
          ],
          "geoloc_notfound": false,
          "asn_notfound": false,
          "dnstap_msg_type": "auth"
        },
        "metric_groups": {
          "enable": [
            "top_ecs",
            "top_qnames_details"
          ],
          "disable": [
            "cardinality",
            "counters",
            "dns_transaction",
            "top_qnames",
            "top_ports"
          ]
        }
      }
    }
  },
  "input": {
    "input_type": "pcap",
    "tap": "default_pcap",
    "filter": {
      "bpf": "udp port 53"
    },
    "config": {
      "iface": "wlo1",
      "host_spec": "192.168.1.167/24",
      "pcap_source": "libpcap",
      "debug": true
    }
  },
  "config": {
    "merge_like_handlers": true
  },
  "kind": "collection"
}


Handler Type: "dns"

Metrics Group
Metric Group Default
top_ecs disabled
top_qnames_details disabled
cardinality enabled
counters enabled
dns_transaction enabled
top_qnames enabled
top_ports enabled
Configurations
  • public_suffix_list: bool.
  • Abstract configurations.

public_suffix_list

Some names to be resolved by a dns server have public suffixes. These suffixes cause metrics to be generated considering non-relevant data.

The example below illustrates the benefit of using this type of configuration. The qnames consider each part of the name to be resolved. When a name has a public suffix, generic information is generated. Note that in the standard configuration, Qname2 and Qname3 are the same for both domains. With the public suffix setting true (which makes the entire public part be considered as a single part), Qname3 already displays relevant information about the name.
The list of suffixes considered public can be accessed here.

Name Qname2 Standard Qname3 Standard Qname2 Public Suffix Qname3 Public Suffix
www.imagine.qname.co.uk co.uk qname.co.uk qname.co.uk imagine.qname.co.uk
other.example.qname.co.uk co.uk qname.co.uk qname.co.uk example.qname.co.uk

The public_suffix_list filter usage syntax is:

public_suffix_list: true
{
  "public_suffix_list": true
}
Filters
Filter Type Input
only_rcode int PCAP
exclude_noerror bool PCAP
only_dnssec_response bool PCAP
answer_count int PCAP
only_qtype str[] PCAP
only_qname_suffix str[] PCAP
geoloc_notfound bool PCAP
asn_notfound bool PCAP
dnstap_msg_type str DNSTAP

only_rcode: int.

Input: PCAP

When a DNS server returns a response to a query made, one of the properties of the response is the "return code" (rcode), a code that describes what happened to the query that was made.

Most return codes indicate why the query failed and when the query succeeds, the return is an RCODE:0, whose name is NOERROR.
There are several possible return codes for a DNS server response, which you can access here, but supported types are in the table below (if you use any other code that is not in the table below, your policy will fail):

DNS Return Code DNS Return Message Description
0 NOERROR DNS Query completed successfully
1 FORMERR DNS Query Format Error
2 SERVFAIL Server failed to complete the DNS request
3 NXDOMAIN Domain name does not exist
4 NOTIMP Function not implemented
5 REFUSED The server refused to answer for the query
6 YXDOMAIN Name that should not exist, does exist
7 YXRRSET RR set that should not exist, does exist
8 NXRRSET RR Set that should exist, does not exist
9 NOTAUTH Server Not Authoritative for zone or Not Authorized
10 NOTZONE Name not contained in zone
11 DSOTYPENI DSO-TYPE Not Implemented
16 BADVERS/BADSIG Bad OPT Version or TSIG Signature Failure
17 BADKEY Key not recognized
18 BADTIME Signature out of time window
19 BADMODE Bad TKEY Mode
20 BADNAME Duplicate key name
21 BADALG Algorithm not supported
22 BADTRUNC Bad Truncation
23 BADCOOKIE Bad/missing Server Cookie

The only_rcode filter usage syntax is:

only_rcode: int
{
  "only_rcode": int
}

with the int referring to the return code to be filtered.

Example:
If you want to filter only successful queries responses you should use (note that all that the query will be discarded and the result will be just the responses):

only_rcode: 0
{
"only_rcode": 0
}

Important information is that only one return code is possible for each handler. So, in order to have multiple filters on the same policy, multiple handlers must be created, each with a rcode type.

exclude_noerror: bool

Input: PCAP

You may still want to filter out only responses with any kind of error. For this, there is the exclude_noerror filter, which removes from its results all responses that did not return any type of error. The exclude_noerror filter usage syntax is:

exclude_noerror: true
{
  "exclude_noerror": true
}

Attention: the filter of exclude_noerror is dominant in relation to the filter of only_rcode, that is, if the filter of exclude_noerror is true, even if the filter of only_rcode is set, the results will be composed only by responses without any type of error (all type of errors will be kept).

only_dnssec_response: bool

Input: PCAP

When you make a DNS query, the response you get may have a DNSSEC signature, which authenticates that DNS records originate from an authorized sender, thus protecting DNS from falsified information.
To filter only responses signed by an authorized sender, use: The only_dnssec_response filter usage syntax is:

only_dnssec_response: true
{
"only_dnssec_response": true
}


answer_count: int

Input: PCAP

One of the properties present in the query message structure is Answer RRs, which is the count of entries in the responses section (RR stands for “resource record”).
The number of answers in the query is always zero, as a query message has only questions and no answers, and when the server sends the answer to that query, the value is set to the amount of entries in the answers section.

The answer_count filter usage syntax is:

answer_count: int
{
  "answer_count": int
}

with the int referring to the desired amount of answer.
Note that any value greater than zero that is defined will exclude queries from the results, since in queries the number of answers is always 0.
As the answers count of queries is 0, whenever the value set for the answer_count is 0, both queries and responses will compose the result.

A special case is the concept of NODATA, which is one of the possible returns to a query made to a DNS server is known as. This happens when the query is successful (so rcode:0), but there is no data as a response, so the number of answers is 0.
In this case, to have in the results only the cases of NODATA, that is, the responses, the filter must be used together with the filter exclude_noerror.

Important information is that only one answer_count is possible for each handler. So, in order to have multiple counts on the same policy, multiple handlers must be created, each with an amount of answers.

only_qtype: str[]

Input: PCAP

DNS record types are records that provide important information about a hostname or domain. Supported default types can be seen here.

The only_qtype filter usage syntax is:

only_qtype: 
  - array
{
  "only_qtype": [
    "array"
  ]
}

If you want to filter only IPV4 record types, for example, you should use:

only_qtype:
  - "A"
{
  "only_qtype": [
    "A"
  ]
}

or

only_qtype:
  - 1
{
  "only_qtype": [
    1
  ]
}

Multiple types are also supported and both queries and responses that have any of the values in the array will be considered.

only_qtype:
  - 1
  - 2
  - "A"
{
  "only_qtype": [
    1,
    2,
    "A"
  ]
}

only_qname_suffix: str[]

Input: PCAP

The only_qname_suffix filters queries and responses whose endings (suffixes) of the names match the strings present in the array.
The only_qname_suffix filter usage syntax is:

only_qname_suffix:
  - array
{
  "only_qname_suffix": [
    "array"
  ]
}

Examples:

only_qname_suffix:
  - .google.com
{
  "only_qname_suffix": [
    ".google.com"
  ]
}

or

only_qname_suffix:
  - google.com
  - .nsone.net
{
  "only_qname_suffix": [
    "google.com",
    ".nsone.net"
  ]
}


geoloc_notfound: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the geolocation of where the query is being made. When the Subnet refers to a region found in the standard databases, the city, state and country (approximated) are returned. However, when based on the subnet it is not possible to determine the geolocation, a not found is returned.
The geoloc_notfound filter only keeps responses whose geolocations were not found.
The geoloc_notfound filter usage syntax is:

geoloc_notfound: true
{
  "geoloc_notfound": true
}


asn_notfound: bool

Input: PCAP

Based on ECS (EDNS Client Subnet) information, it is possible to determine the ASN (Autonomous System Number). When the IP of the subnet belongs to some not known ASN in the standard databases, a not found is returned.
The asn_notfound filter only keeps responses whose asn were not found.
The asn_notfound filter usage syntax is:

asn_notfound: true
{
  "asn_notfound": true
}


dnstap_msg_type: str

Input: DNSTAP

With a dnstap protocol it is possible to know the type of message that must be resolved in the request to the server. This filter therefore allows you to filter by response types. Supported message types are: auth, resolver, client, forwarder, stub, tool and update.

The dnstap_msg_type filter usage syntax is:

dnstap_msg_type: str
Example:
dnstap_msg_type: auth

{
  "dnstap_msg_type": "str"
}
Example:
{
  "dnstap_msg_type": "auth"
}


Network (L2-L3) Analyzer (net)

Example of policy with input pcap and handler NET
handlers:
  config:
    deep_sample_rate: 100
    num_periods: 5
    topn_count: 10
  modules:
    default_net:
      type: net
      config:
        deep_sample_rate: 1
        num_periods: 2
        topn_count: 25
      filter:
        geoloc_notfound: true
        asn_notfound: true
        only_geoloc_prefix:
          - BR
          - US/CA
        only_asn_number:
          - 7326
          - 16136
      metric_groups:
        disable:
          - cardinality
          - counters
          - top_geo
          - top_ips
input:
  input_type: pcap
  tap_selector:
    any:
      - key1: value1
      - key2: value2
  filter:
    bpf: net 192.168.1.0/24
  config:
    iface: wlo1
    host_spec: 192.168.1.0/24
    pcap_source: libpcap
    debug: true
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 5,
      "topn_count": 10
    },
    "modules": {
      "default_net": {
        "type": "net",
        "config": {
          "deep_sample_rate": 1,
          "num_periods": 2,
          "topn_count": 25
        },
        "filter": {
          "geoloc_notfound": true,
          "asn_notfound": true,
          "only_geoloc_prefix": [
            "BR",
            "US/CA"
          ],
          "only_asn_number": [
            7326,
            16136
          ]
        },
        "metric_groups": {
          "disable": [
            "cardinality",
            "counters",
            "top_geo",
            "top_ips"
          ]
        }
      }
    }
  },
  "input": {
    "input_type": "pcap",
    "tap_selector": {
      "any": [
        {
          "key1": "value1"
        },
        {
          "key2": "value2"
        }
      ]
    },
    "filter": {
      "bpf": "net 192.168.1.0/24"
    },
    "config": {
      "iface": "wlo1",
      "host_spec": "192.168.1.0/24",
      "pcap_source": "libpcap",
      "debug": true
    }
  },
  "kind": "collection"
}


Handler Type: "net"

Metrics Group
Metric Group Default
cardinality enabled
counters enabled
top_geo enabled
top_ips enabled


Configurations
  • Abstract configurations.

Filters
Filter Type Input
geoloc_notfound bool PCAP, DNSTAP
asn_notfound bool PCAP, DNSTAP
only_geoloc_prefix str[] PCAP, DNSTAP
only_asn_number str[] PCAP, DNSTAP

geoloc_notfound: bool

Input: PCAP

The source and destination IPs are used to determine the geolocation to know where the data is from and where it is going. When the IPs refer to a region found in the standard databases, the city, state and country (approximated) are returned. However, when it is not possible to determine the IP geolocation, a not found is returned.

The geoloc_notfound filter usage syntax is:

geoloc_notfound: true
{
  "geoloc_notfound": true
}


asn_notfound: bool

Input: PCAP

Based on source and destination IP, it is possible to determine the ASN (Autonomous System Number). When the IP of the source or destination belongs to some not known ASN in the standard databases, a not found is returned.

The asn_notfound filter usage syntax is:

asn_notfound: true
{
  "asn_notfound": true
}


only_geoloc_prefix: str[]

Input: PCAP

Source and destination IPs are used to determine the geolocation to know where the data is from and where it is going. In this way it is possible to filter the data considering the geolocation using the filter only_geoloc_prefix.

The only_geoloc_prefix filter usage syntax is:

only_geoloc_prefix: 
  - array
Example:
only_geoloc_prefix:
  - BR
  - US/CA

{
  "only_geoloc_prefix": [
    "array"
  ]
}
Example:
{
  "only_geoloc_prefix": [
    "BR",
    "US/CA"
  ]
}


only_asn_number: str[]

Input: PCAP

Based on source and destination IP, it is possible to determine the ASN (Autonomous System Number). In this way it is possible to filter the data considering a specific ASN using the filter only_asn_number.

The only_asn_number filter usage syntax is:

only_asn_number:
  - array
Example:
only_asn_number:
  - 7326
  - 16136

{
  "only_asn_number": [
    "array"
  ]
}
Example:
{
  "only_asn_number": [
    7326,
    16136
  ]
}

DHCP Analyzer (dhcp)

Example of policy with input pcap and handler DHCP
handlers:
  config:
    deep_sample_rate: 100
    num_periods: 8
    topn_count: 10
  modules:
    default_dhcp:
      type: dhcp
      config:
        deep_sample_rate: 1
        num_periods: 8
        topn_count: 25
input:
  input_type: pcap
  tap_selector:
    all:
      - key1: value1
      - key2: value
  filter:
    bpf: net 192.168.1.0/24
  config:
    iface: wlo1
    host_spec: 192.168.1.0/24
    pcap_source: libpcap
    debug: true
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 8,
      "topn_count": 10
    },
    "modules": {
      "default_dhcp": {
        "type": "dhcp",
        "config": {
          "deep_sample_rate": 1,
          "num_periods": 8,
          "topn_count": 25
        }
      }
    }
  },
  "input": {
    "input_type": "pcap",
    "tap_selector": {
      "all": [
        {
          "key1": "value1"
        },
        {
          "key2": "value"
        }
      ]
    },
    "filter": {
      "bpf": "net 192.168.1.0/24"
    },
    "config": {
      "iface": "wlo1",
      "host_spec": "192.168.1.0/24",
      "pcap_source": "libpcap",
      "debug": true
    }
  },
  "kind": "collection"
}


Handler Type: "dhcp"

Metrics Group
  • No metrics group available
Configurations
  • Abstract configurations.

Filters
  • No filters available.

BGP Analyzer (bgp)

Example of policy with input pcap and handler BGP
handlers:
  config:
    deep_sample_rate: 100
    num_periods: 8
    topn_count: 10
  modules:
    default_bgp:
      type: bgp
      config:
        deep_sample_rate: 1
        num_periods: 8
        topn_count: 25
input:
  input_type: pcap
  tap_selector:
    all:
      - key1: value1
      - key2: value
  filter:
    bpf: net 192.168.1.0/24
  config:
    iface: wlo1
    host_spec: 192.168.1.0/24
    pcap_source: libpcap
    debug: true
config:
  merge_like_handlers: true        
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 8,
      "topn_count": 10
    },
    "modules": {
      "default_bgp": {
        "type": "bgp",
        "config": {
          "deep_sample_rate": 1,
          "num_periods": 8,
          "topn_count": 25
        }
      }
    }
  },
  "input": {
    "input_type": "pcap",
    "tap_selector": {
      "all": [
        {
          "key1": "value1"
        },
        {
          "key2": "value"
        }
      ]
    },
    "filter": {
      "bpf": "net 192.168.1.0/24"
    },
    "config": {
      "iface": "wlo1",
      "host_spec": "192.168.1.0/24",
      "pcap_source": "libpcap",
      "debug": true
    }
  },
  "config": {
    "merge_like_handlers": true
  },
  "kind": "collection"
}


Handler Type: "bgp"

Metrics Group
  • No metrics group available
Configurations
  • Abstract configurations.

Filters
  • No filters available.

Packet Capture Analyzer (pcap)

Example of policy with input pcap and handler PCAP
handlers:
  config:
    deep_sample_rate: 100
    num_periods: 8
    topn_count: 10
  modules:
    default_pcap:
      type: pcap
      config:
        deep_sample_rate: 6
        num_periods: 3
        topn_count: 25
input:
  input_type: pcap
  tap: default_pcap
  filter:
    bpf: net 192.168.1.0/24
  config:
    iface: wlo1
    host_spec: 192.168.1.0/24
    pcap_source: libpcap
    debug: true
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 100,
      "num_periods": 8,
      "topn_count": 10
    },
    "modules": {
      "default_pcap": {
        "type": "pcap",
        "config": {
          "deep_sample_rate": 6,
          "num_periods": 3,
          "topn_count": 25
        }
      }
    }
  },
  "input": {
    "input_type": "pcap",
    "tap": "default_pcap",
    "filter": {
      "bpf": "net 192.168.1.0/24"
    },
    "config": {
      "iface": "wlo1",
      "host_spec": "192.168.1.0/24",
      "pcap_source": "libpcap",
      "debug": true
    }
  },
  "kind": "collection"
}


Handler Type: "pcap"

Metrics Group
  • No metrics group available.
Configurations
  • Abstract configurations.
Filters
  • No filters available.

Flow Analyzer (flow) [BETA]

Warning

Status: Beta. The metric names and configuration options may still change

Example of policy with input flow and handler FLOW
handlers:
    config:
        deep_sample_rate: 95
        num_periods: 6
        topn_count: 8
    modules:
        my_flow:
            type: flow
            config:
                sample_rate_scaling: false
                deep_sample_rate: 85
                num_periods: 5
                topn_count: 7
                first_filter_if_as_label: true
                device_map:
                    - router01,192.168.0.127,eth0,5
                    - router01,192.168.0.127,eth1,6
            metric_groups:
                disable:
                    - cardinality
                    - counters
                    - top_geo
                    - by_packets
                    - by_bytes
                    - conversations
                    - top_ports
                    - top_ips
                    - top_interfaces
                    - top_ips_ports
            filter:
                only_devices:
                    - 216.239.38.10/24
                    - 192.158.1.38/32
                only_ports:
                    - 10853
                    - 10860-10890
                only_interfaces:
                    - 10-16
                geoloc_notfound: true
                asn_notfound: true
input:
  input_type: flow
  tap: default_flow
kind: collection
{
  "handlers": {
    "config": {
      "deep_sample_rate": 95,
      "num_periods": 6,
      "topn_count": 8
    },
    "modules": {
      "my_flow": {
        "type": "flow",
        "config": {
          "sample_rate_scaling": false,
          "deep_sample_rate": 85,
          "num_periods": 5,
          "topn_count": 7,
          "first_filter_if_as_label": true,
          "device_map": [
            "router01,192.168.0.127,eth0,5",
            "router01,192.168.0.127,eth1,6"
          ]
        },
        "metric_groups": {
          "disable": [
            "cardinality",
            "counters",
            "top_geo",
            "by_packets",
            "by_bytes",
            "conversations",
            "top_ports",
            "top_ips",
            "top_interfaces",
            "top_ips_ports"
          ]
        },
        "filter": {
          "only_devices": [
            "216.239.38.10/24",
            "192.158.1.38/32"
          ],
          "only_ports": [
            10853,
            "10860-10890"
          ],
          "only_interfaces": [
            "10-16"
          ],
          "geoloc_notfound": true,
          "asn_notfound": true
        }
      }
    }
  },
  "input": {
    "input_type": "flow",
    "tap": "default_flow"
  },
  "kind": "collection"
}


Handler Type: "flow"

Metrics Group
Metric Group Default
cardinality enabled
counters enabled
by_packets enabled
by_bytes enabled
top_ips enabled
top_ports enabled
top_ips_ports enabled
top_geo disabled
conversations disabled
top_interfaces disabled


Configurations
  • sample_rate_scaling: bool
  • first_filter_if_as_label: bool
  • device_map: str[]
  • recorded_stream: #todo
  • Abstract configurations.

sample_rate_scaling

By default, flow metrics are generated by an approximation based on sampling the data. 1 packet every N is analyzed and the prediction of the entire population is made from the sample. If you want to see exactly all the exact data, you can disable sample_rate_scaling.

The sample_rate_scaling filter usage syntax is:

sample_rate_scaling: false
{
  "sample_rate_scaling": false
}

first_filter_if_as_label

This configuration requires the only_interfaces filter to be active (true). If this setting is true, the interfaces will be used as labels for the metrics.

The first_filter_if_as_label filter usage syntax is:

first_filter_if_as_label: true
{
"first_filter_if_as_label": true
}

device_map

This configuration allows the user to assign a custom name to devices and/or interfaces. You can also set only the device, as long as the pair [custom_name, default_identifier] is passed.

The device_map filter usage syntax is:

device_map:
  - device_custom_name,device_ip,interface_custom_name,interface_index
{
  "device_map": [
    "device_custom_name,device_ip,interface_custom_name,interface_index"
  ]
}
Filters
Filter Type Input
only_devices str[] FLOW
only_ips str[] FLOW
only_ports str[] FLOW
only_interfaces str[] FLOW
geoloc_notfound bool FLOW
asn_notfound bool FLOW

only_devices: str[]

Input: FLOW

Considering a flow traffic, the same port can be monitoring data from different routers or/and switches. If you want to filter the flow data coming from a specific device, the only_devices filter should be used. CIDR (Inter-Domain Routing Classes) ranges are supported on this filter.
The difference between only_devices and only_ips is that while this one filters the ids of the device that is sending the data, the other filters the ips that are communicating with each other (source or destination).

The only_devices filter usage syntax is:

only_devices:
  - array
Example:
only_devices:
  - 216.239.38.10/24
  - 192.158.1.38/32

{
  "only_devices": [
    "array"
  ]
}
Example:
{
  "only_devices": [
    "216.239.38.10/24",
    "192.158.1.38/32"
  ]
}


only_ips: str[]

Input: FLOW

To filter data only from certain source OR destination, you can use only_ips filter, for which CIDR (Inter-Domain Routing Classes) ranges are supported.

The only_ips filter usage syntax is:

only_ips:
  - array
Example:
only_ips:
  - 192.168.1.1/24
  - 192.158.1.38/32

{
  "only_ips": [
    "array"
  ]
}
Example:
{
  "only_ips": [
    "192.168.1.1/24",
    "192.158.1.38/32"
  ]
}


only_ports: str[]

Input: FLOW

only_ports filter only filters data being sent to or received on one of the selected IP ports (or range of ports).

The only_ports filter usage syntax is:

only_ports:
  - array
Example:
only_ports:
  - 10853 #port can be passed as int
  - "10854" #port can be passed as str
  - 10860-10890 #range from 10860 to 10890. All ports in this interval will be accepted

{
  "only_ports": [
    "array"
  ]
}
Example:
{
  "only_ports": [
    10853,
    "10854",
    "10860-10890"
  ]
}


only_interfaces: str

Input: FLOW

only_interfaces filters data by device ports (not IP ports). In this way, it is possible to filter data referring to a specific type of network connected to the corresponding device port.

The only_interfaces filter usage syntax is:

only_interfaces:
  - array
Example:
only_interfaces:
  - 10 #port can be passed as int
  - "11" #port can be passed as str
  - 12-16 #range from 12 to 16. All ports in this interval will be accepted

{
  "only_interfaces": [
    "array"
  ]
}
Example:
{
  "only_interfaces": [
    10,
    "11",
    "12-16"
  ]
}


geoloc_notfound: bool

Input: FLOW

The source and destination IPs are used to determine the geolocation to know where the data is from and where it is going. When the IPs refer to a region found in the standard databases, the city, state and country (approximated) are returned. However, when it is not possible to determine the IP geolocation, a not found is returned.

The geoloc_notfound filter usage syntax is:

geoloc_notfound: true
{
  "geoloc_notfound": true
}


asn_notfound: bool

Input: FLOW

Based on source and destination IP, it is possible to determine the ASN (Autonomous System Number). When the IP of the source or destination belongs to some not known ASN in the standard databases, a not found is returned.

The asn_notfound filter usage syntax is:

asn_notfound: true
{
  "asn_notfound": true
}

Netprobe [BETA]

Warning

Status: Beta. The metric names and configuration options may still change

Example of policy with input netprobe and handler NETPROBE
handlers:
  modules:
    default_netprobe:
      type: netprobe
      metric_groups:
        enable:
          - counters
          - quantiles
          - histograms
input:
  input_type: netprobe
  tap: default_netprobe
  config:
    test_type: ping
    interval_msec: 2000
    timeout_msec: 1000
    packets_per_test: 10
    packets_interval_msec: 25
    packet_payload_size: 56
    targets:
      www.google.com:
        target: www.google.com
      orb_community:
        target: orb.community 
kind: collection
{
  "handlers": {
    "modules": {
      "default_netprobe": {
        "type": "netprobe",
        "metric_groups": {
          "enable": [
            "counters",
            "quantiles",
            "histograms"
          ]
        }
      }
    }
  },
  "input": {
    "input_type": "netprobe",
    "tap": "default_netprobe",
    "config": {
      "test_type": "ping",
      "interval_msec": 2000,
      "timeout_msec": 1000,
      "packets_per_test": 10,
      "packets_interval_msec": 25,
      "packet_payload_size": 56,
      "targets": {
        "www.google.com": {
          "target": "www.google.com"
        },
        "orb_community": {
          "target": "orb.community"
        }
      }
    }
  },
  "kind": "collection"
}


Handler Type: "netprobe"

Metrics Group
Metric Group Default
quantiles disabled
counters enabled
histograms enabled
Configurations
  • Abstract configurations.

  • In netprobe policies it makes a lot of sense to use the settings from the input directly in the policy, since the settings are more related to the probe than the device the orb agent is running on. Therefore, it is worth reinforcing here the ability to override all tap settings in the policy. See here the available configurations for netprobe.
Filters
  • No filters available.