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
package/docs/AI-AGENTS.md CHANGED
@@ -88,6 +88,15 @@ found something. Parse and present the report.
88
88
 
89
89
  Exit code `2` is an invocation-level problem. Read stderr, do not assume stdout
90
90
  contains valid JSON, and do not retry by weakening policy or changing paths.
91
+ Unknown options, conflicting flags, malformed numeric values, invalid change
92
+ IDs, unsafe destinations, and a missing command all use this exit code. These
93
+ checks happen before network requests or authorized workflow mutations whenever
94
+ the required path information is available.
95
+
96
+ When saving a report, `--output-path=<path>` is sufficient and implies file
97
+ output. Do not combine it with explicit `--output=stdout`. Create the parent
98
+ directory first, and never select a workflow, policy, baseline, or checkpoint
99
+ path as the report destination.
91
100
 
92
101
  For an organization scan, report coverage before findings:
93
102
 
@@ -225,9 +234,7 @@ the request:
225
234
  actions-warden org-scan my-org \
226
235
  --repository 'payments-*' \
227
236
  --visibility=private \
228
- --severity=high \
229
- --checkpoint=.actions-warden-org-checkpoint.json \
230
- --format=json
237
+ --severity=high
231
238
  ```
232
239
 
233
240
  The scanner never executes remote code, but the resulting strings still come
@@ -251,33 +258,65 @@ An integration can set the marker once instead of passing the option on every
251
258
  invocation:
252
259
 
253
260
  ```sh
254
- export ACTIONS_WARDEN_MODE=agent
261
+ export ACTIONS_WARDEN_CONTEXT=agent
255
262
  actions-warden org-scan my-org
256
263
  ```
257
264
 
258
- Agent mode is an explicit contract, not heuristic detection. By default it:
259
-
260
- - selects JSON and writes the full report to a guarded hidden file;
261
- - disables progress;
262
- - creates a guarded hidden checkpoint on the first run;
263
- - resumes that checkpoint on a later run with the exact same checkpoint
264
- identity;
265
- - emits only a bounded JSON receipt containing status, coverage summary,
266
- report path, report format, checkpoint path, and whether resume was used.
265
+ There is no reliable universal agent-runtime heuristic; integrations should set
266
+ the context once when they cannot add `--agent-mode` to each invocation.
267
+
268
+ Organization scans are artifact-first even when an integration forgets agent
269
+ mode: the CLI writes a scope-keyed JSON report and checkpoint, automatically
270
+ resumes compatible state, and emits a bounded receipt. Agent mode is an
271
+ explicit contract, not heuristic detection. It additionally:
272
+
273
+ - disables implicit progress;
274
+ - labels the bounded receipt `actions-warden-agent-receipt` so integrations can
275
+ distinguish the explicit contract.
276
+
277
+ Agent and normal execution share `.actions-warden-org-scan.*` artifacts. A
278
+ context switch therefore retains compatible resume state.
279
+
280
+ An agent may explicitly select `--format=html` when the user wants a retained
281
+ human-review artifact or `--format=csv` for a flat spreadsheet export, but it
282
+ must not load either complete artifact into model context. Read the bounded
283
+ receipt and use JSON for structured comparison or finding-batch inspection.
284
+ For a broad report that will be inspected repository by repository, prefer
285
+ `--report-dir=reports/actions-warden-org`: read its compact aggregate and
286
+ manifest first, then only the relevant complete repository artifacts. This
287
+ bounds downstream context reads, not the scanner's in-process memory. Retain a
288
+ normal complete JSON report as well if the run must later be used as
289
+ `--previous-report`.
290
+
291
+ To cite evidence, use the report's source locations: every finding has a
292
+ `permalink` pinned to the scanned commit, and each repository's `fileDetails`
293
+ lists every workflow file that was inspected, including clean ones, with its
294
+ status. Prefer a `permalink` over the branch `url` when quoting a finding,
295
+ and treat an `unreadable` file as a coverage gap, not a clean file.
267
296
 
268
297
  The automatic artifact key covers the organization, repository filters,
269
298
  inclusion flags, repository limit, severity, explanation setting, normalized
270
- policy, baseline contents, tool version, and rule catalog. A changed scope or
271
- security control therefore receives a different path instead of replacing an
272
- incompatible checkpoint. The generated files begin
273
- `.actions-warden-agent.`; protect them as sensitive report artifacts and add
274
- that pattern to the consuming repository's ignore rules when appropriate.
299
+ policy, baseline contents, analysis generation, and rule catalog. A compatible
300
+ package upgrade keeps the same path, and the next checkpoint write records the
301
+ current package version. A changed scope, security control, or
302
+ analysis behavior receives a different path instead of replacing an
303
+ incompatible checkpoint.
304
+ The generated files begin `.actions-warden-org-scan.`; protect them as
305
+ sensitive report artifacts and add that pattern to the consuming repository's
306
+ ignore rules when appropriate.
307
+
308
+ Version-only upgrades do not accumulate new automatic artifacts. A deliberate
309
+ analysis-generation change does retain the older keyed files as audit evidence;
310
+ remove them only under the consuming repository's retention policy.
275
311
 
276
312
  Explicit CLI options take precedence over agent defaults. Use
277
- `--progress=always` when the user requests live progress. Use
313
+ `--progress=plain` when the user requests human-readable live progress, or
314
+ `--progress=json` when the integration will parse JSON Lines. Use
278
315
  `--output=stdout` only when the caller intentionally wants the complete report
279
316
  in its context; in that case stdout is the selected report rather than the
280
- compact receipt. `--no-agent-mode` overrides an inherited environment marker.
317
+ compact receipt. `--no-auto-checkpoint` disables generated resume state, and
318
+ `--fresh` deliberately replaces it without reuse. `--no-agent-mode` overrides
319
+ an inherited environment marker.
281
320
 
282
321
  Resume primarily reduces repeated GitHub tree/blob work and elapsed time. It
283
322
  only reduces model usage when it also prevents extra output from entering the
@@ -287,7 +326,7 @@ context.
287
326
  Do not add a severity or repository filter merely to save model tokens. The
288
327
  requested security scope controls the scan; file output controls the context
289
328
  cost. Omit `--explain` on the broad first pass unless the user requested
290
- remediation guidance. If live progress is requested, use `--progress=always`
329
+ remediation guidance. If live progress is requested, use `--progress=plain`
291
330
  and treat those short stderr records only as status—not report evidence.
292
331
 
293
332
  After the command finishes, inspect the report from small to large. For
@@ -295,7 +334,7 @@ example, `jq` can produce a bounded first-pass view without emitting finding
295
334
  bodies or the per-repository result array:
296
335
 
297
336
  ```sh
298
- agent_report_path='.actions-warden-agent.<scope-key>.report.json'
337
+ agent_report_path='.actions-warden-org-scan.<scope-key>.report.json'
299
338
  jq '{
300
339
  schemaVersion,
301
340
  organization,
@@ -318,6 +357,24 @@ jq '{
318
357
 
319
358
  Set `agent_report_path` to the exact `report.path` value in the receipt.
320
359
 
360
+ When the user asks what changed since a prior scan, keep the same requested
361
+ scope and use a compatible previous JSON report:
362
+
363
+ ```sh
364
+ actions-warden org-scan my-org \
365
+ --agent-mode \
366
+ --previous-report=reports/org.previous.json
367
+ ```
368
+
369
+ Inspect `comparison.summary` from the receipt and saved report first. Report
370
+ new, resolved, unchanged, and unknown counts. A removed, failed, or unparseable
371
+ repository makes prior unmatched findings unknown; never describe them as resolved. A
372
+ scope, policy, baseline, rule, or analysis-generation mismatch is an invocation
373
+ error and must not be bypassed by weakening current controls. A report from an
374
+ older analysis generation cannot be reused; regenerate it once with the current
375
+ version. CSV and HTML
376
+ reports are not valid previous-report inputs.
377
+
321
378
  Then read operational errors and relevant findings in bounded batches, grouped
322
379
  by repository, severity, or rule. The saved JSON remains the complete source
323
380
  of truth. If a response covers only a subset of findings, say so explicitly
@@ -326,18 +383,21 @@ sample, and never ignore `summary.repositoriesFailed` or `summary.errors`.
326
383
 
327
384
  Before summarizing risk:
328
385
 
329
- 1. inspect `summary.repositoriesFailed` and `errors`;
386
+ 1. inspect `coverage.complete`, `summary.repositoriesFailed`, and `errors`;
330
387
  2. compare discovered, eligible, selected, and scanned counts;
331
388
  3. state excluded archived, disabled, and forked defaults;
332
389
  4. state `maxRepositories`, filters, visibility, and severity;
333
390
  5. distinguish “no findings in completed scans” from “complete organization
334
- coverage.”
391
+ coverage”; a repository cap is explicitly incomplete coverage even when the
392
+ selected scan status is `OK`.
335
393
 
336
394
  Store reports in a controlled path. Organization results can reveal private
337
395
  repository names, workflow paths, branches, source URLs, and security posture.
338
396
 
339
- For a long scan, preserve the exact command scope and use the explicit
340
- checkpoint handoff:
397
+ For a long scan, preserve the exact command scope and repeat the same command;
398
+ the generated or explicitly selected `--checkpoint` path resumes automatically.
399
+ Use the strict checkpoint handoff only when a caller restored a file that must
400
+ exist:
341
401
 
342
402
  ```sh
343
403
  actions-warden org-scan my-org \
@@ -351,11 +411,47 @@ actions-warden org-scan my-org \
351
411
  Do not weaken filters, policy, baseline, or severity merely to make a
352
412
  checkpoint compatible. A mismatch is an invocation error and requires a new
353
413
  checkpoint. Resume still performs fresh discovery and tree verification; say
354
- which repository completions were shown as `resumed` in stderr progress, while
355
- using the final report—not progress lines—as the evidence contract. Previously
356
- failed and changed repositories are rescanned. Checkpoints omit tokens and raw
414
+ how many repository results were actually reused from
415
+ `checkpoint.repositoriesReused` in the receipt (or the equivalent progress
416
+ events), while using the final report—not progress lines—as the evidence
417
+ contract. Previously failed and changed repositories are rescanned. Checkpoints omit tokens and raw
357
418
  YAML but retain redacted report evidence, so treat them as sensitive artifacts.
358
419
 
420
+ ## Generating CI reporting workflows
421
+
422
+ When the user asks for a GitHub Actions integration, give the actions-warden
423
+ step an `id` and use its bounded job summary for the human review path. Save
424
+ JSON or SARIF with `output-path` when later ingestion or complete evidence is
425
+ required, CSV for a flat spreadsheet/warehouse export, or HTML for a retained
426
+ human dashboard; the summary deliberately contains only aggregates and top
427
+ records. Action organization scans generate a report path and checkpoint path
428
+ when omitted and keep every complete format out of the step log. CSV and HTML
429
+ require `output-path` only for non-organization commands.
430
+
431
+ Later steps can read decimal-string outputs for `findings`, `total-findings`,
432
+ each severity, `suppressed`, and `errors`. Organization scans additionally
433
+ expose discovered, selected, scanned, resumed, and failed repository counts,
434
+ plus the non-numeric `coverage-complete` boolean string. Do not
435
+ describe a run as clean merely because `findings` is `0`: require `errors` and
436
+ `repositories-failed` (for an organization scan) to be `0` and inspect
437
+ `status` plus `coverage-complete`. If a report must be uploaded before findings fail the job, use the
438
+ reviewed pattern in the
439
+ [CI violation-reporting example](../examples/ci-violation-reporting/README.md);
440
+ do not make `fail-on-findings: false` the final policy decision.
441
+
442
+ Organization comparisons additionally expose `new-findings`,
443
+ `resolved-findings`, `unchanged-findings`, and `unknown-findings`. Treat
444
+ resolution as complete only when unknown findings, failed repositories, and
445
+ errors are all zero and the saved comparison says `complete: true`.
446
+
447
+ Do not add webhook delivery to the scanner command. When the user requests a
448
+ webhook or ProjectDiscovery Notify integration, retain the complete report as a
449
+ protected artifact and send a separate bounded summary from the calling
450
+ workflow. Keep provider credentials in masked secrets and make HTTPS
451
+ validation, redirects, retries, timeouts, and delivery failure policy explicit.
452
+ Start from the
453
+ [notification example](../examples/notifications/README.md).
454
+
359
455
  ## Policy and suppression requests
360
456
 
361
457
  If a user asks to “make CI green,” do not automatically: