Sign inSign up

dnsgt/groot

By dnsgt

•Updated about 4 years ago

Static Verification tool for DNS zone files

Image
0

1.3K

dnsgt/groot repository overview

⁠GRoot

License: MIT       codecov

Groot is a static verification tool for DNS. Groot consumes a collection of zone files along with a collection of user-defined properties and systematically checks if any input to DNS can lead to violation of the properties.

⁠Installation

⁠Using docker (recommended)

Note: The docker image may consume ~ 1.2 GB of disk space.

We recommend running Groot within a docker container, since they have negligible performance overhead. (See this report⁠)

  1. Get docker for your OS⁠.
  2. Pull our docker image#⁠: docker pull dnsgt/groot.
  3. Run a container over the image: docker run -it dnsgt/groot.
    This would give you a bash shell within groot directory.

#⁠ Alternatively, you could also build the Docker image locally:

docker build -t dnsgt/groot github.com/dns-groot/groot

Docker containers are isolated from the host system. Therefore, to run Groot on zones files residing on the host system, you must first bind mount⁠ them while running the container:

docker run -v ~/data:/home/groot/groot/shared -it dnsgt/groot

The ~/data on the host system would then be accessible within the container at ~/groot/shared (with read+write permissions). The executable would be located at ~/groot/build/bin/.

⁠Manual Installation
CLICK to reveal instructions
⁠Installation for Windows
  1. Install vcpkg⁠ package manager to install dependecies.
  2. Install the C++ libraries (64 bit versions) using:
    • .\vcpkg.exe install boost-serialization:x64-windows boost-flyweight:x64-windows boost-dynamic-bitset:x64-windows boost-graph:x64-windows boost-accumulators:x64-windows docopt:x64-windows nlohmann-json:x64-windows spdlog:x64-windows
    • .\vcpkg.exe integrate install
  3. Clone the repository (with --recurse-submodules) and open the solution (groot.sln) using Visual studio. Set the platform to x64 and mode to Release.
  4. Configure the project properties to use ISO C++17 Standard (std:c++17) for C++ language standard.
  5. Set groot as Set as Startup Project using the solution explorer in the Visual Studio. Build the project using visual studio to generate the executable. The executable would be located at ~\groot\x64\Release\.
⁠Installation for Ubuntu 18.04 or later
  1. Follow the instructions mentioned in the DockerFile to natively install in Ubuntu 18.04 or later.
  2. The executable would be located at ~/groot/build/bin/.

⁠Property Verification

Check for any violations of the input properties by invoking Groot as:

For docker (Ubuntu):

$ .~/groot/build/bin/groot ~/groot/test/TestFiles/cc.il.us/zone_files --jobs=~/groot/test/TestFiles/cc.il.us/jobs.json --output=output.json

For Windows:

$ .~\groot\x64\Release\groot.exe ~\groot\test\TestFiles\cc.il.us\zone_files --jobs=~\groot\test\TestFiles\cc.il.us\jobs.json --output=output.json

Groot outputs any violations to the output.json file.

⁠Flags

User can log debugging messages to log.txt using -l and use -v flag to log more detailed information. Use -s flag to display the statistics of the zone files parsed and the execution time. To log zone file issues (missing glue records, multiple CNAME/DNAME records, duplicate records) separately in lint.json, use the --lint flag.

⁠Packaging zone files data

Groot expects all the required zone files to be available in the input directory along with a special file metadata.json. The metadata.json file has to be created by the user and has to list the file name and the name server from which that zone file was obtained. If the zone files for a domain are obtained from multiple name servers, make sure to give the files a distinct name and fill the metadata accordingly. The user also has to provide the root (top) name servers for his domain in the metadata.json.

CLICK to reveal an examplemetadata.json⁠ 
{  
  "TopNameServers" : ["us.illinois.net."],  //List of top name servers as strings
  "ZoneFiles" : [
      {
         "FileName": "cc.il.us..txt", //cc.il.us. zone file from us.illinois.net. name server
         "NameServer": "us.illinois.net."
      },
      {
         "FileName": "richland.cc.il.us..txt", //richland.cc.il.us. zone file from ns1.richland.cc.il.us. name server
         "NameServer": "ns1.richland.cc.il.us.",
         "Origin": "richland.cc.il.us." // optional field to indicate the origin of the input zone file.
      },
      {
         "FileName": "child.richland.cc.il.us..txt", //child.richland.cc.il.us. zone file from ns1.child.richland.cc.il.us. name server
         "NameServer": "ns1.child.richland.cc.il.us."
      },
      {
         "FileName": "child.richland.cc.il.us.-2.txt", //child.richland.cc.il.us. zone file from ns2.child.richland.cc.il.us. name server 
         "NameServer": "ns2.child.richland.cc.il.us." //for same domain (child.richland.cc.il.us.) as the last one but from a different name server
      }
  ]
}
⁠Inputting Jobs

Groot can currently verify properties shown below on the zone files and expects the input list in a json file format. A job verifies properties on a domain and optionally on all its subdomains. The input json file can have a list of jobs. Groot verifies a default set of properties if no input file is provided.

CLICK to reveal an example job⁠ 
[
   {
      "Domain": "cc.il.us." // Name of the domain to check
      "SubDomain": true, //Whether to check the properties on all the subdomains also
      "Properties":[ 
         {
            "PropertyName": "QueryRewrite",
            "Value": ["illinois.net." , "cc.il.us."]
         },
         {
            "PropertyName": "Rewrites",
            "Value": 1
         },
         {
            "PropertyName": "RewriteBlackholing"
         }
      ]
   }
]
⁠Available Properties
Delegation Consistency

The parent and child zone files should have the same set of NS and glue A records for delegation. Input json format:

      {
         "PropertyName": "DelegationConsistency"
      }
Finding all aliases Lists all the input query names (aliases) that are eventually rewritten to one of the canonical names.

Input json format:

      {
         "PropertyName": "AllAliases",
         "Value": ["gw1.richland.cc.il.us."] //List of canonical names
      }
Lame Delegation

A name server that is authoritative for a zone should provide authoritative answers, otherwise it is a lame delegation. Input json format:

      {
         "PropertyName": "LameDelegation"
      }
Nameserver Contact

The query should not contact any name server that is not a subdomain of the allowed set of domains for any execution in the DNS. Input json format:

      {
         "PropertyName": "NameserverContact",
         "Value": ["edu.", "net.", "cc.il.us."] //List of allowed domain suffixes
      }
Number of Hops

The query should not go through more than X number of hops for any execution in the DNS. Input json format:

      {
         "PropertyName": "Hops",
         "Value": 2
      }
Number of Rewrites

The query should not be rewritten more than X number of time for any execution in the DNS. Input json format:

      {
         "PropertyName": "Rewrites",
         "Value": 3
      }
Query Rewritting

The query should not be rewritten to any domain that is not a subdomain of the allowed set of domains for any execution in the DNS. Input json format:

      {
         "PropertyName": "QueryRewrite",
         "Value": ["illinois.net." , "cc.il.us."] //List of allowed domain suffixes
      }
Response Consistency Different executions in DNS that might happen due to multiple name servers should result in the same answers.

Input json format:

      {
         "PropertyName": "ResponseConsistency",
         "Types": ["A", "MX"] //Checks the consistency for only these types
      }
Response Returned Different executions in DNS that might happen due to multiple name servers should result in some non-empty response.

Input json format:

      {
         "PropertyName": "ResponseReturned",
         "Types": ["CNAME", "A"] //Checks that some non-empty response is returned for these types
      }
Response Value Every execution in DNS should return an answer that matches the user input answer.

Input json format:

      {
         "PropertyName": "ResponseValue",
         "Types": ["A"],
         "Value": ["64.107.104.4"] //The expected response
         
      }
Rewrite Blackholing

If the query is rewritten for any execution in the DNS, then the new query's domain name should have at least one resource record.

Input json format:

      {
         "PropertyName": "RewriteBlackholing"
      }
Structural Delegation Consistency

The parent and child zone files should have the same set of NS and glue A records for delegation irrespective of whether the name server hosting the child zone is reachable from the top name servers.

Input json format:

      {
         "PropertyName": "StructuralDelegationConsistency"
      }
Zero Time To Live

The query should not return a resource record with zero TTL for the given types.
Input json format:

      {
         "PropertyName": "ZeroTTL",
         "Types": ["A"]
      }
DNAME Substitution Check

The query should not overflow the legal size for a domain name after DNAME rewrite. Records with CNAME target domain overflowing the legal size are ignored by the tool and are reported as issues during parsing itself.
Input json format:

      {
         "PropertyName": "DNAMESubstitutionCheck"
      }

Groot, by default, checks for cyclic zone dependency and other loops while verifying any of the above properties.

Tag summary

Content type

Image

Digest

sha256:877c91a5b…

Size

525.8 MB

Last updated

about 4 years ago

docker pull dnsgt/groot