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/AI-AGENTS.md
CHANGED
|
@@ -88,6 +88,15 @@ found something. Parse and present the report.
|
|
|
88
88
|
|
|
89
89
|
Exit code `2` is an invocation-level problem. Read stderr, do not assume stdout
|
|
90
90
|
contains valid JSON, and do not retry by weakening policy or changing paths.
|
|
91
|
+
Unknown options, conflicting flags, malformed numeric values, invalid change
|
|
92
|
+
IDs, unsafe destinations, and a missing command all use this exit code. These
|
|
93
|
+
checks happen before network requests or authorized workflow mutations whenever
|
|
94
|
+
the required path information is available.
|
|
95
|
+
|
|
96
|
+
When saving a report, `--output-path=<path>` is sufficient and implies file
|
|
97
|
+
output. Do not combine it with explicit `--output=stdout`. Create the parent
|
|
98
|
+
directory first, and never select a workflow, policy, baseline, or checkpoint
|
|
99
|
+
path as the report destination.
|
|
91
100
|
|
|
92
101
|
For an organization scan, report coverage before findings:
|
|
93
102
|
|
|
@@ -225,9 +234,7 @@ the request:
|
|
|
225
234
|
actions-warden org-scan my-org \
|
|
226
235
|
--repository 'payments-*' \
|
|
227
236
|
--visibility=private \
|
|
228
|
-
--severity=high
|
|
229
|
-
--checkpoint=.actions-warden-org-checkpoint.json \
|
|
230
|
-
--format=json
|
|
237
|
+
--severity=high
|
|
231
238
|
```
|
|
232
239
|
|
|
233
240
|
The scanner never executes remote code, but the resulting strings still come
|
|
@@ -251,33 +258,65 @@ An integration can set the marker once instead of passing the option on every
|
|
|
251
258
|
invocation:
|
|
252
259
|
|
|
253
260
|
```sh
|
|
254
|
-
export
|
|
261
|
+
export ACTIONS_WARDEN_CONTEXT=agent
|
|
255
262
|
actions-warden org-scan my-org
|
|
256
263
|
```
|
|
257
264
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
265
|
+
There is no reliable universal agent-runtime heuristic; integrations should set
|
|
266
|
+
the context once when they cannot add `--agent-mode` to each invocation.
|
|
267
|
+
|
|
268
|
+
Organization scans are artifact-first even when an integration forgets agent
|
|
269
|
+
mode: the CLI writes a scope-keyed JSON report and checkpoint, automatically
|
|
270
|
+
resumes compatible state, and emits a bounded receipt. Agent mode is an
|
|
271
|
+
explicit contract, not heuristic detection. It additionally:
|
|
272
|
+
|
|
273
|
+
- disables implicit progress;
|
|
274
|
+
- labels the bounded receipt `actions-warden-agent-receipt` so integrations can
|
|
275
|
+
distinguish the explicit contract.
|
|
276
|
+
|
|
277
|
+
Agent and normal execution share `.actions-warden-org-scan.*` artifacts. A
|
|
278
|
+
context switch therefore retains compatible resume state.
|
|
279
|
+
|
|
280
|
+
An agent may explicitly select `--format=html` when the user wants a retained
|
|
281
|
+
human-review artifact or `--format=csv` for a flat spreadsheet export, but it
|
|
282
|
+
must not load either complete artifact into model context. Read the bounded
|
|
283
|
+
receipt and use JSON for structured comparison or finding-batch inspection.
|
|
284
|
+
For a broad report that will be inspected repository by repository, prefer
|
|
285
|
+
`--report-dir=reports/actions-warden-org`: read its compact aggregate and
|
|
286
|
+
manifest first, then only the relevant complete repository artifacts. This
|
|
287
|
+
bounds downstream context reads, not the scanner's in-process memory. Retain a
|
|
288
|
+
normal complete JSON report as well if the run must later be used as
|
|
289
|
+
`--previous-report`.
|
|
290
|
+
|
|
291
|
+
To cite evidence, use the report's source locations: every finding has a
|
|
292
|
+
`permalink` pinned to the scanned commit, and each repository's `fileDetails`
|
|
293
|
+
lists every workflow file that was inspected, including clean ones, with its
|
|
294
|
+
status. Prefer a `permalink` over the branch `url` when quoting a finding,
|
|
295
|
+
and treat an `unreadable` file as a coverage gap, not a clean file.
|
|
267
296
|
|
|
268
297
|
The automatic artifact key covers the organization, repository filters,
|
|
269
298
|
inclusion flags, repository limit, severity, explanation setting, normalized
|
|
270
|
-
policy, baseline contents,
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
299
|
+
policy, baseline contents, analysis generation, and rule catalog. A compatible
|
|
300
|
+
package upgrade keeps the same path, and the next checkpoint write records the
|
|
301
|
+
current package version. A changed scope, security control, or
|
|
302
|
+
analysis behavior receives a different path instead of replacing an
|
|
303
|
+
incompatible checkpoint.
|
|
304
|
+
The generated files begin `.actions-warden-org-scan.`; protect them as
|
|
305
|
+
sensitive report artifacts and add that pattern to the consuming repository's
|
|
306
|
+
ignore rules when appropriate.
|
|
307
|
+
|
|
308
|
+
Version-only upgrades do not accumulate new automatic artifacts. A deliberate
|
|
309
|
+
analysis-generation change does retain the older keyed files as audit evidence;
|
|
310
|
+
remove them only under the consuming repository's retention policy.
|
|
275
311
|
|
|
276
312
|
Explicit CLI options take precedence over agent defaults. Use
|
|
277
|
-
`--progress=
|
|
313
|
+
`--progress=plain` when the user requests human-readable live progress, or
|
|
314
|
+
`--progress=json` when the integration will parse JSON Lines. Use
|
|
278
315
|
`--output=stdout` only when the caller intentionally wants the complete report
|
|
279
316
|
in its context; in that case stdout is the selected report rather than the
|
|
280
|
-
compact receipt. `--no-
|
|
317
|
+
compact receipt. `--no-auto-checkpoint` disables generated resume state, and
|
|
318
|
+
`--fresh` deliberately replaces it without reuse. `--no-agent-mode` overrides
|
|
319
|
+
an inherited environment marker.
|
|
281
320
|
|
|
282
321
|
Resume primarily reduces repeated GitHub tree/blob work and elapsed time. It
|
|
283
322
|
only reduces model usage when it also prevents extra output from entering the
|
|
@@ -287,7 +326,7 @@ context.
|
|
|
287
326
|
Do not add a severity or repository filter merely to save model tokens. The
|
|
288
327
|
requested security scope controls the scan; file output controls the context
|
|
289
328
|
cost. Omit `--explain` on the broad first pass unless the user requested
|
|
290
|
-
remediation guidance. If live progress is requested, use `--progress=
|
|
329
|
+
remediation guidance. If live progress is requested, use `--progress=plain`
|
|
291
330
|
and treat those short stderr records only as status—not report evidence.
|
|
292
331
|
|
|
293
332
|
After the command finishes, inspect the report from small to large. For
|
|
@@ -295,7 +334,7 @@ example, `jq` can produce a bounded first-pass view without emitting finding
|
|
|
295
334
|
bodies or the per-repository result array:
|
|
296
335
|
|
|
297
336
|
```sh
|
|
298
|
-
agent_report_path='.actions-warden-
|
|
337
|
+
agent_report_path='.actions-warden-org-scan.<scope-key>.report.json'
|
|
299
338
|
jq '{
|
|
300
339
|
schemaVersion,
|
|
301
340
|
organization,
|
|
@@ -318,6 +357,24 @@ jq '{
|
|
|
318
357
|
|
|
319
358
|
Set `agent_report_path` to the exact `report.path` value in the receipt.
|
|
320
359
|
|
|
360
|
+
When the user asks what changed since a prior scan, keep the same requested
|
|
361
|
+
scope and use a compatible previous JSON report:
|
|
362
|
+
|
|
363
|
+
```sh
|
|
364
|
+
actions-warden org-scan my-org \
|
|
365
|
+
--agent-mode \
|
|
366
|
+
--previous-report=reports/org.previous.json
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
Inspect `comparison.summary` from the receipt and saved report first. Report
|
|
370
|
+
new, resolved, unchanged, and unknown counts. A removed, failed, or unparseable
|
|
371
|
+
repository makes prior unmatched findings unknown; never describe them as resolved. A
|
|
372
|
+
scope, policy, baseline, rule, or analysis-generation mismatch is an invocation
|
|
373
|
+
error and must not be bypassed by weakening current controls. A report from an
|
|
374
|
+
older analysis generation cannot be reused; regenerate it once with the current
|
|
375
|
+
version. CSV and HTML
|
|
376
|
+
reports are not valid previous-report inputs.
|
|
377
|
+
|
|
321
378
|
Then read operational errors and relevant findings in bounded batches, grouped
|
|
322
379
|
by repository, severity, or rule. The saved JSON remains the complete source
|
|
323
380
|
of truth. If a response covers only a subset of findings, say so explicitly
|
|
@@ -326,18 +383,21 @@ sample, and never ignore `summary.repositoriesFailed` or `summary.errors`.
|
|
|
326
383
|
|
|
327
384
|
Before summarizing risk:
|
|
328
385
|
|
|
329
|
-
1. inspect `summary.repositoriesFailed
|
|
386
|
+
1. inspect `coverage.complete`, `summary.repositoriesFailed`, and `errors`;
|
|
330
387
|
2. compare discovered, eligible, selected, and scanned counts;
|
|
331
388
|
3. state excluded archived, disabled, and forked defaults;
|
|
332
389
|
4. state `maxRepositories`, filters, visibility, and severity;
|
|
333
390
|
5. distinguish “no findings in completed scans” from “complete organization
|
|
334
|
-
coverage
|
|
391
|
+
coverage”; a repository cap is explicitly incomplete coverage even when the
|
|
392
|
+
selected scan status is `OK`.
|
|
335
393
|
|
|
336
394
|
Store reports in a controlled path. Organization results can reveal private
|
|
337
395
|
repository names, workflow paths, branches, source URLs, and security posture.
|
|
338
396
|
|
|
339
|
-
For a long scan, preserve the exact command scope and
|
|
340
|
-
checkpoint
|
|
397
|
+
For a long scan, preserve the exact command scope and repeat the same command;
|
|
398
|
+
the generated or explicitly selected `--checkpoint` path resumes automatically.
|
|
399
|
+
Use the strict checkpoint handoff only when a caller restored a file that must
|
|
400
|
+
exist:
|
|
341
401
|
|
|
342
402
|
```sh
|
|
343
403
|
actions-warden org-scan my-org \
|
|
@@ -351,11 +411,47 @@ actions-warden org-scan my-org \
|
|
|
351
411
|
Do not weaken filters, policy, baseline, or severity merely to make a
|
|
352
412
|
checkpoint compatible. A mismatch is an invocation error and requires a new
|
|
353
413
|
checkpoint. Resume still performs fresh discovery and tree verification; say
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
414
|
+
how many repository results were actually reused from
|
|
415
|
+
`checkpoint.repositoriesReused` in the receipt (or the equivalent progress
|
|
416
|
+
events), while using the final report—not progress lines—as the evidence
|
|
417
|
+
contract. Previously failed and changed repositories are rescanned. Checkpoints omit tokens and raw
|
|
357
418
|
YAML but retain redacted report evidence, so treat them as sensitive artifacts.
|
|
358
419
|
|
|
420
|
+
## Generating CI reporting workflows
|
|
421
|
+
|
|
422
|
+
When the user asks for a GitHub Actions integration, give the actions-warden
|
|
423
|
+
step an `id` and use its bounded job summary for the human review path. Save
|
|
424
|
+
JSON or SARIF with `output-path` when later ingestion or complete evidence is
|
|
425
|
+
required, CSV for a flat spreadsheet/warehouse export, or HTML for a retained
|
|
426
|
+
human dashboard; the summary deliberately contains only aggregates and top
|
|
427
|
+
records. Action organization scans generate a report path and checkpoint path
|
|
428
|
+
when omitted and keep every complete format out of the step log. CSV and HTML
|
|
429
|
+
require `output-path` only for non-organization commands.
|
|
430
|
+
|
|
431
|
+
Later steps can read decimal-string outputs for `findings`, `total-findings`,
|
|
432
|
+
each severity, `suppressed`, and `errors`. Organization scans additionally
|
|
433
|
+
expose discovered, selected, scanned, resumed, and failed repository counts,
|
|
434
|
+
plus the non-numeric `coverage-complete` boolean string. Do not
|
|
435
|
+
describe a run as clean merely because `findings` is `0`: require `errors` and
|
|
436
|
+
`repositories-failed` (for an organization scan) to be `0` and inspect
|
|
437
|
+
`status` plus `coverage-complete`. If a report must be uploaded before findings fail the job, use the
|
|
438
|
+
reviewed pattern in the
|
|
439
|
+
[CI violation-reporting example](../examples/ci-violation-reporting/README.md);
|
|
440
|
+
do not make `fail-on-findings: false` the final policy decision.
|
|
441
|
+
|
|
442
|
+
Organization comparisons additionally expose `new-findings`,
|
|
443
|
+
`resolved-findings`, `unchanged-findings`, and `unknown-findings`. Treat
|
|
444
|
+
resolution as complete only when unknown findings, failed repositories, and
|
|
445
|
+
errors are all zero and the saved comparison says `complete: true`.
|
|
446
|
+
|
|
447
|
+
Do not add webhook delivery to the scanner command. When the user requests a
|
|
448
|
+
webhook or ProjectDiscovery Notify integration, retain the complete report as a
|
|
449
|
+
protected artifact and send a separate bounded summary from the calling
|
|
450
|
+
workflow. Keep provider credentials in masked secrets and make HTTPS
|
|
451
|
+
validation, redirects, retries, timeouts, and delivery failure policy explicit.
|
|
452
|
+
Start from the
|
|
453
|
+
[notification example](../examples/notifications/README.md).
|
|
454
|
+
|
|
359
455
|
## Policy and suppression requests
|
|
360
456
|
|
|
361
457
|
If a user asks to “make CI green,” do not automatically:
|