Skip to content

Commit 99d42cc

Browse files
TMHSDigitalclaude
andcommitted
feat: composite GitHub Action (action.yml) for scheduled monitoring
Installs a release checked against checksums.txt (or builds the checkout with version: source), downloads the newest baseline artifact for -diff, runs subenum with -silent/-stats/JSONL and optional -sarif, writes a job summary table, sets verdict/found/added/removed/results/stats outputs, saves a complete run's results as the next baseline, and fails on the configured verdict. A CI job runs it against a lab zone on Linux, macOS and Windows, including a diff run. Monitoring docs show it end to end. Marketplace listing needs a release and a manual publish step. Refs #126 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 58e19ad commit 99d42cc

5 files changed

Lines changed: 317 additions & 1 deletion

File tree

‎.github/workflows/go.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,58 @@ jobs:
9797
if: matrix.go == 'stable'
9898
run: go run golang.org/x/vuln/cmd/govulncheck@latest ./...
9999

100+
# Runs the composite action (action.yml, #126) from this checkout against
101+
# a lab zone on every runner OS: a scan, then a diff against its results.
102+
action:
103+
runs-on: ${{ matrix.os }}
104+
permissions:
105+
contents: read
106+
strategy:
107+
fail-fast: false
108+
matrix:
109+
os: [ ubuntu-latest, macos-latest, windows-latest ]
110+
steps:
111+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
112+
113+
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
114+
with:
115+
go-version-file: 'go.mod'
116+
cache: false
117+
118+
- name: Scan a lab zone with the action
119+
id: scan
120+
uses: ./
121+
with:
122+
version: source
123+
domain: lab.example
124+
args: -simulate-zone examples/labs/lab1-first-scan.zone -type A,CNAME
125+
sarif: takeovers.sarif
126+
127+
- name: Check the first scan
128+
shell: bash
129+
run: |
130+
set -euo pipefail
131+
test "${{ steps.scan.outputs.verdict }}" = complete
132+
test "${{ steps.scan.outputs.found }}" -ge 5
133+
grep -q 'dangling-cname' takeovers.sarif
134+
cp "${{ steps.scan.outputs.results }}" previous.jsonl
135+
echo "gone.lab.example" >> previous.jsonl
136+
137+
- name: Diff against it
138+
id: diff
139+
uses: ./
140+
with:
141+
version: source
142+
domain: lab.example
143+
args: -simulate-zone examples/labs/lab1-first-scan.zone -type A,CNAME
144+
previous: previous.jsonl
145+
146+
- name: Check the diff
147+
shell: bash
148+
run: |
149+
test "${{ steps.diff.outputs.added }}" = 0
150+
test "${{ steps.diff.outputs.removed }}" = 1
151+
100152
# Builds the Dockerfile for both published platforms without pushing, so a
101153
# broken image is caught on the PR rather than during a release.
102154
docker:

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [Unreleased]
99

1010
### Added
11+
- A GitHub Action: `uses: TMHSDigital/subenum@<release>` installs a release verified against `checksums.txt`, diffs against the previous complete run (kept as an artifact, or a `previous` file), can write SARIF, writes a job summary table, exposes `verdict`/`found`/`added`/`removed` outputs and fails the job on a configurable verdict. CI runs it from the checkout against a lab zone on Linux, macOS and Windows (#126).
1112
- Certificate Transparency seeding: `-ct` adds the names crt.sh knows under each target (one HTTPS request, no API key) as candidates after the wordlist and as `-permute` seeds; every name is still resolved before it is reported. A crt.sh outage is a warning, the report gains `ct_names` and `ct_error`, a resumed scan reuses the fetched names, and lab mode refuses `-ct` (#130).
1213
- `-sarif <file>` writes takeover candidates as a SARIF 2.1.0 log (validated against the OASIS schema): one rule per kind of finding, with a security severity, the CNAME target in the message and a stable fingerprint per name, ready for `github/codeql-action/upload-sarif`. The Monitoring page shows the upload step (#129).
1314
- `-silent` for pipelines: bare result names on stdout and nothing on stderr but errors and a one-line warning when results are simulated. A new [Pipelines](docs/pipelines.md) page chains subenum with dnsx, httpx and nuclei and gates each step on the run-quality verdict (#128).

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -442,7 +442,7 @@ subenum -permute -format jsonl -o results.jsonl example.com
442442

443443
### Monitoring for new subdomains
444444

445-
`-diff previous.jsonl` reports only what changed since an earlier run: `+ name` for new subdomains and `- name` for ones that disappeared (only when the run's verdict is `complete`, and only after a fresh lookup of the name returns NXDOMAIN, so names this run did not test and failed lookups are never mistaken for removals). The `-o` file keeps the full current results for the next comparison, and the exit code is `4` when anything changed. [docs/monitoring.md](docs/monitoring.md) has a ready-to-use scheduled GitHub Actions workflow that opens an issue when new names appear.
445+
`-diff previous.jsonl` reports only what changed since an earlier run: `+ name` for new subdomains and `- name` for ones that disappeared (only when the run's verdict is `complete`, and only after a fresh lookup of the name returns NXDOMAIN, so names this run did not test and failed lookups are never mistaken for removals). The `-o` file keeps the full current results for the next comparison, and the exit code is `4` when anything changed. The repository is also a GitHub Action (`uses: TMHSDigital/subenum@<release>`) that installs a verified release, keeps the baseline as an artifact, writes a job summary and fails on a bad verdict; [docs/monitoring.md](docs/monitoring.md) documents it and a hand-written scheduled workflow that opens an issue when new names appear.
446446

447447
```bash
448448
subenum -w wordlist.txt -format jsonl -diff previous.jsonl -o current.jsonl example.com

‎action.yml‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
name: subenum
2+
description: Subdomain enumeration you can trust, with change detection and a run-quality verdict that gates the job.
3+
author: TMHSDigital
4+
branding:
5+
icon: search
6+
color: blue
7+
8+
inputs:
9+
domain:
10+
description: Domain to scan. Only scan domains you own or are authorized to test.
11+
required: false
12+
default: ""
13+
domains-file:
14+
description: File of apex domains, one per line (-dL), instead of domain.
15+
required: false
16+
default: ""
17+
wordlist:
18+
description: Wordlist file (-w). Empty uses the bundled top-5000 list.
19+
required: false
20+
default: ""
21+
args:
22+
description: Extra subenum flags, space-separated (no quoting), e.g. "-rate 200 -type A,AAAA,CNAME -ct".
23+
required: false
24+
default: ""
25+
previous:
26+
description: A previous results file to diff against (-diff). Overrides baseline-artifact.
27+
required: false
28+
default: ""
29+
baseline-artifact:
30+
description: >-
31+
Name of a workflow artifact holding the previous results. The newest one
32+
is downloaded and diffed against, and a complete run uploads its results
33+
under the same name for next time. Empty disables it.
34+
required: false
35+
default: ""
36+
sarif:
37+
description: Write takeover candidates to this SARIF file, for github/codeql-action/upload-sarif. Needs CNAME in -type.
38+
required: false
39+
default: ""
40+
fail-on:
41+
description: "Fail the step when the verdict is at least this bad: unreliable, degraded or never."
42+
required: false
43+
default: unreliable
44+
version:
45+
description: subenum release to install ("latest", or a tag such as v0.9.0), or "source" to build the action's own checkout (needs Go).
46+
required: false
47+
default: latest
48+
token:
49+
description: Token for downloading the release and the baseline artifact.
50+
required: false
51+
default: ${{ github.token }}
52+
53+
outputs:
54+
verdict:
55+
description: Run-quality verdict, complete, degraded or unreliable.
56+
value: ${{ steps.scan.outputs.verdict }}
57+
found:
58+
description: Names found.
59+
value: ${{ steps.scan.outputs.found }}
60+
added:
61+
description: Names added since the previous results (with previous or baseline-artifact).
62+
value: ${{ steps.scan.outputs.added }}
63+
removed:
64+
description: Names removed since the previous results.
65+
value: ${{ steps.scan.outputs.removed }}
66+
results:
67+
description: Path of the full results (JSONL).
68+
value: ${{ steps.scan.outputs.results }}
69+
stats:
70+
description: Path of the run-quality report (JSON).
71+
value: ${{ steps.scan.outputs.stats }}
72+
73+
runs:
74+
using: composite
75+
steps:
76+
- name: Install subenum
77+
shell: bash
78+
env:
79+
GH_TOKEN: ${{ inputs.token }}
80+
VERSION: ${{ inputs.version }}
81+
run: |
82+
set -euo pipefail
83+
bin="$RUNNER_TEMP/subenum-bin"
84+
mkdir -p "$bin"
85+
if [ "$VERSION" = source ]; then
86+
(cd "$GITHUB_ACTION_PATH" && go build -trimpath -o "$bin/" .)
87+
else
88+
if [ "$VERSION" = latest ]; then
89+
VERSION=$(gh release view --repo TMHSDigital/subenum --json tagName --jq .tagName)
90+
fi
91+
v="${VERSION#v}"
92+
case "$(uname -s)" in
93+
Linux) os=linux ext=tar.gz ;;
94+
Darwin) os=darwin ext=tar.gz ;;
95+
MINGW* | MSYS* | CYGWIN*) os=windows ext=zip ;;
96+
*) echo "unsupported runner OS $(uname -s)"; exit 1 ;;
97+
esac
98+
case "$(uname -m)" in
99+
x86_64 | amd64) arch=amd64 ;;
100+
arm64 | aarch64) arch=arm64 ;;
101+
*) echo "unsupported runner architecture $(uname -m)"; exit 1 ;;
102+
esac
103+
archive="subenum_${v}_${os}_${arch}.${ext}"
104+
dl="$RUNNER_TEMP/subenum-dl"
105+
mkdir -p "$dl"
106+
gh release download "v${v}" --repo TMHSDigital/subenum --dir "$dl" --clobber \
107+
--pattern "$archive" --pattern checksums.txt
108+
(cd "$dl" && if command -v sha256sum > /dev/null; then sha256sum --check --ignore-missing checksums.txt; \
109+
else shasum -a 256 --check --ignore-missing checksums.txt; fi)
110+
if [ "$ext" = zip ]; then unzip -o -q "$dl/$archive" -d "$dl/x"; else mkdir -p "$dl/x" && tar -xzf "$dl/$archive" -C "$dl/x"; fi
111+
find "$dl/x" -maxdepth 2 -name 'subenum*' -type f \( -name subenum -o -name subenum.exe \) -exec cp {} "$bin/" \;
112+
fi
113+
echo "$bin" >> "$GITHUB_PATH"
114+
115+
- name: Download the baseline
116+
if: inputs.baseline-artifact != '' && inputs.previous == ''
117+
shell: bash
118+
env:
119+
GH_TOKEN: ${{ inputs.token }}
120+
NAME: ${{ inputs.baseline-artifact }}
121+
run: |
122+
set -euo pipefail
123+
dir="$RUNNER_TEMP/subenum-baseline"
124+
mkdir -p "$dir"
125+
run=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=$NAME&per_page=1" \
126+
--jq '.artifacts[0] | select(.expired == false) | .workflow_run.id // empty')
127+
if [ -n "$run" ]; then
128+
gh run download "$run" --repo "$GITHUB_REPOSITORY" --name "$NAME" --dir "$dir"
129+
else
130+
echo "No baseline artifact named $NAME yet; this run sets it."
131+
fi
132+
133+
- name: Scan
134+
id: scan
135+
shell: bash
136+
env:
137+
DOMAIN: ${{ inputs.domain }}
138+
DOMAINS_FILE: ${{ inputs.domains-file }}
139+
WORDLIST: ${{ inputs.wordlist }}
140+
ARGS: ${{ inputs.args }}
141+
PREVIOUS: ${{ inputs.previous }}
142+
BASELINE: ${{ inputs.baseline-artifact }}
143+
SARIF: ${{ inputs.sarif }}
144+
FAIL_ON: ${{ inputs.fail-on }}
145+
run: |
146+
set -o pipefail
147+
out="$RUNNER_TEMP/subenum-out"
148+
mkdir -p "$out"
149+
flags=(-silent -format jsonl -o "$out/results.jsonl" -stats "$out/run.json")
150+
[ -n "$WORDLIST" ] && flags+=(-w "$WORDLIST")
151+
[ -n "$SARIF" ] && flags+=(-sarif "$SARIF")
152+
prev="$PREVIOUS"
153+
if [ -z "$prev" ] && [ -n "$BASELINE" ] && [ -s "$RUNNER_TEMP/subenum-baseline/results.jsonl" ]; then
154+
prev="$RUNNER_TEMP/subenum-baseline/results.jsonl"
155+
fi
156+
[ -n "$prev" ] && flags+=(-diff "$prev")
157+
read -r -a extra <<< "$ARGS"
158+
if [ -n "$DOMAINS_FILE" ]; then target=(-dL "$DOMAINS_FILE"); else target=("$DOMAIN"); fi
159+
if [ -z "$DOMAIN" ] && [ -z "$DOMAINS_FILE" ]; then echo "::error::set domain or domains-file"; exit 2; fi
160+
161+
subenum "${flags[@]}" "${extra[@]}" "${target[@]}" > "$out/changes.jsonl"
162+
code=$?
163+
if [ ! -s "$out/run.json" ]; then echo "::error::subenum exited $code without a report"; exit "$code"; fi
164+
165+
verdict=$(jq -r .verdict "$out/run.json")
166+
reason=$(jq -r .reason "$out/run.json")
167+
found=$(jq '[.targets[].found] | add // 0' "$out/run.json")
168+
added=$(jq '.diff.added // 0' "$out/run.json")
169+
removed=$(jq '.diff.removed // 0' "$out/run.json")
170+
{
171+
echo "verdict=$verdict"; echo "found=$found"; echo "added=$added"; echo "removed=$removed"
172+
echo "results=$out/results.jsonl"; echo "stats=$out/run.json"
173+
} >> "$GITHUB_OUTPUT"
174+
175+
{
176+
echo "### subenum: $verdict"
177+
echo
178+
echo "$reason"
179+
echo
180+
echo "| Target | Verdict | Found | Queries |"
181+
echo "|---|---|---|---|"
182+
jq -r '.targets[] | "| \(.domain) | \(.verdict) | \(.found // 0) | \(.queries_sent // 0) |"' "$out/run.json"
183+
if [ -n "$prev" ]; then
184+
echo
185+
echo "**Changes since the previous results:** $added added, $removed removed."
186+
jq -r 'select(.change == "added") | "- `+ \(.subdomain)`"' "$out/changes.jsonl" | head -50
187+
jq -r 'select(.change == "removed") | "- `- \(.subdomain)`"' "$out/changes.jsonl" | head -50
188+
fi
189+
} >> "$GITHUB_STEP_SUMMARY"
190+
191+
if [ -n "$BASELINE" ] && [ "$verdict" = complete ]; then
192+
echo "upload=true" >> "$GITHUB_OUTPUT"
193+
fi
194+
# 0 = ok, 4 = changes found; 3 = some -dL targets failed (the verdict says how bad).
195+
case "$code" in 0 | 3 | 4) ;; *) exit "$code" ;; esac
196+
case "$FAIL_ON:$verdict" in
197+
unreliable:unreliable | degraded:unreliable | degraded:degraded)
198+
echo "::error::subenum verdict is $verdict: $reason"; exit 1 ;;
199+
esac
200+
201+
- name: Save the baseline
202+
if: steps.scan.outputs.upload == 'true'
203+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
204+
with:
205+
name: ${{ inputs.baseline-artifact }}
206+
path: ${{ runner.temp }}/subenum-out/results.jsonl
207+
retention-days: 90
208+
overwrite: true

‎docs/monitoring.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,61 @@ subenum -w wordlist.txt -format jsonl -diff previous.jsonl -o current.jsonl exam
4343
object with the `added` and `removed` counts, plus `still_resolving` and
4444
`unverified` when there were any.
4545

46+
## The subenum GitHub Action
47+
48+
The repository is also a GitHub Action. It installs a release (checked against
49+
its `checksums.txt`), diffs against the previous complete run's results kept as
50+
an artifact, writes a summary table to the job, and fails the job when the
51+
verdict is not good enough:
52+
53+
```yaml
54+
name: Subdomain monitor
55+
on:
56+
schedule:
57+
- cron: "0 6 * * 1"
58+
workflow_dispatch:
59+
60+
permissions:
61+
contents: read
62+
actions: read
63+
security-events: write # only for the SARIF upload
64+
65+
jobs:
66+
monitor:
67+
runs-on: ubuntu-latest
68+
steps:
69+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
70+
- id: subenum
71+
uses: TMHSDigital/subenum@v0.9.0 # pin a release, or its commit SHA
72+
with:
73+
domain: example.com # a domain you own or may test
74+
wordlist: wordlist.txt
75+
args: -rate 200 -type A,AAAA,CNAME -ct
76+
baseline-artifact: subenum-example.com
77+
sarif: takeovers.sarif
78+
fail-on: degraded
79+
- if: always() && hashFiles('takeovers.sarif') != ''
80+
uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
81+
with:
82+
sarif_file: takeovers.sarif
83+
category: subenum
84+
```
85+
86+
| Input | Default | Meaning |
87+
|---|---|---|
88+
| `domain` / `domains-file` | | What to scan (one of them) |
89+
| `wordlist` | bundled top 5000 | `-w` |
90+
| `args` | | Extra flags, space-separated |
91+
| `previous` | | A previous results file to diff against |
92+
| `baseline-artifact` | | Artifact name for the baseline: downloaded before, replaced after a complete run |
93+
| `sarif` | | Write takeover candidates as SARIF |
94+
| `fail-on` | `unreliable` | Fail on this verdict or worse: `unreliable`, `degraded` or `never` |
95+
| `version` | `latest` | Release to install, or `source` to build the action's checkout |
96+
97+
Outputs: `verdict`, `found`, `added`, `removed`, and the paths `results` (JSONL)
98+
and `stats` (the run-quality report). The step below builds the same thing by
99+
hand, if you prefer to see every command.
100+
46101
## Example: a scheduled GitHub Actions workflow
47102

48103
This workflow scans every Monday, keeps the previous results as a workflow

0 commit comments

Comments
 (0)