Skip to content

Commit 1793b6b

Browse files
Make DNS tests hermetic and pin the 0.7.0 release path.
Public-resolver tests now hit an in-process UDP/TCP responder; live smoke is gated on SUBENUM_NETWORK_TESTS=1. Version is a ldflags-injected var, -version writes stdout, go.mod is 1.24, golangci-lint-action and distroless images are pinned, and releases attest provenance. Domain validation gained the 63-character label limit and xn-- TLDs rather than dropping the RFC-compliant README claim. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 703169a commit 1793b6b

19 files changed

Lines changed: 492 additions & 527 deletions

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ If applicable, add screenshots or copy the terminal output to help explain your
2525

2626
**Environment (please complete the following information):**
2727
- OS: [e.g. Ubuntu 22.04, Windows 11, macOS 13.0]
28-
- Go Version: [e.g. 1.24.2]
29-
- subenum Version: [e.g. 0.3.0]
28+
- Go Version: [e.g. 1.24]
29+
- subenum Version: [e.g. 0.7.0]
3030

3131
**Additional context**
3232
Add any other context about the problem here.

‎.github/workflows/go.yml‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@ jobs:
1515

1616
steps:
1717
- uses: actions/checkout@v6
18+
with:
19+
fetch-depth: 0
1820

1921
- name: Set up Go
2022
uses: actions/setup-go@v6
@@ -35,15 +37,15 @@ jobs:
3537
run: go mod verify
3638

3739
- name: Build
38-
run: go build -v -buildvcs=false ./...
40+
run: go build -v -buildvcs=false -ldflags "-X main.Version=$(git describe --tags --dirty)" ./...
3941

4042
- name: Test
4143
run: go test -v -race ./...
4244

4345
- name: Run golangci-lint
4446
uses: golangci/golangci-lint-action@v9
4547
with:
46-
version: latest
48+
version: v2.12.2
4749

4850
# Single job that owns release creation. It runs once (not a matrix), so
4951
# exactly one job ever creates the release for the tag. The upload-assets
@@ -75,6 +77,8 @@ jobs:
7577
if: startsWith(github.ref, 'refs/tags/v')
7678
permissions:
7779
contents: write
80+
id-token: write
81+
attestations: write
7882

7983
strategy:
8084
matrix:
@@ -109,6 +113,8 @@ jobs:
109113

110114
steps:
111115
- uses: actions/checkout@v6
116+
with:
117+
fetch-depth: 0
112118

113119
- name: Set up Go
114120
uses: actions/setup-go@v6
@@ -129,7 +135,8 @@ jobs:
129135
env:
130136
GOOS: ${{ matrix.goos }}
131137
GOARCH: ${{ matrix.goarch }}
132-
run: go build -v -buildvcs=false -o ${{ matrix.artifact_name }}
138+
shell: bash
139+
run: go build -v -buildvcs=false -ldflags "-X main.Version=$(git describe --tags --dirty)" -o ${{ matrix.artifact_name }}
133140

134141
- name: Rename for release
135142
shell: bash
@@ -142,6 +149,11 @@ jobs:
142149
shell: bash
143150
run: sha256sum ${{ matrix.asset_name }} > ${{ matrix.asset_name }}.sha256
144151

152+
- name: Attest build provenance
153+
uses: actions/attest-build-provenance@v3
154+
with:
155+
subject-path: ${{ matrix.asset_name }}
156+
145157
# The release already exists (created by create-release), so each matrix leg
146158
# only adds its binary and checksum. No matrix job creates the release, which
147159
# avoids the concurrent-create race entirely. draft: true is set explicitly

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.7.0] - 2026-09-16
11+
1012
### Added
1113
- Scan outcome accounting: each query is classified as found, nxdomain, timeout, refused, or other. The breakdown is printed after every scan (stderr) and carried on `EventDone.Stats` for the TUI summary line.
1214
- Reliability guard: once 200 queries have completed, if more than 20% failed as timeout/refused/other the scan emits an error naming the failure rate and likely resolver rate-limiting at the configured `-t` and `-rate`, then aborts. `-no-abort` keeps the warning but continues the scan.
1315
- TUI record-type selection (`-type` parity): a Record Types form field, persisted to the session config and wired into the scan.
1416
- TUI recursive enumeration (`-recursive`/`-depth` parity): a Recursive toggle with a Depth field gated on it, persisted across sessions.
1517
- TUI rate limiting (`-rate` parity): a queries-per-second form field, persisted across sessions.
1618
- TUI output file support (`-o`/`-format` parity): results can be written to a file as `text`, `json`, or `csv`. The format applies only to the file; the live viewport stays human-readable. Backed by a new file-only `output.NewFile` writer so structured output never collides with the alt-screen.
19+
- Release provenance attestations (`actions/attest-build-provenance`) on tagged builds.
1720

1821
### Changed
1922
- `dns.ResolveDomainWithRetry` returns `([]Record, Outcome)` instead of `([]Record, bool)`, so callers can distinguish NXDOMAIN from infrastructure failure.
@@ -23,6 +26,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2326
- `-max-queries` caps admitted work. Recursive scans warn about the theoretical ceiling and refuse to start above 1e7 jobs unless `-max-queries` or `-force` is set. The dispatcher queue uses a head index with periodic compaction. Unreachable resolvers fail a preflight lookup before wildcard probes.
2427
- CLI `EventError` handling now drains the event channel so a reliability abort still delivers `EventDone` with partial stats. Wildcard-without-`-force` still skips structured `Finish`.
2528
- TUI form now validates domain syntax and DNS server `ip:port` format up front, matching the CLI. The validators were extracted into a shared `internal/validate` package used by both entry points (previously the form only checked for non-empty values).
29+
- `validate.Domain` now enforces the 63-character per-label limit and accepts punycode TLDs (`xn--...`).
30+
- `Version` is a `var` injected via `-ldflags "-X main.Version=$(git describe --tags --dirty)"`. `-version` writes to stdout.
31+
- `go` directive is `1.24`. golangci-lint CI is pinned to v2.12.2. Docker final stage is distroless static nonroot, with builder and runtime images pinned by digest.
2632

2733
### Removed
2834
- Removed the unused `dns.Resolve` function, superseded by `dns.ResolveTypes`.
@@ -39,6 +45,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3945
- GitHub Pages landing page (`docs/index.md`) refreshed to the 0.6.0 feature set, adding cards for Output Formats (`-format`), Rate Limiting (`-rate`), Record Types (`-type`), and Recursive Enumeration (`-recursive`/`-depth`).
4046
- Normalized em dashes to hyphens across `docs/` for consistency with the no-em-dash convention.
4147
- Documented outcome classification, `EventDone.Stats`, and the reliability guard in ARCHITECTURE.
48+
- Corrected ARCHITECTURE output-format note (TUI file output shipped in P5) and DEVELOPER_GUIDE "CLI-only zero deps" claim.
4249

4350
### Tests
4451
- Added TUI coverage: session-config round-trip, form navigation across gated fields, record-type and depth validation, and structured-output finalization on both the success and error paths.
@@ -49,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
4956
- Added a local UDP+TCP responder test proving truncated (TC=1) answers complete over TCP.
5057
- Added wildcard fingerprint tests: matching answers are filtered, and recursive expansion of a wildcard branch is skipped.
5158
- Added tests for `-max-queries` admission, the recursive ceiling refusal, and resolver preflight against a black-holed UDP listener.
59+
- Replaced public-resolver tests with an in-process UDP/TCP responder. Live smoke is gated on `SUBENUM_NETWORK_TESTS=1`.
5260

5361
## [0.6.0] - 2026-06-03
5462

‎Dockerfile‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
FROM golang:1.24.2-alpine AS builder
1+
FROM golang:1.24.2-alpine@sha256:7772cb5322baa875edd74705556d08f0eeca7b9c4b5367754ce3f2f00041ccee AS builder
22

33
WORKDIR /app
44

5+
ARG VERSION=0.7.0
6+
57
# Copy module files first and download deps to leverage Docker layer caching
68
COPY go.mod go.sum ./
79
RUN go mod download
@@ -11,27 +13,21 @@ COPY main.go ./
1113
COPY internal/ ./internal/
1214

1315
# Build the binary with optimizations
14-
RUN CGO_ENABLED=0 GOOS=linux go build -o subenum -ldflags="-w -s" .
15-
16-
# Use a minimal alpine image for the final container
17-
FROM alpine:latest
16+
RUN CGO_ENABLED=0 GOOS=linux go build -o subenum -ldflags="-w -s -X main.Version=${VERSION}" .
1817

19-
RUN apk --no-cache add ca-certificates
18+
FROM gcr.io/distroless/static:nonroot@sha256:e2e927ec666bae08560abb3c55d0659eceabb657f56b6782ab500a9fc7f555e3
2019

21-
WORKDIR /root/
20+
WORKDIR /home/nonroot
2221

23-
# Copy binary from builder stage
24-
COPY --from=builder /app/subenum .
25-
26-
# Copy examples directory with wordlists
22+
COPY --from=builder /app/subenum /usr/local/bin/subenum
2723
COPY examples/ ./examples/
2824

29-
# Create volume mount point for custom wordlists and output
3025
VOLUME ["/data"]
3126

32-
ENTRYPOINT ["./subenum"]
27+
USER nonroot
28+
29+
ENTRYPOINT ["/usr/local/bin/subenum"]
3330

34-
# Default command - shows help
3531
CMD ["-version"]
3632

3733
LABEL org.opencontainers.image.title="subenum"
@@ -40,4 +36,4 @@ LABEL org.opencontainers.image.source="https://github.com/TMHSDigital/subenum"
4036
LABEL org.opencontainers.image.licenses="GPL-3.0"
4137
LABEL org.opencontainers.image.documentation="https://github.com/TMHSDigital/subenum/blob/main/README.md"
4238
LABEL org.opencontainers.image.vendor="Educational Use Only"
43-
LABEL org.opencontainers.image.usage="For educational and legitimate security testing purposes only"
39+
LABEL org.opencontainers.image.usage="For educational and legitimate security testing purposes only"

‎Makefile‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ GOTEST=$(GOCMD) test
88
GOVET=$(GOCMD) vet
99
BINARY_NAME=subenum
1010
WORDLIST_GEN=wordlist-gen
11+
VERSION ?= $(shell git describe --tags --dirty --always 2>/dev/null || echo 0.7.0)
12+
LDFLAGS = -ldflags "-X main.Version=$(VERSION)"
1113

1214
# Default run parameters - CHANGE THESE!
1315
WORDLIST=examples/sample_wordlist.txt
@@ -27,7 +29,7 @@ WL_OUTPUT=custom-wordlist.txt
2729
all: build
2830

2931
build:
30-
$(GOBUILD) -buildvcs=false -o $(BINARY_NAME)
32+
$(GOBUILD) -buildvcs=false $(LDFLAGS) -o $(BINARY_NAME)
3133

3234
test:
3335
$(GOTEST) -v ./...
@@ -84,15 +86,15 @@ run-custom: wordlist build
8486

8587
# Docker commands
8688
docker-build:
87-
docker build -t $(BINARY_NAME) .
89+
docker build --build-arg VERSION=$(VERSION) -t $(BINARY_NAME) .
8890

8991
docker-run:
9092
docker run --rm -v $(PWD)/data:/data $(BINARY_NAME) -w /data/wordlist.txt -v example.com
9193

9294
# Run Docker in simulation mode (completely safe)
9395
docker-simulate:
94-
docker build -t $(BINARY_NAME) .
95-
docker run --rm $(BINARY_NAME) -simulate -hit-rate $(HIT_RATE) -w /root/examples/sample_wordlist.txt -v example.com
96+
docker build --build-arg VERSION=$(VERSION) -t $(BINARY_NAME) .
97+
docker run --rm $(BINARY_NAME) -simulate -hit-rate $(HIT_RATE) -w /home/nonroot/examples/sample_wordlist.txt -v example.com
9698

9799
# Help command
98100
help:

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
[![Build](https://img.shields.io/github/actions/workflow/status/TMHSDigital/subenum/go.yml?branch=main&style=for-the-badge&label=build)](https://github.com/TMHSDigital/subenum/actions)
88
[![Release](https://img.shields.io/github/v/release/TMHSDigital/subenum?style=for-the-badge)](https://github.com/TMHSDigital/subenum/releases)
9-
[![Go](https://img.shields.io/badge/Go-1.24.2+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev)
9+
[![Go](https://img.shields.io/badge/Go-1.24+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev)
1010
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg?style=for-the-badge)](LICENSE)
1111
[![CodeQL](https://img.shields.io/github/actions/workflow/status/TMHSDigital/subenum/codeql.yml?label=CodeQL&style=for-the-badge)](https://github.com/TMHSDigital/subenum/actions/workflows/codeql.yml)
1212
[![Go Report Card](https://goreportcard.com/badge/github.com/TMHSDigital/subenum?style=for-the-badge&v=0.6.0)](https://goreportcard.com/report/github.com/TMHSDigital/subenum)
@@ -128,7 +128,7 @@ flowchart LR
128128

129129
## Installation
130130

131-
**Prerequisites:** Go 1.24.2+ &middot; Git &middot; Make _(optional)_ &middot; Docker _(optional)_
131+
**Prerequisites:** Go 1.24+ &middot; Git &middot; Make _(optional)_ &middot; Docker _(optional)_
132132

133133
<details>
134134
<summary><strong>Build from source</strong></summary>
@@ -310,10 +310,10 @@ No flags required. Fill in the form and press `ctrl+r` to start scanning. Last-u
310310

311311
| Layer | Components |
312312
| :--- | :--- |
313-
| Core Engine | Go 1.24.2 &middot; `net.Resolver` &middot; `context` &middot; `sync/atomic` |
313+
| Core Engine | Go 1.24 &middot; `net.Resolver` &middot; `context` &middot; `sync/atomic` |
314314
| Concurrency | goroutines &middot; channels &middot; `sync.WaitGroup` &middot; `sync.Mutex` |
315315
| TUI | Bubble Tea &middot; Bubbles (textinput, viewport, progress) &middot; Lip Gloss |
316-
| Infrastructure | Docker &middot; Alpine &middot; Make &middot; docker-compose |
316+
| Infrastructure | Docker &middot; distroless static nonroot &middot; Make &middot; docker-compose |
317317
| CI/CD | GitHub Actions &middot; CodeQL &middot; Dependabot &middot; golangci-lint v2 |
318318
| Quality | `go test -race` &middot; gosec &middot; govet &middot; staticcheck |
319319

‎docker-compose.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ services:
22
subenum:
33
build: .
44
volumes:
5-
- ./examples:/root/examples
5+
- ./examples:/home/nonroot/examples
66
- ./data:/data
77
tty: true
88
stdin_open: true

‎docs/ARCHITECTURE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ internal/tui/config.go - Session persistence (load/save ~/.config/subenu
101101
* **Purpose**: Thread-safe output that keeps stdout pipe-clean. Resolved subdomains go to stdout; everything else (progress, verbose diagnostics, errors) goes to stderr.
102102
* **Implementation**:
103103
* `output.Writer` struct with mutex-protected methods:
104-
* `Result(domain, records)` - in `text` format prints `Found: <domain>` to stdout (and the output file if configured); in `json` format buffers `{"subdomain", "records"}` objects and writes a single array at completion; in `csv` format streams `subdomain,type,value` rows with a header. The format is selected with `-format text|json|csv` (default `text`, which is byte-for-byte identical to prior behavior). The JSON array is buffered because it is a single document and does not stream; JSONL would be the streaming-friendly alternative if needed. Output formats are CLI-only for now (TUI-pending).
104+
* `Result(domain, records)` - in `text` format prints `Found: <domain>` to stdout (and the output file if configured); in `json` format buffers `{"subdomain", "records"}` objects and writes a single array at completion; in `csv` format streams `subdomain,type,value` rows with a header. The format is selected with `-format text|json|csv` (default `text`, which is byte-for-byte identical to prior behavior). The JSON array is buffered because it is a single document and does not stream; JSONL would be the streaming-friendly alternative if needed. The TUI uses `output.NewFile` for the optional result file; the live viewport stays human-readable text.
105105
* `Progress(pct, processed, total, found)` - writes a carriage-return progress line to stderr.
106106
* `Info(format, args...)` - writes an informational line to stderr.
107107
* `Error(format, args...)` - writes an error line to stderr.

‎docs/CONTRIBUTING.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ See the [Code of Conduct](CODE_OF_CONDUCT.html).
1313

1414
### Prerequisites
1515

16-
- Go 1.24.2 or later
16+
- Go 1.24 or later
1717
- Git
1818
- Make (optional but recommended)
1919
- Docker (optional, for containerized development)
@@ -142,4 +142,6 @@ go test -v -race ./...
142142
```
143143

144144
New features should include tests. New flags must be covered by at least one test case.
145-
Add network-dependent tests under `if testing.Short() { t.Skip(...) }` so they can be skipped in offline environments.
145+
Do not hit public resolvers. Use `-simulate` or the in-process responder in
146+
`internal/dns/testdns_test.go`. The optional live smoke test is gated on
147+
`SUBENUM_NETWORK_TESTS=1`.

‎docs/DEVELOPER_GUIDE.md‎

Lines changed: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This guide provides information for developers looking to contribute to or build
1313

1414
To work with `subenum`, you'll need:
1515

16-
* **Go Programming Language**: [Go 1.24.2+](https://golang.org/dl/) is required.
16+
* **Go Programming Language**: [Go 1.24+](https://golang.org/dl/) is required.
1717
* **Git**: For version control.
1818
* **Text Editor or IDE**: VS Code, GoLand, or any editor with Go support is recommended.
1919

@@ -31,11 +31,11 @@ To work with `subenum`, you'll need:
3131
To build the project, run:
3232

3333
```bash
34-
# Standard build
35-
go build
36-
37-
# If encountering VCS issues
34+
# Standard build (version fallback is the `Version` var in main.go)
3835
go build -buildvcs=false
36+
37+
# Inject the git tag into the binary
38+
go build -buildvcs=false -ldflags "-X main.Version=$(git describe --tags --dirty)"
3939
```
4040

4141
3. **Run the Tool**
@@ -92,6 +92,7 @@ subenum/
9292
│ ├── dns/
9393
│ │ ├── resolver.go # ResolveTypes, ResolveDomainWithRetry, CheckWildcard, ParseTypes
9494
│ │ ├── resolver_test.go # DNS resolution and wildcard detection tests
95+
│ │ ├── testdns_test.go # In-process UDP/TCP DNS responder for hermetic tests
9596
│ │ ├── simulate.go # SimulateResolve (synthetic DNS)
9697
│ │ └── simulate_test.go # Simulation logic tests
9798
│ ├── output/
@@ -115,8 +116,8 @@ subenum/
115116
├── .golangci.yml # Linter configuration (golangci-lint v2)
116117
├── main.go # CLI entry point: flag parsing, wiring
117118
├── main_test.go # CLI-level tests: validation, flag logic
118-
├── go.mod # Go module (Bubble Tea for TUI; zero deps in CLI-only builds)
119-
├── Dockerfile # Multi-stage Alpine build
119+
├── go.mod # Go module (Bubble Tea TUI is linked into every binary)
120+
├── Dockerfile # Multi-stage distroless static nonroot build
120121
├── docker-compose.yml # Compose orchestration
121122
├── Makefile # Build, test, lint, simulate, Docker targets
122123
├── CHANGELOG.md # Versioned release history
@@ -133,10 +134,16 @@ To run all tests:
133134
go test -v -race ./...
134135
```
135136

136-
To run only fast, offline tests (skips network-dependent tests):
137+
Default `go test ./...` is hermetic (in-process DNS responder, no outbound
138+
network). The optional live resolver smoke test is gated on an env var:
137139

138140
```bash
139-
go test -v -short ./...
141+
# Unix
142+
SUBENUM_NETWORK_TESTS=1 go test ./internal/dns -run TestLiveResolverSmoke
143+
144+
# PowerShell
145+
$env:SUBENUM_NETWORK_TESTS = "1"
146+
go test ./internal/dns -run TestLiveResolverSmoke
140147
```
141148

142149
### Writing Tests
@@ -241,10 +248,12 @@ Please follow these style guidelines when contributing:
241248

242249
`subenum` aims to minimize external dependencies, relying primarily on the Go standard library.
243250

244-
The CLI path (`run()`) has zero external dependencies. The TUI path (`-tui` flag) adds:
251+
There is no CLI-only build: `main` imports `internal/tui`, so Bubble Tea links
252+
into every binary. Direct third-party deps:
245253

246254
- [`github.com/charmbracelet/bubbletea`](https://github.com/charmbracelet/bubbletea) - Elm-architecture terminal UI framework
247255
- [`github.com/charmbracelet/bubbles`](https://github.com/charmbracelet/bubbles) - reusable TUI components (textinput, viewport, progress bar)
256+
- [`github.com/charmbracelet/lipgloss`](https://github.com/charmbracelet/lipgloss) - terminal styling
248257

249258
If you need to add a further dependency:
250259

@@ -267,9 +276,8 @@ The following capabilities are implemented and available today:
267276
268277
## Future Development
269278
270-
Areas for potential enhancement include:
279+
See `docs/ROADMAP.md` for the next-pass list. Areas still open:
271280
272-
* **TUI parity**: surface the remaining CLI options (`-type`, `-recursive`/`-depth`, `-rate`, and structured file output) in the interactive form. See `docs/ROADMAP.md`.
273281
* **Additional record types**: extend `dns.ResolveTypes` beyond A/AAAA/CNAME (for example MX, TXT, NS).
274282
* **Streaming JSON output**: a JSONL mode for live structured output that, unlike the buffered JSON array, can be piped incrementally.
275283

0 commit comments

Comments
 (0)