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.
Files changed (76) hide show
  1. package/AGENTS.md +46 -8
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +171 -61
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +15 -5
  6. package/docs/AI-AGENTS.md +109 -29
  7. package/docs/CLI.md +284 -60
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +97 -24
  10. package/docs/GITHUB-ACTION.md +157 -27
  11. package/docs/JAVASCRIPT-API.md +172 -8
  12. package/docs/OUTPUTS.md +399 -36
  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 +78 -35
  35. package/src/action.js +351 -174
  36. package/src/cli.js +191 -177
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +451 -280
  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 +137 -96
  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/paths.js +18 -1
  69. package/src/lib/redact.js +58 -7
  70. package/src/lib/resolver.js +66 -9
  71. package/src/lib/types.js +137 -0
  72. package/src/rules/pull-request-target-checkout.js +5 -0
  73. package/src/rules/unpinned-action.js +2 -3
  74. package/src/rules/workflow-structure.js +2 -4
  75. package/src/version.js +1 -1
  76. package/src/lib/agent-mode.js +0 -174
@@ -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
  ```
@@ -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
- agent-mode.js explicit bounded AI-agent CLI defaults
90
+ org-artifacts.js scope-keyed organization artifacts and receipts
89
91
  org-checkpoint.js validated atomic organization resume state
90
- 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
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, 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)
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 → bounded YAML blob reads
129
- → 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)
130
143
 
131
- optional checkpoint → identity validation → fresh tree SHA comparison
132
- → 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
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 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.
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. Failed results
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 and compatible checkpoints migrate
167
- through the guarded atomic writer.
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 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.
170
220
  - Progress stays outside deterministic report serialization; CLI progress is
171
- 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.
172
227
  - Agent mode is an explicit opt-in, never a TTY, parent-process, CI, or
173
- vendor-environment heuristic. Explicit CLI output and progress options win.
174
- Its automatic artifact key uses the validated checkpoint compatibility
175
- identity, and its stdout receipt never includes findings or repository result
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 agent mode selects a
299
- new artifact key; a compatible format migration must prove the old checkpoint
300
- is validated, rewritten atomically, and still subject to fresh tree checks.
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 all four formats;
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
@@ -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,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.report-path }}
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
- actions-warden-org-report.json
235
- .actions-warden-org-checkpoint.json
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 has explicit
247
- `output-path`, checkpoint, progress, summary, and output channels; configure
248
- those inputs directly when an agent generates a workflow.
249
-
250
- `checkpoint-path` starts a new checkpoint. To resume, restore that file into
251
- the working directory before the actions-warden step, remove
252
- `checkpoint-path`, and set `resume-from` to the restored path. The Action does
253
- not itself retain files between ephemeral runners; use a protected artifact or
254
- other caller-managed storage. Scope, policy, baseline, analysis generation, and
255
- rule identity must match; a compatible package-version change is allowed and
256
- atomically refreshes checkpoint metadata on the first successful resume. Fresh
257
- repository discovery and tree checks still occur, and changed or previously
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
- `output-path`.
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