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