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/CLI.md CHANGED
@@ -21,7 +21,7 @@ actions-warden --version
21
21
  For reproducible one-off automation, invoke an exact package version:
22
22
 
23
23
  ```sh
24
- npx --yes actions-warden@0.3.0 audit
24
+ npx --yes actions-warden@0.6.0 audit
25
25
  ```
26
26
 
27
27
  Network-backed commands resolve credentials in this order:
@@ -35,19 +35,53 @@ Prefer an environment variable over `--token` because command-line arguments
35
35
  may be visible to other local processes. Give the token only the repository
36
36
  metadata and contents read access needed for the requested scope.
37
37
 
38
+ ## Quick cheat sheet
39
+
40
+ Here is a quick summary of the most common commands you will use daily:
41
+
42
+ ```sh
43
+ # 1. Audit your workflows for security vulnerabilities with clear explanations
44
+ actions-warden audit --explain
45
+
46
+ # 2. Preview the pin plan (safe dry-run; no files are modified)
47
+ actions-warden pin
48
+
49
+ # 3. Apply the reviewed pin plan to your workflow files
50
+ actions-warden pin --write
51
+
52
+ # 4. Verify that pinned commit SHAs match their GitHub repositories
53
+ actions-warden verify
54
+
55
+ # 5. Check if newer versions of your pinned actions are available
56
+ actions-warden upgrade
57
+
58
+ # 6. Apply available upgrades to your files
59
+ actions-warden upgrade --write
60
+
61
+ # 7. Scan an entire GitHub organization
62
+ actions-warden org-scan my-org --severity=high
63
+
64
+ # 8. Export an interactive HTML report to view in your browser
65
+ actions-warden audit --format=html --output-path=audit-report.html
66
+ ```
67
+
38
68
  ## Target and output options
39
69
 
40
70
  The repository commands (`audit`, `pin`, `verify`, `upgrade`, and `report`)
41
- share these options:
71
+ share these target and output options:
42
72
 
43
73
  | option | default | behavior |
44
74
  |---|---|---|
45
75
  | `-w, --workflow <pattern...>` | discovery | One or more files, directories, or globs |
46
76
  | `--cwd <dir>` | current directory | Repository and path-safety root |
47
- | `--token <token>` | environment | GitHub API credential for network-backed work |
48
- | `--format <format>` | `toon` | `toon`, `json`, `text`, or `sarif` |
77
+ | `--format <format>` | `toon` | `toon`, `json`, `text`, `csv`, `sarif`, or `html` |
49
78
  | `--output <destination>` | `stdout` | `stdout` or `file` |
50
- | `--output-path <path>` | none | Required with `--output=file`; resolved inside `--cwd` |
79
+ | `--output-path <path>` | none | Report path inside `--cwd`; implies `--output=file` |
80
+
81
+ `pin`, `verify`, `upgrade`, and online `report` also accept `--token`. `audit`
82
+ is entirely local and does not accept a token. `report --offline` rejects an
83
+ explicit token, mode, or cooldown because those options would otherwise be
84
+ silently unused.
51
85
 
52
86
  Without `--workflow`, actions-warden discovers:
53
87
 
@@ -72,19 +106,53 @@ actions-warden audit --cwd ../service
72
106
  ```
73
107
 
74
108
  Output files are created atomically and must remain within the real working
75
- directory after symlinks are resolved:
109
+ directory after symlinks are resolved. Their parent directory must already
110
+ exist. `--output=file` without a path and an explicit
111
+ `--output=stdout --output-path=...` are invocation errors. Report, baseline,
112
+ and checkpoint destinations are preflighted before network or mutation work;
113
+ they cannot be directories, symlinks, selected workflows, default workflow
114
+ discovery paths, or the reserved `.actions-warden.yml` and
115
+ `.actions-warden.yaml` policy paths. Active configuration and baseline paths
116
+ are checked again before any report or baseline destination is written.
76
117
 
77
118
  ```sh
78
119
  actions-warden audit \
79
120
  --format=sarif \
80
- --output=file \
81
121
  --output-path=reports/actions-warden.sarif
82
122
  ```
83
123
 
124
+ `--output=file --output-path=...` remains valid when an explicit destination
125
+ is clearer in automation.
126
+
127
+ HTML is intended as a saved human-review artifact:
128
+
129
+ ```sh
130
+ actions-warden audit \
131
+ --format=html \
132
+ --output-path=reports/actions-warden.html
133
+ ```
134
+
135
+ It is self-contained and does not load external assets. The report is
136
+ credential-redacted, HTML-escaped, protected by a restrictive content security
137
+ policy, deterministic for unchanged inputs, and capped at 32 MiB.
138
+
139
+ CSV can stream to stdout or be written as a guarded file:
140
+
141
+ ```sh
142
+ actions-warden audit \
143
+ --format=csv \
144
+ --output-path=reports/actions-warden.csv
145
+ ```
146
+
147
+ CSV provides a flat spreadsheet/export view. Use JSON for the versioned,
148
+ lossless machine contract and for future organization comparisons.
149
+
84
150
  ## `audit`
85
151
 
86
- Scan local workflows and composite actions without making network calls or
87
- changing files.
152
+ The `audit` command is completely local and offline. It inspects your workflow
153
+ files and composite actions for vulnerabilities, excessive permissions, script
154
+ injections, and unpinned dependencies without executing any workflows or making
155
+ network requests. It writes only an explicitly requested report or baseline.
88
156
 
89
157
  ```sh
90
158
  actions-warden audit \
@@ -96,30 +164,39 @@ actions-warden audit \
96
164
 
97
165
  The default includes every severity. `--severity` keeps findings at or above
98
166
  the selected threshold; parse errors always remain visible. `--explain` adds a
99
- plain-language remediation field.
167
+ plain-language remediation explanation to each finding.
100
168
 
101
- Create a reviewed baseline from all current findings:
169
+ Create a reviewed baseline from all current findings (useful when adopting on existing projects):
102
170
 
103
171
  ```sh
104
172
  actions-warden audit \
105
173
  --create-baseline=.actions-warden-baseline.json
106
174
  ```
107
175
 
108
- `--create-baseline` cannot be combined with `--baseline`. Parser failures are
109
- never written into the baseline. See [configuration and baselines](./CONFIGURATION.md).
176
+ `--create-baseline` cannot be combined with `--baseline`, cannot share the
177
+ report output path, and is validated before the audit begins. Parser failures
178
+ are never written into the baseline. See
179
+ [configuration and baselines](./CONFIGURATION.md).
110
180
 
111
- Exit code `0` means no unsuppressed findings; `1` means findings were reported;
112
- `2` means the scan could not be invoked safely or correctly.
181
+ > [!TIP]
182
+ > **Understanding exit codes:**
183
+ > - `0`: Clean! No unsuppressed security findings were found.
184
+ > - `1`: Findings reported. This is the normal exit code when issues are detected, allowing CI pipelines to catch vulnerabilities.
185
+ > - `2`: Invocation error. Occurs when command-line flags are invalid, contradictory, or missing required values.
113
186
 
114
187
  ## `pin`
115
188
 
116
- Resolve mutable external action and reusable-workflow refs to full commit SHAs.
189
+ The `pin` command protects your workflows against supply-chain attacks. It
190
+ resolves mutable version tags (such as `@v4` or `@main`) into immutable
191
+ 40-character commit SHAs from GitHub, while preserving the human-readable version
192
+ as an inline comment.
117
193
 
118
194
  ```sh
119
195
  actions-warden pin [--dry-run] [--write] [--fix=<id>]
120
196
  ```
121
197
 
122
- Dry-run is the default. A planned rewrite looks like:
198
+ **Dry-run is the default.** Running `actions-warden pin` will only show you a
199
+ safe preview on your terminal without touching any files. A planned rewrite looks like:
123
200
 
124
201
  ```yaml
125
202
  - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5
@@ -129,23 +206,26 @@ The metadata preserves the readable version for `verify` and `upgrade`.
129
206
  Existing comments and scalar quoting are preserved. The target commit is
130
207
  verified as belonging to the referenced repository before a plan is accepted.
131
208
 
132
- Review the dry-run output, then either apply the whole plan:
209
+ Review the dry-run output, then apply the whole plan to your files:
133
210
 
134
211
  ```sh
135
212
  actions-warden pin --write
136
213
  ```
137
214
 
138
- or one exact stable ID:
215
+ Or apply one exact reviewed action occurrence by its stable ID:
139
216
 
140
217
  ```sh
141
218
  actions-warden pin --fix=18b82e86d7c14fe2 --write
142
219
  ```
143
220
 
144
- `--write` and `--dry-run` together are rejected.
221
+ `--write` and `--dry-run` together are rejected. `--fix` must be one exact
222
+ 16-character hexadecimal ID from a current plan; uppercase input is normalized
223
+ for convenience.
145
224
 
146
225
  ## `verify`
147
226
 
148
- Verify action and reusable-workflow pins against GitHub.
227
+ The `verify` command checks that all pinned actions in your repository are
228
+ authentic and unmodified.
149
229
 
150
230
  ```sh
151
231
  actions-warden verify
@@ -154,8 +234,8 @@ actions-warden verify
154
234
  For every external reference, verification checks that:
155
235
 
156
236
  1. the ref is a full 40-character commit SHA;
157
- 2. the commit belongs to the referenced repository; and
158
- 3. `actions-warden-ref` metadata, when present, resolves to that SHA.
237
+ 2. the commit truly belongs to the referenced repository on GitHub; and
238
+ 3. `actions-warden-ref` metadata, when present, resolves to that exact SHA.
159
239
 
160
240
  A valid SHA without version metadata produces a warning. An unpinned,
161
241
  unverifiable, or metadata-mismatched reference is an error and returns status
@@ -163,7 +243,10 @@ unverifiable, or metadata-mismatched reference is an error and returns status
163
243
 
164
244
  ## `upgrade`
165
245
 
166
- Plan or apply newer action versions while preserving immutable SHA pins.
246
+ The `upgrade` command checks for newer releases of your pinned actions while
247
+ keeping them securely pinned to commit SHAs. It includes a built-in **cooldown period**
248
+ (default: 7 days) to protect your team against newly published releases that may have
249
+ day-zero issues or compromised tags.
167
250
 
168
251
  ```sh
169
252
  actions-warden upgrade \
@@ -176,13 +259,15 @@ Defaults are `--mode=minor --min-age=7` and dry-run. Tag discovery is paginated;
176
259
  prereleases and downgrades are excluded. A candidate tag must be older than the
177
260
  cooldown. The age comes from GitHub release publication data when available,
178
261
  then from locally recorded first-seen evidence for the exact tag-to-SHA mapping.
179
- Missing evidence fails closed.
262
+ Missing evidence fails closed. `--min-age` accepts only a non-negative integer;
263
+ values such as `7days`, `1.5`, and values outside JavaScript's safe integer
264
+ range are rejected rather than truncated.
180
265
 
181
266
  SHA-pinned references need `actions-warden-ref` metadata to establish the
182
267
  current semantic version. Legacy plain-semver comments remain readable.
183
268
 
184
269
  ```sh
185
- # Review every eligible minor update
270
+ # Review every eligible minor update (dry-run preview)
186
271
  actions-warden upgrade --mode=minor --min-age=14 --format=json
187
272
 
188
273
  # Apply one reviewed change
@@ -207,7 +292,8 @@ actions-warden report \
207
292
  The audit determines the target set; pin and upgrade use exactly that same
208
293
  scope. A location with an upgrade is not duplicated as a pin proposal.
209
294
  `--offline` skips both network-backed planning phases and returns only the
210
- local audit.
295
+ local audit. Because they cannot affect an offline report, explicitly combining
296
+ `--offline` with `--token`, `--mode`, or `--min-age` is rejected.
211
297
 
212
298
  Use report for review, issue generation, or an AI planning step. It never
213
299
  accepts `--write`.
@@ -224,10 +310,13 @@ actions-warden org-scan <organization> \
224
310
  [--max-repos=<count>] [--concurrency=<1-16>] \
225
311
  [--severity=low|medium|high|critical] [--explain] \
226
312
  [--config=<path> | --ignore-config] [--baseline=<path>] \
227
- [--checkpoint=<path> | --resume=<path>] \
228
- [--progress=auto|always|never] \
313
+ [--checkpoint=<path> | --resume=<path>] [--fresh] \
314
+ [--no-auto-checkpoint] \
315
+ [--previous-report=<path>] \
316
+ [--progress=auto|plain|json|none] \
317
+ [--report-dir=<dedicated-directory>] \
229
318
  [--agent-mode | --no-agent-mode] \
230
- [--format=toon|json|text|sarif] \
319
+ [--format=toon|json|text|csv|sarif|html] \
231
320
  [--output=stdout|file] [--output-path=<path>]
232
321
  ```
233
322
 
@@ -238,13 +327,39 @@ Defaults:
238
327
  - repository concurrency: `4`;
239
328
  - repository count: every eligible repository;
240
329
  - audit severity: every level;
241
- - progress: `auto` (stderr only when attached to an interactive terminal);
330
+ - format: `json`;
331
+ - output: a guarded scope-keyed file plus a compact JSON receipt on stdout;
332
+ - checkpoint: a guarded scope-keyed file, automatically resumed when present;
333
+ - progress: `auto` (plain stderr only when attached to an interactive terminal);
242
334
  - agent mode: disabled unless explicitly selected or enabled by the
243
335
  environment.
244
336
 
245
337
  Repository patterns match either `name` or `owner/name`, case-insensitively.
246
338
  An explicit pattern set that matches no eligible repository is an error.
247
- Selection is stable before `--max-repos` is applied.
339
+ Selection is stable before `--max-repos` is applied. `--max-repos` must be a
340
+ positive safe integer, and `--concurrency` must be an integer from 1 through
341
+ 16; malformed, fractional, or imprecise values fail before any API request.
342
+
343
+ The generated paths use these shapes:
344
+
345
+ ```text
346
+ .actions-warden-org-scan.<scope-key>.report.json
347
+ .actions-warden-org-scan.<scope-key>.checkpoint.json
348
+ ```
349
+
350
+ An explicit format changes the report extension while keeping the same
351
+ compatibility key. New files use mode `0600`; both report and checkpoint can
352
+ contain private repository names and security evidence.
353
+
354
+ The key covers scan scope, policy, baseline, rules, and analysis generation.
355
+ Running the same command again selects the same paths and resumes only
356
+ compatible, unchanged, error-free repository results. The report is complete;
357
+ stdout is a bounded `actions-warden-org-scan-receipt` containing status,
358
+ summary, report metadata, exact checkpoint reuse, coverage metadata, and
359
+ optional comparison counts.
360
+ Use `--output=stdout` when the complete selected report is intentionally wanted
361
+ on stdout. Use `--no-auto-checkpoint` for a stateless scan; file output still
362
+ uses a generated report path unless `--output-path` is supplied.
248
363
 
249
364
  ```sh
250
365
  actions-warden org-scan my-org \
@@ -259,46 +374,140 @@ actions-warden org-scan my-org \
259
374
  The result includes discovered, eligible, selected, scanned, skipped, failed,
260
375
  and workflow-bearing repository counts. Per-repository operational errors make
261
376
  the overall status `FAIL`; they do not abort reporting for repositories that
262
- can still be scanned.
377
+ can still be scanned. The `coverage` object separately states whether every
378
+ eligible repository was covered. A deliberate `--max-repos` cap makes
379
+ `coverage.complete` false without turning an otherwise clean selected scan
380
+ into `FAIL`.
381
+
382
+ ### HTML, CSV, and report comparison
383
+
384
+ Create a self-contained organization dashboard for human review:
385
+
386
+ ```sh
387
+ actions-warden org-scan my-org \
388
+ --severity=high \
389
+ --format=html \
390
+ --output-path=reports/org.html
391
+ ```
392
+
393
+ It includes the requested scope, incomplete-coverage warning, severity and
394
+ rule summary, repository table, searchable/filterable evidence, HTTPS source
395
+ links, comparison sections when present, and operational errors. Treat the
396
+ file as sensitive because it may identify private repositories and findings.
397
+
398
+ Compare a current scan with a previous actions-warden organization JSON report:
399
+
400
+ ```sh
401
+ actions-warden org-scan my-org \
402
+ --severity=high \
403
+ --previous-report=reports/org.previous.json \
404
+ --format=json \
405
+ --output-path=reports/org.current.json
406
+ ```
407
+
408
+ The previous report must be inside `--cwd`, use schema `1.0`, contain a public
409
+ analysis identity, and match the current organization, scope, normalized
410
+ policy, baseline contents, rule catalog, and analysis generation. Reports made
411
+ by an earlier analysis generation, including every report made before commits,
412
+ file inventories, and permalinks were added, must be regenerated once. Token,
413
+ concurrency, progress, and output destination do not affect compatibility.
414
+
415
+ Comparison uses semantic fingerprints and returns complete `new`, `resolved`,
416
+ `unchanged`, and `unknown` finding arrays plus repository and count summaries.
417
+ A previous finding is resolved only when its repository is present and has no
418
+ current API, blob, or workflow-parse coverage error. Missing, failed, or
419
+ unparseable repositories make unmatched prior findings unknown, and
420
+ `summary.complete` becomes `false`. The scan's normal
421
+ status remains based on current findings and errors.
422
+
423
+ `--previous-report` cannot be combined with SARIF because SARIF has no resolved
424
+ or unknown-result contract. Its path must differ from the output and checkpoint
425
+ paths so evidence is never overwritten. Retain JSON when it will be used as a
426
+ future comparison source; HTML is the human view rather than a comparison
427
+ input. CSV is likewise an export view rather than a comparison input.
428
+
429
+ ### Directory JSON reports
430
+
431
+ For a broad report that will be uploaded or inspected repository by
432
+ repository, select a dedicated directory instead of one large JSON file:
433
+
434
+ ```sh
435
+ actions-warden org-scan my-org \
436
+ --severity=high \
437
+ --report-dir=reports/actions-warden-org
438
+ ```
439
+
440
+ `--report-dir` implies JSON file output. It cannot be combined with
441
+ `--output-path`, `--output=stdout`, or a non-JSON format. The directory must be
442
+ inside `--cwd`, cannot be the working directory itself or a workflow discovery
443
+ path, and cannot overlap the active checkpoint, config, baseline, previous
444
+ report, or reserved config paths. Symbolic-link layout components and non-file artifact entries are
445
+ rejected.
446
+
447
+ The layout is:
448
+
449
+ ```text
450
+ reports/actions-warden-org/
451
+ organization-report.json compact aggregate and artifact pointers
452
+ organization-comparison.json complete comparison, when requested
453
+ repositories/
454
+ <repository>.<16-hex-id>.json complete repository evidence
455
+ manifest.json paths, byte counts, and SHA-256 digests
456
+ ```
457
+
458
+ Directories created by the command use mode `0700`; generated files use mode
459
+ `0600`. `manifest.json` is written last and is the authoritative file set for
460
+ the run. Unrelated and stale regular files are not deleted automatically.
461
+ Consumers should verify every listed byte count and digest and reject a
462
+ mismatch, which also detects an interrupted multi-file update.
463
+ Directory output bounds downstream reads and artifact handling, but the
464
+ scanner still constructs the complete result in memory before writing it. A
465
+ directory aggregate is not accepted as `--previous-report`; retain a normal
466
+ complete JSON report when future comparison input is required.
263
467
 
264
468
  ### Agent mode
265
469
 
266
- There is no reliable cross-agent process or environment signal. Agent callers
267
- opt in explicitly:
470
+ There is no reliable universal way to infer that a process is running inside
471
+ an AI agent. Agent callers opt in explicitly:
268
472
 
269
473
  ```sh
270
474
  actions-warden org-scan my-org --agent-mode
271
475
  ```
272
476
 
273
- An integration can instead set the mode once:
477
+ An integration can instead set the preferred execution context once:
274
478
 
275
479
  ```sh
276
- export ACTIONS_WARDEN_MODE=agent
480
+ export ACTIONS_WARDEN_CONTEXT=agent
277
481
  actions-warden org-scan my-org
278
482
  ```
279
483
 
280
- When the corresponding options were not explicitly supplied, agent mode sets:
484
+ `ACTIONS_WARDEN_CONTEXT` accepts `agent`, `auto`, `ci`, or `interactive`.
485
+ With implicit `--progress=auto`, agent context is quiet, CI and interactive
486
+ contexts use plain progress, and auto context follows stderr TTY state.
281
487
 
282
- - `--format=json`;
283
- - `--output=file` with a guarded scope-keyed report path;
284
- - `--progress=never`;
285
- - a guarded scope-keyed checkpoint path, creating it when absent and resuming
286
- it when present.
488
+ The general organization-scan defaults already select JSON file output, a
489
+ scope-keyed checkpoint, compatible automatic resume, and a bounded receipt.
490
+ When progress was not explicitly supplied, agent context selects no progress.
491
+ It also selects `actions-warden-agent-receipt` so integrations can recognize
492
+ the bounded contract. It does not change scan scope, analysis, or artifact
493
+ identity.
287
494
 
288
495
  The artifact key includes the organization, repository filters, inclusion
289
496
  flags, repository limit, severity, explanation setting, normalized policy,
290
- baseline contents, package version, and rule catalog. A scope or security
291
- control change therefore selects a different checkpoint rather than
292
- overwriting incompatible state. Generated paths have these shapes:
497
+ baseline contents, analysis generation, and rule catalog. A compatible package
498
+ upgrade therefore keeps the same paths, while a scope, security-control, or
499
+ analysis-behavior change selects a different checkpoint rather than
500
+ overwriting incompatible state. Normal, CI, interactive, and agent contexts
501
+ all use these paths:
293
502
 
294
503
  ```text
295
- .actions-warden-agent.<scope-key>.report.json
296
- .actions-warden-agent.<scope-key>.checkpoint.json
504
+ .actions-warden-org-scan.<scope-key>.report.json
505
+ .actions-warden-org-scan.<scope-key>.checkpoint.json
297
506
  ```
298
507
 
299
508
  An explicitly selected report format changes the report extension. Generated
300
509
  files are mode `0600` when first created and may reveal private security
301
- posture; protect them and ignore `.actions-warden-agent.*` in consuming
510
+ posture; protect them and ignore `.actions-warden-org-scan.*` in consuming
302
511
  repositories when appropriate.
303
512
 
304
513
  After writing the full report, stdout contains only a bounded JSON receipt:
@@ -311,29 +520,63 @@ After writing the full report, stdout contains only a bounded JSON receipt:
311
520
  organization: string,
312
521
  status: 'OK' | 'FAIL',
313
522
  summary: object,
314
- report: { path: string, format: 'toon' | 'json' | 'text' | 'sarif' },
315
- checkpoint: { path: string, resumed: boolean }
523
+ report: {
524
+ path: string,
525
+ format: 'toon' | 'json' | 'text' | 'csv' | 'sarif' | 'html',
526
+ layout: 'single' | 'directory',
527
+ directory?: string,
528
+ manifest?: string
529
+ },
530
+ checkpoint: {
531
+ path: string | null,
532
+ resumed: boolean,
533
+ repositoriesReused: number
534
+ },
535
+ coverage: {
536
+ complete: boolean,
537
+ enumerationComplete: boolean,
538
+ selectedRepositoriesComplete: boolean,
539
+ eligibleRepositoriesComplete: boolean,
540
+ limitedByMaxRepositories: boolean,
541
+ repositoriesOmittedByLimit: number,
542
+ incompleteRepositories: number
543
+ },
544
+ comparison?: object
316
545
  }
317
546
  ```
318
547
 
319
548
  The process still exits `0` for `OK`, `1` for a completed `FAIL`, and `2` for
320
549
  an invocation error. Explicit `--format`, `--output`, `--output-path`,
321
- `--progress`, `--checkpoint`, and `--resume` choices override agent defaults.
550
+ `--report-dir`, `--progress`, `--checkpoint`, `--resume`, `--fresh`, and
551
+ `--no-auto-checkpoint` choices override agent defaults.
322
552
  With explicit `--output=stdout`, stdout is the complete selected report and no
323
553
  receipt is added. Use `--no-agent-mode` to override an inherited environment
324
- marker. `ACTIONS_WARDEN_MODE` must be exactly `agent` when set.
554
+ marker. Passing both agent-mode flags is rejected. An explicit agent-mode flag
555
+ has precedence over `ACTIONS_WARDEN_CONTEXT`.
325
556
 
326
557
  ### Progress and resume
327
558
 
328
559
  Progress is independent of the report format and is written only to stderr.
329
- This keeps stdout valid JSON, SARIF, TOON, or text. Select `always` for CI or a
330
- redirected terminal log, and `never` when a caller wants no progress channel:
560
+ This keeps stdout valid JSON, CSV, SARIF, TOON, text, or HTML. Select `plain`
561
+ for human CI or redirected logs, `json` for one parseable event per line, and
562
+ `none` when a caller wants no progress channel:
331
563
 
332
564
  ```sh
333
- actions-warden org-scan my-org --format=json --progress=always > report.json
565
+ actions-warden org-scan my-org \
566
+ --format=json \
567
+ --output=stdout \
568
+ --no-auto-checkpoint \
569
+ --progress=plain > report.json
334
570
  ```
335
571
 
336
- Create an atomic checkpoint after each completed repository:
572
+ JSON Lines events use `schemaVersion: "1.0"`, kind
573
+ `actions-warden-org-scan-progress`, an event name, ISO timestamp, elapsed
574
+ milliseconds, and event-specific bounded fields. A fatal scan error ends that
575
+ channel with `scan-failed`; a post-scan comparison or persistence failure ends
576
+ it with `command-failed`. Neither appends a plain-text error line.
577
+
578
+ Choose stable, caller-managed report and checkpoint names when required by an
579
+ external storage convention:
337
580
 
338
581
  ```sh
339
582
  actions-warden org-scan my-org \
@@ -344,9 +587,9 @@ actions-warden org-scan my-org \
344
587
  --output-path=reports/org.json
345
588
  ```
346
589
 
347
- Resume with the same organization, filters, inclusion flags, repository limit,
348
- severity, explanation setting, configuration, baseline, tool version, and rule
349
- catalog:
590
+ The first run creates the checkpoint; repeating that exact command
591
+ automatically resumes it. Use the strict `--resume` form when external
592
+ automation restored a checkpoint that must exist:
350
593
 
351
594
  ```sh
352
595
  actions-warden org-scan my-org \
@@ -358,14 +601,24 @@ actions-warden org-scan my-org \
358
601
  ```
359
602
 
360
603
  The token, concurrency, output format, progress mode, and report destination do
361
- not affect checkpoint compatibility. A resumed scan always lists repositories
362
- again and fetches a fresh default-branch tree for each selected repository.
363
- An error-free result is reused only when repository identity, default branch,
364
- and tree SHA still match. Changed repositories and any checkpointed result with
365
- an operational error are scanned again.
366
-
367
- `--checkpoint` starts a new checkpoint and replaces an existing file at that
368
- path. `--resume` requires a valid existing checkpoint and updates it. The
604
+ not affect checkpoint compatibility. Neither does a package-version-only
605
+ upgrade: the producing version is retained as checkpoint metadata that the next
606
+ checkpoint write refreshes. The
607
+ explicit analysis generation is advanced when discovery, parsing, finding
608
+ identity, rule evaluation, or persisted result behavior changes. An
609
+ incompatible generation fails closed; automatic organization scans select a
610
+ new keyed path. A checkpoint from an older schema or generation is rejected.
611
+ A resumed scan always lists repositories again and resolves the current
612
+ default-branch commit and its tree for each selected repository. An error-free
613
+ result is reused only when repository identity, default branch, and tree SHA still match.
614
+ Changed repositories and any checkpointed result with an operational error are
615
+ scanned again.
616
+
617
+ `--checkpoint` creates a checkpoint when absent and automatically resumes it
618
+ when present. Add `--fresh` to ignore reusable results and atomically replace
619
+ the selected checkpoint. `--resume` requires a valid existing checkpoint and
620
+ cannot be combined with `--fresh`. `--no-auto-checkpoint` disables only the
621
+ generated checkpoint; an explicit `--checkpoint` or `--resume` still applies. The
369
622
  checkpoint and report paths must differ, remain inside `--cwd`, and have an
370
623
  existing parent directory. A checkpoint cannot replace the active config or
371
624
  baseline. Checkpoints contain redacted report evidence and revision metadata,
@@ -373,7 +626,14 @@ not the token or raw YAML, but can still reveal private repository names,
373
626
  paths, findings, and security posture; protect and retain them accordingly.
374
627
  Checkpoint reads and writes are capped at 256 MiB.
375
628
 
376
- The scanner reads the default-branch Git tree and YAML blobs in memory. It
629
+ Version-only upgrades and context switches do not create extra automatic
630
+ artifacts. When an analysis generation intentionally changes, the older keyed report and checkpoint are
631
+ retained rather than deleted automatically because they may be needed as audit
632
+ evidence; remove them according to the consuming repository's retention policy.
633
+
634
+ The scanner resolves the default-branch commit, reads that commit's Git tree,
635
+ and reads YAML blobs in memory, so each repository costs one extra request for
636
+ the commit that permalinks point at. It
377
637
  never clones, checks out, or executes remote content. It fails closed on
378
638
  truncated trees and enforces these bounds per repository:
379
639
 
@@ -398,6 +658,23 @@ actions-warden rules --format=json
398
658
 
399
659
  This command has no repository or network dependency.
400
660
 
661
+ ## Exit status and invocation errors
662
+
663
+ Every command uses the same process contract:
664
+
665
+ - `0`: completed with status `OK`, or displayed help/version information;
666
+ - `1`: completed with a structured `FAIL` result, such as findings or
667
+ operational errors;
668
+ - `2`: could not start or complete safely because the command line, paths,
669
+ configuration, inputs, or environment were invalid.
670
+
671
+ Commander-level failures such as unknown flags, missing values, invalid
672
+ choices, conflicts, excess arguments, and a missing command also return `2`.
673
+ Argument parsing and destination preflight run before network requests and
674
+ before authorized workflow writes; active-control collisions are checked again
675
+ before output. On exit `2`, treat stderr as the error channel and do not assume
676
+ stdout contains a complete structured result.
677
+
401
678
  ## Cache and network behavior
402
679
 
403
680
  Local `pin`, `verify`, `upgrade`, and online `report` work caches successful