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/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,56 +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>`. Unknown
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
51
61
  options, missing values, invalid choices, conflicting flags, malformed numeric
52
62
  values, unsafe destinations, and a missing command all return `2`. The failure
53
63
  may occur before a structured payload can be rendered, so do not assume stdout
54
64
  contains JSON when the process exits `2`.
55
65
 
56
66
  Organization-scan live progress is also a stderr-only channel. It never becomes
57
- part of JSON, SARIF, TOON, or text stdout. `--progress=auto` enables it for an
58
- interactive stderr, `always` enables it for redirected/CI logs, and `never`
59
- disables it. GitHub Action organization scans show the same phase, repository,
60
- 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.
61
74
 
62
- ### Agent-mode receipt
75
+ Each `--progress=json` line is an independently parseable object:
63
76
 
64
- `org-scan --agent-mode`, or `ACTIONS_WARDEN_MODE=agent`, defaults the complete
65
- report to a guarded scope-keyed file. Its stdout is a separate bounded JSON
66
- 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:
67
103
 
68
104
  ```js
69
105
  {
70
106
  schemaVersion: '1.0',
71
- kind: 'actions-warden-agent-receipt',
107
+ kind: 'actions-warden-org-scan-receipt' | 'actions-warden-agent-receipt',
72
108
  command: 'org-scan',
73
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
+ },
74
116
  status: 'OK' | 'FAIL',
75
117
  summary: object,
76
118
  report: {
77
119
  path: string,
78
- format: 'toon' | 'json' | 'text' | 'sarif'
120
+ format: 'toon' | 'json' | 'text' | 'csv' | 'sarif' | 'html',
121
+ layout: 'single' | 'directory',
122
+ directory?: string,
123
+ manifest?: string
79
124
  },
80
125
  checkpoint: {
81
- path: string,
82
- resumed: boolean
83
- }
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
84
140
  }
85
141
  ```
86
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.
87
145
  `summary` is the normal bounded organization coverage and severity summary;
88
146
  the receipt never embeds repository arrays, findings, or operational error
89
- details. Read `report.path` for the complete evidence. The receipt remains JSON
90
- 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.
91
154
  Status and process exit semantics are unchanged. An invocation error may occur
92
155
  before a receipt exists.
93
156
 
94
157
  Explicit `--output=stdout` overrides the file default. In that case stdout is
95
- 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.
96
161
 
97
162
  A mutation plan may contain changes and still return `0`: proposed changes are
98
163
  not errors. Conversely, `audit` may emit valid JSON and return `1`: findings are
@@ -155,7 +220,7 @@ Record labels by command:
155
220
  | `upgrade` | `UPGRADE`, `SKIP`, `ERROR`, `SUMMARY` |
156
221
  | `verify` | `VERIFIED`, `WARNING`, `ERROR`, `SUMMARY` |
157
222
  | `report` | `FINDING`, `PIN`, `UPGRADE`, `SKIP`, `ERROR`, `SUMMARY` |
158
- | `org-scan` | `REPOSITORY`, `FINDING`, `ERROR`, `SUMMARY` |
223
+ | `org-scan` | `REPOSITORY`, `FILE`, `FINDING`, `ERROR`, `COVERAGE`, optional comparison records, `SUMMARY` |
159
224
  | `rules` | `RULE` |
160
225
 
161
226
  Example:
@@ -171,6 +236,11 @@ Consumers should split only on the first `:`, then parse whitespace-delimited
171
236
  `key=value` fields with JSON-string awareness. If a real parser is available,
172
237
  prefer JSON rather than implementing a partial TOON parser.
173
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
+
174
244
  ## JSON
175
245
 
176
246
  JSON output is command-specific and ends with a newline. Every top-level object
@@ -203,7 +273,23 @@ Audit and organization findings use this core shape:
203
273
  }
204
274
  ```
205
275
 
206
- 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`.
207
293
  `fields.type`, `fields.sev`, and `fields.file` provide the equivalent flat
208
294
  fields used by line-oriented formats.
209
295
 
@@ -322,7 +408,20 @@ fields used by line-oriented formats.
322
408
  {
323
409
  schemaVersion: '1.0',
324
410
  organization: string,
411
+ analysis: {
412
+ generation: number,
413
+ identity: string // stable 64-hex scope/policy/rule identity
414
+ },
325
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
+ },
326
425
  repositories: [{
327
426
  repository: {
328
427
  owner: string,
@@ -336,8 +435,20 @@ fields used by line-oriented formats.
336
435
  disabled: boolean,
337
436
  htmlUrl: string
338
437
  },
339
- revision: { branch: string | null, treeSha: string | null },
340
- 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
+ }],
341
452
  findings: Finding[],
342
453
  errors: object[],
343
454
  summary: object,
@@ -348,14 +459,116 @@ fields used by line-oriented formats.
348
459
  summary: object,
349
460
  baseline: object,
350
461
  configPath: string | null,
462
+ comparison?: OrganizationComparison,
351
463
  status: 'OK' | 'FAIL'
352
464
  }
353
465
  ```
354
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
+
355
472
  The organization summary includes repository coverage counts in addition to
356
473
  file, finding, suppression, error, and severity counts. A consumer can use the
357
474
  flattened arrays for ingestion and the `repositories` array for coverage and
358
- 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.
359
572
 
360
573
  ### `rules`
361
574
 
@@ -371,22 +584,128 @@ ownership views.
371
584
  }
372
585
  ```
373
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
+
374
660
  ## SARIF
375
661
 
376
662
  SARIF output uses version 2.1.0 and identifies the tool as `actions-warden`.
377
- Findings and operational records become SARIF results. Finding IDs and semantic
378
- fingerprints are included as partial fingerprints where available, and source
379
- 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.
380
698
 
381
699
  For a local repository, upload the generated file with the code-scanning tool
382
- used by your CI platform. Organization findings point at files in other
383
- repositories, so a single organization SARIF artifact is best treated as a
384
- portable report unless your ingestion system explicitly supports
385
- cross-repository locations.
700
+ used by your CI platform.
386
701
 
387
702
  GitHub Action annotations are separate from the selected output format. Choosing
388
703
  SARIF does not disable annotations.
389
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
+
390
709
  ## Stable identities and ordering
391
710
 
392
711
  Occurrence IDs exclude absolute checkout paths so a cloned repository produces
@@ -404,11 +723,55 @@ repository access change.
404
723
  Resuming an organization scan does not add execution-history fields to the
405
724
  final report. When all validated repository revisions are unchanged, a resumed
406
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.
407
728
  Checkpoint and progress metadata stay outside the report contract.
408
729
 
409
730
  ## GitHub Action outputs
410
731
 
411
- The Action exposes `status`, `findings`, `report-path`, `annotations`, and
412
- `annotations-skipped`. Its `fail-on-findings` input can allow audit findings to
413
- 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
414
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.
@@ -0,0 +1,79 @@
1
+ # Adopt enforcement with a reviewed baseline
2
+
3
+ A baseline lets an existing repository record reviewed findings as accepted
4
+ debt while making every new matching violation fail CI. It is an adoption
5
+ mechanism, not an automatic allowlist: generating or expanding one accepts
6
+ security risk and should require the same review as a policy change.
7
+
8
+ ## Files
9
+
10
+ | file | copy to | purpose |
11
+ |---|---|---|
12
+ | [`github-actions.yml`](./github-actions.yml) | `.github/workflows/actions-warden.yml` | Report unsuppressed findings, upload JSON, and enforce the result |
13
+ | [`policy.yml`](./policy.yml) | `.actions-warden.yml` | Load the reviewed baseline and define repository policy |
14
+
15
+ The baseline itself is deliberately not included because its IDs and
16
+ fingerprints must come from the repository being protected.
17
+
18
+ ## One-time adoption
19
+
20
+ 1. Install a reviewed actions-warden version and audit the current repository
21
+ without a baseline:
22
+
23
+ ```sh
24
+ actions-warden audit --format=json --explain
25
+ ```
26
+
27
+ 2. Investigate the findings. Fix what can be fixed immediately. For every
28
+ remaining finding, record the owner, justification, and remediation plan in
29
+ the repository's normal risk-tracking system.
30
+ 3. Generate the deterministic baseline from the reviewed remaining findings:
31
+
32
+ ```sh
33
+ actions-warden audit \
34
+ --create-baseline=.actions-warden-baseline.json \
35
+ --format=json
36
+ ```
37
+
38
+ 4. Review `.actions-warden-baseline.json` before committing it. Copy
39
+ `policy.yml` to `.actions-warden.yml` and `github-actions.yml` to
40
+ `.github/workflows/actions-warden.yml` in the consuming repository.
41
+ 5. Protect the workflow, policy, and baseline with `CODEOWNERS` and branch
42
+ rules. Make `Report new Actions violations` a required status check when it
43
+ is ready to block merging.
44
+
45
+ The JSON report exposes both `totalFindings` and `suppressed`; the Action also
46
+ provides `total-findings`, `suppressed`, and `findings` outputs for later steps.
47
+ The blocking `findings` count contains only unsuppressed violations. Moving an
48
+ unchanged finding to another line normally remains matched through its semantic
49
+ fingerprint.
50
+
51
+ ## Prove that the ratchet works
52
+
53
+ Run the audit after the baseline and policy are installed:
54
+
55
+ ```sh
56
+ actions-warden audit --format=json --explain
57
+ ```
58
+
59
+ Reviewed legacy findings should be counted as suppressed. Introduce a
60
+ temporary unsafe reference such as `uses: owner/action@v1` on a throwaway
61
+ branch and run it again. The new occurrence should be reported and exit `1`.
62
+ Remove the temporary violation after the check.
63
+
64
+ Never regenerate or expand the baseline automatically in CI. Adding a record
65
+ accepts a finding; deleting a record causes a still-present finding to become
66
+ active again. Remove obsolete records as their underlying findings are fixed,
67
+ and review every baseline diff as a security-control change.
68
+
69
+ ## CI behavior
70
+
71
+ The workflow runs actions-warden with `fail-on-findings: 'false'` so it can
72
+ upload `actions-warden-new-violations.json` before the final gate fails.
73
+ It passes `config: .actions-warden.yml` explicitly, so a missing policy or
74
+ referenced baseline fails closed instead of reverting to built-in defaults.
75
+ Operational errors still fail the audit step directly. To start in advisory
76
+ mode, omit the final gate until the baseline and ownership process are ready.
77
+
78
+ Baseline and report files contain repository paths and security evidence.
79
+ Restrict access and retention according to the repository's security policy.