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