TMHSDigital/subenum

## 功能矩阵 | 模块 | 描述 | | :--- | :--- | | Worker Pool | 生成 N 个 goroutines 用于并行 DNS 解析，支持可配置的并发上限 | | DNS Engine | 针对任何 DNS 服务器解析子域名，支持单次查询超时和重试退避 | | Wildcard Detection | 扫描前进行双重探测检查；除非设置 `-force`，否则提前中止 | | Graceful Shutdown | 捕获 SIGINT/SIGTERM 信号，排空正在进行的 worker，刷新部分结果 | | Input Validation | 符合 RFC 的域名语法和严格的 `ip:port` 格式强制执行 | | Wordlist Dedup | 扫描开始前通过单次遍历对字典条目进行去重 | | Simulation Mode | 以可配置的命中率生成合成 DNS 结果 —— 零网络 I/O | | Output Pipeline | 已解析域名输出至 stdout（管道清洁）；进度和诊断信息输出至 stderr | | Interactive TUI | 通过 `-tui` 提供基于表单的配置和实时滚动结果；会话值持久化 |

## 系统架构 ``` flowchart LR subgraph Input A[Wordlist File] -->|"dedup + load"| B(Entry Slice) C[CLI Flags / TUI Form] --> D(Argument Parser) end subgraph PreScan D --> W{Wildcard\nDetection} W -->|"no wildcard / -force"| E end subgraph Engine B --> E{Worker Pool\nN Goroutines} E -->|subdomain.domain| F[DNS Resolver] F -->|retry + backoff| F G[Context] -->|cancel| E G -->|timeout| F end subgraph OutputLayer ["Output"] F -->|resolved| H["stdout (results)"] F -->|resolved| I[Output File] E -->|atomic counters| J["stderr (progress)"] end K[SIGINT / SIGTERM] -->|cancel| G ```

## 安装 **前置条件：** Go 1.22+ · Git · Make _(可选)_ · Docker _(可选)_

从源码构建

``` git clone https://github.com/TMHSDigital/subenum.git cd subenum go build -buildvcs=false -o subenum ```

预编译二进制文件

从 [Releases](https://github.com/TMHSDigital/subenum/releases) 页面下载适合您平台的二进制文件。 平台：Linux (amd64, arm64) · macOS (amd64, arm64) · Windows (amd64) 每个二进制文件均提供 SHA-256 校验和。

Docker

``` docker build -t subenum . docker run --rm -v $(pwd)/data:/data subenum -w /data/wordlist.txt example.com ``` 或使用 Compose： ``` docker compose run subenum ```

Make 目标

``` make build # compile binary make test # run test suite with race detector make lint # run golangci-lint make simulate # safe run — no DNS queries make tui # launch interactive TUI make docker-build # build Docker image make help # list all targets ```

## 配置 ### CLI 标志 | 标志 | 默认值 | 描述 | | :--- | :---: | :--- | | `-w ` | — | 字典文件，每行一个前缀 **（必需）** | | `-t ` | `100` | 并发 worker goroutines 数量 | | `-timeout ` | `1000` | 单次 DNS 查询超时（毫秒） | | `-dns-server ` | `8.8.8.8:53` | DNS 服务器地址（启动时验证） | | `-attempts ` | `1` | 每个子域名的 DNS 解析尝试次数（1 = 不重试） | | `-force` | `false` | 即使检测到泛解析 DNS 仍继续扫描 | | `-o ` | — | 将结果写入文件（同时也输出到 stdout） | | `-v` | `false` | 详细输出：IP、耗时、单次查询详情 | | `-progress` | `true` | 在 stderr 上显示实时进度行 | | `-simulate` | `false` | 模拟模式：不进行真实的 DNS 查询 | | `-hit-rate ` | `15` | 模拟解析率，百分比（1–100） | | `-tui` | `false` | 启动交互式终端 UI (Terminal UI) | | `-version` | — | 打印版本并退出 | | `-retries ` | — | **已弃用** — `-attempts` 的别名，会打印警告 |


## 使用方法 ### 命令行界面 ``` subenum -w [flags] ```

示例

**基础扫描** ``` ./subenum -w wordlist.txt example.com ``` **使用 Cloudflare DNS 进行高吞吐量扫描并保存结果** ``` ./subenum -w wordlist.txt -t 300 -timeout 500 -dns-server 1.1.1.1:53 -o results.txt example.com ``` **针对不稳定网络的弹性扫描** ``` ./subenum -w wordlist.txt -attempts 3 -timeout 2000 example.com ``` **管道友好 —— 仅在 stdout 输出已解析的子域名** ``` ./subenum -w wordlist.txt example.com | cut -d' ' -f2 | your-takeover-scanner ``` **强制扫描泛解析域名** ``` ./subenum -w wordlist.txt -force example.com ``` **模拟 —— 零网络 I/O** ``` ./subenum -simulate -hit-rate 20 -w examples/sample_wordlist.txt example.com ```

随时按 `Ctrl+C` 中止。退出前会排空进行中的查询并刷新部分结果。
### 交互式 TUI ``` ./subenum -tui ``` 无需标志。填写表单并按 `ctrl+r` 开始扫描。最后使用的值会保存到 `~/.config/subenum/last.json`，并在下次启动时恢复。


TUI 键盘快捷键

| 按键 | 操作 | | :--- | :--- | | `tab` / `shift+tab` / `↑` `↓` | 切换字段 | | `space` | 切换 Simulate / Force | | `ctrl+r` | 开始扫描 | | `ctrl+c` | 中止扫描（扫描视图）/ 退出（表单） | | `r` | 新建扫描 —— 恢复上次使用的值 | | `q` | 扫描完成后退出 |

## 技术栈 | 层级 | 组件 | | :--- | :--- | | 核心引擎 | Go 1.22 · `net.Resolver` · `context` · `sync/atomic` | | 并发 | goroutines · channels · `sync.WaitGroup` · `sync.Mutex` | | TUI | Bubble Tea · Bubbles (textinput, viewport, progress) · Lip Gloss | | 基础设施 | Docker · Alpine · Make · docker-compose | | CI/CD | GitHub Actions · CodeQL · Dependabot · golangci-lint v2 | | 质量 | `go test -race` · gosec · govet · staticcheck |

项目结构

``` subenum/ ├── .github/ │ ├── workflows/ │ │ ├── go.yml # CI: build, test, lint, release │ │ ├── codeql.yml # Weekly CodeQL security analysis │ │ └── pages.yml # GitHub Pages deployment │ ├── ISSUE_TEMPLATE/ │ │ ├── bug_report.md │ │ └── feature_request.md │ ├── dependabot.yml │ └── PULL_REQUEST_TEMPLATE.md ├── data/ │ └── wordlist.txt # Default wordlist for Docker/Make ├── docs/ │ ├── assets/ │ │ └── tui-form.png # TUI screenshot │ ├── ARCHITECTURE.md │ ├── CONTRIBUTING.md │ ├── DEVELOPER_GUIDE.md │ ├── docker.md │ ├── _config.yml │ └── index.md ├── examples/ │ ├── sample_wordlist.txt │ ├── advanced_usage.md │ ├── demo.sh │ └── multi_domain_scan.sh ├── internal/ │ ├── dns/ # ResolveDomain, CheckWildcard, SimulateResolution │ ├── output/ # Thread-safe Writer (stdout/stderr separation) │ ├── scan/ # Scan engine: Config, Event types, Run() │ ├── tui/ # Bubble Tea UI: form, scan view, session config │ └── wordlist/ # LoadWordlist (dedup + sanitize) ├── tools/ │ └── wordlist-gen.go ├── main.go # CLI entry point ├── main_test.go ├── go.mod ├── Dockerfile ├── docker-compose.yml ├── Makefile ├── .golangci.yml # golangci-lint v2 configuration ├── CHANGELOG.md ├── SECURITY.md └── LICENSE # GNU General Public License v3.0 ```

## 开发 有关 Pull Request 工作流程和道德准则，请参阅 [CONTRIBUTING.md](./docs/CONTRIBUTING.md)。 有关构建设置、测试和项目结构，请参阅 [DEVELOPER_GUIDE.md](./docs/DEVELOPER_GUIDE.md)。

[GPL-3.0 许可证](./LICENSE)  ·  [安全策略](./SECURITY.md)  ·  [TM Hospitality Strategies](https://github.com/TMHSDigital)

标签：EVTX分析, GitHub, Go语言, GraphQL安全矩阵, Snort, 域名探测, 子域名枚举, 安全扫描器, 日志审计, 程序破解, 系统安全, 网络安全, 请求拦截, 隐私保护, 零依赖, 高并发