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.
Files changed (78) hide show
  1. package/AGENTS.md +60 -12
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +180 -58
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +23 -8
  6. package/docs/AI-AGENTS.md +125 -29
  7. package/docs/CLI.md +346 -69
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +114 -18
  10. package/docs/GITHUB-ACTION.md +163 -29
  11. package/docs/JAVASCRIPT-API.md +177 -11
  12. package/docs/OUTPUTS.md +408 -40
  13. package/docs/README.md +1 -1
  14. package/examples/README.md +21 -0
  15. package/examples/baseline-adoption/README.md +79 -0
  16. package/examples/baseline-adoption/github-actions.yml +56 -0
  17. package/examples/baseline-adoption/policy.yml +7 -0
  18. package/examples/ci-violation-reporting/README.md +82 -0
  19. package/examples/ci-violation-reporting/github-actions.yml +55 -0
  20. package/examples/ci-violation-reporting/policy.yml +7 -0
  21. package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
  22. package/examples/csv-reporting/README.md +50 -0
  23. package/examples/csv-reporting/github-actions.yml +59 -0
  24. package/examples/html-organization-report/README.md +35 -0
  25. package/examples/html-organization-report/github-actions.yml +61 -0
  26. package/examples/notifications/README.md +67 -0
  27. package/examples/notifications/github-actions.yml +163 -0
  28. package/examples/org-scan.yml +24 -5
  29. package/examples/sarif-code-scanning/README.md +42 -0
  30. package/examples/sarif-code-scanning/github-actions.yml +66 -0
  31. package/examples/upgrade-pr.yml +1 -1
  32. package/llms.txt +14 -5
  33. package/package.json +8 -4
  34. package/skills/actions-warden/SKILL.md +91 -39
  35. package/src/action.js +353 -187
  36. package/src/cli.js +416 -209
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +452 -286
  39. package/src/commands/pin.js +9 -5
  40. package/src/commands/report.js +7 -2
  41. package/src/commands/upgrade.js +9 -5
  42. package/src/commands/verify.js +24 -4
  43. package/src/index.js +5 -1
  44. package/src/lib/action-summary.js +656 -0
  45. package/src/lib/annotations.js +4 -6
  46. package/src/lib/baseline.js +11 -1
  47. package/src/lib/config.js +10 -5
  48. package/src/lib/destination.js +98 -0
  49. package/src/lib/execution.js +5 -1
  50. package/src/lib/formats/csv.js +125 -0
  51. package/src/lib/formats/html.js +394 -0
  52. package/src/lib/formats/json.js +17 -0
  53. package/src/lib/formats/sarif.js +229 -0
  54. package/src/lib/formats/text.js +30 -0
  55. package/src/lib/formats/toon.js +50 -0
  56. package/src/lib/formatter.js +25 -192
  57. package/src/lib/github-org.js +208 -102
  58. package/src/lib/org-artifacts.js +211 -0
  59. package/src/lib/org-checkpoint.js +159 -35
  60. package/src/lib/org-progress.js +182 -4
  61. package/src/lib/org-report-comparison.js +505 -0
  62. package/src/lib/org-report-directory.js +251 -0
  63. package/src/lib/org-report.js +223 -0
  64. package/src/lib/org-run.js +305 -0
  65. package/src/lib/org-schema.js +89 -0
  66. package/src/lib/org-source-links.js +39 -0
  67. package/src/lib/parser.js +5 -0
  68. package/src/lib/path-equality.js +30 -0
  69. package/src/lib/paths.js +18 -1
  70. package/src/lib/redact.js +58 -7
  71. package/src/lib/resolver.js +66 -9
  72. package/src/lib/types.js +137 -0
  73. package/src/lib/writer.js +3 -0
  74. package/src/rules/pull-request-target-checkout.js +5 -0
  75. package/src/rules/unpinned-action.js +2 -3
  76. package/src/rules/workflow-structure.js +2 -4
  77. package/src/version.js +1 -1
  78. package/src/lib/agent-mode.js +0 -175
@@ -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 accepts existing, reviewed findings while allowing new findings to
263
- fail the scan.
264
-
265
- Create one from the current unfiltered finding set:
266
-
267
- ```sh
268
- actions-warden audit \
269
- --create-baseline=.actions-warden-baseline.json
270
- ```
271
-
272
- The command writes a deterministic document:
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
 
@@ -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 local documentation links |
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
- agent-mode.js explicit bounded AI-agent CLI defaults
90
+ org-artifacts.js scope-keyed organization artifacts and receipts
88
91
  org-checkpoint.js validated atomic organization resume state
89
- org-progress.js human rendering of structured scan progress
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, redact.js structured output and credential redaction
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 → bounded YAML blob reads
128
- → in-memory auditSources → repository aggregation
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
- optional checkpoint → identity validation → fresh tree SHA comparison
131
- → reuse unchanged error-free result or rescan
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
- - Credentials are redacted in JSON, TOON, text, SARIF, annotations, and
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 fail.
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. Failed results
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 and raw YAML, and cannot replace active policy or baseline files.
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 and Action progress cannot form workflow commands.
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. Explicit CLI output and progress options win.
163
- Its automatic artifact key uses the validated checkpoint identity, and its
164
- stdout receipt never includes findings or repository result 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.
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 all four formats;
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
@@ -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` | `toon` | all | `toon`, `json`, `text`, or `sarif` |
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` | none | `org-scan` | Create or replace an atomic resumable checkpoint |
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` | none | all | Save the selected format inside the working directory |
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` | Finding count for `audit`, `report`, and `org-scan` |
103
- | `report-path` | Absolute saved path when `output-path` is supplied |
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
- run: echo "status=${{ steps.warden.outputs.status }} findings=${{ steps.warden.outputs.findings }}"
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` writes the selected format in addition to stdout:
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.report-path }}
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
- actions-warden-org-report.json
233
- .actions-warden-org-checkpoint.json
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 has explicit
245
- `output-path`, checkpoint, progress, summary, and output channels; configure
246
- those inputs directly when an agent generates a workflow.
247
-
248
- `checkpoint-path` starts a new checkpoint. To resume, restore that file into
249
- the working directory before the actions-warden step, remove
250
- `checkpoint-path`, and set `resume-from` to the restored path. The Action does
251
- not itself retain files between ephemeral runners; use a protected artifact or
252
- other caller-managed storage. Scope, policy, baseline, package, and rule
253
- identity must match. Fresh repository discovery and tree checks still occur,
254
- and changed or previously failed repositories are rescanned. Checkpoints hold
255
- redacted report evidence about repositories and findings, so protect them like
256
- the organization report. `checkpoint-path` and `resume-from` are mutually
257
- exclusive and cannot equal `output-path`.
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