Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Onboarding

Registration

  1. Contact info@dnstapir.se (?)
  2. Provide User/Organisation, contact person, contact information (email/phone)
  3. Provide PGP key, Signal user handle or other trusted out-of-band channel.

Contract

  • In the test phase of DNS TAPIR all users need a contract with the TAPIR Core operations partner (The Swedish Internet Foundation, IIS)
  • Consumer only might not need this in the future.

Enrollment Key

  • After the contract is signed, the organisation/user will receive enrollments credentials from a DNS TAPIR representative on a trusted out-of-band channel.

Consumer only

  • Not available in first phases

Offboarding

Sad to see you leave but when all other options are not available this might happen

  1. Terminate the contract with the operations provider
  2. Keys will be de-activated and prevented from renewal. This will be matched with the termination date of contract.
  3. Uninstall TAPIR EDM, TAPIR POP, TAPIR-CLI
  4. Data will no longer be sent to TAPIR Core

Getting the Packages

DNS TAPIR provides three packages for an Edge installation: tapir-pop, tapir-edm and tapir-cli. They are built using Fedora's public Copr instance with the @dnstapir group. Currently, packages are being built for EPEL 10, EPEL 9, Fedora 42 and OpenSUSE Leap 15.6.

Packages in the @dnstapir/edge-testing repo are signed with this PGP key:

07FC 9787 0134 6ED4 522A 17E7 2C4D 4FAC 02CF 0AC2

Packaging code lives side-by-side with the source code in the respecive repos:

Enable the repositories in your package manager:

dnf

dnf copr enable @dnstapir/edge-testing

yum

TODO

zypper

TODO

And install them:

dnf

TODO

sudo dnf install tapir-pop tapir-cli tapir-edm

yum

TODO

zypper

TODO

Managing permissions

Three system users, tapir-pop, tapir-edm and tapir-renew, and a group, dnstapir, will have been created. Add your administrator user to this group for easier bootstrapping and maintenance:

sudo usermod -a -G dnstapir <USERNAME>

Log out and back in and make sure the new group membership is in effect before proceeding.

Enrolling with the DNS TAPIR Node Manager

To connect with DNS TAPIR Core, an Edge node needs to be enrolled. You should have received enrollments credentials from a DNS TAPIR representative on a trusted out-of-band channel. They will look something like the following:

{
    "name":"enroll-example.test.dnstapir.se",
    "key":{
        "kty":"OKP",
        "kid":"123456789012345678901234",
        "alg":"EdDSA",
        "crv":"Ed25519",
        "x":"ABCD_EFGHIJKLMNO_PQRSTUVW_XYZ123456789_12345",
        "d":"abcdefghijklmno_pqrstuvwxyz_123456789012345"
    },
    "nodeman_url":"https://nodeman.test.dnstapir.se/"
}

Store the credentials in a file on the node that is to be enrolled. Then run:

sudo -g dnstapir tapir-cli --standalone enroll --enroll-credentials <PATH TO ENROLL CREDS>

The reason for running with sudo -g dnstapir is that, apart from exchanging cryptographic material with DNS TAPIR Core, the above enrollment command also generates a number of config files under /etc/dnstapir (by default). They need to have dnstapir as the group owner so that they can be used by the three system users mentioned before.

Edits to the Configuration Boilerplate

The configuration generated in the enrollment step contains sensible defaults for most deployments. However, some final touches need to be made before it can be properly integrated with a recursive resolver and with DNS TAPIR Core. By default, these files will be generated under /etc/dnstapir. This guide uses the default.

pop-outputs.yaml

Edit this file where annotated (1 location) with the destination to which POP will be sending DNS NOTIFY messages about changes to the RPZ zone it has generated based on the observations from Core and on the local policies.

tapir-pop.yaml

Edit this file where annotated (1 location) with the interface on which POP will listen to incoming zone transfer requests for the RPZ zone it has generated.

tapir-edm.toml

Edit this file where annotated (2 locations) with a strong secret/password and a DNSTAP interface. The secret is used when pseudonymizing the recursive traffic with Crypto-PAn. The DNSTAP interface is the IP + port where EDM listens for DNSTAP traffic from the recursive resolver.

Edge services

In addition to a recursive resolver, an Edge installation consists of three services.

tapir-pop

The tapir-pop service is provided by the tapir-pop package. It consists of a daemon process that communicates with a DNS TAPIR Core instance over MQTT and with a recursive resolver using zone transfers. It receives observations about domain names over MQTT and, based on a locally configured policy, produces an RPZ zone which it transfers to a recursive resolver.

tapir-renew

The tapir-renew service is installed by the tapir-cli package. It automates the process of renewing mTLS certificates (used to secure the MQTT connection) by issuing tapir-cli commands on a systemd timer.

tapir-edm

The tapir-edm service is installed by the tapir-edm package. It consists of a daemon process that communicates with a recursive resolver using DNSTAP and a DNS TAPIR Core instance over MQTT and HTTPS. It receives DNSTAP data from the resolver, which it anonymizes and sends to the Core instance in aggregates using HTTPS. Certain events, such as domain names being encountered for the first time, is sent over MQTT to the same Core instance.

Start the services

sudo systemctl start tapir-pop
sudo systemctl start tapir-edm
sudo systemctl start tapir-renew

Enable the services

sudo systemctl enable tapir-pop
sudo systemctl enable tapir-edm
sudo systemctl enable tapir-renew

Verification

  • Verify that TAPIR Core receives histograms from TAPIR EDM: ....
  • Verify that TAPIR POP receives observations from TAPIR Core: ....

TAPIR-POP: DNS TAPIR Policy Processor

The DNS TAPIR Policy Processor, TAPIR-POP, is the component that processes the intelligence data from the TAPIR-Core (and possibly other sources) and applies local policy to reach a filtering decision.

It is the connection between TAPIR Core and the Edge platform. It manages local configurations and gets updates from TAPIR Core with alerts and config changes.

TAPIR-POP is responsible for the task of integrating all intelligence sources into a single Response Policy Zone (RPZ) that is as compact as possible. The RPZ file is used by the DNS resolver to implement blocklists and other policy-related functions.

A unified single RPZ zone instead of multiple sources

TAPIR-POP presents a single output with all conflicts resolved, rather than feeding the resolver multiple sources of data from which to look for policy guidance, where sources can even be conflicting (eg. a domainname may be flagged by one source but allowlisted by another).

The result is smaller, as no allowlisting information is needed for the resolver.

TAPIR-POP supports a local policy configuration

TAPIR-POP is able to apply further policy to the intelligence data, based on a local policy configuration. To enable the resolver operator to design a suitable threat policy TAPIR-POP uses a number of concepts:

  • lists: there are three types of lists of domain names:

    • allowlists (names that must not be blocked)
    • denylists (names that must be blocked)
    • doubtlists (names that should perhaps be blocked)

  • observations: these are attributes of a suspicious domain name. In reality whether a particular domain name should be blocked or not is not an absolute, it is a question of propabilities. Therefore, rather than a binary directive, "this name must be blocked", some intelligence sources, including DNS TAPIR, present the resolver operator with observed attributes of the name. Examples include:

    • the name has only been observed on the Internet for a short time
    • the name draws huge query traffic
    • the name resolves to an IP address known to host bad things, etc.

  • sources: TAPIR-POP supports the following types of sources for intelligence data:

    • RPZ: imported via AXFR or IXFR. TAPIR-POP understands DNS NOTIFY.
    • MQTT: DNS TAPIR Core Analyser sends out rapid updates for small numbers of names via an MQTT message bus infrastructure.
    • DAWG: Directed Acyclic Word Graphs are extremely compact data structures. TAPIR-POP is able to mmap very large lists in DAWG format which is used for large allowlists.
    • CSV Files: Text files on local disk, either with just domain names, or in CSV format are supported.
    • HTTPS: To bootstrap an intelligence feed that only distributes deltas (like DNS TAPIR, over MQTT), TAPIR-POP can bootstrap the current state of the complete feed via HTTPS.

  • outputs: TAPIR-POP outputs RPZ zones to one or several recipients. Both AXFR and IXFR is supported.

Overview of the TAPIR-POP policy

The resulting policy has the following structure (in order of precedence):

  • no allowlisted name is ever included.
  • blocklisted names are always included, together with a configurable RPZ action.
  • doubtlisted names that have particular tags that the resolver operator chooses are included, together with a configurable RPZ action.
  • the same doubtlisted name that appear in N distinct intelligence feeds is included, where N is configureable, as is the RPZ action.
  • a doubtlisted name that has M or more tags is included, where both M and the action are configurable.

Logging

Logging is done by writing either to stdout or stderr and letting systemd handle it. Logging will consist of four verbosity levels: Debug, Info, Warning and Error. Each component is responsible for its own logging.

Telemetry

Telemetry is done by publishing on a dedicated MQTT topic. Each component has its own topic and is responsible for publishing its own data. Most of the data will be aggregated statistics such as packet counters.

"Exceptional" Events

Some events are of special interest, both to the operator of a particular Edge deployment and to the Core operator. An example of such an event would be failure to renew a TLS certificate. As such, those events are written BOTH to the syslog and published over the MQTT telemetry topic by the component that observes the event. The component also assigns an identifier that is visible both in the log and in the telemetry packet so that the two can be associated.

Example of multi-new observation

sequenceDiagram
    participant NATS Server
    participant microservice
    participant NATS KV-Store

    microservice->>+NATS Server: Subscribe(EVENT_NEW_QNAME)
    note over microservice,NATS Server: ...some time passes...
    NATS Server->>microservice: Publish(EVENT_NEW_QNAME, "new.example.com.")
    microservice->>+NATS KV-Store: Request("new.example.com.")
    note over microservice,NATS KV-Store: ...gets collected data about the domain...
    microservice->>microservice: Has "new.example.com." been observed as new by other resolvers recently?
    microservice->>NATS Server: Publish(OBSERVATION_MULTI_NEW, "new.example.com.")

Example of ramp observation

sequenceDiagram
    participant NATS Server
    participant Data Loader
    participant S3
    participant microservice

    NATS Server->>Data Loader: Publish(EVENT_NEW_AGGREGATE)
    Data Loader->>S3: Get(NEW_AGGREGATE)
    Data Loader->>Data Loader: Create histogram
    Data Loader->>S3: Post(Histogram)
    S3-->>microservice: Publish(EVENT_NEW_HIST)
    microservice->>microservice: For domain in hist, hasRamp?
    microservice->>NATS Server: Publish(OBSERVATION_RAMP, "evil.hula.se")
    note over microservice: ...Publish ramping domains...
    microservice->>NATS Server: Publish(OBSERVATION_RAMP, "z5.nu")

Communication pattern for "NOT well-known" domains

flowchart
    EDM-->|2, EVENT_NEW_QNAME, MQTT, mTLS, RFC 7515|bridge
    bridge-->|7, OBSERVATION_RAMP, MQTT, mTLS, RFC 7515|POP

    subgraph CORE
    bridge-->|3, EVENT_NEW_QNAME|NATS_Server
    NATS_Server-->|4, EVENT_NEW_QNAME|MULTINEW_microservice
    MULTINEW_microservice-->|5, OBSERVATION_MULTI_NEW|NATS_Server
    NATS_Server-->|6, OBSERVATION_MULTI_NEW|bridge
    end

    subgraph EDGE
    POP-->|8, RPZ XFR|RecResolver
    RecResolver-->|1, DNSTAP|EDM
    end

Communication pattern for "well-known" domains

There is some discrepancy between this image and the sequence diagram for the ramp observation has the data loader component has not been taken into account here.

flowchart
    EDM-->|2, one-minute aggregate, HTTPS, mTLS, RFC 7515|aggrec
    bridge-->|7, OBSERVATION_RAMP, MQTT, mTLS, RFC 7515|POP

    subgraph CORE
    aggrec-->|3, Publish EVENT_NEW_AGGREGATE|NATS_Server
    NATS_Server-->|4, Publish EVENT_NEW_AGGREGATE|RAMP_microservice
    RAMP_microservice-->|5, Publish OBSERVATION_RAMP|NATS_Server
    NATS_Server-->|6, OBSERVATION_RAMP|bridge
    end

    subgraph EDGE
    POP-->|8, RPZ XFR|RecResolver
    RecResolver-->|1, DNSTAP|EDM
    end