actions-warden 0.3.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 +60 -12
- package/CONTRIBUTING.md +6 -2
- package/README.md +180 -58
- package/RELEASING.md +3 -2
- package/SECURITY.md +23 -8
- package/docs/AI-AGENTS.md +125 -29
- package/docs/CLI.md +346 -69
- package/docs/CONFIGURATION.md +34 -11
- package/docs/DEVELOPMENT.md +114 -18
- package/docs/GITHUB-ACTION.md +163 -29
- package/docs/JAVASCRIPT-API.md +177 -11
- package/docs/OUTPUTS.md +408 -40
- 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 +91 -39
- package/src/action.js +353 -187
- package/src/cli.js +416 -209
- package/src/commands/audit.js +17 -30
- package/src/commands/org-scan.js +452 -286
- 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 +159 -35
- 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/path-equality.js +30 -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/lib/writer.js +3 -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 -175
package/docs/CONFIGURATION.md
CHANGED
|
@@ -259,17 +259,34 @@ Unmatched `ignore-start` directives extend to the end of the file. An
|
|
|
259
259
|
|
|
260
260
|
## Baselines
|
|
261
261
|
|
|
262
|
-
A baseline
|
|
263
|
-
fail
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
262
|
+
A baseline records existing, reviewed findings so that your CI stays green on
|
|
263
|
+
day one, while ensuring that any **new** vulnerabilities fail future pull requests.
|
|
264
|
+
|
|
265
|
+
### How to adopt on an existing codebase (without breaking CI)
|
|
266
|
+
|
|
267
|
+
When introducing `actions-warden` to an established project, you may encounter
|
|
268
|
+
existing warnings. Rather than blocking your team until every single issue is
|
|
269
|
+
resolved, follow this recommended baseline adoption workflow:
|
|
270
|
+
|
|
271
|
+
1. **Record current findings in a baseline file:**
|
|
272
|
+
```sh
|
|
273
|
+
actions-warden audit \
|
|
274
|
+
--create-baseline=.actions-warden-baseline.json
|
|
275
|
+
```
|
|
276
|
+
2. **Reference the baseline in `.actions-warden.yml`:**
|
|
277
|
+
```yaml
|
|
278
|
+
version: 1
|
|
279
|
+
baseline: .actions-warden-baseline.json
|
|
280
|
+
```
|
|
281
|
+
3. **Commit both files to your repository.**
|
|
282
|
+
4. **Enable `actions-warden` in your CI pipeline.**
|
|
283
|
+
All existing issues are now suppressed so builds remain green. However, if any
|
|
284
|
+
pull request introduces a **new** security finding or unpinned action, CI will
|
|
285
|
+
fail immediately—preventing security debt from growing.
|
|
286
|
+
5. **Gradually fix issues over time:**
|
|
287
|
+
As you pin actions or fix permissions, simply re-generate or update your baseline.
|
|
288
|
+
|
|
289
|
+
The baseline file is saved as a deterministic, human-readable JSON document:
|
|
273
290
|
|
|
274
291
|
```json
|
|
275
292
|
{
|
|
@@ -314,6 +331,12 @@ reports `totalFindings` and `suppressed`. Parser failures cannot be baselined.
|
|
|
314
331
|
|
|
315
332
|
Review baseline diffs carefully. Deleting a finding from the baseline makes it
|
|
316
333
|
active again; adding one accepts that risk without changing the workflow.
|
|
334
|
+
Organization report comparison includes normalized policy and baseline
|
|
335
|
+
contents in its analysis identity. Changing either intentionally requires a
|
|
336
|
+
new comparison starting point instead of presenting policy-driven differences
|
|
337
|
+
as resolved workflow findings.
|
|
338
|
+
The [baseline-adoption example](../examples/baseline-adoption/README.md) shows
|
|
339
|
+
the complete review, artifact, and CI-gating flow.
|
|
317
340
|
|
|
318
341
|
## Policy ownership
|
|
319
342
|
|
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
|
```
|
|
@@ -81,16 +83,27 @@ src/
|
|
|
81
83
|
lib/
|
|
82
84
|
parser.js YAML-to-normalized-workflow model
|
|
83
85
|
targets.js, paths.js repository target discovery
|
|
86
|
+
path-equality.js real-path destination/control comparisons
|
|
84
87
|
config.js, baseline.js policy and accepted-finding controls
|
|
85
88
|
resolver.js, cache.js GitHub API, caching, ref and ownership checks
|
|
86
89
|
github-org.js read-only organization/tree/blob access
|
|
87
|
-
|
|
90
|
+
org-artifacts.js scope-keyed organization artifacts and receipts
|
|
88
91
|
org-checkpoint.js validated atomic organization resume state
|
|
89
|
-
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
|
|
90
99
|
identity.js stable IDs and semantic fingerprints
|
|
91
100
|
patcher.js, writer.js source-range rewrites and guarded atomic writes
|
|
92
|
-
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)
|
|
93
105
|
annotations.js GitHub workflow annotations
|
|
106
|
+
action-summary.js bounded Action metrics and job summaries
|
|
94
107
|
concurrency.js bounded async work
|
|
95
108
|
rules/ one module per audit rule
|
|
96
109
|
|
|
@@ -124,44 +137,98 @@ normalized action refs → GitHub resolution and ownership verification
|
|
|
124
137
|
An organization scan follows:
|
|
125
138
|
|
|
126
139
|
```text
|
|
127
|
-
repository listing → default-branch Git tree
|
|
128
|
-
→ 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)
|
|
129
143
|
|
|
130
|
-
|
|
131
|
-
|
|
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
|
|
132
153
|
```
|
|
133
154
|
|
|
134
155
|
Remote repositories are never cloned, checked out, imported, or executed.
|
|
135
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
|
+
|
|
136
164
|
## Safety invariants
|
|
137
165
|
|
|
138
166
|
Changes must preserve these boundaries:
|
|
139
167
|
|
|
140
168
|
- `pin` and `upgrade` default to dry-run at the command and API layers.
|
|
141
169
|
- CLI and Action mutation require an explicit write option.
|
|
170
|
+
- CLI integers and 16-hex change IDs use strict whole-value parsing. Commander
|
|
171
|
+
usage failures and application-level invocation failures both exit `2`.
|
|
142
172
|
- A resolver failure must not fall back to a guessed tag or SHA.
|
|
143
173
|
- Commits must be verified as belonging to the referenced repository.
|
|
144
174
|
- Workflow rewrites operate on parsed scalar ranges and reparse before write.
|
|
145
175
|
- Writes and configured paths remain inside the real repository root.
|
|
146
176
|
- Symlink escapes and explicit targets that match nothing fail.
|
|
147
|
-
-
|
|
177
|
+
- CLI report, baseline, and checkpoint destinations are preflighted before
|
|
178
|
+
network or workflow mutation, cannot replace selected/default-discovery
|
|
179
|
+
workflows or reserved policy paths, and are checked against active controls
|
|
180
|
+
again before output is written.
|
|
181
|
+
- Credentials are redacted in JSON, TOON, text, CSV, SARIF, HTML, annotations, and
|
|
148
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.
|
|
149
189
|
- Finding and change IDs exclude absolute checkout paths.
|
|
150
190
|
- Parser errors remain findings and cannot be baselined away.
|
|
151
|
-
- 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.
|
|
152
196
|
- Organization source reads remain count- and size-bounded and bypass disk
|
|
153
197
|
cache.
|
|
198
|
+
- Embedded source audits consume only the caller-supplied file set; they do not
|
|
199
|
+
perform a second repository discovery pass.
|
|
154
200
|
- Organization resume never trusts a stale result without fresh discovery and
|
|
155
|
-
a matching repository identity, default branch, and tree SHA.
|
|
156
|
-
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.
|
|
209
|
+
- Organization result compatibility is controlled by
|
|
210
|
+
`ORGANIZATION_ANALYSIS_GENERATION`, not by the package version. Producer
|
|
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.
|
|
157
214
|
- Checkpoints use guarded atomic writes, remain inside the working directory,
|
|
158
|
-
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.
|
|
159
220
|
- Progress stays outside deterministic report serialization; CLI progress is
|
|
160
|
-
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.
|
|
161
227
|
- Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
|
|
162
|
-
vendor-environment heuristic.
|
|
163
|
-
|
|
164
|
-
|
|
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.
|
|
165
232
|
- Attacker-controlled values cannot forge TOON lines or GitHub annotations.
|
|
166
233
|
|
|
167
234
|
Tests should demonstrate the fail-closed behavior for any change touching these
|
|
@@ -276,6 +343,17 @@ previous repository errors, output equivalence, and concurrent completions.
|
|
|
276
343
|
Persist each completed result before emitting its completion event so an
|
|
277
344
|
observer failure or process interruption loses at most in-flight work.
|
|
278
345
|
|
|
346
|
+
`ORGANIZATION_ANALYSIS_GENERATION` in `src/lib/org-checkpoint.js` is the manual
|
|
347
|
+
semantic compatibility switch. Increment it whenever organization workflow
|
|
348
|
+
selection, parsing, finding identity, rule evaluation, suppression, summaries,
|
|
349
|
+
or other persisted repository-result semantics can change. Keep it unchanged
|
|
350
|
+
for documentation, release metadata, progress rendering, authentication,
|
|
351
|
+
concurrency, or internal refactors that preserve those results. The rule
|
|
352
|
+
catalog hash independently invalidates catalog changes. A generation change
|
|
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.
|
|
356
|
+
|
|
279
357
|
## Output compatibility
|
|
280
358
|
|
|
281
359
|
JSON is the public machine interface. Raw command results and serialized JSON
|
|
@@ -287,7 +365,7 @@ When changing output:
|
|
|
287
365
|
- retain top-level `status`;
|
|
288
366
|
- treat new fields as additive where possible;
|
|
289
367
|
- update `docs/OUTPUTS.md`;
|
|
290
|
-
- test
|
|
368
|
+
- test every supported format;
|
|
291
369
|
- prevent embedded control characters from forging records;
|
|
292
370
|
- ensure error details are visible in every format;
|
|
293
371
|
- verify stable IDs remain stable unless their semantic input changed.
|
|
@@ -340,6 +418,24 @@ When CLI, Action, config, output, or API behavior changes:
|
|
|
340
418
|
Keep examples copyable, use exact package versions for `npx`, and use full
|
|
341
419
|
commit placeholders for the Action itself.
|
|
342
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
|
+
|
|
343
439
|
## Releases
|
|
344
440
|
|
|
345
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,11 +259,49 @@ 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
|
|
|
185
|
-
The output path must remain inside `working-directory
|
|
266
|
+
The output path must remain inside `working-directory`, its parent directory
|
|
267
|
+
must already exist, and an existing destination must be a regular file rather
|
|
268
|
+
than a directory or symlink.
|
|
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.
|
|
186
305
|
|
|
187
306
|
## Organization report
|
|
188
307
|
|
|
@@ -218,9 +337,6 @@ jobs:
|
|
|
218
337
|
token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
|
|
219
338
|
severity: high
|
|
220
339
|
explain: 'true'
|
|
221
|
-
format: json
|
|
222
|
-
output-path: actions-warden-org-report.json
|
|
223
|
-
checkpoint-path: .actions-warden-org-checkpoint.json
|
|
224
340
|
fail-on-findings: 'false'
|
|
225
341
|
|
|
226
342
|
- name: Upload organization report
|
|
@@ -229,32 +345,50 @@ jobs:
|
|
|
229
345
|
with:
|
|
230
346
|
name: actions-warden-org-report
|
|
231
347
|
path: |
|
|
232
|
-
|
|
233
|
-
.
|
|
348
|
+
${{ steps.warden.outputs['report-path'] }}
|
|
349
|
+
${{ steps.warden.outputs['checkpoint-path'] }}
|
|
350
|
+
include-hidden-files: true
|
|
234
351
|
if-no-files-found: error
|
|
235
352
|
```
|
|
236
353
|
|
|
237
354
|
Keep the token in Actions secrets, avoid printing it, and grant only metadata
|
|
238
355
|
and contents read access for selected repositories. The complete copyable file
|
|
239
|
-
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.
|
|
240
359
|
|
|
241
360
|
The Action writes live progress to the step log separately from the selected
|
|
242
361
|
report format. Set `progress: 'false'` to disable it.
|
|
243
362
|
|
|
244
|
-
CLI `--agent-mode` is not an Action input. The Action already
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
the
|
|
250
|
-
|
|
251
|
-
|
|
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
|
|
379
|
+
failed repositories are rescanned. Checkpoints hold redacted report evidence
|
|
380
|
+
about repositories and findings, so protect them like the organization report.
|
|
381
|
+
`checkpoint-path` and `resume-from` are mutually exclusive and cannot equal
|
|
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.
|
|
258
392
|
|
|
259
393
|
## Mutation workflows
|
|
260
394
|
|