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.
- package/AGENTS.md +46 -8
- package/CONTRIBUTING.md +6 -2
- package/README.md +171 -61
- package/RELEASING.md +3 -2
- package/SECURITY.md +15 -5
- package/docs/AI-AGENTS.md +109 -29
- package/docs/CLI.md +284 -60
- package/docs/CONFIGURATION.md +34 -11
- package/docs/DEVELOPMENT.md +97 -24
- package/docs/GITHUB-ACTION.md +157 -27
- package/docs/JAVASCRIPT-API.md +172 -8
- package/docs/OUTPUTS.md +399 -36
- package/docs/README.md +1 -1
- package/examples/README.md +21 -0
- package/examples/baseline-adoption/README.md +79 -0
- package/examples/baseline-adoption/github-actions.yml +56 -0
- package/examples/baseline-adoption/policy.yml +7 -0
- package/examples/ci-violation-reporting/README.md +82 -0
- package/examples/ci-violation-reporting/github-actions.yml +55 -0
- package/examples/ci-violation-reporting/policy.yml +7 -0
- package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
- package/examples/csv-reporting/README.md +50 -0
- package/examples/csv-reporting/github-actions.yml +59 -0
- package/examples/html-organization-report/README.md +35 -0
- package/examples/html-organization-report/github-actions.yml +61 -0
- package/examples/notifications/README.md +67 -0
- package/examples/notifications/github-actions.yml +163 -0
- package/examples/org-scan.yml +24 -5
- package/examples/sarif-code-scanning/README.md +42 -0
- package/examples/sarif-code-scanning/github-actions.yml +66 -0
- package/examples/upgrade-pr.yml +1 -1
- package/llms.txt +14 -5
- package/package.json +8 -4
- package/skills/actions-warden/SKILL.md +78 -35
- package/src/action.js +351 -174
- package/src/cli.js +191 -177
- package/src/commands/audit.js +17 -30
- package/src/commands/org-scan.js +451 -280
- package/src/commands/pin.js +9 -5
- package/src/commands/report.js +7 -2
- package/src/commands/upgrade.js +9 -5
- package/src/commands/verify.js +24 -4
- package/src/index.js +5 -1
- package/src/lib/action-summary.js +656 -0
- package/src/lib/annotations.js +4 -6
- package/src/lib/baseline.js +11 -1
- package/src/lib/config.js +10 -5
- package/src/lib/destination.js +98 -0
- package/src/lib/execution.js +5 -1
- package/src/lib/formats/csv.js +125 -0
- package/src/lib/formats/html.js +394 -0
- package/src/lib/formats/json.js +17 -0
- package/src/lib/formats/sarif.js +229 -0
- package/src/lib/formats/text.js +30 -0
- package/src/lib/formats/toon.js +50 -0
- package/src/lib/formatter.js +25 -192
- package/src/lib/github-org.js +208 -102
- package/src/lib/org-artifacts.js +211 -0
- package/src/lib/org-checkpoint.js +137 -96
- package/src/lib/org-progress.js +182 -4
- package/src/lib/org-report-comparison.js +505 -0
- package/src/lib/org-report-directory.js +251 -0
- package/src/lib/org-report.js +223 -0
- package/src/lib/org-run.js +305 -0
- package/src/lib/org-schema.js +89 -0
- package/src/lib/org-source-links.js +39 -0
- package/src/lib/parser.js +5 -0
- package/src/lib/paths.js +18 -1
- package/src/lib/redact.js +58 -7
- package/src/lib/resolver.js +66 -9
- package/src/lib/types.js +137 -0
- package/src/rules/pull-request-target-checkout.js +5 -0
- package/src/rules/unpinned-action.js +2 -3
- package/src/rules/workflow-structure.js +2 -4
- package/src/version.js +1 -1
- 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`.
|
|
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
|
-
|
|
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
|
|
58
|
-
interactive stderr, `
|
|
59
|
-
disables it.
|
|
60
|
-
|
|
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
|
-
|
|
75
|
+
Each `--progress=json` line is an independently parseable object:
|
|
63
76
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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.
|
|
90
|
-
|
|
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
|
|
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`,
|
|
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: {
|
|
340
|
-
|
|
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
|
|
378
|
-
|
|
379
|
-
locations use repository-relative
|
|
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.
|
|
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
|
-
|
|
412
|
-
|
|
413
|
-
|
|
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
|
|
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.
|