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_versionis the field responsible for allowing different schema versions and backward compatibility. Default should be "1.0". -
Format
Theformatspecifies in which format the policy data will be written. The options arejsonandyaml.jsonis 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
dnstap_msg_type: auth
{
"dnstap_msg_type": "str"
}
{
"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
only_geoloc_prefix:
- BR
- US/CA
{
"only_geoloc_prefix": [
"array"
]
}
{
"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
only_asn_number:
- 7326
- 16136
{
"only_asn_number": [
"array"
]
}
{
"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
only_devices:
- 216.239.38.10/24
- 192.158.1.38/32
{
"only_devices": [
"array"
]
}
{
"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
only_ips:
- 192.168.1.1/24
- 192.158.1.38/32
{
"only_ips": [
"array"
]
}
{
"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
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"
]
}
{
"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
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"
]
}
{
"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.