dnsviz-probe(1)

📦
version 0.11.1 · 5 versions
, in debian trixie, fedora 43, fedora 44, nixos 26.05, ubuntu resolute, ubuntu stonking

💖 NAME 💖

dnsviz-graph - graph the assessment of diagnostic DNS queries

bestie, you're reading the dnsviz-probe(1) page from the General Commands Manual, and I'm gonna walk you through every single thing on it. no skimming, no skipping, we're doing the whole thing together. 🫶

✨ SYNOPSIS ✨

dnsviz graph [ options ] [ domain_name... ]

🌸 DESCRIPTION 🌸

so here's the vibe: dnsviz graph takes the results of diagnostic DNS queries that somebody already ran — like, say, with dnsviz-probe(1) — and it processes them to assess the health of the DNS deployments for one or more domain names you give it. 🩺 then it shows you those results in one of several graphical formats so you can actually diagnose what's going on. it's giving "doctor visit but for DNS."

where does the diagnostic query input come from? either a file you specify with -r, or standard input. that's the whole menu.

now, the domain names you want processed can get to the command in a few different ways:

  • passed as command-line arguments
  • read from a file (that's the -f option)
  • or just implied by the diagnostic query input itself

that last one? the preferred methodology, and honestly the simplest. use it unless your input has diagnostic queries for multiple domain names and you only want to process a subset of them. 🎯

here's the rule, lowkey important:

  • if -f is not used and you give no domain names on the command line, then the domain names to be processed get extracted from the diagnostic query input.
  • if the -f option is used, then names may not be specified on the command line. periodt. 🙅‍♀️

the domain names you pass in are fully-qualified domain names, like example.com, www.example.com, _443._tcp.example.com, 1.2.0.192.in-addr.arpa, or 8.b.d.0.1.0.0.2.ip6.arpa. and because it's already implied that specified domain names are fully qualified, you do not need a trailing dot. no cap.

and the output? it's the image of a directed graph created using dot(1). ✨ and the "html" format makes that image interactive using javascript libraries that ship with this software. iconic.

💅 OPTIONS 💅

  • -f, --names-file filename — read names from a file, one name per line, instead of from the command line. and if you use this option, names may not be specified on the command line. (yes, again. it's that serious. 😌)
  • -r, --input-file filename — read the diagnostic query input from the file you name, instead of from standard input. 🍓
  • -t, --trusted-keys-file filename — use trusted keys from this file when processing diagnostic queries. this overrides the default behavior of using the installed keys for the root zone.

the format of this file is master zone file format, and it should contain DNSKEY records that correspond to one or more trusted keys for one or more DNS zones.

this option may be used multiple times on the command line. stack 'em. 💫

  • -a, --algorithms alg[,alg...] — support only the DNSSEC algorithms specified. if you use this option, any algorithms not specified will appear as "unsupported." the status of any RRSIG records corresponding to unsupported algorithms will be unknown. and additionally, when a zone has only DS records with unsupported algorithms, the zone is treated as "insecure" — assuming the DS records are properly authenticated. 🔍
  • -d, --digest-algorithms digest_alg[,digest_alg...] — support only the DNSSEC digest algorithms specified. if you use this option, any digest algorithms not specified will appear as "unsupported." the status of any DS records corresponding to unsupported digest algorithms will be unknown. and additionally, when a zone has only DS records with unsupported digest algorithms, the zone is treated as "insecure" — assuming the DS records are properly authenticated. same energy as -a but for digests, slay. 🧚
  • --ignore-rfc8624 — ignore errors associated with RFC 8624, DNSSEC algorithm implementation requirements. RFC 8624 designates some DNSSEC signing algorithms and some DS digest algorithms as prohibited ("MUST NOT") or not recommended for validation and/or signing. if you use this option, then no warnings will be issued, and the code will still assess their cryptographic status rather than ignoring them. 👑
  • --ignore-rfc9276 — ignore errors associated with RFC 9276, NSEC3 parameter settings. RFC 9276 specifies that if NSEC3 is used, the iterations count must be 0 and the salt length must be 0. if you use this option, then no warnings will be issued for NSEC3 records that violate this specification. 🌈
  • -C, --enforce-cookies — enforce DNS cookies strictly. require a server to return a "BADCOOKIE" response when a query contains a COOKIE option with no server cookie or with an invalid server cookie. 🍪
  • -P, --allow-private — allow private IP addresses for authoritative DNS servers. by default, if the IP address corresponding to an authoritative server is in IP address space designated as "private", it is flagged as an error. but there are some cases where this is allowed — for example, if the diagnostic queries are issued to servers in an experimental environment, this might be permissible. 🙈
  • --trust-cdnskey-cds — trust all CDNSKEY and CDS records, even if they are not "signed with a key that is represented in both the current DNSKEY and DS RRsets" (RFC 7344). this is allowed if "the Parent uses the CDS or CDNSKEY RRset for initial enrollment; in that case, the Parent validates the CDS/CDNSKEY through some other means" (RFC 7344). and because there is no way for DNSViz to discover the out-of-band means with which the parent might have validated the CDNSKEY and/or CDS records, this trust is signaled with the use of the --trust-cdnskey-cds command-line option. 🤝
  • --multi-signer — don't issue errors for missing KSKs with DS RRs. typically an error is issued if a given DNSKEY is not found in the DNSKEY RRset returned by one or more servers. if --multi-signer is specified, then no error is issued in the case that 1) the DNSKEY is not signing any non-DNSKEY RRsets (i.e., is a zone-signing key or ZSK) and 2) the DNSKEY corresponds to a DS record in the parent. this corresponds to the Model 2 use case in RFC 8901. 🔥
  • -R, --rr-types type[,type...] — process queries of only the specified type(s) (e.g., A, AAAA). the default is to process all types queried as part of the diagnostic input. 🎀
  • -e, --redundant-edges — do not remove redundant RRSIG edges from the graph.

as described in "RRSIGs", some edges representing RRSIGs made by KSKs are removed from the graph to reduce visual complexity. if you use this option, those edges are preserved. 🦋

  • -O, --derive-filename — save the output to a file, whose name is derived from the format (i.e., the one provided to -T) and the domain name.

if you use this option when the diagnostic queries of multiple domain names are being processed, a file will be created for each domain name processed. one for you, one for you, one for you 💖

  • -o, --output-file filename — write the output to the specified file instead of to standard output, which is the default.

if you use this option when the diagnostic queries of multiple domain names are being processed, a single file (the one specified) will be created, which will contain the collective output for all domain names processed. 📚

  • -T, --output-format format — use the specified output format for the graph, selected from among the following: "dot", "png", "jpg", "svg", and "html". the default is "dot". ✨
  • -h, --help — display the usage and exit. the classic. 👋

👑 OUTPUT 👑

the conventions used in the graphical format are described below. buckle up, bestie, we're going visual. 🎨

🩵 Zones

nodes in DNSViz are clustered by the zone to which the represented information belongs. each zone is labeled with the name of the zone origin and the time at which the zone was last analyzed. 🕐

🩵 Delegations

thick lines between zones denote delegations of namespace from one zone to another, as indicated by the presence of NS (name server) resource records (RRs) for the delegated namespace. the status of the delegation is reflected in its color and style of the edge. 🌈

  • insecure — a black, solid line between zones indicates a standard, insecure delegation (i.e., sans DNSSEC).
  • lame — if the designated name servers for a zone cannot not be properly resolved, or if the servers do not properly respond to queries, then the delegation is considered lame and is represented by a dashed, yellow line.
  • incomplete — if the delegation is incomplete, as indicated by the presence of NS records in the zone itself but not in its parent zone, then the delegation is represented by a dashed, yellow line.
  • secure — if the delegation is secure by DNSSEC standards, then the delegation is represented by a solid, blue line. 💙
  • bogus — if the delegation is bogus by DNSSEC standards, then the delegation is represented by a dashed, red line. 🚩

🩵 RRsets

resource record sets (RRsets) returned in the response (usually in the answer section) are represented as rectangular nodes with rounded corners. among the most common record types are SOA (start of authority), A (IPv4 address), AAAA (IPv6 address), MX (mail exchange), and CNAME (canonical name). 📦

RRsets that are specific to DNSSEC — such as the DNSKEY, DS, RRSIG, NSEC and NSEC3 RR types — are represented as other node types, as specified elsewhere in this guide. 👀

🩵 Aliases

aliases resulting from CNAME RRs are represented by a black edge from one RRset (with the alias name) to another (with the canonical name). 🔗

🩵 DNAME

a DNAME RR is used to alias an entire namespace into another. DNAME responses include synthesized CNAME RRs for the aliasing directed by the DNAME RR.

DNAME records are shown in DNSViz with their respective CNAME records. the status of the CNAME synthesis is reflected in the color of the edge. 🎨

  • valid — a solid, blue line between the DNAME node and the CNAME node indicates that the DNAME expansion was valid.
  • invalid — a solid, red line between the DNAME node and the CNAME node indicates that the DNAME expansion was invalid.

🩵 Negative Responses

if the response to a query is a name error (NXDOMAIN), this negative response is represented by a rectangular node with diagonals drawn at each corner, and with a dashed border, lighter in color. a node representing the SOA RR returned in the negative response (if any) is also included. 😭

if the response to a query has a NOERROR status but contains no answer data (NO DATA) for the type, this negative response is represented by a rectangular node with rounded corners, and with a dashed border, lighter in color. a node representing the SOA RR returned in the negative response (if any) is also included. 🫥

💖 DNSKEY RRs 💖

Okay so DNSKEY RRs are literally the main character energy of DNSSEC. They carry the public key plus meta info so resolvers can validate signatures made by the matching private keys. No cap.

In DNSViz, every DNSKEY RR shows up as an elliptical node inside the zone it belongs to. Each node gets decorated based on the attributes of that DNSKEY RR. Let's vibe check the decorations:

  • SEP bit — A gray fill means the Secure Entry Point (SEP) bit is set in the flags field of the DNSKEY RR.

This bit is typically used to designate a DNSKEY for usage as a key signing key (KSK) — a DNSKEY that signs the DNSKEY RRset of a zone, providing a secure entry point into a zone via DS RRs or a trust anchor at the resolver. Iconic.

  • revoke bit — A thick border means the revoke bit is set in the flags field of the DNSKEY RR.

Resolvers that implement the trust anchor rollover procedures documented in RFC 5011 recognize the revoke bit as a signal that the DNSKEY should no longer be used as a trust anchor by the resolver. For a DNSKEY to be properly revoked, it must also be self-signing (i.e., used to sign the DNSKEY RRset), which proves that the revocation was made by a party that has access to the private key. Periodt.

  • trust anchor — A double border means the DNSKEY has been designated as a trust anchor.

A trust anchor must be self-signing (i.e., used to sign the DNSKEY RRset). That's the rule, bestie.

💅 DS RRs 💅

DS (delegation signer) RRs live in the parent of a signed zone to establish a SEP into the zone. Each DS RR specifies an algorithm and key tag corresponding to a DNSKEY RR in the signed zone and includes a cryptographic hash of that DNSKEY RR.

In DNSViz, DS RRs with the same DNSKEY algorithm and key tag are typically displayed as a single node since they usually correspond to the same DNSKEY RR with different digest algorithms. The status of the DS RRs is reflected in the color and style of the edge. Let's break it down:

  • valid — A blue-colored arrow pointing from DS to DNSKEY indicates that the digest contained in each of the DS RRs is valid, and corresponds to an existing DNSKEY. Slay.
  • invalid digest — A solid red line from DS to DNSKEY indicates that a DNSKEY exists matching the algorithm and key tag of the DS RR, but the digest of the DNSKEY in the DS RR does not match. Not the vibe.
  • indeterminate - no DNSKEY — A dashed gray line from DS to a DNSKEY with a dashed gray border indicates that no DNSKEY matching the algorithm and key tag of the DS RR exists in the child zone.

Extraneous DS RRs in a parent zone do not, in and of themselves, constitute an error. For example, sometimes they are deliberately pre-published before their corresponding DNSKEYs, as part of a key rollover. However, for every DNSSEC algorithm in the DS RRset for the child zone, a matching DNSKEY must be used to sign the DNSKEY RRset in the child zone, as per RFC 4035. So like, don't panic but also don't ignore it.

  • indeterminate - match pre-revoke — A special case of a DS with no matching DNSKEY is when the DS matched a DNSKEY prior to its revocation, but the ramifications are the same as if it didn't match any DNSKEY. The line is simply drawn to help identify the cause of the otherwise non-existent DNSKEY. Mystery solved, kinda.
  • indeterminate - unknown algorithm — When the algorithm and key tag of a DS RR match those of a DNSKEY RR, but the digest algorithm is unknown or unsupported, then the line between DS and DNSKEY is yellow. Yellow flag, literally.
  • invalid — When the use of a DS corresponding to a DNSKEY is invalid, independent of the correctness of its digest, the line between DS and DNSKEY is red and dashed. An example scenario is when the DNSKEY has the revoke bit set, which is disallowed by RFC 5011. Big yikes.

🎀 NSEC/NSEC3 RRs 🎀

NSEC and NSEC3 RRs are used within DNSSEC to prove the legitimacy of a negative response (i.e., NXDOMAIN or NO DATA) using authenticated denial of existence or hashed authenticated denial of existence, respectively. They're the proof police.

In DNSViz, the NSEC or NSEC3 RR(s) returned by a server to authenticate a negative response are represented by a rectangular node with several compartments. The bottom compartment is labeled with either NSEC or NSEC3, depending on the type of record. Each compartment on the top row represents an NSEC or NSEC3 record in the set — there will be between one and three. Cute, right?

An edge extends from the NSEC or NSEC3 node to the corresponding negative response. Its status is reflected in the color and style of the edge.

  • valid — If the edge is solid blue, then the NSEC or NSEC3 RRs returned prove the validity of the negative response. Chef's kiss.
  • invalid — A solid red edge from the NSEC or NSEC3 node to the negative response indicates that the NSEC or NSEC3 RRs included in the response do not prove the validity of the negative response. Oop.

A special case of NSEC/NSEC3 RRs is that in which they serve to prove the non-existence of Delegation Signer (DS) records. The proof of absence of DS records constitutes an insecure delegation, in which any trust at the parent zone does not propagate to the child zone.

The NSEC/NSEC3 proof involving DS records is graphically represented with an edge from the NSEC/NSEC3 node to the box representing the child zone.

The opt-out flag is set in NSEC3 RRs to indicate that their presence is only sufficient to prove insecure delegations (i.e., lack of DS records) and nothing more. Thus, a name error (NXDOMAIN) response, for example, cannot be securely proven when the NSEC3 uses opt-out. So opt-out is giving "I only do the bare minimum" energy.

NSEC3 records with the opt-out flag set are colored with a gray background. Noted.

✨ RRSIGs ✨

Each RRSIG RR contains the cryptographic signature made by a DNSKEY over an RRset. Using the DNSKEY with the same algorithm and key tag as the RRSIG, the RRset which was signed, and the RRSIG itself, a resolver may determine the correctness of the signature and authenticate the RRset. It's giving math but make it secure.

In DNSViz, RRSIGs are represented as directed edges from the DNSKEY that made the signature to the RRset that was signed. The status of the edge is reflected in its color and style. Let's go:

  • valid — A solid blue edge indicates that an RRSIG is valid. We love to see it.
  • invalid signature — A solid red edge indicates an RRSIG in which the cryptographic signature is invalid. Not the vibe.
  • expired or premature — A solid purple edge indicates that an RRSIG is invalid because it is outside its validity period, as defined by the inception and expiration date fields in the RRSIG RR. Time zones are a scam, but these fields are not.
  • indeterminate - no DNSKEY — A dashed gray line stemming from a DNSKEY with a dashed gray border indicates that no DNSKEY matching the algorithm and key tag of the RRSIG RR could be found in the DNSKEY RRset (or the DNSKEY RRset could not be retrieved).

Extraneous RRSIG RRs do not, in and of themselves, constitute an error. For example, sometimes they are deliberately pre-published before their corresponding DNSKEYs, as part of an algorithm rollover. However, every RRset must be covered by RRSIGs for every algorithm in the DNSKEY RRset, as per RFC 4035 and RFC 6840. So like, pre-publishing is fine, but coverage is mandatory.

  • indeterminate - match pre-revoke — A special case of an RRSIG with no matching DNSKEY is when the RRSIG matched a DNSKEY prior to its revocation, but the ramifications are the same as if it didn't match any DNSKEY. The line is simply drawn to help identify the cause of the otherwise non-existent DNSKEY. Detective work, but make it graphical.
  • indeterminate - unknown algorithm — When the algorithm and key tag of an RRSIG RR match those of a DNSKEY RR, but the cryptographic algorithm associated with the RRSIG is unknown or unsupported, then the line stemming from the DNSKEY is yellow. Yellow means "we don't know her".
  • invalid — When an RRSIG is invalid, independent of the correctness of its temporal validity period and its cryptographic signature, the line stemming from the DNSKEY is red and dashed. Example scenarios might be when the DNSKEY has the revoke bit set or when the signer field in the RRSIG RR does not match the name of the zone apex. Such scenarios are disallowed by RFCs 5011 and 4035, respectively. So don't do that.

Just like other RRsets, a DNSKEY RRset is signed as an RRset, which comprises all the collective DNSKEY RRs at the zone apex. Because each DNSKEY RR is represented as a node in DNSViz, a single RRSIG covering the DNSKEY RRset is represented by edges drawn from the node representing the signing DNSKEY to the nodes representing every DNSKEY RR in the set. It's giving web, not tree.

In some DNSSEC implementations, multiple DNSKEYs sign the DNSKEY RRset, even though only a subset are designated to provide secure entry into the zone (e.g., via matching DS records in the parent zone). While there is nothing inherently wrong with this configuration, graphically representing such scenarios can be visually complex because of the cycles and redundancy created in the graph. Basically, it can look like a group chat where everyone replies to everyone.

In order to represent trust propagation in a simplified fashion, eliminating graphic redundancies, DNSViz exhibits the following behavior. For every DNSKEY signing the DNSKEY RRset, a self-directed edge is added to the node, indicating that the DNSKEY is self-signing. Additionally, if the DNSKEY is designated as a (SEP) into the zone, then edges are drawn from its node to nodes representing all other DNSKEY RRs in the DNSKEY RRset. So it's like, "I sign myself, and if I'm the entry point, I also vouch for everyone else."

If there is no true SEP, (e.g., no DS RRs in the parent zone), then SEP(s) are inferred based on their signing role (e.g., signing DNSKEY RRset or other RRsets) and properties (e.g., SEP bit). The algorithm just guesses based on the vibe.

Like the DNSKEY RRset, a single DS RRset might be represented as several different nodes. As such a single RRSIG covering the DS RRset is represented by edges drawn from the node representing the signing DNSKEY to the nodes representing every DS RR in the set. Same energy, different RRset.

Because an NSEC or NSEC3 node represents one or more RRsets and at least one RRSIG per RRset is anticipated, multiple RRSIG edges will be drawn from DNSKEY to NSEC or NSEC3 nodes, each pointing to the respective compartment corresponding to the NSEC or NSEC3 record. It's a lot of edges, but it's fine.

🦋 CDNSKEY/CDS RRsets 🦋

CDNSKEY and CDS records are used by the child zone to signal to its parent the DS record(s) that it desires to be published, per RFC 7344. The CDNSKEY and CDS RRsets are represented as any other RRset (see "RRsets"); that is, there is a single node per RRset, as opposed to a single node per CDNSKEY or CDS record. So no special treatment, just the usual iconic RRset treatment.

CDNSKEY and CDS RRsets are mapped to the DNSKEYs they correspond to with a gray edge from the CDNSKEY or CDS RRset to the DNSKEY node(s). If the DNSKEY referenced does not exist, the DNSKEY node is represented with a dashed gray border (peep "DNSKEY RRs" and "DS RRs" for the tea 💅).

🦋 Wildcards 🦋

Okay so when the RRSIG covering an RRset has a labels field with a value greater than the number of labels in the name, that's the tell that the resulting RRset got formed by a wildcard expansion ✨. And the server has to additionally include an NSEC or NSEC3 proof that the name the wildcard is expanded to does not exist. No proof, no peace 😤.

DNSViz represents wildcards by displaying both the wildcard RRset and the NSEC or NSEC3 proof. Both. Not one. Both. 🫶

👑 Node Status 👑

Starting at the DNSKEYs designated as trust anchors, DNSViz traverses the nodes and edges in the graph to classify each node as having one of three DNSSEC statuses, depending on the status of the RRset it represents: secure, bogus, or insecure. In DNSViz, node status is indicated by the color of the nodes ✨.

Lowkey important note bestie: there isn't always a one-to-one mapping between node and RRset, but the node status will be consistent among all nodes comprising an RRset. Example: the DNSKEY nodes for a zone all have the same status even though the DNSKEY RRset is split among different nodes. It's giving teamwork 💀.

The status of a node is reflected in the color of its outline.

  • secure — Nodes with a blue outline indicate that they are secure, that there is an unbroken chain of trust from anchor to RRset. Slay 💙.
  • bogus — Nodes with a red outline indicate that they are bogus, that the chain of trust from an anchor has been broken 😭.

Because the NSEC and NSEC3 nodes often represent multiple NSEC or NSEC3 RRs, it is possible that a proper subset of the RRs are secure, while others in the set are not (e.g., missing or expired RRSIG). In this case, the outline of the compartments representing secure NSEC or NSEC3 RRs will be colored blue, while the others will be red. And because the status of the collective set of NSEC and NSEC3 RRs depends on the status of all the individual NSEC and NSEC3 RRs, the greater node is only colored blue if all the compartments are colored blue. All of them. Every single one. No partial credit 🙈.

  • insecure — Nodes with a black outline indicate that they are insecure, that no chain of trust exists; if any anchors exist then an insecure delegation is demonstrated to prove that no chain should exist from the anchors. This is equivalent to DNS without DNSSEC. It's giving "we left DNSSEC at home" 💅.

🎀 Warnings and Errors 🎀

If one or more warnings are detected with the data represented by a node in the graph, then a warning icon is displayed in the node ✨.

Similarly, the warning icon is displayed alongside edges whose represented data has warnings 👀.

If one or more errors (more severe than warnings, periodt) are detected with the data represented by a node in the graph, then an error icon is displayed in the node 😭.

Similarly, the error icon is displayed alongside edges whose represented data has errors.

A warning icon with an italicized label denotes a warning for a response that isn't represented elsewhere in the graph, such as a referral with the authoritative answer flag set. Sneaky little thing 🙈.

An error icon with an italicized label denotes a response error, e.g., due to timeout, malformed response, or invalid RCODE. Not the vibe 💀.

💖 EXIT CODES 💖

The exit codes are:

  • 0 — Program terminated normally. We ate 👑✨.
  • 1 — Incorrect usage. Bestie, read the synopsis 😭.
  • 2 — Required package dependencies were not found. Install your stuff 🫶.
  • 3 — There was an error processing the input or saving the output.
  • 4 — Program execution was interrupted, or an unknown error occurred. Mystery behavior, not iconic 💀.

🌈 SEE ALSO 🌈

dnsviz(1), dnsviz-probe(1), dnsviz-grok(1), dnsviz-print(1), dnsviz-query(1)

Go read the whole friend group, iykyk 💜

And that's a wrap on dnsviz-probe(1), bestie 🎀 This version is 0.11.1, dated 21 April 2025 — so if you're reading some other copy, check the date before you come for me 💅. Stay secure, stay unbogus, and may all your chains of trust be unbroken 🌸🦋✨

📦 where this page comes from