actions-warden 0.4.0 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +46 -8
- package/CONTRIBUTING.md +6 -2
- package/README.md +171 -61
- package/RELEASING.md +3 -2
- package/SECURITY.md +15 -5
- package/docs/AI-AGENTS.md +109 -29
- package/docs/CLI.md +284 -60
- package/docs/CONFIGURATION.md +34 -11
- package/docs/DEVELOPMENT.md +97 -24
- package/docs/GITHUB-ACTION.md +157 -27
- package/docs/JAVASCRIPT-API.md +172 -8
- package/docs/OUTPUTS.md +399 -36
- package/docs/README.md +1 -1
- package/examples/README.md +21 -0
- package/examples/baseline-adoption/README.md +79 -0
- package/examples/baseline-adoption/github-actions.yml +56 -0
- package/examples/baseline-adoption/policy.yml +7 -0
- package/examples/ci-violation-reporting/README.md +82 -0
- package/examples/ci-violation-reporting/github-actions.yml +55 -0
- package/examples/ci-violation-reporting/policy.yml +7 -0
- package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
- package/examples/csv-reporting/README.md +50 -0
- package/examples/csv-reporting/github-actions.yml +59 -0
- package/examples/html-organization-report/README.md +35 -0
- package/examples/html-organization-report/github-actions.yml +61 -0
- package/examples/notifications/README.md +67 -0
- package/examples/notifications/github-actions.yml +163 -0
- package/examples/org-scan.yml +24 -5
- package/examples/sarif-code-scanning/README.md +42 -0
- package/examples/sarif-code-scanning/github-actions.yml +66 -0
- package/examples/upgrade-pr.yml +1 -1
- package/llms.txt +14 -5
- package/package.json +8 -4
- package/skills/actions-warden/SKILL.md +78 -35
- package/src/action.js +351 -174
- package/src/cli.js +191 -177
- package/src/commands/audit.js +17 -30
- package/src/commands/org-scan.js +451 -280
- package/src/commands/pin.js +9 -5
- package/src/commands/report.js +7 -2
- package/src/commands/upgrade.js +9 -5
- package/src/commands/verify.js +24 -4
- package/src/index.js +5 -1
- package/src/lib/action-summary.js +656 -0
- package/src/lib/annotations.js +4 -6
- package/src/lib/baseline.js +11 -1
- package/src/lib/config.js +10 -5
- package/src/lib/destination.js +98 -0
- package/src/lib/execution.js +5 -1
- package/src/lib/formats/csv.js +125 -0
- package/src/lib/formats/html.js +394 -0
- package/src/lib/formats/json.js +17 -0
- package/src/lib/formats/sarif.js +229 -0
- package/src/lib/formats/text.js +30 -0
- package/src/lib/formats/toon.js +50 -0
- package/src/lib/formatter.js +25 -192
- package/src/lib/github-org.js +208 -102
- package/src/lib/org-artifacts.js +211 -0
- package/src/lib/org-checkpoint.js +137 -96
- package/src/lib/org-progress.js +182 -4
- package/src/lib/org-report-comparison.js +505 -0
- package/src/lib/org-report-directory.js +251 -0
- package/src/lib/org-report.js +223 -0
- package/src/lib/org-run.js +305 -0
- package/src/lib/org-schema.js +89 -0
- package/src/lib/org-source-links.js +39 -0
- package/src/lib/parser.js +5 -0
- package/src/lib/paths.js +18 -1
- package/src/lib/redact.js +58 -7
- package/src/lib/resolver.js +66 -9
- package/src/lib/types.js +137 -0
- package/src/rules/pull-request-target-checkout.js +5 -0
- package/src/rules/unpinned-action.js +2 -3
- package/src/rules/workflow-structure.js +2 -4
- package/src/version.js +1 -1
- package/src/lib/agent-mode.js +0 -174
package/docs/DEVELOPMENT.md
CHANGED
|
@@ -38,8 +38,9 @@ pre-commit install --hook-type pre-push
|
|
|
38
38
|
| `npm test` | Run the complete Vitest suite once |
|
|
39
39
|
| `npm run test:watch` | Run Vitest in watch mode |
|
|
40
40
|
| `npm run lint` | Lint source, scripts, and tests |
|
|
41
|
+
| `npm run typecheck` | Type-check the modules that opt in with `// @ts-check` (`tsc --noEmit`) |
|
|
41
42
|
| `npm run check:yaml` | Parse repository YAML files |
|
|
42
|
-
| `npm run check:docs` | Validate
|
|
43
|
+
| `npm run check:docs` | Validate links and require 100% public-surface documentation/JSDoc coverage |
|
|
43
44
|
| `npm run check:package` | Inspect the exact npm tarball manifest, required files, executable mode, and size bounds |
|
|
44
45
|
| `npm run verify-deps` | Require exact runtime and development versions |
|
|
45
46
|
| `npm run verify-version-sync` | Keep package, lockfile, bundled runtime, plugin, and public invocations aligned |
|
|
@@ -58,6 +59,7 @@ npm run check:yaml
|
|
|
58
59
|
npm run check:docs
|
|
59
60
|
npm run check:package
|
|
60
61
|
npm run lint
|
|
62
|
+
npm run typecheck
|
|
61
63
|
npm test
|
|
62
64
|
npm run audit
|
|
63
65
|
```
|
|
@@ -85,13 +87,23 @@ src/
|
|
|
85
87
|
config.js, baseline.js policy and accepted-finding controls
|
|
86
88
|
resolver.js, cache.js GitHub API, caching, ref and ownership checks
|
|
87
89
|
github-org.js read-only organization/tree/blob access
|
|
88
|
-
|
|
90
|
+
org-artifacts.js scope-keyed organization artifacts and receipts
|
|
89
91
|
org-checkpoint.js validated atomic organization resume state
|
|
90
|
-
org-
|
|
92
|
+
org-schema.js shared name/SHA patterns, severity and visibility sets, guards
|
|
93
|
+
org-source-links.js branch links and commit-pinned permalinks for scanned files
|
|
94
|
+
org-run.js shared CLI/Action organization runner: artifacts, destination checks, scan
|
|
95
|
+
org-report.js canonical organization report document and record projections
|
|
96
|
+
org-report-comparison.js validated fail-closed report change analysis
|
|
97
|
+
org-report-directory.js guarded compact/per-repository report layout
|
|
98
|
+
org-progress.js plain and JSONL structured scan progress
|
|
91
99
|
identity.js stable IDs and semantic fingerprints
|
|
92
100
|
patcher.js, writer.js source-range rewrites and guarded atomic writes
|
|
93
|
-
formatter.js,
|
|
101
|
+
formatter.js format dispatch, severity summary, and renderer re-exports
|
|
102
|
+
formats/ one serializer each: toon, text, csv, sarif, html, json
|
|
103
|
+
redact.js credential redaction
|
|
104
|
+
types.js shared JSDoc typedefs (findings, reports, records)
|
|
94
105
|
annotations.js GitHub workflow annotations
|
|
106
|
+
action-summary.js bounded Action metrics and job summaries
|
|
95
107
|
concurrency.js bounded async work
|
|
96
108
|
rules/ one module per audit rule
|
|
97
109
|
|
|
@@ -125,15 +137,30 @@ normalized action refs → GitHub resolution and ownership verification
|
|
|
125
137
|
An organization scan follows:
|
|
126
138
|
|
|
127
139
|
```text
|
|
128
|
-
repository listing → default-branch Git tree
|
|
129
|
-
→ in-memory auditSources
|
|
140
|
+
repository listing → default-branch commit → Git tree by that tree SHA
|
|
141
|
+
→ bounded YAML blob reads → in-memory auditSources
|
|
142
|
+
→ repository aggregation (file details, permalinks)
|
|
130
143
|
|
|
131
|
-
|
|
132
|
-
|
|
144
|
+
default/explicit checkpoint → identity validation → fresh tree SHA comparison
|
|
145
|
+
→ reuse unchanged error-free result or rescan
|
|
146
|
+
|
|
147
|
+
optional previous JSON report → analysis identity validation
|
|
148
|
+
→ fingerprint comparison
|
|
149
|
+
→ new/resolved/unchanged/unknown evidence
|
|
150
|
+
|
|
151
|
+
optional report directory → compact aggregate + repository evidence
|
|
152
|
+
→ integrity manifest written last
|
|
133
153
|
```
|
|
134
154
|
|
|
135
155
|
Remote repositories are never cloned, checked out, imported, or executed.
|
|
136
156
|
|
|
157
|
+
Broader scanners that already own a bounded GitHub evidence snapshot integrate
|
|
158
|
+
at `auditSources`; they must not invoke `scanOrganization` over the same scope.
|
|
159
|
+
The caller retains acquisition, snapshot, and aggregate-policy ownership while
|
|
160
|
+
actions-warden retains parser, suppression, identity, and workflow-rule
|
|
161
|
+
ownership. Caller caches must include the exact actions-warden version and live
|
|
162
|
+
rule catalog in their compatibility identity.
|
|
163
|
+
|
|
137
164
|
## Safety invariants
|
|
138
165
|
|
|
139
166
|
Changes must preserve these boundaries:
|
|
@@ -151,29 +178,57 @@ Changes must preserve these boundaries:
|
|
|
151
178
|
network or workflow mutation, cannot replace selected/default-discovery
|
|
152
179
|
workflows or reserved policy paths, and are checked against active controls
|
|
153
180
|
again before output is written.
|
|
154
|
-
- Credentials are redacted in JSON, TOON, text, SARIF, annotations, and
|
|
181
|
+
- Credentials are redacted in JSON, TOON, text, CSV, SARIF, HTML, annotations, and
|
|
155
182
|
top-level errors.
|
|
183
|
+
- HTML contains no externally loaded assets or dynamic report data in
|
|
184
|
+
executable JavaScript. Values are escaped, links require HTTPS, a restrictive
|
|
185
|
+
content security policy is emitted, and output is capped at 32 MiB.
|
|
186
|
+
- CSV keeps one physical line per record, escapes control characters, applies
|
|
187
|
+
spreadsheet-formula protection, uses deterministic columns, and retains an
|
|
188
|
+
explicit final status row.
|
|
156
189
|
- Finding and change IDs exclude absolute checkout paths.
|
|
157
190
|
- Parser errors remain findings and cannot be baselined away.
|
|
158
|
-
- Organization coverage failures remain visible and make status
|
|
191
|
+
- Organization operational coverage failures remain visible and make status
|
|
192
|
+
fail; intentional repository caps remain visible through `coverage.complete`.
|
|
193
|
+
- Organization comparison requires a matching scope/policy/rule analysis
|
|
194
|
+
identity. Unmatched previous findings are resolved only when the current
|
|
195
|
+
repository result has complete coverage; otherwise they remain unknown.
|
|
159
196
|
- Organization source reads remain count- and size-bounded and bypass disk
|
|
160
197
|
cache.
|
|
198
|
+
- Embedded source audits consume only the caller-supplied file set; they do not
|
|
199
|
+
perform a second repository discovery pass.
|
|
161
200
|
- Organization resume never trusts a stale result without fresh discovery and
|
|
162
|
-
a matching repository identity, default branch, and tree SHA.
|
|
163
|
-
are never reused
|
|
201
|
+
a matching repository identity, default branch, and tree SHA. Results with
|
|
202
|
+
operational failures or parse-error findings are never reused and are always
|
|
203
|
+
rescanned. The commit and every permalink come from the current run, never
|
|
204
|
+
from a checkpoint.
|
|
205
|
+
- Organization ref resolution is pinned: the default-branch commit is resolved
|
|
206
|
+
first (`commits/heads/<branch>`), the tree is read by that commit's tree SHA
|
|
207
|
+
and must match it, and only an HTTP 409 on the commit request means an empty
|
|
208
|
+
repository.
|
|
164
209
|
- Organization result compatibility is controlled by
|
|
165
210
|
`ORGANIZATION_ANALYSIS_GENERATION`, not by the package version. Producer
|
|
166
|
-
versions remain checkpoint metadata
|
|
167
|
-
|
|
211
|
+
versions remain checkpoint metadata that the next guarded atomic write
|
|
212
|
+
refreshes. Only the current checkpoint schema is accepted; an older schema
|
|
213
|
+
fails closed.
|
|
168
214
|
- Checkpoints use guarded atomic writes, remain inside the working directory,
|
|
169
|
-
omit tokens
|
|
215
|
+
omit tokens, raw YAML, commits, and links, and cannot replace active policy or
|
|
216
|
+
baseline files.
|
|
217
|
+
- Report directories remain dedicated and inside the working directory, reject
|
|
218
|
+
symbolic links and control-file overlap, preserve unrelated regular files,
|
|
219
|
+
and use a final manifest as the authoritative artifact set.
|
|
170
220
|
- Progress stays outside deterministic report serialization; CLI progress is
|
|
171
|
-
stderr-only
|
|
221
|
+
stderr-only, JSONL envelopes cannot be overridden by callback data, and
|
|
222
|
+
Action progress cannot form workflow commands.
|
|
223
|
+
- Organization CLI and Action adapters default complete reports to guarded,
|
|
224
|
+
scope-keyed files, emit only bounded log/stdout metadata, and create or
|
|
225
|
+
resume compatible checkpoints. Fresh and stateless execution remain explicit
|
|
226
|
+
caller choices.
|
|
172
227
|
- Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
|
|
173
|
-
vendor-environment heuristic.
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
arrays.
|
|
228
|
+
vendor-environment heuristic. It changes progress presentation and receipt
|
|
229
|
+
kind, not artifact identity; explicit CLI output and progress options win.
|
|
230
|
+
Automatic artifact keys use the validated checkpoint compatibility identity,
|
|
231
|
+
and receipts never include findings or repository result arrays.
|
|
177
232
|
- Attacker-controlled values cannot forge TOON lines or GitHub annotations.
|
|
178
233
|
|
|
179
234
|
Tests should demonstrate the fail-closed behavior for any change touching these
|
|
@@ -295,9 +350,9 @@ or other persisted repository-result semantics can change. Keep it unchanged
|
|
|
295
350
|
for documentation, release metadata, progress rendering, authentication,
|
|
296
351
|
concurrency, or internal refactors that preserve those results. The rule
|
|
297
352
|
catalog hash independently invalidates catalog changes. A generation change
|
|
298
|
-
must add tests proving the old checkpoint fails closed and
|
|
299
|
-
new artifact key
|
|
300
|
-
|
|
353
|
+
must add tests proving the old checkpoint fails closed and automatic scans
|
|
354
|
+
select a new artifact key. A checkpoint schema change does the same; the
|
|
355
|
+
project does not carry migration paths for older checkpoints.
|
|
301
356
|
|
|
302
357
|
## Output compatibility
|
|
303
358
|
|
|
@@ -310,7 +365,7 @@ When changing output:
|
|
|
310
365
|
- retain top-level `status`;
|
|
311
366
|
- treat new fields as additive where possible;
|
|
312
367
|
- update `docs/OUTPUTS.md`;
|
|
313
|
-
- test
|
|
368
|
+
- test every supported format;
|
|
314
369
|
- prevent embedded control characters from forging records;
|
|
315
370
|
- ensure error details are visible in every format;
|
|
316
371
|
- verify stable IDs remain stable unless their semantic input changed.
|
|
@@ -363,6 +418,24 @@ When CLI, Action, config, output, or API behavior changes:
|
|
|
363
418
|
Keep examples copyable, use exact package versions for `npx`, and use full
|
|
364
419
|
commit placeholders for the Action itself.
|
|
365
420
|
|
|
421
|
+
`check:docs` calculates coverage from live repository surfaces rather than a
|
|
422
|
+
manually maintained percentage. It requires:
|
|
423
|
+
|
|
424
|
+
- every exported runtime function or class under `src/` to have directly
|
|
425
|
+
leading, non-empty JSDoc that states its contract;
|
|
426
|
+
- every package-root JavaScript export to have direct JSDoc and a non-empty
|
|
427
|
+
entry in the complete API reference;
|
|
428
|
+
- every package subpath, CLI command and option, Action input and output, and
|
|
429
|
+
audit rule to appear in its owning reference;
|
|
430
|
+
- every focused guide to be linked from the documentation index;
|
|
431
|
+
- every example file to be reachable from the examples index through its
|
|
432
|
+
local README links.
|
|
433
|
+
|
|
434
|
+
The check prints the covered and total surface count and fails if the result is
|
|
435
|
+
below 100%, or if an API/table entry is stale. `test/doc-coverage.test.js`
|
|
436
|
+
locks the reviewed category totals so a public-surface change updates both its
|
|
437
|
+
documentation and the expected inventory deliberately.
|
|
438
|
+
|
|
366
439
|
## Releases
|
|
367
440
|
|
|
368
441
|
The authoritative [release runbook](../RELEASING.md) defines maintainer and
|
package/docs/GITHUB-ACTION.md
CHANGED
|
@@ -48,7 +48,7 @@ for clarity.
|
|
|
48
48
|
| `command` | `audit` | all | `audit`, `pin`, `upgrade`, `verify`, `report`, `org-scan`, or `rules` |
|
|
49
49
|
| `workflow` | discovery | repository commands | One path/glob per line or a JSON string array |
|
|
50
50
|
| `severity` | all levels | `audit`, `report`, `org-scan` | Minimum `low`, `medium`, `high`, or `critical` |
|
|
51
|
-
| `format` | `
|
|
51
|
+
| `format` | `auto` | all | `auto` uses JSON for `org-scan` and TOON otherwise; explicit formats are also accepted |
|
|
52
52
|
| `mode` | `minor` | `upgrade`, `report` | `major`, `minor`, or `patch` |
|
|
53
53
|
| `min-age` | `7` | `upgrade`, `report` | Non-negative cooldown in days |
|
|
54
54
|
| `write` | `false` | `pin`, `upgrade` | Apply changes in the checked-out workspace |
|
|
@@ -68,12 +68,16 @@ for clarity.
|
|
|
68
68
|
| `include-forks` | `false` | `org-scan` | Include forked repositories |
|
|
69
69
|
| `max-repos` | none | `org-scan` | Positive repository limit |
|
|
70
70
|
| `concurrency` | `4` | `org-scan` | Concurrent repository scans from 1 through 16 |
|
|
71
|
-
| `checkpoint-path` |
|
|
71
|
+
| `checkpoint-path` | generated | `org-scan` | Create or automatically resume this atomic checkpoint |
|
|
72
72
|
| `resume-from` | none | `org-scan` | Resume from and update an existing checkpoint |
|
|
73
|
+
| `fresh` | `false` | `org-scan` | Ignore reusable results and replace the selected checkpoint |
|
|
74
|
+
| `auto-checkpoint` | `true` | `org-scan` | Generate a scope-keyed checkpoint when no path is supplied |
|
|
75
|
+
| `previous-report` | none | `org-scan` | Compare with a compatible previous organization JSON report |
|
|
73
76
|
| `progress` | `true` | `org-scan` | Show discovery, repository, retry, and completion updates in the step log |
|
|
74
|
-
| `output-path` |
|
|
77
|
+
| `output-path` | generated for `org-scan` | all | Save inside the working directory; CSV/HTML require it for other commands |
|
|
75
78
|
| `token` | none | network commands | GitHub API token; normally `${{ github.token }}` or a secret |
|
|
76
79
|
| `working-directory` | `$GITHUB_WORKSPACE` | all | Scan and path-safety root |
|
|
80
|
+
| `node-version` | ignored | all | Deprecated compatibility input; the bundled runtime is managed by GitHub |
|
|
77
81
|
|
|
78
82
|
`node-version` is a deprecated compatibility input. It is accepted but ignored
|
|
79
83
|
because the Action runtime is declared by the bundle.
|
|
@@ -99,11 +103,49 @@ with:
|
|
|
99
103
|
| output | description |
|
|
100
104
|
|---|---|
|
|
101
105
|
| `status` | Semantic `OK` or `FAIL` |
|
|
102
|
-
| `findings` |
|
|
103
|
-
| `
|
|
106
|
+
| `findings` | Unsuppressed findings after severity filtering |
|
|
107
|
+
| `total-findings` | Findings before baseline suppression and after severity filtering |
|
|
108
|
+
| `critical` | Unsuppressed critical findings |
|
|
109
|
+
| `high` | Unsuppressed high findings |
|
|
110
|
+
| `medium` | Unsuppressed medium findings |
|
|
111
|
+
| `low` | Unsuppressed low findings |
|
|
112
|
+
| `suppressed` | Findings accepted by the active baseline |
|
|
113
|
+
| `errors` | Operational errors, including workflow parse failures |
|
|
114
|
+
| `repositories-discovered` | Repositories visible during `org-scan` discovery |
|
|
115
|
+
| `repositories-selected` | Repositories selected by `org-scan` scope and limits |
|
|
116
|
+
| `repositories-scanned` | Selected repositories whose scan completed, including failed results |
|
|
117
|
+
| `repositories-resumed` | Completed repositories reused from a revision-verified checkpoint |
|
|
118
|
+
| `repositories-failed` | Repositories with API, tree, or blob coverage errors |
|
|
119
|
+
| `coverage-complete` | `true` when every eligible repository was covered, `false` for caps/gaps, empty outside `org-scan` |
|
|
120
|
+
| `new-findings` | Findings added since `previous-report` |
|
|
121
|
+
| `resolved-findings` | Findings safely resolved since `previous-report` |
|
|
122
|
+
| `unchanged-findings` | Findings unchanged since `previous-report` |
|
|
123
|
+
| `unknown-findings` | Prior findings whose resolution is unknown because coverage was incomplete |
|
|
124
|
+
| `report-path` | Absolute saved path; always populated for `org-scan` |
|
|
125
|
+
| `checkpoint-path` | Absolute active `org-scan` checkpoint path, or empty when disabled |
|
|
104
126
|
| `annotations` | Number of annotations emitted |
|
|
105
127
|
| `annotations-skipped` | Number omitted by the per-level cap |
|
|
106
128
|
|
|
129
|
+
All numeric outputs are decimal strings and are always set. Finding and
|
|
130
|
+
repository outputs are `0` for commands where they do not apply. For
|
|
131
|
+
`audit`, `report`, and `org-scan`, `total-findings` equals `findings` plus
|
|
132
|
+
`suppressed`, and the four severity outputs sum to `findings`.
|
|
133
|
+
Use expression index syntax for hyphenated names, for example
|
|
134
|
+
`${{ steps.warden.outputs['total-findings'] }}`.
|
|
135
|
+
`coverage-complete` is the one non-numeric coverage output and can be `false`
|
|
136
|
+
for an otherwise `OK` scan intentionally capped by `max-repos`.
|
|
137
|
+
|
|
138
|
+
Comparison outputs are also always set and remain `0` unless an organization
|
|
139
|
+
scan uses `previous-report`. Never treat `resolved-findings` as complete unless
|
|
140
|
+
`unknown-findings`, `repositories-failed`, and `errors` are all `0` and the
|
|
141
|
+
saved comparison reports `summary.complete: true`.
|
|
142
|
+
|
|
143
|
+
`errors` follows the Action's operational-failure policy: it counts YAML parse
|
|
144
|
+
failures plus resolution, verification, write, and organization coverage
|
|
145
|
+
errors as applicable. An invocation-level failure that occurs before a normal
|
|
146
|
+
result sets `status: FAIL`, `errors: 1`, and all finding and repository counts
|
|
147
|
+
to `0`.
|
|
148
|
+
|
|
107
149
|
Give the step an `id` to read outputs:
|
|
108
150
|
|
|
109
151
|
```yaml
|
|
@@ -115,7 +157,17 @@ Give the step an `id` to read outputs:
|
|
|
115
157
|
fail-on-findings: 'false'
|
|
116
158
|
|
|
117
159
|
- name: Show result
|
|
118
|
-
|
|
160
|
+
shell: bash
|
|
161
|
+
env:
|
|
162
|
+
WARDEN_STATUS: ${{ steps.warden.outputs.status }}
|
|
163
|
+
WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
|
|
164
|
+
WARDEN_CRITICAL: ${{ steps.warden.outputs.critical }}
|
|
165
|
+
WARDEN_HIGH: ${{ steps.warden.outputs.high }}
|
|
166
|
+
WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
|
|
167
|
+
run: |
|
|
168
|
+
printf 'status=%s findings=%s critical=%s high=%s errors=%s\n' \
|
|
169
|
+
"$WARDEN_STATUS" "$WARDEN_FINDINGS" "$WARDEN_CRITICAL" \
|
|
170
|
+
"$WARDEN_HIGH" "$WARDEN_ERRORS"
|
|
119
171
|
```
|
|
120
172
|
|
|
121
173
|
`fail-on-findings: 'false'` changes step failure only for security findings in
|
|
@@ -133,6 +185,32 @@ Operational failures always fail the step, including:
|
|
|
133
185
|
`pin`, `upgrade`, and `verify` errors always fail. Warnings from `verify` do
|
|
134
186
|
not fail.
|
|
135
187
|
|
|
188
|
+
## Job summary
|
|
189
|
+
|
|
190
|
+
The Action writes a structured, bounded Markdown summary instead of copying
|
|
191
|
+
the raw selected output format into the page. Depending on the command, it
|
|
192
|
+
includes:
|
|
193
|
+
|
|
194
|
+
- result, finding, suppression, annotation, and operational-error counts;
|
|
195
|
+
- severity and rule breakdowns plus the highest-severity finding details;
|
|
196
|
+
- organization repository coverage, exact checkpoint reuse, and
|
|
197
|
+
previous-report change counts;
|
|
198
|
+
- planned or applied dependency changes and cooldown skips;
|
|
199
|
+
- verification warnings and operational error details;
|
|
200
|
+
- the repository-relative saved-report path when a report is written;
|
|
201
|
+
- the checkpoint path, whether it was loaded, and how many repository results
|
|
202
|
+
were actually reused.
|
|
203
|
+
|
|
204
|
+
Detail sections show at most 10 ordered records. Organization reports are
|
|
205
|
+
always file-only so large or private cross-repository evidence is not copied
|
|
206
|
+
into the step log. CSV and HTML are also file-only for repository commands;
|
|
207
|
+
other repository-command formats remain in stdout and in a saved report when
|
|
208
|
+
configured.
|
|
209
|
+
Dynamic values are
|
|
210
|
+
credential-redacted, Markdown-escaped, control-character-normalized, and
|
|
211
|
+
length-bounded before GitHub renders them. Invocation-level failures receive a
|
|
212
|
+
summary with the redacted error even when no normal report could be produced.
|
|
213
|
+
|
|
136
214
|
## Native annotations
|
|
137
215
|
|
|
138
216
|
Annotations are independent of `format`:
|
|
@@ -160,7 +238,10 @@ emission.
|
|
|
160
238
|
|
|
161
239
|
## Save a report artifact
|
|
162
240
|
|
|
163
|
-
`output-path`
|
|
241
|
+
`output-path` saves the selected format. For repository commands, TOON, JSON,
|
|
242
|
+
text, and SARIF also remain on stdout while CSV and HTML are file-only.
|
|
243
|
+
Organization scans always save the complete report and put only progress,
|
|
244
|
+
annotations, and a short saved-path message in the step log:
|
|
164
245
|
|
|
165
246
|
```yaml
|
|
166
247
|
- name: Generate report
|
|
@@ -178,7 +259,7 @@ emission.
|
|
|
178
259
|
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
|
|
179
260
|
with:
|
|
180
261
|
name: actions-warden-report
|
|
181
|
-
path: ${{ steps.warden.outputs
|
|
262
|
+
path: ${{ steps.warden.outputs['report-path'] }}
|
|
182
263
|
if-no-files-found: error
|
|
183
264
|
```
|
|
184
265
|
|
|
@@ -186,6 +267,42 @@ The output path must remain inside `working-directory`, its parent directory
|
|
|
186
267
|
must already exist, and an existing destination must be a regular file rather
|
|
187
268
|
than a directory or symlink.
|
|
188
269
|
|
|
270
|
+
With `format: csv` or `format: html`, `output-path` is required for commands
|
|
271
|
+
other than `org-scan`; organization scans generate a path when it is omitted.
|
|
272
|
+
The complete report is written there and is not copied into the step log. The bounded
|
|
273
|
+
Markdown job summary and native annotations remain available. CSV is
|
|
274
|
+
deterministic, control-character escaped, formula-safe, and flat. HTML is
|
|
275
|
+
self-contained, redacted, escaped, protected by a restrictive content security
|
|
276
|
+
policy, and capped at 32 MiB.
|
|
277
|
+
|
|
278
|
+
For a complete enforcing workflow that uploads the report before failing its
|
|
279
|
+
policy gate, copy the
|
|
280
|
+
[CI violation-reporting example](../examples/ci-violation-reporting/README.md).
|
|
281
|
+
For gradual rollout in an existing repository, use the
|
|
282
|
+
[baseline-adoption example](../examples/baseline-adoption/README.md). To publish
|
|
283
|
+
findings into GitHub Code Scanning on trusted runs, use the
|
|
284
|
+
[SARIF example](../examples/sarif-code-scanning/README.md).
|
|
285
|
+
For an offline organization dashboard, use the
|
|
286
|
+
[HTML organization report example](../examples/html-organization-report/README.md).
|
|
287
|
+
For spreadsheet or warehouse ingestion, use the
|
|
288
|
+
[CSV reporting example](../examples/csv-reporting/README.md).
|
|
289
|
+
|
|
290
|
+
## Webhooks and ProjectDiscovery Notify
|
|
291
|
+
|
|
292
|
+
The Action does not own a webhook destination or send outbound notifications.
|
|
293
|
+
Keep delivery in a separate workflow step so provider credentials, payload
|
|
294
|
+
mapping, retries, timeouts, and delivery failure policy remain explicit in the
|
|
295
|
+
calling repository. Send bounded Action outputs and a workflow-run link by
|
|
296
|
+
default; retain the complete report as a protected artifact instead of posting
|
|
297
|
+
private evidence to a chat provider.
|
|
298
|
+
|
|
299
|
+
The [notification example](../examples/notifications/README.md) includes a
|
|
300
|
+
generic HTTPS workflow and an optional ProjectDiscovery Notify adapter. The
|
|
301
|
+
generic path validates HTTPS, avoids redirects, applies bounded retries and
|
|
302
|
+
timeouts, and never places the webhook URL in a command-line argument or
|
|
303
|
+
report. ProjectDiscovery provider configuration belongs in a masked secret and
|
|
304
|
+
is materialized only for the delivery step.
|
|
305
|
+
|
|
189
306
|
## Organization report
|
|
190
307
|
|
|
191
308
|
The default repository `GITHUB_TOKEN` generally sees only the repository where
|
|
@@ -220,9 +337,6 @@ jobs:
|
|
|
220
337
|
token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
|
|
221
338
|
severity: high
|
|
222
339
|
explain: 'true'
|
|
223
|
-
format: json
|
|
224
|
-
output-path: actions-warden-org-report.json
|
|
225
|
-
checkpoint-path: .actions-warden-org-checkpoint.json
|
|
226
340
|
fail-on-findings: 'false'
|
|
227
341
|
|
|
228
342
|
- name: Upload organization report
|
|
@@ -231,34 +345,50 @@ jobs:
|
|
|
231
345
|
with:
|
|
232
346
|
name: actions-warden-org-report
|
|
233
347
|
path: |
|
|
234
|
-
|
|
235
|
-
.
|
|
348
|
+
${{ steps.warden.outputs['report-path'] }}
|
|
349
|
+
${{ steps.warden.outputs['checkpoint-path'] }}
|
|
350
|
+
include-hidden-files: true
|
|
236
351
|
if-no-files-found: error
|
|
237
352
|
```
|
|
238
353
|
|
|
239
354
|
Keep the token in Actions secrets, avoid printing it, and grant only metadata
|
|
240
355
|
and contents read access for selected repositories. The complete copyable file
|
|
241
|
-
is [examples/org-scan.yml](../examples/org-scan.yml).
|
|
356
|
+
is [examples/org-scan.yml](../examples/org-scan.yml). Generated organization
|
|
357
|
+
paths are dotfiles, so artifact upload steps must opt in to hidden files or use
|
|
358
|
+
explicit non-hidden `output-path` and `checkpoint-path` values.
|
|
242
359
|
|
|
243
360
|
The Action writes live progress to the step log separately from the selected
|
|
244
361
|
report format. Set `progress: 'false'` to disable it.
|
|
245
362
|
|
|
246
|
-
CLI `--agent-mode` is not an Action input. The Action already
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
the
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
363
|
+
CLI `--agent-mode` is not an Action input. The Action already keeps the complete
|
|
364
|
+
organization report in a generated file, creates or resumes a generated
|
|
365
|
+
checkpoint, exposes both paths as outputs, and uses bounded progress,
|
|
366
|
+
annotation, and summary channels.
|
|
367
|
+
|
|
368
|
+
`checkpoint-path` creates the file when absent and automatically resumes it
|
|
369
|
+
when present, so a repeated step configuration does not need to switch inputs.
|
|
370
|
+
Use `resume-from` when a restored checkpoint must already exist, `fresh: 'true'`
|
|
371
|
+
to replace selected state without reuse, or `auto-checkpoint: 'false'` for a
|
|
372
|
+
stateless scan. `fresh` and `resume-from` are mutually exclusive. The Action
|
|
373
|
+
does not itself retain files between ephemeral runners; restore a protected
|
|
374
|
+
artifact or other caller-managed file to the same path before the step when
|
|
375
|
+
cross-run resume is required. Scope, policy, baseline, analysis generation,
|
|
376
|
+
and rule identity must match; a compatible package-version change is allowed
|
|
377
|
+
and the next checkpoint write refreshes its metadata.
|
|
378
|
+
Fresh repository discovery and tree checks still occur, and changed or previously
|
|
258
379
|
failed repositories are rescanned. Checkpoints hold redacted report evidence
|
|
259
380
|
about repositories and findings, so protect them like the organization report.
|
|
260
381
|
`checkpoint-path` and `resume-from` are mutually exclusive and cannot equal
|
|
261
|
-
|
|
382
|
+
the resolved report path.
|
|
383
|
+
|
|
384
|
+
To calculate change, restore a previous JSON report into the working directory
|
|
385
|
+
and set `previous-report` to that path. It must match the current scope, policy,
|
|
386
|
+
baseline, rules, and analysis generation (reports from versions before commits
|
|
387
|
+
and permalinks were added must be regenerated once), and it cannot equal
|
|
388
|
+
`output-path`, `checkpoint-path`, or `resume-from`. New, resolved, unchanged, and unknown
|
|
389
|
+
counts appear in Action outputs and the job summary. Missing or failed current
|
|
390
|
+
repositories make prior findings unknown rather than resolved. SARIF cannot be
|
|
391
|
+
combined with `previous-report`; use JSON, TOON, text, CSV, or HTML.
|
|
262
392
|
|
|
263
393
|
## Mutation workflows
|
|
264
394
|
|