# knownsec/ksubdomain architecture

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

- Interactive diagram: https://gitdiagram.com/knownsec/ksubdomain
- Repository: https://github.com/knownsec/ksubdomain

## Overview

ksubdomain is a high-speed, stateless DNS brute-force and validation tool. Users provide target domains and wordlists through flags, files, or stdin; the runtime builds DNS probes, sends them through a selected network device, captures replies, and retries unanswered probes. Successful answers can be expanded to deeper labels and written to output. Documented branches include script-based API discovery, wildcard handling, ASN/IP-range summaries, and CSV output. The main execution and packet paths are excerpted; some optional capability links are documented only in the README.

Main entry points: [`core/start.go`](https://github.com/knownsec/ksubdomain/blob/master/core/start.go) (Scan runner), [`core/recv.go`](https://github.com/knownsec/ksubdomain/blob/master/core/recv.go) (Packet receiver), [`core/send.go`](https://github.com/knownsec/ksubdomain/blob/master/core/send.go) (DNS probe sender), [`core/script.go`](https://github.com/knownsec/ksubdomain/blob/master/core/script.go) (Lua script engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Inputs and orchestration"]
  node_cli["CLI options<br/>[options.go]"]
  node_runner["Scan runner<br/>[start.go]"]
  node_inputs["Input streams<br/>[start.go]"]
end

subgraph group_discovery["Discovery and probes"]
  node_devices["Device selection<br/>[device.go]"]
  node_api["API sources<br/>[sources.go]"]
  node_scripts["Lua script engine<br/>[script.go]"]
  node_send["DNS probe sender<br/>[send.go]"]
end

subgraph group_response["Replies and results"]
  node_receive["Packet receiver<br/>[recv.go]"]
  node_pending[("Probe state<br/>[localStruct.go]")]
  node_retry["Retry tracking<br/>[start.go]"]
  node_answers["DNS results<br/>[recv.go]"]
end

subgraph group_enhance["Result enrichment"]
  node_wildcard["Wildcard filtering<br/>[filterwild.go]"]
  node_summary["ASN summary<br/>[summary.go]"]
  node_networkmath["IP range utilities<br/>[network.go]"]
  node_csv["Spreadsheet export<br/>[excel.go]"]
end

node_operator(("User"))
node_interface["Network device"]
node_scriptfiles["API scripts"]
node_dns["DNS resolvers"]

node_operator -->|"sets flags"| node_cli
node_cli -->|"starts scan"| node_runner
node_runner -->|"reads input"| node_inputs
node_runner -->|"selects device"| node_devices
node_devices -.->|"uses device"| node_interface
node_runner -->|"starts capture"| node_receive
node_runner -->|"initializes sender"| node_send
node_runner -->|"runs API mode"| node_api
node_api -.->|"uses scripts"| node_scripts
node_scripts -.->|"loads scripts"| node_scriptfiles
node_scripts -.->|"queries web APIs"| node_dns
node_runner -->|"dispatches retries"| node_retry
node_retry -->|"resends probes"| node_send
node_send -->|"records probes"| node_pending
node_send -.->|"sends DNS probes"| node_dns
node_receive -->|"matches replies"| node_pending
node_receive -->|"queues deeper probes"| node_retry
node_receive -->|"writes answers"| node_answers
node_receive -.->|"feeds output"| node_wildcard
node_runner -->|"runs summary"| node_summary
node_summary -.->|"uses IP ranges"| node_networkmath
node_runner -.->|"exports spreadsheet"| node_csv

click node_cli "https://github.com/knownsec/ksubdomain/blob/master/core/options.go"
click node_runner "https://github.com/knownsec/ksubdomain/blob/master/core/start.go"
click node_inputs "https://github.com/knownsec/ksubdomain/blob/master/core/start.go"
click node_devices "https://github.com/knownsec/ksubdomain/blob/master/core/device.go"
click node_api "https://github.com/knownsec/ksubdomain/blob/master/core/sources.go"
click node_scripts "https://github.com/knownsec/ksubdomain/blob/master/core/script.go"
click node_scriptfiles "https://github.com/knownsec/ksubdomain/tree/master/resources/scripts"
click node_send "https://github.com/knownsec/ksubdomain/blob/master/core/send.go"
click node_receive "https://github.com/knownsec/ksubdomain/blob/master/core/recv.go"
click node_pending "https://github.com/knownsec/ksubdomain/blob/master/core/localStruct.go"
click node_retry "https://github.com/knownsec/ksubdomain/blob/master/core/start.go"
click node_answers "https://github.com/knownsec/ksubdomain/blob/master/core/recv.go"
click node_wildcard "https://github.com/knownsec/ksubdomain/blob/master/core/filterwild.go"
click node_summary "https://github.com/knownsec/ksubdomain/blob/master/core/summary.go"
click node_networkmath "https://github.com/knownsec/ksubdomain/blob/master/core/network.go"
click node_csv "https://github.com/knownsec/ksubdomain/blob/master/core/excel.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_runner,node_inputs,node_operator toneBlue
class node_devices,node_api,node_scripts,node_send toneAmber
class node_receive,node_pending,node_retry,node_answers,node_scriptfiles toneMint
class node_wildcard,node_summary,node_networkmath,node_csv toneRose
class node_interface,node_dns toneIndigo
```

## Components

### Inputs and orchestration

- [CLI options](https://github.com/knownsec/ksubdomain/blob/master/core/options.go): `core/options.go`
- [Scan runner](https://github.com/knownsec/ksubdomain/blob/master/core/start.go): `core/start.go`
- [Input streams](https://github.com/knownsec/ksubdomain/blob/master/core/start.go): `core/start.go`

### Discovery and probes

- [Device selection](https://github.com/knownsec/ksubdomain/blob/master/core/device.go): `core/device.go`
- [API sources](https://github.com/knownsec/ksubdomain/blob/master/core/sources.go): `core/sources.go`
- [Lua script engine](https://github.com/knownsec/ksubdomain/blob/master/core/script.go): `core/script.go`
- [DNS probe sender](https://github.com/knownsec/ksubdomain/blob/master/core/send.go): `core/send.go`

### Replies and results

- [Packet receiver](https://github.com/knownsec/ksubdomain/blob/master/core/recv.go): `core/recv.go`
- [Probe state](https://github.com/knownsec/ksubdomain/blob/master/core/localStruct.go): `core/localStruct.go`
- [Retry tracking](https://github.com/knownsec/ksubdomain/blob/master/core/start.go): `core/start.go`
- [DNS results](https://github.com/knownsec/ksubdomain/blob/master/core/recv.go): `core/recv.go`

### Result enrichment

- [Wildcard filtering](https://github.com/knownsec/ksubdomain/blob/master/core/filterwild.go): `core/filterwild.go`
- [ASN summary](https://github.com/knownsec/ksubdomain/blob/master/core/summary.go): `core/summary.go`
- [IP range utilities](https://github.com/knownsec/ksubdomain/blob/master/core/network.go): `core/network.go`
- [Spreadsheet export](https://github.com/knownsec/ksubdomain/blob/master/core/excel.go): `core/excel.go`

### Other components

- **User**
- **Network device**
- [API scripts](https://github.com/knownsec/ksubdomain/tree/master/resources/scripts): `resources/scripts`
- **DNS resolvers**

## Connections

- User → CLI options: sets flags (evidence: `core/options.go`)
- CLI options → Scan runner: starts scan
- Scan runner → Input streams: reads input (evidence: `core/start.go`)
- Scan runner → Device selection: selects device (evidence: `core/start.go`)
- Device selection → Network device: uses device
- Scan runner → Packet receiver: starts capture (evidence: `core/start.go`)
- Scan runner → DNS probe sender: initializes sender (evidence: `core/start.go`)
- Scan runner → API sources: runs API mode (evidence: `core/start.go`)
- API sources → Lua script engine: uses scripts
- Lua script engine → API scripts: loads scripts (evidence: `readme.md`)
- Lua script engine → DNS resolvers: queries web APIs (evidence: `readme.md`)
- Scan runner → Retry tracking: dispatches retries (evidence: `core/start.go`)
- Retry tracking → DNS probe sender: resends probes (evidence: `core/start.go`)
- DNS probe sender → Probe state: records probes (evidence: `core/send.go`)
- DNS probe sender → DNS resolvers: sends DNS probes
- Packet receiver → Probe state: matches replies (evidence: `core/recv.go`)
- Packet receiver → Retry tracking: queues deeper probes (evidence: `core/recv.go`)
- Packet receiver → DNS results: writes answers (evidence: `core/recv.go`)
- Packet receiver → Wildcard filtering: feeds output (evidence: `readme.md`)
- Scan runner → ASN summary: runs summary (evidence: `core/start.go`)
- ASN summary → IP range utilities: uses IP ranges
- Scan runner → Spreadsheet export: exports spreadsheet (evidence: `readme.md`)
