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/OUTPUTS.md CHANGED
@@ -15,9 +15,14 @@ Automation should read all three deliberately.
15
15
  | `toon` | Labeled, one-record-per-line text | Compact terminal or LLM context |
16
16
  | `json` | Command-specific object with `schemaVersion: "1.0"` | Programmatic integrations |
17
17
  | `text` | Bracketed, one-record-per-line text | Human-readable logs |
18
+ | `csv` | Flat RFC 4180-compatible record table | Spreadsheets, warehouses, and compliance exports |
18
19
  | `sarif` | SARIF 2.1.0 JSON | Code scanning and compatible tooling |
20
+ | `html` | Self-contained interactive document | Human review and retained artifacts |
19
21
 
20
- Select a format with `--format`. The default is `toon`.
22
+ Select a format with `--format`. Repository commands default to `toon`.
23
+ `org-scan` defaults to JSON saved in a guarded scope-keyed file, because a
24
+ complete organization result can be large and may expose private security
25
+ posture.
21
26
 
22
27
  All serialized values pass through credential redaction. Known token formats,
23
28
  credential-shaped key/value pairs, private keys, JWTs, and likely high-entropy
@@ -27,7 +32,8 @@ transport.
27
32
  ## Status and exit codes
28
33
 
29
34
  Every normal command result has semantic status `OK` or `FAIL`. TOON ends with
30
- `STATUS: ...`; JSON has a top-level `status`; text ends with `==> ...`.
35
+ `STATUS: ...`; JSON has a top-level `status`; text ends with `==> ...`; CSV ends
36
+ with a `STATUS` record; HTML shows the status in its report header.
31
37
 
32
38
  | command | `OK` | `FAIL` |
33
39
  |---|---|---|
@@ -43,54 +49,115 @@ The CLI maps results to process codes:
43
49
 
44
50
  | code | meaning |
45
51
  |---|---|
46
- | `0` | Semantic status `OK` |
47
- | `1` | Semantic status `FAIL`; inspect the emitted report |
52
+ | `0` | Semantic status `OK` (No unsuppressed findings) |
53
+ | `1` | Semantic status `FAIL`; findings were reported, inspect the emitted report |
48
54
  | `2` | Invalid arguments, invalid policy, unsafe paths, or another invocation-level failure |
49
55
 
50
- An invocation-level failure is written to stderr as `error: <message>`. It may
51
- occur before a structured payload can be rendered, so do not assume stdout
56
+ > [!NOTE]
57
+ > **Why exit code 1 is normal for findings:**
58
+ > Just like linters or compilers in CI/CD, an exit code of `1` allows automated pipelines (such as GitHub Actions or GitLab CI) to flag pull requests containing security vulnerabilities. It does not mean the command crashed; the full structured report is available on stdout (or in the saved report file). Exit code `2` indicates an actual invocation or syntax failure.
59
+
60
+ An invocation-level failure is normally written to stderr as `error: <message>`. Unknown
61
+ options, missing values, invalid choices, conflicting flags, malformed numeric
62
+ values, unsafe destinations, and a missing command all return `2`. The failure
63
+ may occur before a structured payload can be rendered, so do not assume stdout
52
64
  contains JSON when the process exits `2`.
53
65
 
54
66
  Organization-scan live progress is also a stderr-only channel. It never becomes
55
- part of JSON, SARIF, TOON, or text stdout. `--progress=auto` enables it for an
56
- interactive stderr, `always` enables it for redirected/CI logs, and `never`
57
- disables it. GitHub Action organization scans show the same phase, repository,
58
- retry, and completion updates in the step log by default.
67
+ part of JSON, CSV, SARIF, TOON, text, or HTML stdout. `--progress=auto` enables
68
+ plain lines for an interactive stderr, `plain` enables human-readable output,
69
+ `json` emits JSON Lines, and `none` disables it. Once a JSON progress channel has
70
+ started, a fatal scan error is represented by `scan-failed` instead of an
71
+ additional plain `error:` line. GitHub Action organization scans show the same
72
+ phase, repository, retry, checkpoint, and completion updates in the step log by
73
+ default.
59
74
 
60
- ### Agent-mode receipt
75
+ Each `--progress=json` line is an independently parseable object:
61
76
 
62
- `org-scan --agent-mode`, or `ACTIONS_WARDEN_MODE=agent`, defaults the complete
63
- report to a guarded scope-keyed file. Its stdout is a separate bounded JSON
64
- receipt:
77
+ ```js
78
+ {
79
+ schemaVersion: '1.0',
80
+ kind: 'actions-warden-org-scan-progress',
81
+ event: string,
82
+ timestamp: string, // ISO 8601 UTC
83
+ elapsedMs: number,
84
+ // event-specific bounded fields
85
+ }
86
+ ```
87
+
88
+ Event names are `scan-started`, `checkpoint-loaded`, `checkpoint-created`,
89
+ `discovery-started`, `discovery-page`, `discovery-completed`,
90
+ `repository-started`, `repository-phase`, `request-retry`,
91
+ `checkpoint-written`, `repository-completed`, `scan-completed`, and
92
+ `scan-failed`. A failure after scanning, such as incompatible comparison
93
+ evidence or report persistence, emits `command-failed`. Values are
94
+ credential-redacted before serialization.
95
+
96
+ ### Organization file receipt
97
+
98
+ `org-scan` defaults the complete report to a guarded scope-keyed file. Its
99
+ stdout is a separate bounded JSON receipt. Normal scans use kind
100
+ `actions-warden-org-scan-receipt`; `--agent-mode`, or
101
+ `ACTIONS_WARDEN_CONTEXT=agent`, uses `actions-warden-agent-receipt` and disables
102
+ implicit progress:
65
103
 
66
104
  ```js
67
105
  {
68
106
  schemaVersion: '1.0',
69
- kind: 'actions-warden-agent-receipt',
107
+ kind: 'actions-warden-org-scan-receipt' | 'actions-warden-agent-receipt',
70
108
  command: 'org-scan',
71
109
  organization: string,
110
+ tool: { name: 'actions-warden', version: string },
111
+ run: {
112
+ startedAt: string, // ISO 8601 UTC
113
+ finishedAt: string, // ISO 8601 UTC
114
+ durationMs: number // integer
115
+ },
72
116
  status: 'OK' | 'FAIL',
73
117
  summary: object,
74
118
  report: {
75
119
  path: string,
76
- format: 'toon' | 'json' | 'text' | 'sarif'
120
+ format: 'toon' | 'json' | 'text' | 'csv' | 'sarif' | 'html',
121
+ layout: 'single' | 'directory',
122
+ directory?: string,
123
+ manifest?: string
77
124
  },
78
125
  checkpoint: {
79
- path: string,
80
- resumed: boolean
81
- }
126
+ path: string | null,
127
+ resumed: boolean,
128
+ repositoriesReused: number
129
+ },
130
+ coverage: {
131
+ complete: boolean,
132
+ enumerationComplete: boolean,
133
+ selectedRepositoriesComplete: boolean,
134
+ eligibleRepositoriesComplete: boolean,
135
+ limitedByMaxRepositories: boolean,
136
+ repositoriesOmittedByLimit: number,
137
+ incompleteRepositories: number
138
+ },
139
+ comparison?: object
82
140
  }
83
141
  ```
84
142
 
143
+ `tool` and `run` are run provenance. They appear only in the receipt, so the
144
+ saved report, the directory aggregate, and the manifest stay byte-deterministic.
85
145
  `summary` is the normal bounded organization coverage and severity summary;
86
146
  the receipt never embeds repository arrays, findings, or operational error
87
- details. Read `report.path` for the complete evidence. The receipt remains JSON
88
- even when an explicit format selects TOON, text, or SARIF for the saved report.
147
+ details. When comparison was requested, `comparison` is its bounded count
148
+ summary rather than its finding arrays. Read `report.path` for the complete
149
+ evidence. The receipt remains JSON even when an explicit format selects TOON,
150
+ text, CSV, SARIF, or HTML for the saved report.
151
+ `checkpoint.resumed` says that checkpoint input was loaded;
152
+ `checkpoint.repositoriesReused` is the exact number whose live revision still
153
+ matched. Directory layout receipts also identify the directory and manifest.
89
154
  Status and process exit semantics are unchanged. An invocation error may occur
90
155
  before a receipt exists.
91
156
 
92
157
  Explicit `--output=stdout` overrides the file default. In that case stdout is
93
- the complete report in the selected format and no agent receipt is appended.
158
+ the complete report in the selected format and no receipt is appended. The
159
+ automatic checkpoint remains enabled unless `--no-auto-checkpoint` is also
160
+ passed.
94
161
 
95
162
  A mutation plan may contain changes and still return `0`: proposed changes are
96
163
  not errors. Conversely, `audit` may emit valid JSON and return `1`: findings are
@@ -119,16 +186,19 @@ node -e '
119
186
  '
120
187
  ```
121
188
 
122
- Writing reports through `--output=file` is safer than shell redirection when
123
- repository path containment matters:
189
+ Writing reports through a guarded output path is safer than shell redirection
190
+ when repository path containment matters. `--output-path` implies file output:
124
191
 
125
192
  ```sh
126
193
  actions-warden audit \
127
194
  --format=json \
128
- --output=file \
129
195
  --output-path=reports/actions-warden.json
130
196
  ```
131
197
 
198
+ The parent directory must exist. Destination safety is checked before command
199
+ work, then active policy and baseline collisions are checked again before the
200
+ report is written. Explicit `--output=stdout --output-path=...` is rejected.
201
+
132
202
  ## TOON
133
203
 
134
204
  TOON is Token-Oriented Object Notation. Each line is:
@@ -150,7 +220,7 @@ Record labels by command:
150
220
  | `upgrade` | `UPGRADE`, `SKIP`, `ERROR`, `SUMMARY` |
151
221
  | `verify` | `VERIFIED`, `WARNING`, `ERROR`, `SUMMARY` |
152
222
  | `report` | `FINDING`, `PIN`, `UPGRADE`, `SKIP`, `ERROR`, `SUMMARY` |
153
- | `org-scan` | `REPOSITORY`, `FINDING`, `ERROR`, `SUMMARY` |
223
+ | `org-scan` | `REPOSITORY`, `FILE`, `FINDING`, `ERROR`, `COVERAGE`, optional comparison records, `SUMMARY` |
154
224
  | `rules` | `RULE` |
155
225
 
156
226
  Example:
@@ -166,6 +236,11 @@ Consumers should split only on the first `:`, then parse whitespace-delimited
166
236
  `key=value` fields with JSON-string awareness. If a real parser is available,
167
237
  prefer JSON rather than implementing a partial TOON parser.
168
238
 
239
+ An organization comparison adds `COMPARISON`, `NEW_FINDING`,
240
+ `RESOLVED_FINDING`, `UNCHANGED_FINDING`, and `UNKNOWN_FINDING` records before
241
+ the normal organization `SUMMARY`. Text, CSV, and HTML use the same underlying
242
+ record set.
243
+
169
244
  ## JSON
170
245
 
171
246
  JSON output is command-specific and ends with a newline. Every top-level object
@@ -198,7 +273,23 @@ Audit and organization findings use this core shape:
198
273
  }
199
274
  ```
200
275
 
201
- Organization findings additionally include `repository`, `branch`, and `url`.
276
+ Organization findings additionally include `repository`, `branch`, `url`, and
277
+ the source location:
278
+
279
+ ```js
280
+ {
281
+ url: string, // default-branch link, #L<line> when line > 0
282
+ path: string, // repo-relative POSIX path
283
+ blobSha: string | null, // lowercase 40-hex blob of the scanned file
284
+ permalink: string // {htmlUrl}/blob/{commitSha}/{path}, #L<line> when line > 0
285
+ }
286
+ ```
287
+
288
+ `file`, `fields.file`, `url`, `id`, and `fingerprint` are unchanged; `path` is
289
+ the same location without the `owner/repo/` prefix. `permalink` pins the exact
290
+ commit that was scanned, so it stays valid after the branch moves. It falls back
291
+ to the `url` form only when no commit is known. An organization `errors` entry
292
+ that has a `path` also carries a `permalink`.
202
293
  `fields.type`, `fields.sev`, and `fields.file` provide the equivalent flat
203
294
  fields used by line-oriented formats.
204
295
 
@@ -317,7 +408,20 @@ fields used by line-oriented formats.
317
408
  {
318
409
  schemaVersion: '1.0',
319
410
  organization: string,
411
+ analysis: {
412
+ generation: number,
413
+ identity: string // stable 64-hex scope/policy/rule identity
414
+ },
320
415
  scope: object,
416
+ coverage: {
417
+ complete: boolean,
418
+ enumerationComplete: true,
419
+ selectedRepositoriesComplete: boolean,
420
+ eligibleRepositoriesComplete: boolean,
421
+ limitedByMaxRepositories: boolean,
422
+ repositoriesOmittedByLimit: number,
423
+ incompleteRepositories: string[]
424
+ },
321
425
  repositories: [{
322
426
  repository: {
323
427
  owner: string,
@@ -331,8 +435,20 @@ fields used by line-oriented formats.
331
435
  disabled: boolean,
332
436
  htmlUrl: string
333
437
  },
334
- revision: { branch: string | null, treeSha: string | null },
335
- files: string[],
438
+ revision: {
439
+ branch: string | null,
440
+ treeSha: string | null,
441
+ commitSha: string | null // null only for an empty repository or a failed read
442
+ },
443
+ files: string[], // workflow files that were read and audited
444
+ fileDetails: [{ // every selected workflow file, sorted by path
445
+ path: string,
446
+ blobSha: string | null,
447
+ bytes: number | null, // decoded size when read, else tree size, else null
448
+ status: 'scanned' | 'parse-error' | 'unreadable',
449
+ findings: number, // unsuppressed findings reported for this file
450
+ permalink: string
451
+ }],
336
452
  findings: Finding[],
337
453
  errors: object[],
338
454
  summary: object,
@@ -343,14 +459,116 @@ fields used by line-oriented formats.
343
459
  summary: object,
344
460
  baseline: object,
345
461
  configPath: string | null,
462
+ comparison?: OrganizationComparison,
346
463
  status: 'OK' | 'FAIL'
347
464
  }
348
465
  ```
349
466
 
467
+ `fileDetails` lists every workflow tree entry selected after ignore filtering,
468
+ including clean files, so a consumer can prove which files were inspected.
469
+ `unreadable` marks an entry that produced a fetch error; it is absent from
470
+ `files` and appears in `errors`. `files` itself stays a `string[]`.
471
+
350
472
  The organization summary includes repository coverage counts in addition to
351
473
  file, finding, suppression, error, and severity counts. A consumer can use the
352
474
  flattened arrays for ingestion and the `repositories` array for coverage and
353
- ownership views.
475
+ ownership views. `coverage.complete` requires every eligible repository in the
476
+ requested filters to be selected and free of API, blob, or parse coverage
477
+ gaps. A deliberate repository cap is therefore visible even when the selected
478
+ repositories have status `OK`.
479
+
480
+ `analysis.identity` covers the organization, repository filters, inclusion
481
+ flags, repository limit, severity, explanation setting, normalized policy,
482
+ baseline contents, analysis generation, and rule catalog. It is public hash
483
+ material rather than a credential and remains stable across compatible package
484
+ versions and concurrency changes.
485
+
486
+ With `--report-dir`, `organization-report.json` uses kind
487
+ `actions-warden-org-scan-directory`. It retains the top-level analysis, scope,
488
+ coverage, summary, baseline, config, comparison summary, and status, but each
489
+ repository entry contains counts plus an artifact pointer instead of complete
490
+ finding and error arrays:
491
+
492
+ ```js
493
+ {
494
+ schemaVersion: '1.0',
495
+ kind: 'actions-warden-org-scan-directory',
496
+ organization: string,
497
+ analysis: object,
498
+ scope: object,
499
+ coverage: object,
500
+ repositories: [{
501
+ repository: object,
502
+ revision: object,
503
+ summary: object,
504
+ status: 'OK' | 'FAIL',
505
+ files: number,
506
+ findings: number,
507
+ errors: number,
508
+ artifact: { path: string, bytes: number, sha256: string }
509
+ }],
510
+ summary: object,
511
+ baseline: object,
512
+ configPath: string | null,
513
+ comparison?: { summary: object, artifact: object },
514
+ status: 'OK' | 'FAIL'
515
+ }
516
+ ```
517
+
518
+ Each repository pointer names an
519
+ `actions-warden-org-scan-repository` document containing the complete
520
+ repository result, including `fileDetails`; the compact aggregate keeps only the
521
+ file count and the `revision` (with its `commitSha`). `manifest.json` uses kind
522
+ `actions-warden-org-scan-manifest` and lists the compact report, every
523
+ repository artifact, and optional comparison artifact with its exact UTF-8
524
+ byte count and SHA-256 digest. The final manifest, rather than a directory
525
+ listing, identifies the current run; unrelated or stale regular files can
526
+ remain in the directory. Consumers must verify the listed sizes and digests;
527
+ a mismatch means the multi-file report is incomplete or was modified.
528
+
529
+ When `--previous-report` is supplied, `comparison` has this shape:
530
+
531
+ ```js
532
+ {
533
+ schemaVersion: '1.0',
534
+ analysis: object,
535
+ repositories: {
536
+ previous: number,
537
+ current: number,
538
+ comparable: number,
539
+ added: string[],
540
+ removed: string[],
541
+ failed: string[]
542
+ },
543
+ findings: {
544
+ new: Finding[],
545
+ resolved: Finding[],
546
+ unchanged: Finding[],
547
+ unknown: Finding[]
548
+ },
549
+ summary: {
550
+ newFindings: number,
551
+ resolvedFindings: number,
552
+ unchangedFindings: number,
553
+ unknownFindings: number,
554
+ repositoriesComparable: number,
555
+ repositoriesAdded: number,
556
+ repositoriesRemoved: number,
557
+ repositoriesFailed: number,
558
+ complete: boolean
559
+ }
560
+ }
561
+ ```
562
+
563
+ Semantic fingerprints tolerate line movement. Resolution is fail-closed:
564
+ unmatched previous findings are `resolved` only for repositories successfully
565
+ covered and parsed by the current report; otherwise they are `unknown`. A
566
+ missing, failed, or unparseable repository makes the comparison incomplete. Current scan status does
567
+ not change merely because findings were resolved. Comparison requires matching
568
+ analysis identities and is unavailable with SARIF. Analysis generation 3 added
569
+ the commit, file inventory, and permalinks, so a report produced by an earlier
570
+ version cannot be used with `--previous-report`; regenerate it once with the
571
+ current version.
354
572
 
355
573
  ### `rules`
356
574
 
@@ -366,22 +584,128 @@ ownership views.
366
584
  }
367
585
  ```
368
586
 
587
+ ## CSV
588
+
589
+ CSV is a deterministic flat view of the same labeled records used by TOON,
590
+ text, SARIF, and HTML. It uses UTF-8, commas, and CRLF row endings. The first
591
+ column is always `record_type`; every scanner record occupies one physical row;
592
+ and a final `STATUS` row contains `OK` or `FAIL`.
593
+
594
+ The remaining header is the union of fields present in the result. Common
595
+ fields use this stable preferred order when present:
596
+
597
+ ```text
598
+ status,organization,repo,repository,file,path,line,id,type,ruleId,sev,severity,
599
+ action,image,from,to,sha,version,level,change,msg,explain,url,permalink
600
+ ```
601
+
602
+ Additional field names follow in lexical order. Empty, null, and missing
603
+ values produce empty cells. Nested arrays and objects become compact JSON
604
+ cells. The name `record_type` is reserved for the scanner label.
605
+
606
+ Values containing commas or quotes use standard CSV quoting, with embedded
607
+ quotes doubled. Carriage returns, newlines, tabs, and remaining control
608
+ characters are rendered as visible backslash escapes so untrusted evidence
609
+ cannot create extra rows or GitHub workflow commands. String cells whose first
610
+ non-whitespace character is `=`, `+`, `-`, or `@` receive a leading apostrophe
611
+ to prevent spreadsheet formula execution. Credential redaction runs before
612
+ serialization.
613
+
614
+ ```csv
615
+ record_type,status,file,line,id,type,sev,action,files,findings
616
+ SCAN,,.github/workflows/ci.yml,,,,,,,
617
+ FINDING,,.github/workflows/ci.yml,14,18b82e86d7c14fe2,unpinned-action,high,actions/checkout@v5,,
618
+ SUMMARY,,,,,,,,1,1
619
+ STATUS,FAIL,,,,,,,,
620
+ ```
621
+
622
+ CSV is intended for review and flat ingestion, not lossless round trips. Use
623
+ JSON for nested command data, schema-versioned automation, or a future
624
+ `--previous-report` input. Organization comparison rows are included in CSV,
625
+ but the previous report itself must remain compatible organization JSON. See
626
+ the [CSV reporting example](../examples/csv-reporting/README.md).
627
+
628
+ ## HTML
629
+
630
+ HTML reports are deterministic, self-contained documents designed for saved
631
+ human-review artifacts. They provide:
632
+
633
+ - status and explicit incomplete-coverage warnings;
634
+ - report scope and summary metric cards;
635
+ - severity/rule and organization repository breakdowns;
636
+ - client-side search plus record type, severity, and repository filters;
637
+ - complete record tables, including a "Scanned files" table, HTTPS source and
638
+ permalink links, and comparison groups;
639
+ - print styling without external fonts, scripts, stylesheets, or network calls.
640
+
641
+ Every dynamic value passes through credential redaction and HTML escaping. No
642
+ report data is inserted into executable JavaScript, unsafe URL schemes are not
643
+ linked, and a restrictive content security policy blocks external resources.
644
+ The generated document is capped at 32 MiB; use JSON, CSV, or SARIF, or narrow the
645
+ requested scope, if rendering exceeds that bound.
646
+
647
+ ```sh
648
+ actions-warden org-scan my-org \
649
+ --format=html \
650
+ --output-path=reports/actions-warden.html
651
+ ```
652
+
653
+ The document can contain private repository names, paths, source URLs, and
654
+ security posture. Protect it with the same retention and access controls as a
655
+ JSON organization report. HTML is not accepted as `--previous-report`; retain
656
+ JSON when a later scan will calculate changes.
657
+ See the [HTML organization report example](../examples/html-organization-report/README.md)
658
+ for a copyable artifact-first workflow.
659
+
369
660
  ## SARIF
370
661
 
371
662
  SARIF output uses version 2.1.0 and identifies the tool as `actions-warden`.
372
- Findings and operational records become SARIF results. Finding IDs and semantic
373
- fingerprints are included as partial fingerprints where available, and source
374
- locations use repository-relative POSIX paths.
663
+ Findings and operational records become SARIF results; `FILE` inventory records
664
+ do not. Finding IDs and semantic fingerprints are included as partial
665
+ fingerprints where available, and source locations use repository-relative
666
+ POSIX paths.
667
+
668
+ Every rule descriptor that has a severity carries
669
+ `properties['security-severity']`, a string GitHub uses to rank code-scanning
670
+ alerts: critical `9.5`, high `7.0`, medium `4.0`, and low `1.0`. GitHub maps
671
+ scores over 9.0 to critical, 7.0 to 8.9 to high, 4.0 to 6.9 to medium, and 0.1
672
+ to 3.9 to low, so critical uses 9.5 instead of the boundary value. Descriptors
673
+ for operational errors, warnings, and change plans have no score because they
674
+ are not security alerts.
675
+
676
+ Local commands (`audit`, `pin`, `upgrade`, `verify`, and `report`) write a
677
+ single run. An organization scan writes one run per repository, in repository
678
+ order, with an empty `results` array for a repository that has no findings:
679
+
680
+ ```js
681
+ {
682
+ tool: { driver: { name: 'actions-warden', rules: [/* ... */] } },
683
+ versionControlProvenance: [{
684
+ repositoryUri: string, // https://github.com/<owner>/<repo>
685
+ revisionId?: string, // scanned commit; omitted when it is unknown
686
+ branch?: string // default branch
687
+ }],
688
+ invocations: [{ executionSuccessful: boolean }],
689
+ results: [/* locations use the repo-relative `path` */]
690
+ }
691
+ ```
692
+
693
+ A repository-level error, such as an unreadable tree, is a result in that
694
+ repository's run. Organization findings point at files in other repositories, so
695
+ treat the combined file as a portable report. GitHub code scanning accepts at
696
+ most 20 runs per SARIF file and one repository per upload, so split an
697
+ organization file by run before uploading anything to code scanning.
375
698
 
376
699
  For a local repository, upload the generated file with the code-scanning tool
377
- used by your CI platform. Organization findings point at files in other
378
- repositories, so a single organization SARIF artifact is best treated as a
379
- portable report unless your ingestion system explicitly supports
380
- cross-repository locations.
700
+ used by your CI platform.
381
701
 
382
702
  GitHub Action annotations are separate from the selected output format. Choosing
383
703
  SARIF does not disable annotations.
384
704
 
705
+ The [SARIF Code Scanning example](../examples/sarif-code-scanning/README.md)
706
+ shows a least-privilege trusted-run workflow that retains the file, uploads it,
707
+ and then enforces the actions-warden result.
708
+
385
709
  ## Stable identities and ordering
386
710
 
387
711
  Occurrence IDs exclude absolute checkout paths so a cloned repository produces
@@ -399,11 +723,55 @@ repository access change.
399
723
  Resuming an organization scan does not add execution-history fields to the
400
724
  final report. When all validated repository revisions are unchanged, a resumed
401
725
  report has the same serialized bytes as a fresh result with the same inputs.
726
+ Checkpoints store neither commits nor links; a resumed report rebuilds finding
727
+ `path`s, `permalink`s, and `revision.commitSha` from the current run's commit.
402
728
  Checkpoint and progress metadata stay outside the report contract.
403
729
 
404
730
  ## GitHub Action outputs
405
731
 
406
- The Action exposes `status`, `findings`, `report-path`, `annotations`, and
407
- `annotations-skipped`. Its `fail-on-findings` input can allow audit findings to
408
- leave the step successful, but operational errors always fail. See the
732
+ Action outputs are a small machine-readable channel separate from the selected
733
+ TOON, JSON, text, CSV, SARIF, or HTML payload:
734
+
735
+ | output | semantics |
736
+ |---|---|
737
+ | `status` | Semantic `OK` or `FAIL` |
738
+ | `findings` | Unsuppressed findings after severity filtering |
739
+ | `total-findings` | Findings before baseline suppression and after severity filtering |
740
+ | `critical`, `high`, `medium`, `low` | Unsuppressed findings at each severity |
741
+ | `suppressed` | Findings accepted by the active baseline |
742
+ | `errors` | Operational errors, including parse failures |
743
+ | `repositories-discovered` | Repositories visible to `org-scan` discovery |
744
+ | `repositories-selected` | Repositories selected by `org-scan` scope and limit |
745
+ | `repositories-scanned` | Selected repositories with a completed result |
746
+ | `repositories-resumed` | Completed repositories reused from a revision-verified checkpoint |
747
+ | `repositories-failed` | Repositories with API, tree, or blob coverage errors |
748
+ | `coverage-complete` | `true` or `false` for eligible organization coverage; empty for other commands |
749
+ | `new-findings` | Findings added since `previous-report` |
750
+ | `resolved-findings` | Findings safely resolved since `previous-report` |
751
+ | `unchanged-findings` | Findings unchanged since `previous-report` |
752
+ | `unknown-findings` | Prior findings whose resolution is unknown because coverage was incomplete |
753
+ | `report-path` | Absolute saved report path; always populated by `org-scan` |
754
+ | `checkpoint-path` | Absolute active `org-scan` checkpoint path, or empty when disabled |
755
+ | `annotations` | Native annotations emitted |
756
+ | `annotations-skipped` | Annotations omitted by the per-level cap |
757
+
758
+ Every numeric output is emitted as a decimal string for every command, using
759
+ `0` when it does not apply. For finding commands, `total-findings` equals
760
+ `findings + suppressed`; severity counts describe `findings`, not suppressed
761
+ records. `errors` adds parse-error findings to the command's structured error
762
+ arrays so it matches the Action's operational-failure policy. An invocation
763
+ error sets `errors` to `1` and the finding and repository counts to `0`.
764
+ `coverage-complete` is not numeric: it is empty outside `org-scan`, and it can
765
+ be `false` for an otherwise `OK` capped scan.
766
+
767
+ The Action job summary is also separate from the selected format. It contains
768
+ bounded result tables, organization coverage, checkpoint/resume state,
769
+ severity/rule aggregates, and
770
+ top finding, change, warning, or error records as applicable. It does not embed
771
+ the complete payload. Dynamic summary text is redacted, Markdown-escaped, and
772
+ length-bounded. Organization scans and Action CSV/HTML reports keep complete
773
+ evidence in files; other formats remain on stdout and may also be saved.
774
+
775
+ The `fail-on-findings` input can allow audit findings to leave the step
776
+ successful, but operational errors always fail. See the
409
777
  [GitHub Action guide](./GITHUB-ACTION.md#outputs-and-failure-policy).
package/docs/README.md CHANGED
@@ -9,7 +9,7 @@ documentation.
9
9
  |---|---|
10
10
  | [CLI reference](./CLI.md) | Running audits, pinning, upgrades, verification, reports, or organization scans |
11
11
  | [Configuration](./CONFIGURATION.md) | Defining policy, baselines, path exclusions, inline ignores, or runner trust |
12
- | [Output contracts](./OUTPUTS.md) | Parsing JSON or TOON, uploading SARIF, or handling status and exit codes |
12
+ | [Output contracts](./OUTPUTS.md) | Parsing JSON/TOON/CSV/JSONL, reviewing HTML or directory manifests, comparing scans, uploading SARIF, or handling status and exits |
13
13
  | [GitHub Action](./GITHUB-ACTION.md) | Adding repository or organization scanning to a workflow |
14
14
  | [JavaScript API](./JAVASCRIPT-API.md) | Calling commands or parser utilities from Node.js |
15
15
 
@@ -0,0 +1,21 @@
1
+ # Examples
2
+
3
+ These examples are copyable starting points. Keep every third-party Action at a
4
+ reviewed full commit SHA, then adapt permissions and retention to the consuming
5
+ repository.
6
+
7
+ | example | use it when |
8
+ |---|---|
9
+ | [CI violation reporting](./ci-violation-reporting/README.md) | A pull request should receive annotations and a JSON artifact before a policy gate blocks it |
10
+ | [Baseline adoption](./baseline-adoption/README.md) | An existing repository needs to accept reviewed legacy findings while blocking new ones |
11
+ | [SARIF Code Scanning](./sarif-code-scanning/README.md) | Findings should be uploaded to GitHub Code Scanning on trusted branch or scheduled runs |
12
+ | [HTML organization report](./html-organization-report/README.md) | Review organization coverage and findings in a searchable offline dashboard |
13
+ | [CSV reporting](./csv-reporting/README.md) | Export flat, spreadsheet-safe rows and retain them before enforcing policy |
14
+ | [Webhook and notification delivery](./notifications/README.md) | Send a bounded summary through generic HTTPS or ProjectDiscovery Notify without exposing the complete report |
15
+ | [Organization scan](./org-scan.yml) | A scheduled job should report workflow risks across an organization |
16
+ | [Upgrade pull request](./upgrade-pr.yml) | A scheduled job should apply eligible dependency upgrades and open a pull request |
17
+
18
+ The examples do not grant actions-warden permission to execute scanned code.
19
+ Repository audits are local and need no token input. Organization and
20
+ dependency-resolution commands need only the GitHub read access documented by
21
+ their individual guides.