path: root/doc/man/dnsviz-graph.1

.\"
.\" This file is a part of DNSViz, a tool suite for DNS/DNSSEC monitoring,
.\" analysis, and visualization.
.\" Created by Casey Deccio (casey@deccio.net)
.\"
.\" Copyright 2015-2016 VeriSign, Inc.
.\"
.\" Copyright 2016-2019 Casey Deccio
.\"
.\" DNSViz is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" DNSViz is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with DNSViz.  If not, see <http://www.gnu.org/licenses/>.
.\"
.TH dnsviz-probe 1 "25 Jan 2019" "0.8.1"
.SH NAME
dnsviz-graph \- graph the assessment of diagnostic DNS queries
.SH SYNOPSIS
.B dnsviz
\fBgraph\fR
[ \fIoptions\fR ]
[ \fIdomain_name...\fR ]
.SH DESCRIPTION
Process the results of diagnostic DNS queries previously performed, e.g., using
\fBdnsviz-probe(1)\fR, to assess the health of the associated DNS deployments
for one or more domain names specified.  The results of this processing are
presented in one of several graphical formats for user diagnostics.

The source of the diagnostic query input is either a file specified with
\fB-r\fR or standard input.

Domain names to be processed may be passed either as command-line arguments, in
a file (using the \fB-f\fR option), or simply implied using the diagnostic
query input.  The latter is the preferred methodology (and the simplest) and is
useful, except in cases where the input contains diagnostic queries for
multiple domain names, only a subset of which are to be processed.

If \fB-f\fR is not used and no domain names are supplied on the command line,
then the domain names to be processed are extracted from the diagnostic query
input.  If the \fB-f\fR option is used, then names may not be specified on the
command line.

The domain names passed as input are fully-qualified domain names, such as
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.  Because it is implied that specified domain names
are fully qualified, no trailing dot is necessary.

The graphical output is the image of a directed graph created using
\fBdot(1)\fR.  The "html" format makes this image interactive using javascript
libraries that are distributed with this software.

.SH OPTIONS
.TP
.B -f, --names-file \fIfilename\fR
Read names from a file (one name per line), instead of from command line.

If this option is used, then names may not be specified on the command line.
.TP
.B -r, --input-file \fIfilename\fR
Read diagnostic query input from the specified file, instead of from standard
input.
.TP
.B -t, --trusted-keys-file \fIfilename\fR
Use trusted keys from the specified 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 should contain DNSKEY
records that correspond to one more trusted keys for one or more DNS zones.

This option may be used multiple times on the command line.
.TP
.B -a, --algorithms \fIalg\fR[,\fIalg...\fI]
Support only the DNSSEC algorithms specified.  If this option is used, any
algorithms not specified will appear as "unsupported."  The status of any RRSIG
records corresponding to unsupported algorithms will be unknown.  Additionally,
when a zone has only DS records with unsupported algorithms, the zone is
treated as "insecure", assuming the DS records are properly authenticated.
.TP
.B -d, --digest-algorithms \fIdigest_alg\fR[,\fIdigest_alg...\fI]
Support only the DNSSEC digest algorithms specified.  If this option is used,
any digest algorithms not specified will appear as "unsupported."  The status
of any DS records corresponding to unsupported digest algorithms will be
unknown.  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.
.TP
.B -b, --validate-prohibited-algs
Validate algorithms for which validation is otherwise prohibited.  Current
DNSSEC specification prohibits validators from validating older, weaker
algorithms associated with DNSKEY and DS records (see RFC 8624).  If this
option is used, then a warning will be still be issued for DNSSEC records that
use these older algorithms, but the code will still assess their cryptographic
status, rather than ignoring them.
.TP
.B -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.
.TP
.B -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.  However, 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.
.TP
.B -R, --rr-types \fItype\fR[,\fItype...\fI]
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.
.TP
.B -e, --redundant-edges
Do not remove redundant RRSIG edges from the graph.

As described in \fB"RRSIGs"\fR, some edges representing RRSIGs made by KSKs are
removed from the graph to reduce visual complexity.  If this option is used,
those edges are preserved.
.TP
.B -O, --derive-filename
Save the output to a file, whose name is derived from the format (i.e.,
provided to \fB-T\fR) and the domain name.

If this option is used when the diagnostic queries of multiple domain names are
being processed, a file will be created for each domain name processed.
.TP
.B -o, --output-file \fIfilename\fR
Write the output to the specified file instead of to standard output, which
is the default.

If this option is used when the diagnostic queries of multiple domain name are
being processed, a single file (the one specified) will be created, which will
contain the collective output for all domain names processed.
.TP
.B -T, --output-format \fIformat\fR
Use the specified output format for the graph, selected from among the
following: "dot", "png", "jpg", "svg", and "html".  The default is "dot".
.TP
.B -h, --help
Display the usage and exit.

.SH OUTPUT

The conventions used in the graphical format are described below.

.SS 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.

.SS 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.

.IP insecure
A black, solid line between zones indicates a standard, insecure delegation
(i.e., sans DNSSEC).

.IP 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.

.IP 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.

.IP secure
If the delegation is secure by DNSSEC standards, then then the delegation is
represented by a solid, blue line.

.IP bogus
If the delegation is bogus by DNSSEC standards, then then the delegation is
represented by a dashed, red line.

.SS 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.

.SS 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).

.SS 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 color of the edge.

.IP valid
A solid, blue line between DNAME node and CNAME node indicates that the DNAME
expansion was valid.

.IP invalid
A solid, red line between DNAME node and CNAME node indicates that the DNAME
expansion was invalid.

.SS 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.

.SS DNSKEY RRs
DNSKEY RRs include public key and meta information to enable resolvers to
validate signatures made by the corresponding private keys.

In DNSViz, each DNSKEY RR is represented as an elliptical node in the zone to
which it belongs.

Each DNSKEY node is decorated based on the attributes of the corresponding
DNSKEY RR.

.IP "SEP bit"
A gray fill indicates that 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 is used to sign the DNSKEY RRset of a zone, providing a
secure entry point into a zone via DS RRs or a trust anchor at the resolver.

.IP "revoke bit"
A thick border indicates that the revoke bit is set in the flags field of the
DNSKEY RR.

Resolvers which 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.

.IP "trust anchor"
A double border indicates that the DNSKEY has been designated as a trust
anchor.

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

.SS DS RRs
DS (delegation signer) RRs exist 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.

.IP 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.

.IP "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.

.IP "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.

.IP "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.

.IP "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.

.IP "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.

.SS 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.

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.

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.

.IP valid
If the edge is solid blue, then the NSEC or NSEC3 RRs returned prove the
validity of the negative response.

.IP invalid
A solid red edge from the NSEC or NSEC3 node to the negative response indicates
that the NSEC or NSEC3 RRs included in in the response do not prove the
validity of the negative response.

.PP
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.

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

.SS 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.

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.

.IP valid
A solid blue edge indicates that an RRSIG is valid.

.IP "invalid signature"
A solid red edge indicates an RRSIG in which the cryptographic signature is
invalid.

.IP "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.

.IP "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.

.IP "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.

.IP "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.

.IP 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.

.PP
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.

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.

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.

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., siging DNSKEY RRset or other
RRsets) and properties (e.g., SEP bit).

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.

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.

.SS Wildcards
When the RRSIG covering an RRset has a labels field with value greater than the
number of labels in the name, it is indicative that the resulting RRset was
formed by a wildcard expansion.  The server must additionally include an NSEC
or NSEC3 proof that the name to which the wildcard is expanded does not exist.

DNSViz represents wildcards by displaying both the wildcard RRset and the NSEC
or NSEC3 proof.

.SS Node Status
Beginning 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 which it represents:
secure, bogus, or insecure.  In DNSViz, node status is indicated by the color
of the nodes (Note that 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.  An example is the DNSKEY nodes for a zone, which all have the same
status even though the DNSKEY RRset is split among different nodes).

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

.IP secure
Nodes with blue outline indicate that they are secure, that there is an
unbroken chain of trust from anchor to RRset.

.IP bogus
Nodes with 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.  Because the status of the collective set of NSEC and
NSEC3 RRs is dependent 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.

.IP insecure
Nodes with 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.

.SS 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) 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.

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

.SH EXIT CODES
The exit codes are:
.IP 0
Program terminated normally.
.IP 1
Incorrect usage.
.IP 2
Required package dependencies were not found.
.IP 3
There was an error processing the input or saving the output.
.IP 4
Program execution was interrupted, or an unknown error occurred.
.SH SEE ALSO
.BR dnsviz(1),
.BR dnsviz-probe(1),
.BR dnsviz-grok(1),
.BR dnsviz-print(1),
.BR dnsviz-query(1)