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
package/docs/AI-AGENTS.md CHANGED
@@ -234,9 +234,7 @@ the request:
234
234
  actions-warden org-scan my-org \
235
235
  --repository 'payments-*' \
236
236
  --visibility=private \
237
- --severity=high \
238
- --checkpoint=.actions-warden-org-checkpoint.json \
239
- --format=json
237
+ --severity=high
240
238
  ```
241
239
 
242
240
  The scanner never executes remote code, but the resulting strings still come
@@ -260,40 +258,65 @@ An integration can set the marker once instead of passing the option on every
260
258
  invocation:
261
259
 
262
260
  ```sh
263
- export ACTIONS_WARDEN_MODE=agent
261
+ export ACTIONS_WARDEN_CONTEXT=agent
264
262
  actions-warden org-scan my-org
265
263
  ```
266
264
 
267
- Agent mode is an explicit contract, not heuristic detection. By default it:
268
-
269
- - selects JSON and writes the full report to a guarded hidden file;
270
- - disables progress;
271
- - creates a guarded hidden checkpoint on the first run;
272
- - resumes that checkpoint on a later run with the same compatibility identity,
273
- including across package-version-only upgrades;
274
- - emits only a bounded JSON receipt containing status, coverage summary,
275
- 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.
276
296
 
277
297
  The automatic artifact key covers the organization, repository filters,
278
298
  inclusion flags, repository limit, severity, explanation setting, normalized
279
299
  policy, baseline contents, analysis generation, and rule catalog. A compatible
280
- package upgrade keeps the same path and atomically migrates older checkpoint
281
- metadata on the first successful resume. A changed scope, security control, or
300
+ package upgrade keeps the same path, and the next checkpoint write records the
301
+ current package version. A changed scope, security control, or
282
302
  analysis behavior receives a different path instead of replacing an
283
303
  incompatible checkpoint.
284
- The generated files begin
285
- `.actions-warden-agent.`; protect them as sensitive report artifacts and add
286
- that pattern to the consuming repository's ignore rules when appropriate.
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.
287
307
 
288
308
  Version-only upgrades do not accumulate new automatic artifacts. A deliberate
289
309
  analysis-generation change does retain the older keyed files as audit evidence;
290
310
  remove them only under the consuming repository's retention policy.
291
311
 
292
312
  Explicit CLI options take precedence over agent defaults. Use
293
- `--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
294
315
  `--output=stdout` only when the caller intentionally wants the complete report
295
316
  in its context; in that case stdout is the selected report rather than the
296
- 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.
297
320
 
298
321
  Resume primarily reduces repeated GitHub tree/blob work and elapsed time. It
299
322
  only reduces model usage when it also prevents extra output from entering the
@@ -303,7 +326,7 @@ context.
303
326
  Do not add a severity or repository filter merely to save model tokens. The
304
327
  requested security scope controls the scan; file output controls the context
305
328
  cost. Omit `--explain` on the broad first pass unless the user requested
306
- remediation guidance. If live progress is requested, use `--progress=always`
329
+ remediation guidance. If live progress is requested, use `--progress=plain`
307
330
  and treat those short stderr records only as status—not report evidence.
308
331
 
309
332
  After the command finishes, inspect the report from small to large. For
@@ -311,7 +334,7 @@ example, `jq` can produce a bounded first-pass view without emitting finding
311
334
  bodies or the per-repository result array:
312
335
 
313
336
  ```sh
314
- agent_report_path='.actions-warden-agent.<scope-key>.report.json'
337
+ agent_report_path='.actions-warden-org-scan.<scope-key>.report.json'
315
338
  jq '{
316
339
  schemaVersion,
317
340
  organization,
@@ -334,6 +357,24 @@ jq '{
334
357
 
335
358
  Set `agent_report_path` to the exact `report.path` value in the receipt.
336
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
+
337
378
  Then read operational errors and relevant findings in bounded batches, grouped
338
379
  by repository, severity, or rule. The saved JSON remains the complete source
339
380
  of truth. If a response covers only a subset of findings, say so explicitly
@@ -342,18 +383,21 @@ sample, and never ignore `summary.repositoriesFailed` or `summary.errors`.
342
383
 
343
384
  Before summarizing risk:
344
385
 
345
- 1. inspect `summary.repositoriesFailed` and `errors`;
386
+ 1. inspect `coverage.complete`, `summary.repositoriesFailed`, and `errors`;
346
387
  2. compare discovered, eligible, selected, and scanned counts;
347
388
  3. state excluded archived, disabled, and forked defaults;
348
389
  4. state `maxRepositories`, filters, visibility, and severity;
349
390
  5. distinguish “no findings in completed scans” from “complete organization
350
- coverage.”
391
+ coverage”; a repository cap is explicitly incomplete coverage even when the
392
+ selected scan status is `OK`.
351
393
 
352
394
  Store reports in a controlled path. Organization results can reveal private
353
395
  repository names, workflow paths, branches, source URLs, and security posture.
354
396
 
355
- For a long scan, preserve the exact command scope and use the explicit
356
- 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:
357
401
 
358
402
  ```sh
359
403
  actions-warden org-scan my-org \
@@ -367,11 +411,47 @@ actions-warden org-scan my-org \
367
411
  Do not weaken filters, policy, baseline, or severity merely to make a
368
412
  checkpoint compatible. A mismatch is an invocation error and requires a new
369
413
  checkpoint. Resume still performs fresh discovery and tree verification; say
370
- which repository completions were shown as `resumed` in stderr progress, while
371
- using the final report—not progress lines—as the evidence contract. Previously
372
- 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
373
418
  YAML but retain redacted report evidence, so treat them as sensitive artifacts.
374
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
+
375
455
  ## Policy and suppression requests
376
456
 
377
457
  If a user asks to “make CI green,” do not automatically: