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/JAVASCRIPT-API.md
CHANGED
|
@@ -32,6 +32,76 @@ const { audit } = await import('actions-warden');
|
|
|
32
32
|
The raw API result does not include `schemaVersion`; renderers add the versioned
|
|
33
33
|
wire format.
|
|
34
34
|
|
|
35
|
+
## Complete root export reference
|
|
36
|
+
|
|
37
|
+
The package root deliberately exposes a finite public surface. Every export is
|
|
38
|
+
listed here; adding an export without a non-empty reference entry fails
|
|
39
|
+
`npm run check:docs`.
|
|
40
|
+
|
|
41
|
+
| export | category | contract |
|
|
42
|
+
|---|---|---|
|
|
43
|
+
| `audit` | command | Audit discovered or selected local workflow files |
|
|
44
|
+
| `auditSources` | command | Audit caller-supplied YAML sources entirely in memory |
|
|
45
|
+
| `renderAudit` | renderer | Serialize an audit result in a supported output format |
|
|
46
|
+
| `pin` | command | Plan or explicitly apply immutable SHA pins |
|
|
47
|
+
| `renderPin` | renderer | Serialize a pin result in a supported output format |
|
|
48
|
+
| `rewriteUses` | rewrite utility | Return source with one parsed action reference rewritten to a SHA |
|
|
49
|
+
| `upgrade` | command | Plan or explicitly apply cooldown-aware dependency upgrades |
|
|
50
|
+
| `renderUpgrade` | renderer | Serialize an upgrade result in a supported output format |
|
|
51
|
+
| `report` | command | Combine audit, dry-run pin, and dry-run upgrade results |
|
|
52
|
+
| `renderReport` | renderer | Serialize a combined report result |
|
|
53
|
+
| `verify` | command | Verify SHA ownership and version metadata against GitHub |
|
|
54
|
+
| `renderVerify` | renderer | Serialize a verification result |
|
|
55
|
+
| `scanOrganization` | command | Audit eligible organization repositories through read-only GitHub APIs |
|
|
56
|
+
| `renderOrganizationScan` | renderer | Serialize an organization scan result |
|
|
57
|
+
| `compareOrganizationReports` | comparison | Classify new, resolved, unchanged, and unknown findings across compatible organization reports |
|
|
58
|
+
| `loadOrganizationReport` | comparison | Safely load and validate a bounded organization JSON report inside the working directory |
|
|
59
|
+
| `listRules` | rule catalog | Return the live rule IDs, default severities, and descriptions |
|
|
60
|
+
| `parseWorkflowFile` | parser | Read and parse one workflow or composite-action YAML file |
|
|
61
|
+
| `parseWorkflowSource` | parser | Parse one supplied YAML string without executing it |
|
|
62
|
+
| `collectUses` | parser utility | Return external, reusable, local, and Docker action references from a parsed document |
|
|
63
|
+
| `collectImages` | parser utility | Return job, service, and Docker-action image references from a parsed document |
|
|
64
|
+
| `parseActionRef` | parser utility | Classify one `uses` scalar while preserving source location metadata |
|
|
65
|
+
| `format` | formatter | Dispatch records to TOON, JSON, text, CSV, SARIF, or HTML rendering |
|
|
66
|
+
| `renderToon` | formatter | Render line-oriented TOON records |
|
|
67
|
+
| `renderJson` | formatter | Render recursively redacted, indented JSON |
|
|
68
|
+
| `renderText` | formatter | Render escaped human-readable records |
|
|
69
|
+
| `renderCsv` | formatter | Render deterministic, control-safe, spreadsheet-safe CSV records |
|
|
70
|
+
| `renderSarif` | formatter | Render SARIF 2.1.0 results |
|
|
71
|
+
| `renderHtml` | formatter | Render a deterministic, self-contained, searchable HTML report |
|
|
72
|
+
| `summarize` | formatter utility | Count findings by severity |
|
|
73
|
+
| `SEVERITY_ORDER` | constant | Lowest-to-highest severity ordering |
|
|
74
|
+
| `discoverWorkflows` | discovery | Discover default or caller-selected workflow paths inside a repository |
|
|
75
|
+
| `redact` | security utility | Replace credential-like substrings in one value |
|
|
76
|
+
| `parseIgnoreDirectives` | ignore utility | Parse line, block, next-line, and file ignore directives |
|
|
77
|
+
| `isIgnored` | ignore utility | Test whether a rule occurrence is inside an ignore scope |
|
|
78
|
+
| `loadConfig` | policy | Discover, load, and strictly normalize repository policy |
|
|
79
|
+
| `DEFAULT_CONFIG` | policy constant | Normalized built-in policy used when no config file is active |
|
|
80
|
+
| `listOrganizationRepositories` | GitHub reader | List every organization repository visible to the supplied token |
|
|
81
|
+
| `fetchRepositoryWorkflowTree` | GitHub reader | Fetch and validate a default-branch workflow tree snapshot |
|
|
82
|
+
| `fetchRepositoryWorkflows` | GitHub reader | Fetch bounded workflow YAML blobs from a validated tree |
|
|
83
|
+
| `isWorkflowPath` | GitHub reader utility | Test whether a Git tree path is in remote workflow discovery scope |
|
|
84
|
+
| `MAX_WORKFLOW_BYTES` | limit | Maximum decoded bytes accepted for one remote YAML file |
|
|
85
|
+
| `MAX_WORKFLOW_FILES` | limit | Maximum remote workflow files accepted per repository |
|
|
86
|
+
| `MAX_REPOSITORY_WORKFLOW_BYTES` | limit | Maximum cumulative decoded YAML bytes accepted per repository |
|
|
87
|
+
| `loadBaseline` | baseline | Load and validate accepted finding IDs and fingerprints |
|
|
88
|
+
| `serializeBaseline` | baseline | Serialize reviewed findings deterministically, excluding parser failures |
|
|
89
|
+
| `assignBaselineFingerprints` | baseline | Attach stable semantic fingerprints to finding objects |
|
|
90
|
+
|
|
91
|
+
## Package entry points
|
|
92
|
+
|
|
93
|
+
The command modules are also available as explicit package subpaths. Each
|
|
94
|
+
subpath exposes the exports declared by its referenced command module.
|
|
95
|
+
|
|
96
|
+
| entry point | primary exports |
|
|
97
|
+
|---|---|
|
|
98
|
+
| `actions-warden/commands/audit` | `audit`, `auditSources`, `renderAudit` |
|
|
99
|
+
| `actions-warden/commands/pin` | `pin`, `renderPin`, `rewriteUses` |
|
|
100
|
+
| `actions-warden/commands/upgrade` | `upgrade`, `renderUpgrade` |
|
|
101
|
+
| `actions-warden/commands/report` | `report`, `renderReport` |
|
|
102
|
+
| `actions-warden/commands/verify` | `verify`, `renderVerify` |
|
|
103
|
+
| `actions-warden/commands/org-scan` | `scanOrganization`, `renderOrganizationScan` |
|
|
104
|
+
|
|
35
105
|
## Command functions
|
|
36
106
|
|
|
37
107
|
### `audit(options)`
|
|
@@ -93,6 +163,30 @@ does not execute supplied YAML.
|
|
|
93
163
|
When passing a custom config, use the normalized shape returned by `loadConfig`,
|
|
94
164
|
not raw YAML keys.
|
|
95
165
|
|
|
166
|
+
#### Embedding in a broader repository scanner
|
|
167
|
+
|
|
168
|
+
If a caller already owns GitHub discovery and has downloaded a bounded,
|
|
169
|
+
revision-identified evidence snapshot, call `auditSources` for the workflow
|
|
170
|
+
files in that snapshot. Do not also call `scanOrganization` for the same
|
|
171
|
+
repositories: two independent discovery passes can consume extra API quota and
|
|
172
|
+
can observe different tree revisions.
|
|
173
|
+
|
|
174
|
+
The ownership boundary is:
|
|
175
|
+
|
|
176
|
+
- the embedding scanner owns authentication, organization inventory, Git tree
|
|
177
|
+
completeness, blob-size limits, snapshot identity, cache/checkpoint policy,
|
|
178
|
+
non-workflow checks, and aggregate reporting;
|
|
179
|
+
- actions-warden owns YAML parsing, ignore-directive behavior, finding
|
|
180
|
+
identity, severity/baseline filtering, and the complete rule catalog returned
|
|
181
|
+
by `listRules()`;
|
|
182
|
+
- repository source remains data: neither side should import or execute it.
|
|
183
|
+
|
|
184
|
+
Pass unique paths rooted under one stable virtual `cwd` so finding IDs and
|
|
185
|
+
relative paths remain deterministic. Cache identity must include the exact
|
|
186
|
+
actions-warden version and live rule catalog, in addition to the repository
|
|
187
|
+
revision and caller policy. A rule upgrade must not reuse results from a prior
|
|
188
|
+
catalog.
|
|
189
|
+
|
|
96
190
|
### `pin(options)`
|
|
97
191
|
|
|
98
192
|
```js
|
|
@@ -184,7 +278,9 @@ Returns:
|
|
|
184
278
|
```js
|
|
185
279
|
{
|
|
186
280
|
organization,
|
|
281
|
+
analysis,
|
|
187
282
|
scope,
|
|
283
|
+
coverage,
|
|
188
284
|
repositories,
|
|
189
285
|
findings,
|
|
190
286
|
errors,
|
|
@@ -196,7 +292,15 @@ Returns:
|
|
|
196
292
|
```
|
|
197
293
|
|
|
198
294
|
`findings` and `errors` are flattened for ingestion. `repositories` retains
|
|
199
|
-
per-repository identity, revision
|
|
295
|
+
per-repository identity, revision (`branch`, `treeSha`, and `commitSha`), `files`,
|
|
296
|
+
`fileDetails` (one entry per selected workflow file, with its blob SHA, size,
|
|
297
|
+
status, finding count, and permalink), findings, errors, summary, and status.
|
|
298
|
+
Each finding also carries `path`, `blobSha`, and `permalink`.
|
|
299
|
+
`analysis` contains a compatibility generation and stable public identity that
|
|
300
|
+
covers scan scope, policy, baseline contents, and the rule catalog.
|
|
301
|
+
`coverage` distinguishes successful coverage of selected repositories from
|
|
302
|
+
complete coverage of every eligible repository; `maxRepositories` can make it
|
|
303
|
+
incomplete without changing an otherwise clean selected result to `FAIL`.
|
|
200
304
|
|
|
201
305
|
The organization scan is read-only and does not clone, check out, execute, or
|
|
202
306
|
persist raw remote workflow sources. Repository failures are accumulated when
|
|
@@ -207,8 +311,9 @@ Set `resume: true` to require, validate, and update an existing checkpoint at
|
|
|
207
311
|
that path. The organization, selection and audit options, normalized policy,
|
|
208
312
|
baseline contents, analysis generation, and rule catalog must match.
|
|
209
313
|
Concurrency, token, and compatible package-version changes are allowed. The
|
|
210
|
-
producing package version remains metadata
|
|
211
|
-
|
|
314
|
+
producing package version remains metadata that the next checkpoint write
|
|
315
|
+
refreshes. Only the current checkpoint schema is accepted; checkpoints hold
|
|
316
|
+
file details but neither commits nor links, which each run rebuilds. Resume performs fresh
|
|
212
317
|
discovery and tree reads; it reuses only error-free results whose repository,
|
|
213
318
|
default branch, and tree SHA remain unchanged. Checkpoints contain redacted
|
|
214
319
|
report data and revision metadata, never tokens or raw YAML.
|
|
@@ -224,10 +329,13 @@ objects are shallow-frozen and use these `type` values:
|
|
|
224
329
|
| `checkpoint-loaded` | `repositories` |
|
|
225
330
|
| `checkpoint-created` | none |
|
|
226
331
|
| `discovery-started` | `organization` |
|
|
332
|
+
| `discovery-page` | `organization`, `page`, `repositoriesDiscovered`, optional `rateLimitRemaining` |
|
|
227
333
|
| `discovery-completed` | `discovered`, `eligible`, `selected` |
|
|
228
|
-
| `repository-started` | `repository`, `position`, `total` |
|
|
334
|
+
| `repository-started` | `repository`, `position`, `total`, `completed`, `active`, `concurrency` |
|
|
335
|
+
| `repository-phase` | `repository`, `position`, `total`, `completed`, `active`, `concurrency`, `phase` |
|
|
229
336
|
| `request-retry` | optional `repository`, `attempt`, `maxRetries`, `reason`, `delayMs`, optional `status` |
|
|
230
|
-
| `
|
|
337
|
+
| `checkpoint-written` | `repository`, `position`, `total`, `repositories` |
|
|
338
|
+
| `repository-completed` | `repository`, `completed`, `total`, `reused`, `status`, `files`, `findings`, `errors`, `active`, `concurrency` |
|
|
231
339
|
| `scan-completed` | `organization`, `status`, `completed`, `total`, `reused`, `findings`, `errors`, `elapsedMs` |
|
|
232
340
|
|
|
233
341
|
Progress is observational and is not included in the returned result or its
|
|
@@ -240,6 +348,47 @@ object enters an AI context. Implement the same bounded behavior by saving the
|
|
|
240
348
|
rendered report and returning only `status`, `summary`, and the saved path to
|
|
241
349
|
the agent.
|
|
242
350
|
|
|
351
|
+
### Comparing organization reports
|
|
352
|
+
|
|
353
|
+
Load a prior JSON report, create the current JSON contract, and compare their
|
|
354
|
+
semantic finding fingerprints:
|
|
355
|
+
|
|
356
|
+
```js
|
|
357
|
+
import {
|
|
358
|
+
compareOrganizationReports,
|
|
359
|
+
loadOrganizationReport,
|
|
360
|
+
renderOrganizationScan,
|
|
361
|
+
scanOrganization,
|
|
362
|
+
} from 'actions-warden';
|
|
363
|
+
|
|
364
|
+
const previous = await loadOrganizationReport({
|
|
365
|
+
path: 'reports/org.previous.json',
|
|
366
|
+
cwd: '/repo',
|
|
367
|
+
});
|
|
368
|
+
const currentResult = await scanOrganization({
|
|
369
|
+
organization: 'my-org',
|
|
370
|
+
cwd: '/repo',
|
|
371
|
+
token: process.env.GITHUB_TOKEN,
|
|
372
|
+
severity: 'high',
|
|
373
|
+
});
|
|
374
|
+
const current = JSON.parse(renderOrganizationScan(currentResult, {
|
|
375
|
+
format: 'json',
|
|
376
|
+
cwd: '/repo',
|
|
377
|
+
}));
|
|
378
|
+
const comparison = compareOrganizationReports({ previous, current });
|
|
379
|
+
const html = renderOrganizationScan(currentResult, {
|
|
380
|
+
format: 'html',
|
|
381
|
+
cwd: '/repo',
|
|
382
|
+
comparison,
|
|
383
|
+
});
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
Comparison requires matching analysis identities. It returns deterministically
|
|
387
|
+
ordered `new`, `resolved`, `unchanged`, and `unknown` finding arrays. A prior
|
|
388
|
+
finding is resolved only when the current report successfully covered that
|
|
389
|
+
repository without parse failures; missing, failed, or unparseable repositories
|
|
390
|
+
make resolution unknown.
|
|
391
|
+
|
|
243
392
|
## Renderers
|
|
244
393
|
|
|
245
394
|
Use the matching renderer to obtain the CLI-compatible wire format:
|
|
@@ -274,7 +423,18 @@ Command/render pairs are:
|
|
|
274
423
|
| `scanOrganization` | `renderOrganizationScan` |
|
|
275
424
|
|
|
276
425
|
Lower-level formatters are also exported: `format`, `renderToon`, `renderJson`,
|
|
277
|
-
`renderText`, `renderSarif`, `summarize`, and
|
|
426
|
+
`renderText`, `renderCsv`, `renderSarif`, `renderHtml`, `summarize`, and
|
|
427
|
+
`SEVERITY_ORDER`.
|
|
428
|
+
|
|
429
|
+
`renderCsv(records, options)` accepts labeled records plus optional `status`.
|
|
430
|
+
It emits a deterministic union header, one physical row per record, and a final
|
|
431
|
+
status row. Nested values become compact JSON cells, control characters are
|
|
432
|
+
escaped, formula-like strings are neutralized, and credentials are redacted.
|
|
433
|
+
|
|
434
|
+
`renderHtml(records, options)` accepts the same labeled records used by TOON
|
|
435
|
+
and text plus optional `status`, `title`, and `metadata`. It redacts and escapes
|
|
436
|
+
dynamic values, permits only HTTPS links, loads no external assets, and rejects
|
|
437
|
+
documents larger than 32 MiB.
|
|
278
438
|
|
|
279
439
|
Every renderer applies credential redaction. See [output contracts](./OUTPUTS.md)
|
|
280
440
|
before depending on the serialized structure.
|
|
@@ -300,12 +460,16 @@ import {
|
|
|
300
460
|
Additional exports include baseline helpers, organization GitHub readers
|
|
301
461
|
(`listOrganizationRepositories`, `fetchRepositoryWorkflowTree`, and
|
|
302
462
|
`fetchRepositoryWorkflows`), redaction, the live rule catalog, and organization
|
|
303
|
-
size limits.
|
|
463
|
+
size limits. `fetchRepositoryWorkflowTree` resolves the default-branch commit
|
|
464
|
+
first and reads the tree by its tree SHA; the snapshot carries `commitSha`, and
|
|
465
|
+
`fetchRepositoryWorkflows` also returns per-file `entries`. A validated
|
|
466
|
+
workflow-tree snapshot can be supplied to
|
|
304
467
|
`fetchRepositoryWorkflows` to avoid a duplicate tree request. See
|
|
305
468
|
[src/index.js](../src/index.js) for the exact export list in the checked-out
|
|
306
469
|
version.
|
|
307
470
|
|
|
308
|
-
|
|
471
|
+
The [package entry-point table](#package-entry-points) is exhaustive. Example
|
|
472
|
+
subpath imports:
|
|
309
473
|
|
|
310
474
|
```js
|
|
311
475
|
import { audit } from 'actions-warden/commands/audit';
|