# blechschmidt/massdns architecture

> Architecture diagram of the GitHub repository blechschmidt/massdns, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blechschmidt/massdns
- Repository: https://github.com/blechschmidt/massdns

## Overview

##### Project Type and Purpose
- MassDNS is an open-source, command-line DNS stub resolver optimized for high throughput (millions of queries).
- It comprises a C-based core engine (`src/` → `bin/massdns`), assorted helper scripts (`scripts/`), wordlists/resolver lists (`lists/`), and automated tests.

##### File Structure Analysis
- Top-level:
- `.github/`, `Makefile`, `CMakeLists.txt`, `Dockerfile`: CI/build.
- `src/`: core C modules (networking, DNS, concurrency, hashing, I/O).
- `scripts/`: Python/SH scripts driving MassDNS for PTR, recon, subdomain brute force, extracting resolvers.
- `lists/`: input data (resolvers.txt, names.txt).
- `tests/`: end-to-end test scenarios with expected outputs.
- `doc/`: manual page.
- Pattern: modular C library + single executable + pluggable scripting layer + external data + CI/CD.

##### Key README Insights
- Core features: single-threaded event-driven (epoll or busy-poll), multi-process via `--processes`, custom malloc-free DNS parser, hash map for concurrency control (`-s`), flexible output formats.
- Integration points: scripts pipe domain names into `massdns`, pipe output into further processing.

##### Components
a. Main components:
1. CLI Parser (cmd.h + main.c)
2. Core Resolver Engine
- Concurrency Manager (hashmap.h, auto_concurrency.h)
- Event Loop (net.h, flow.h)
- DNS Packet Builder/Parser (dns.h, buffers.h, security.h)
3. Output Formatter (string.h, cmd.h)
4. Script Layer
- Pre-processors: subbrute.py, ct.py, ptr.py, recon.py
- Post-processors: any shell pipelines consuming ndjson/text/binary output
5. Data Stores
- Resolver list (`lists/resolvers.txt`)
- Wordlists (`lists/names.txt`, `names_small.txt`)
6. Test Harness (tests/ directory, run-tests.sh)
7. Build & CI (Makefile, CMakeLists.txt, Dockerfile, GitHub workflows)

b. Relationships and Data Flows
- User invokes CLI → CLI Parser loads configs and lists → Engine spins up processes → Event Loop sends DNS queries over UDP/TCP to External Resolvers or Authoritative Name Servers → Responses fed back into Packet Parser → Concurrency Manager tracks in-flight queries → Output Formatter writes to STDOUT or file → downstream scripts or user tools consume output.
- Scripts feed domain names into MassDNS via STDIN or file arguments; MassDNS outputs JSON/text to STDOUT, which scripts or other tools can ingest.

c. Architectural Patterns and Principles
- Modular C library layering: separation of CLI, concurrency, networking, packet parsing, I/O.
- Event-driven, non-blocking I/O.
- Forked multi-processing for scale.
- Pluggable scripts for extensibility.
- Single-responsibility modules (hash map, randomization, security).

d. Technologies/Frameworks
- Language: C (gcc), Python/SH for scripts.
- Build: Make, CMake, Docker.
- CI: GitHub Actions.
- Runtime: Linux (epoll, raw sockets), Cygwin support on Windows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Script Layer
    subgraph "Script Layer" 
        direction TB
        SB[subbrute.py]:::script
        CT[ct.py]:::script
        PR[ptr.py]:::script
        RN[recon.py]:::script
        GRS[get-resolvers.sh]:::script
        GRP[get-resolvers.py]:::script
        AA[auth-addrs.sh]:::script
        CE[censys-extract.py]:::script
        DPY[dnsparse.py]:::script
        JQ1[massdnsA.jq]:::script
        JQ2[massdnsAAAA.jq]:::script
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        RES[resolvers.txt]:::data
        NAMES[names.txt]:::data
        NSM[names_small.txt]:::data
    end

    %% CLI Parser
    CLI["CLI Parser"]:::core

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        subgraph "Concurrency Manager"
            direction TB
            AC[auto_concurrency.h]:::core
            HM[hashmap.h]:::core
            TR[timed_ring.h]:::core
        end
        subgraph "Event Loop & Networking"
            direction TB
            NET[net.h]:::core
            FL[flow.h]:::core
            TCP[tcp.h]:::core
        end
        subgraph "DNS Packet Builder/Parser"
            direction TB
            DNS[dns.h]:::core
            BUF[buffers.h]:::core
            SEC[security.h]:::core
            RND[random.h]:::core
        end
        OF["Output Formatter"]:::core
    end

    %% External DNS
    subgraph "External DNS Servers" 
        direction TB
        EX[Public Resolvers & Authoritative Servers]:::external
    end

    %% Output Consumers
    UC["User / Downstream Tools"]:::external

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        MK[Makefile]:::ci
        CMK[CMakeLists.txt]:::ci
        DKR[Dockerfile]:::ci
        GH[.github/workflows/main.yml]:::ci
        GI[.gitignore]:::ci
        RD[README.md]:::ci
        LIC[LICENSE]:::ci
        MAN[massdns.1]:::ci
    end

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        TS[tests/]:::ci
        RT[run-tests.sh]:::ci
    end

    %% Relationships
    RES -->|"Domain List"| CLI
    NAMES -->|"Wordlists"| CLI
    NSM -->|"Wordlists"| CLI

    SB -->|"Feeds Domains"| CLI
    CT -->|"Feeds Domains"| CLI
    PR -->|"Feeds Domains"| CLI
    RN -->|"Feeds Domains"| CLI

    CLI -->|"Init"| AC
    AC -->|"Schedules Queries"| NET
    NET -->|"Build & Send DNS Query"| DNS
    DNS -->|"Parse Responses"| BUF
    BUF -->|"Security Checks"| SEC
    SEC -->|"Randomization"| RND
    RND -->|"Structured Data"| OF

    NET -->|"DNS Query/Response"| EX
    EX -->|"DNS Response"| NET

    OF -->|"Formatted Output"| UC

    %% Build/Test flows
    MK -->|Builds| CLI
    CMK -->|Builds| CLI
    DKR -->|Images| CLI
    GH -->|CI| MK
    TS -->|Validates| CLI
    RT -->|Executes| TS

    %% Click Events
    click CLI "https://github.com/blechschmidt/massdns/blob/master/src/main.c"
    click AC "https://github.com/blechschmidt/massdns/blob/master/src/auto_concurrency.h"
    click HM "https://github.com/blechschmidt/massdns/blob/master/src/hashmap.h"
    click TR "https://github.com/blechschmidt/massdns/blob/master/src/timed_ring.h"
    click NET "https://github.com/blechschmidt/massdns/blob/master/src/net.h"
    click FL "https://github.com/blechschmidt/massdns/blob/master/src/flow.h"
    click TCP "https://github.com/blechschmidt/massdns/blob/master/src/tcp.h"
    click DNS "https://github.com/blechschmidt/massdns/blob/master/src/dns.h"
    click BUF "https://github.com/blechschmidt/massdns/blob/master/src/buffers.h"
    click SEC "https://github.com/blechschmidt/massdns/blob/master/src/security.h"
    click RND "https://github.com/blechschmidt/massdns/blob/master/src/random.h"
    click OF "https://github.com/blechschmidt/massdns/blob/master/src/string.h"
    click SB "https://github.com/blechschmidt/massdns/blob/master/scripts/subbrute.py"
    click CT "https://github.com/blechschmidt/massdns/blob/master/scripts/ct.py"
    click PR "https://github.com/blechschmidt/massdns/blob/master/scripts/ptr.py"
    click RN "https://github.com/blechschmidt/massdns/blob/master/scripts/recon.py"
    click GRS "https://github.com/blechschmidt/massdns/blob/master/scripts/get-resolvers.sh"
    click GRP "https://github.com/blechschmidt/massdns/blob/master/scripts/get-resolvers.py"
    click AA "https://github.com/blechschmidt/massdns/blob/master/scripts/auth-addrs.sh"
    click CE "https://github.com/blechschmidt/massdns/blob/master/scripts/censys-extract.py"
    click DPY "https://github.com/blechschmidt/massdns/blob/master/scripts/dnsparse.py"
    click JQ1 "https://github.com/blechschmidt/massdns/blob/master/scripts/massdnsA.jq"
    click JQ2 "https://github.com/blechschmidt/massdns/blob/master/scripts/massdnsAAAA.jq"
    click RES "https://github.com/blechschmidt/massdns/blob/master/lists/resolvers.txt"
    click NAMES "https://github.com/blechschmidt/massdns/blob/master/lists/names.txt"
    click NSM "https://github.com/blechschmidt/massdns/blob/master/lists/names_small.txt"
    click MK "https://github.com/blechschmidt/massdns/tree/master/Makefile"
    click CMK "https://github.com/blechschmidt/massdns/blob/master/CMakeLists.txt"
    click DKR "https://github.com/blechschmidt/massdns/tree/master/Dockerfile"
    click GH "https://github.com/blechschmidt/massdns/blob/master/.github/workflows/main.yml"
    click GI "https://github.com/blechschmidt/massdns/blob/master/.gitignore"
    click RD "https://github.com/blechschmidt/massdns/blob/master/README.md"
    click LIC "https://github.com/blechschmidt/massdns/tree/master/LICENSE"
    click MAN "https://github.com/blechschmidt/massdns/blob/master/doc/massdns.1"
    click TS "https://github.com/blechschmidt/massdns/tree/master/tests/"
    click RT "https://github.com/blechschmidt/massdns/blob/master/tests/run-tests.sh"

    %% Styles
    classDef core fill:#B3E5FC,stroke:#0288D1,color:#01579B;
    classDef script fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef data fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef external fill:#F8BBD0,stroke:#C2185B,color:#880E4F;
    classDef ci fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
```
