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/AI-AGENTS.md
CHANGED
|
@@ -234,9 +234,7 @@ the request:
|
|
|
234
234
|
actions-warden org-scan my-org \
|
|
235
235
|
--repository 'payments-*' \
|
|
236
236
|
--visibility=private \
|
|
237
|
-
--severity=high
|
|
238
|
-
--checkpoint=.actions-warden-org-checkpoint.json \
|
|
239
|
-
--format=json
|
|
237
|
+
--severity=high
|
|
240
238
|
```
|
|
241
239
|
|
|
242
240
|
The scanner never executes remote code, but the resulting strings still come
|
|
@@ -260,40 +258,65 @@ An integration can set the marker once instead of passing the option on every
|
|
|
260
258
|
invocation:
|
|
261
259
|
|
|
262
260
|
```sh
|
|
263
|
-
export
|
|
261
|
+
export ACTIONS_WARDEN_CONTEXT=agent
|
|
264
262
|
actions-warden org-scan my-org
|
|
265
263
|
```
|
|
266
264
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
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.
|
|
276
296
|
|
|
277
297
|
The automatic artifact key covers the organization, repository filters,
|
|
278
298
|
inclusion flags, repository limit, severity, explanation setting, normalized
|
|
279
299
|
policy, baseline contents, analysis generation, and rule catalog. A compatible
|
|
280
|
-
package upgrade keeps the same path and
|
|
281
|
-
|
|
300
|
+
package upgrade keeps the same path, and the next checkpoint write records the
|
|
301
|
+
current package version. A changed scope, security control, or
|
|
282
302
|
analysis behavior receives a different path instead of replacing an
|
|
283
303
|
incompatible checkpoint.
|
|
284
|
-
The generated files begin
|
|
285
|
-
|
|
286
|
-
|
|
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.
|
|
287
307
|
|
|
288
308
|
Version-only upgrades do not accumulate new automatic artifacts. A deliberate
|
|
289
309
|
analysis-generation change does retain the older keyed files as audit evidence;
|
|
290
310
|
remove them only under the consuming repository's retention policy.
|
|
291
311
|
|
|
292
312
|
Explicit CLI options take precedence over agent defaults. Use
|
|
293
|
-
`--progress=
|
|
313
|
+
`--progress=plain` when the user requests human-readable live progress, or
|
|
314
|
+
`--progress=json` when the integration will parse JSON Lines. Use
|
|
294
315
|
`--output=stdout` only when the caller intentionally wants the complete report
|
|
295
316
|
in its context; in that case stdout is the selected report rather than the
|
|
296
|
-
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.
|
|
297
320
|
|
|
298
321
|
Resume primarily reduces repeated GitHub tree/blob work and elapsed time. It
|
|
299
322
|
only reduces model usage when it also prevents extra output from entering the
|
|
@@ -303,7 +326,7 @@ context.
|
|
|
303
326
|
Do not add a severity or repository filter merely to save model tokens. The
|
|
304
327
|
requested security scope controls the scan; file output controls the context
|
|
305
328
|
cost. Omit `--explain` on the broad first pass unless the user requested
|
|
306
|
-
remediation guidance. If live progress is requested, use `--progress=
|
|
329
|
+
remediation guidance. If live progress is requested, use `--progress=plain`
|
|
307
330
|
and treat those short stderr records only as status—not report evidence.
|
|
308
331
|
|
|
309
332
|
After the command finishes, inspect the report from small to large. For
|
|
@@ -311,7 +334,7 @@ example, `jq` can produce a bounded first-pass view without emitting finding
|
|
|
311
334
|
bodies or the per-repository result array:
|
|
312
335
|
|
|
313
336
|
```sh
|
|
314
|
-
agent_report_path='.actions-warden-
|
|
337
|
+
agent_report_path='.actions-warden-org-scan.<scope-key>.report.json'
|
|
315
338
|
jq '{
|
|
316
339
|
schemaVersion,
|
|
317
340
|
organization,
|
|
@@ -334,6 +357,24 @@ jq '{
|
|
|
334
357
|
|
|
335
358
|
Set `agent_report_path` to the exact `report.path` value in the receipt.
|
|
336
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
|
+
|
|
337
378
|
Then read operational errors and relevant findings in bounded batches, grouped
|
|
338
379
|
by repository, severity, or rule. The saved JSON remains the complete source
|
|
339
380
|
of truth. If a response covers only a subset of findings, say so explicitly
|
|
@@ -342,18 +383,21 @@ sample, and never ignore `summary.repositoriesFailed` or `summary.errors`.
|
|
|
342
383
|
|
|
343
384
|
Before summarizing risk:
|
|
344
385
|
|
|
345
|
-
1. inspect `summary.repositoriesFailed
|
|
386
|
+
1. inspect `coverage.complete`, `summary.repositoriesFailed`, and `errors`;
|
|
346
387
|
2. compare discovered, eligible, selected, and scanned counts;
|
|
347
388
|
3. state excluded archived, disabled, and forked defaults;
|
|
348
389
|
4. state `maxRepositories`, filters, visibility, and severity;
|
|
349
390
|
5. distinguish “no findings in completed scans” from “complete organization
|
|
350
|
-
coverage
|
|
391
|
+
coverage”; a repository cap is explicitly incomplete coverage even when the
|
|
392
|
+
selected scan status is `OK`.
|
|
351
393
|
|
|
352
394
|
Store reports in a controlled path. Organization results can reveal private
|
|
353
395
|
repository names, workflow paths, branches, source URLs, and security posture.
|
|
354
396
|
|
|
355
|
-
For a long scan, preserve the exact command scope and
|
|
356
|
-
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:
|
|
357
401
|
|
|
358
402
|
```sh
|
|
359
403
|
actions-warden org-scan my-org \
|
|
@@ -367,11 +411,47 @@ actions-warden org-scan my-org \
|
|
|
367
411
|
Do not weaken filters, policy, baseline, or severity merely to make a
|
|
368
412
|
checkpoint compatible. A mismatch is an invocation error and requires a new
|
|
369
413
|
checkpoint. Resume still performs fresh discovery and tree verification; say
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
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
|
|
373
418
|
YAML but retain redacted report evidence, so treat them as sensitive artifacts.
|
|
374
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
|
+
|
|
375
455
|
## Policy and suppression requests
|
|
376
456
|
|
|
377
457
|
If a user asks to “make CI green,” do not automatically:
|