Repository navigation
Expand file tree
/
Copy pathaction.yml
More file actions
352 lines (341 loc) · 16.5 KB
/
Copy pathaction.yml
File metadata and controls
352 lines (341 loc) · 16.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
name: subenum
description: Subdomain enumeration you can trust, with change detection and a run-quality verdict that gates the job.
author: TMHSDigital
branding:
icon: search
color: blue
inputs:
domain:
description: Domain to scan. Only scan domains you own or are authorized to test.
required: false
default: ""
domains-file:
description: File of apex domains, one per line (-dL), instead of domain.
required: false
default: ""
wordlist:
description: Wordlist file (-w). Empty uses the bundled top-5000 list.
required: false
default: ""
args:
description: >-
Extra subenum flags, separated by spaces or newlines (no quoting), e.g.
"-rate 200 -type A,AAAA,CNAME -ct". A multi-line "args: |" block works.
required: false
default: ""
previous:
description: A previous results file to diff against (-diff). Overrides baseline-artifact.
required: false
default: ""
baseline-artifact:
description: >-
Name of a workflow artifact holding the previous results. The newest one
is downloaded and diffed against, and a complete run uploads its results
under the same name for next time. A run that max-duration stops saves
its resume state there too, and the next run continues that scan rather
than starting over. Empty disables it.
required: false
default: ""
sarif:
description: Write takeover candidates to this SARIF file, for github/codeql-action/upload-sarif. Needs CNAME or NS in -type.
required: false
default: ""
max-duration:
description: >-
Time budget for the scan (-max-duration), e.g. 20m. Keep it under the
job's timeout-minutes: at the budget the scan stops testing new names
and still writes its results and report, with a degraded verdict. With
baseline-artifact, the next run resumes where this one stopped, so a
scheduled job works through a large wordlist over several runs.
Empty means no budget. Needs a subenum release newer than v0.10.0.
required: false
default: ""
fail-on:
description: >-
Fail the step when the verdict is at least this bad: unreliable, degraded
or never. With never, a scan that failed (verdict unreliable) still passes
the step; read the verdict output instead. Usage errors and a run with no
report always fail.
required: false
default: unreliable
version:
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).
required: false
default: latest
token:
description: Token for downloading the release and the baseline artifact.
required: false
default: ${{ github.token }}
outputs:
verdict:
description: Run-quality verdict, complete, degraded or unreliable.
value: ${{ steps.scan.outputs.verdict }}
resumed:
description: true when this run continued a scan that an earlier run's max-duration stopped (with baseline-artifact).
value: ${{ steps.scan.outputs.resumed }}
found:
description: Names found.
value: ${{ steps.scan.outputs.found }}
added:
description: Names added since the previous results (with previous or baseline-artifact).
value: ${{ steps.scan.outputs.added }}
removed:
description: Names removed since the previous results.
value: ${{ steps.scan.outputs.removed }}
changed:
description: Names whose records changed since the previous results (add -diff-records to args).
value: ${{ steps.scan.outputs.changed }}
changes:
description: >-
Path of the changes (JSONL): one line per added, removed or changed name
with a "change" field, then the run summary. Empty when there were no
previous results to diff against.
value: ${{ steps.scan.outputs.changes }}
takeovers:
description: Takeover candidates among the names found (needs CNAME or NS in -type).
value: ${{ steps.scan.outputs.takeovers }}
internal:
description: Names found that answer with an address that is not public.
value: ${{ steps.scan.outputs.internal }}
results:
description: Path of the full results (JSONL).
value: ${{ steps.scan.outputs.results }}
stats:
description: Path of the run-quality report (JSON).
value: ${{ steps.scan.outputs.stats }}
runs:
using: composite
steps:
- name: Install subenum
shell: bash
env:
GH_TOKEN: ${{ inputs.token }}
VERSION: ${{ inputs.version }}
run: |
set -euo pipefail
bin="$RUNNER_TEMP/subenum-bin"
mkdir -p "$bin"
if [ "$VERSION" = source ]; then
(cd "$GITHUB_ACTION_PATH" && go build -trimpath -o "$bin/" .)
else
if [ "$VERSION" = latest ]; then
VERSION=$(gh release view --repo TMHSDigital/subenum --json tagName --jq .tagName)
fi
v="${VERSION#v}"
case "$(uname -s)" in
Linux) os=linux ext=tar.gz ;;
Darwin) os=darwin ext=tar.gz ;;
MINGW* | MSYS* | CYGWIN*) os=windows ext=zip ;;
*) echo "unsupported runner OS $(uname -s)"; exit 1 ;;
esac
case "$(uname -m)" in
x86_64 | amd64) arch=amd64 ;;
arm64 | aarch64) arch=arm64 ;;
*) echo "unsupported runner architecture $(uname -m)"; exit 1 ;;
esac
archive="subenum_${v}_${os}_${arch}.${ext}"
dl="$RUNNER_TEMP/subenum-dl"
mkdir -p "$dl"
gh release download "v${v}" --repo TMHSDigital/subenum --dir "$dl" --clobber \
--pattern "$archive" --pattern checksums.txt
(cd "$dl" && if command -v sha256sum > /dev/null; then sha256sum --check --ignore-missing checksums.txt; \
else shasum -a 256 --check --ignore-missing checksums.txt; fi)
# Checksums and archive can be replaced together. Provenance binds
# this exact archive to the repository's trusted release workflow.
gh attestation verify "$dl/$archive" --repo TMHSDigital/subenum
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
find "$dl/x" -maxdepth 2 -name 'subenum*' -type f \( -name subenum -o -name subenum.exe \) -exec cp {} "$bin/" \;
fi
echo "$bin" >> "$GITHUB_PATH"
- name: Download the baseline
if: inputs.baseline-artifact != '' && inputs.previous == ''
shell: bash
env:
GH_TOKEN: ${{ inputs.token }}
NAME: ${{ inputs.baseline-artifact }}
run: |
set -euo pipefail
dir="$RUNNER_TEMP/subenum-baseline"
# A second use in the same job must not resume or diff the first's.
rm -rf "$dir"
mkdir -p "$dir"
# An earlier use in this job kept a copy of what it saved: the
# artifact list can lag an upload by seconds, so it may not show yet.
saved="$RUNNER_TEMP/subenum-saved/${NAME//[^A-Za-z0-9._-]/_}"
if [ -d "$saved" ]; then
cp -R "$saved/." "$dir/"
echo "Using the baseline an earlier step in this job saved."
exit 0
fi
# upload-artifact allows &, +, # and % in names. Encode the name so the
# query string cannot truncate or reinterpret it (#407).
encoded=$(jq -rn --arg n "$NAME" '$n|@uri')
run=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=$encoded&per_page=1" \
--jq '.artifacts[0] | select(.expired == false) | .workflow_run.id // empty')
if [ -n "$run" ]; then
gh run download "$run" --repo "$GITHUB_REPOSITORY" --name "$NAME" --dir "$dir"
else
echo "No baseline artifact named $NAME yet; this run sets it."
fi
- name: Scan
id: scan
shell: bash
env:
DOMAIN: ${{ inputs.domain }}
DOMAINS_FILE: ${{ inputs.domains-file }}
WORDLIST: ${{ inputs.wordlist }}
ARGS: ${{ inputs.args }}
PREVIOUS: ${{ inputs.previous }}
BASELINE: ${{ inputs.baseline-artifact }}
SARIF: ${{ inputs.sarif }}
MAX_DURATION: ${{ inputs.max-duration }}
FAIL_ON: ${{ inputs.fail-on }}
run: |
set -o pipefail
out="$RUNNER_TEMP/subenum-out"
mkdir -p "$out"
# A second use in the same job must not read the first use's report.
rm -f "$out/run.json" "$out/results.jsonl" "$out/changes.jsonl" "$out/state.json"
flags=(-silent -format jsonl -o "$out/results.jsonl" -stats "$out/run.json" -state "$out/state.json")
[ -n "$WORDLIST" ] && flags+=(-w "$WORDLIST")
[ -n "$SARIF" ] && flags+=(-sarif "$SARIF")
[ -n "$MAX_DURATION" ] && flags+=(-max-duration "$MAX_DURATION")
prev="$PREVIOUS"
if [ -z "$prev" ] && [ -n "$BASELINE" ] && [ -s "$RUNNER_TEMP/subenum-baseline/results.jsonl" ]; then
prev="$RUNNER_TEMP/subenum-baseline/results.jsonl"
fi
[ -n "$prev" ] && flags+=(-diff "$prev")
# -d '' reads past newlines, so every line of an "args: |" block counts;
# read then returns 1 at the end of input.
read -r -d '' -a extra <<< "$ARGS" || true
if [ -n "$DOMAINS_FILE" ]; then target=(-dL "$DOMAINS_FILE"); else target=("$DOMAIN"); fi
if [ -z "$DOMAIN" ] && [ -z "$DOMAINS_FILE" ]; then echo "::error::set domain or domains-file"; exit 2; fi
# The runner's bash has -e: capture the exit code instead of dying on 4.
code=0
# A run that max-duration stopped left its resume state in the
# baseline artifact (#352). The state replays its own command line,
# output paths included, so it is only resumed when this run's inputs
# (and output directory) are the same; subenum itself refuses a
# changed wordlist or other input file, and then a new scan starts.
base="$RUNNER_TEMP/subenum-baseline"
key=$(printf '%s\n' "$DOMAIN" "$DOMAINS_FILE" "$WORDLIST" "$ARGS" "$SARIF" "$out" "$prev")
resumed=false
if [ -z "$PREVIOUS" ] && [ -n "$BASELINE" ] && [ -s "$base/state.json" ]; then
if [ "$(cat "$base/state.key" 2> /dev/null)" = "$key" ]; then
echo "Resuming the scan an earlier run's time budget stopped."
subenum -resume "$base/state.json" -max-duration "${MAX_DURATION:-0}" > "$out/changes.jsonl" || code=$?
if [ -s "$out/run.json" ]; then
resumed=true
else
echo "::notice::The stopped scan could not be resumed (exit $code, see above); starting a new scan."
code=0
fi
else
echo "::notice::The inputs changed since the run that saved the resume state; starting a new scan."
fi
fi
if [ "$resumed" = false ]; then
subenum "${flags[@]}" "${extra[@]}" "${target[@]}" > "$out/changes.jsonl" || code=$?
fi
if [ ! -s "$out/run.json" ]; then
echo "::error::subenum exited $code without a report"
# -dry-run and -version exit 0 without writing a report; the step
# must still fail rather than pass on the previous use's outputs (#407).
[ "$code" -ne 0 ] || code=1
exit "$code"
fi
verdict=$(jq -r .verdict "$out/run.json")
reason=$(jq -r .reason "$out/run.json")
# -permute hits are counted apart from the main pass.
found=$(jq '[.targets[] | (.found // 0) + (.permutation.found // 0)] | add // 0' "$out/run.json")
added=$(jq '.diff.added // 0' "$out/run.json")
removed=$(jq '.diff.removed // 0' "$out/run.json")
changed=$(jq '.diff.changed // 0' "$out/run.json")
takeovers=$(jq '[.targets[].takeover_candidates // 0] | add // 0' "$out/run.json")
internal=$(jq '[.targets[].internal_addresses // 0] | add // 0' "$out/run.json")
{
echo "verdict=$verdict"; echo "resumed=$resumed"; echo "found=$found";echo "added=$added"; echo "removed=$removed"; echo "changed=$changed"
echo "takeovers=$takeovers"; echo "internal=$internal"
echo "results=$out/results.jsonl"; echo "stats=$out/run.json"
# Without -diff the scan prints every result, not changes.
if [ -n "$prev" ]; then echo "changes=$out/changes.jsonl"; fi
} >> "$GITHUB_OUTPUT"
{
echo "### subenum: $verdict"
echo
echo "$reason"
echo
echo "| Target | Verdict | Found | Queries | Takeover candidates | Internal addresses |"
echo "|---|---|---|---|---|---|"
jq -r '.targets[] | "| \(.domain) | \(.verdict) | \((.found // 0) + (.permutation.found // 0)) | \(.queries_sent // 0) | \(.takeover_candidates // 0) | \(.internal_addresses // 0) |"' "$out/run.json"
if [ "$takeovers" != 0 ]; then
echo
echo "**Takeover candidates:** $takeovers"
# jq stops at 50 itself: `| head -50` would close the pipe under
# pipefail and fail the step on a long list.
jq -rn 'limit(50; inputs | select(.takeover_candidate) | "- `\(.subdomain)`: \(.takeover_candidate)")' "$out/results.jsonl"
fi
if [ -n "$prev" ]; then
echo
echo "**Changes since the previous results:** $added added, $removed removed, $changed changed."
jq -rn 'limit(50; inputs | select(.change == "added") | "- `+ \(.subdomain)`")' "$out/changes.jsonl"
jq -rn 'limit(50; inputs | select(.change == "removed") | "- `- \(.subdomain)`")' "$out/changes.jsonl"
jq -rn 'limit(50; inputs | select(.change == "changed") | "- `~ \(.subdomain)`: \([.previous_records[]? | "\(.type) \(.value)"] | join(", ")) -> \([.records[] | "\(.type) \(.value)"] | join(", "))")' "$out/changes.jsonl"
fi
} >> "$GITHUB_STEP_SUMMARY"
# The artifact carries a complete run's results, or a stopped run's
# resume state next to the results it still diffs against (#352).
carry="$RUNNER_TEMP/subenum-carry"
rm -rf "$carry"
mkdir -p "$carry"
if [ -n "$BASELINE" ] && [ "$verdict" = complete ]; then
cp "$out/results.jsonl" "$carry/"
echo "upload=true" >> "$GITHUB_OUTPUT"
elif [ -n "$BASELINE" ] && [ -z "$PREVIOUS" ] && [ -s "$out/state.json" ]; then
if [ -s "$base/results.jsonl" ]; then cp "$base/results.jsonl" "$carry/"; fi
cp "$out/state.json" "$carry/"
printf '%s\n' "$key" > "$carry/state.key"
echo "carry-state=true" >> "$GITHUB_OUTPUT"
echo "::notice::The scan stopped before it finished; the next run with baseline-artifact $BASELINE continues it."
elif [ -n "$BASELINE" ] && [ "$resumed" = true ]; then
# The resumed scan finished below complete and spent its state.
# Replace the artifact without that state, or every later run
# resumes the same remainder again (#396). The marker file keeps
# the upload from being empty when there are no results to carry.
if [ -s "$base/results.jsonl" ]; then cp "$base/results.jsonl" "$carry/"; fi
printf 'The resumed scan finished %s; the next run starts a new scan.\n' "$verdict" > "$carry/state-spent.txt"
echo "carry-state=true" >> "$GITHUB_OUTPUT"
fi
# 0 = ok, 4 = changes found; 3 = some -dL targets failed and 1 = the
# scan failed, and the verdict says how bad, so fail-on decides. A 1
# with a complete verdict is a failed output file: always fail.
case "$code:$verdict" in
0:* | 3:* | 4:* | 1:degraded | 1:unreliable) ;;
*) exit "$code" ;;
esac
case "$FAIL_ON:$verdict" in
unreliable:unreliable | degraded:unreliable | degraded:degraded)
echo "::error::subenum verdict is $verdict: $reason"; exit 1 ;;
esac
- name: Save the baseline
id: save
# A stopped run whose verdict fails the step under fail-on still saves
# its state.
if: ${{ (success() && steps.scan.outputs.upload == 'true') || (!cancelled() && steps.scan.outputs.carry-state == 'true') }}
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: ${{ inputs.baseline-artifact }}
path: ${{ runner.temp }}/subenum-carry/
retention-days: 90
overwrite: true
- name: Keep the baseline for later uses in this job
if: ${{ !cancelled() && steps.save.outcome == 'success' }}
shell: bash
env:
NAME: ${{ inputs.baseline-artifact }}
run: |
set -euo pipefail
saved="$RUNNER_TEMP/subenum-saved/${NAME//[^A-Za-z0-9._-]/_}"
rm -rf "$saved"
mkdir -p "$saved"
cp -R "$RUNNER_TEMP/subenum-carry/." "$saved/"