policy
policy is the Policy Enforcement Point (PEP) for Themis project implemented as CoreDNS plugin.
Syntax
policy {
endpoint ADDR_1 ADDR_2 ... ADDR_N
streams COUNT
connection_timeout TIMEOUT
max_request_size [[auto] SIZE]
max_response_attributes auto | COUNT
cache [TTL [SIZE]]
edns0 CODE NAME [SRCTYPE] [SIZE START END]
validation1 ATTR_1 ATTR_2 ... ATTR_N
validation2 ATTR_1 ATTR_2 ... ATTR_N
default_decision ATTR_1 ATTR_2 ... ATTR_N
metrics ATTR_1 ATTR_2 ... ATTR_N
dnstap LEVEL ATTR_1 ATTR_2 ... ATTR_N
passthrough SUFFIX_1 SUFFIX_2 ... SUFFIX_N
debug_query_suffix SUFFIX
debug_id ID
log
own_ip_endpoint ADDR
}
Option endpoint defines addresses of PDP servers.
Option streams sets number of gRPC streams to be used in each PDP connection.
Option connection_timeout sets timeout for query validation when no PDP server is available. Negative value or "no" keyword means wait forever. This is default behavior. With zero timeout validation fails instantly if there is no PDP server. The option works only if gRPC streams number is greater than 0.
Option max_request_size sets maximum buffer size in bytes for serialized request. Too high limit makes the plugin to allocate unnecessary memory while too small can lead to buffer overflow errors on validation. With setting auto
plugin automatically allocates required amount of bytes for each request. In case of both auto
and SIZE defined, the SIZE doesn't limit request buffer but used for cache allocations.
Option max_response_attributes defines the limit of attribute number expected in PDP response. If value is auto
the appropriate buffer for all PDP response attributes is allocated automatically.
Option cache enables decision cache. The default value for TTL is 10 minutes. SIZE (in megabytes) limits the memory cache can use. If SIZE is not provided the cache can grow until application crashes due to out of memory.
Option edns0 is used for parsing edns0 options into PDP attributes, option with code CODE is parsed as attribute with name NAME. CODE can be defined as octal, decimal or hexadecimal value. Hexadecimal numbers should start with prefix 0x
, e.g 0xfff5
, octal numbers should start with 0
, e.g. 0177765
. SRCTYPE defines encoding if edns0 data, valid values are hex
(default), bytes
, ip
. Params SIZE, START, END is supported only for SRCTYPE = hex
. Setting param SIZE to value > 0 enables edns0 option data size check. Param START and END (last data byte index + 1) allows picking out a particular part of edns0 option data into a separate attribute. Option edns0 can be used repeatedly to define several ends0 attributes
Option validation1 defines a set of attributes to be sent to PDP for validation before resolving domain name.
Option validation2 defines a set of attributes to be sent to PDP for validation after resolving domain name.
Option default_decision defines default values for some attributes in case if PDP request was failed.
Option metrics defines the attributes for which metric counters to be generated. The metric counters hold the number of recently received queries per attribute/value and look like below.
coredns_policy_recent_queries{attribute="uid",value="9e868487da91153c"} 153
The counter is decremented when queries get expired. The default expiration period is 1 minute. If no new query is received during the expiration period for the given attribute/value then the related counter is removed to save memory.
Option dnstap defines the attributes to be included in extra field of DNStap message if those attributes are available. The option can be used repeatedly with different values of LEVEL parameter to define different sets of dnstap attributes. Value of LEVEL should be in range [0..2]. The level of dnstap logging is defined by PDP response with log
attribute. The default value for log level is 0.
The ATTR_N parameters have the syntax like <name>[=<value>]
where value can be one of quoted string, number or IP address. See examples below.
Option passthrough defines set of domain name suffixes. Domain that has one of these suffixes is resolved without validation. Each suffix should have dot at the end.
Option debug_query_suffix enables debug query feature. Debug query returns some debug information about query processing in text representation. SUFFIX should have dot at the end. Debug query uses protocol CHAOS and TXT resource record. See below an example of dig command for debug query.
dig @127.0.0.1 test.com.debug txt ch
Option debug_id defines a string to be sent with debug response to identify a CoreDNS instance.
Option log enables logging PDP request and response attributes
Option own_ip_endpoint defines the endpoint for which debug requests to it will be responded with the client's own IP(v4/v6).
Predefined attributes
Policy plugin recognizes the following predefined attributes:
-
domain_name (type string) - initialized with domain name taken from DNS query.
-
dns_qtype (type integer) - initialized with numeric code of query type taken from DNS query. For example, code 1 corresponds to type A, code 28 corresponds to type AAAA, code 5 corresponds to CNAME.
-
source_ip (type address) - initialized with IP address from which the DNS query was received.
-
address (type address) - assigned with resolved IP address corresponding to query domain name (the first A or AAAA record in DNS response).
-
policy_action (type integer) - can be assigned with a value defined in default_decision option or with a value taken from PDP response. The valid values are 1 - Drop, 2 - Allow, 3 - Block, 4 - Redirect, 5 - Refuse.
-
redirect_to (type string) - can be assigned with a value defined in default_decision option or with a value taken from PDP response. The valid formats are string representation of IPv4 or IPv6 or domain name.
-
log (type integer) - can be assigned with a value defined in default_decision option or with a value taken from PDP response. The attribute defines the dnstap log level, i.e. the attribute set to be sent with DNStap message. See option dnstap above. The valid range is from 0 to 2 (inclusive).
Example
policy {
endpoint 10.0.0.7:1234, 10.0.0.8:1234
streams 100
connection_timeout 1s
edns0 0xffee client_id hex 32 0 32
edns0 0xffee group_id hex 32 16 32
edns0 0xffef uid
edns0 0xffea client_ip ip
edns0 0xffeb client_name bytes
validation1 type="query" domain_name
validation2 type="response" address
default_decision policy_action=2 log=1 client_ip=192.168.0.101
metrics client_name
dnstap 0 policy_action
dnstap 1 policy_action client_id
dnstap 2 policy_action client_id group_id uid
passthrough mycompanyname.com. mycompanyname.org.
debug_query_suffix debug.
debug_id instance_1
log
}
In example above the edns0 options with code 0xffee is splitted into two attributes - client_id
(first 16 bytes) and group_id
(last 16 bytes). Entire option should have size 32 bytes otherwise client_id
and group_id
will not be parsed.