Skip to content

Commit ffa092c

Browse files
TMHSDigitalclaude
andcommitted
docs(monitoring): pin the example workflow and keep a durable baseline
The scheduled example ran `go install ...@main` with issues: write, used tag-pinned actions, and kept its baseline in an Actions cache that expires after the same seven days as its schedule. - Installs a pinned release archive verified against checksums.txt (v0.9.0 is the first release with -diff); actions are SHA-pinned. - The baseline is the newest unexpired results artifact (90 days), and only a run whose verdict is complete replaces it, so a degraded scan cannot shrink the baseline. Fixes #123 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 504bf1c commit ffa092c

1 file changed

Lines changed: 45 additions & 24 deletions

File tree

‎docs/monitoring.md‎

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -45,11 +45,15 @@ subenum -w wordlist.txt -format jsonl -diff previous.jsonl -o current.jsonl exam
4545

4646
## Example: a scheduled GitHub Actions workflow
4747

48-
This workflow scans every Monday, keeps the previous results in the Actions
49-
cache, and opens an issue when new names appear. Commit your wordlist as
48+
This workflow scans every Monday, keeps the previous results as a workflow
49+
artifact, and opens an issue when new names appear. Commit your wordlist as
5050
`wordlist.txt`, set `TARGET` to a domain you own, and save it as
5151
`.github/workflows/subdomain-monitor.yml`.
5252

53+
It runs with `issues: write`, so it pins everything it runs: subenum is a
54+
release archive checked against the release's `checksums.txt` (`-diff` first
55+
shipped in v0.9.0), and each action is pinned to a commit.
56+
5357
```yaml
5458
name: Subdomain monitor
5559

@@ -60,32 +64,42 @@ on:
6064

6165
permissions:
6266
contents: read
67+
actions: read # download the previous run's results
6368
issues: write
6469

6570
env:
6671
TARGET: example.com # a domain you own or are authorized to scan
72+
SUBENUM_VERSION: 0.9.0 # a release tag without the "v"
6773

6874
jobs:
6975
monitor:
7076
runs-on: ubuntu-latest
7177
steps:
72-
- uses: actions/checkout@v5
73-
74-
- uses: actions/setup-go@v6
75-
with:
76-
go-version: stable
78+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
7779

7880
- name: Install subenum
79-
# -diff ships after v0.8.0; pin the first release tag that includes it
80-
# once one exists, instead of tracking main.
81-
run: go install github.com/TMHSDigital/subenum@main
82-
83-
- name: Restore previous results
84-
uses: actions/cache/restore@v4
85-
with:
86-
path: previous.jsonl
87-
key: subenum-${{ env.TARGET }}-${{ github.run_id }}
88-
restore-keys: subenum-${{ env.TARGET }}-
81+
env:
82+
GH_TOKEN: ${{ github.token }}
83+
run: |
84+
archive="subenum_${SUBENUM_VERSION}_linux_amd64.tar.gz"
85+
gh release download "v${SUBENUM_VERSION}" --repo TMHSDigital/subenum \
86+
--pattern "$archive" --pattern checksums.txt
87+
sha256sum --check --ignore-missing checksums.txt
88+
tar -xzf "$archive" subenum
89+
sudo install subenum /usr/local/bin/
90+
91+
- name: Download previous results
92+
# The newest results artifact, from the last complete run: unlike a
93+
# cache, it does not expire after a skipped week (artifacts keep 90
94+
# days here).
95+
env:
96+
GH_TOKEN: ${{ github.token }}
97+
run: |
98+
run=$(gh api "repos/$GITHUB_REPOSITORY/actions/artifacts?name=subenum-results&per_page=1" \
99+
--jq '.artifacts[0] | select(.expired == false) | .workflow_run.id // empty')
100+
if [ -n "$run" ]; then
101+
gh run download "$run" --repo "$GITHUB_REPOSITORY" --name subenum-results
102+
fi
89103
90104
- name: Scan
91105
id: scan
@@ -96,6 +110,7 @@ jobs:
96110
-o current.jsonl -stats run.json "$TARGET" > changes.jsonl
97111
code=$?
98112
echo "code=$code" >> "$GITHUB_OUTPUT"
113+
echo "verdict=$(jq -r .verdict run.json)" >> "$GITHUB_OUTPUT"
99114
jq -r '"verdict: \(.verdict) (\(.reason))"' run.json
100115
# 0 = no changes, 4 = changes; anything else is a failed scan.
101116
[ "$code" -eq 0 ] || [ "$code" -eq 4 ]
@@ -112,19 +127,25 @@ jobs:
112127
gh issue create --repo "$GITHUB_REPOSITORY" \
113128
--title "New subdomains of $TARGET ($(date -u +%F))" --body-file body.md
114129
130+
# Only a complete run becomes the next baseline: a degraded one may be
131+
# missing names whose lookups failed.
115132
- name: Keep the current results for next time
133+
if: steps.scan.outputs.verdict == 'complete'
116134
run: mv current.jsonl previous.jsonl
117135

118-
- name: Save results
119-
uses: actions/cache/save@v4
136+
- if: steps.scan.outputs.verdict == 'complete'
137+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
120138
with:
121-
path: previous.jsonl
122-
key: subenum-${{ env.TARGET }}-${{ github.run_id }}
139+
name: subenum-results
140+
path: |
141+
previous.jsonl
142+
run.json
143+
retention-days: 90
123144
```
124145
125-
Actions caches expire after seven days without use, so with a weekly schedule
126-
the baseline is refreshed every run. For a longer gap, store `previous.jsonl`
127-
somewhere durable (an artifact, a branch, or object storage) instead.
146+
A failed, degraded or unreliable scan uploads nothing, so the next run still
147+
compares against the last complete baseline. To keep a baseline longer than 90 days,
148+
commit `previous.jsonl` to a branch or store it in object storage instead.
128149

129150
A webhook works the same way as the issue step: post `changes.jsonl` (or the
130151
`added` names) to Slack, Teams or your alerting endpoint.

0 commit comments

Comments
 (0)