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/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
|
|
@@ -205,11 +309,14 @@ possible; failures that prevent organization discovery throw.
|
|
|
205
309
|
`checkpointPath` explicitly enables atomic checkpoint writes inside `cwd`.
|
|
206
310
|
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
|
-
baseline contents,
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
312
|
+
baseline contents, analysis generation, and rule catalog must match.
|
|
313
|
+
Concurrency, token, and compatible package-version changes are allowed. The
|
|
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
|
|
317
|
+
discovery and tree reads; it reuses only error-free results whose repository,
|
|
318
|
+
default branch, and tree SHA remain unchanged. Checkpoints contain redacted
|
|
319
|
+
report data and revision metadata, never tokens or raw YAML.
|
|
213
320
|
|
|
214
321
|
`onProgress` may be synchronous or asynchronous and is awaited in event order
|
|
215
322
|
at each emission point. A callback error rejects the scan; repository results
|
|
@@ -222,10 +329,13 @@ objects are shallow-frozen and use these `type` values:
|
|
|
222
329
|
| `checkpoint-loaded` | `repositories` |
|
|
223
330
|
| `checkpoint-created` | none |
|
|
224
331
|
| `discovery-started` | `organization` |
|
|
332
|
+
| `discovery-page` | `organization`, `page`, `repositoriesDiscovered`, optional `rateLimitRemaining` |
|
|
225
333
|
| `discovery-completed` | `discovered`, `eligible`, `selected` |
|
|
226
|
-
| `repository-started` | `repository`, `position`, `total` |
|
|
334
|
+
| `repository-started` | `repository`, `position`, `total`, `completed`, `active`, `concurrency` |
|
|
335
|
+
| `repository-phase` | `repository`, `position`, `total`, `completed`, `active`, `concurrency`, `phase` |
|
|
227
336
|
| `request-retry` | optional `repository`, `attempt`, `maxRetries`, `reason`, `delayMs`, optional `status` |
|
|
228
|
-
| `
|
|
337
|
+
| `checkpoint-written` | `repository`, `position`, `total`, `repositories` |
|
|
338
|
+
| `repository-completed` | `repository`, `completed`, `total`, `reused`, `status`, `files`, `findings`, `errors`, `active`, `concurrency` |
|
|
229
339
|
| `scan-completed` | `organization`, `status`, `completed`, `total`, `reused`, `findings`, `errors`, `elapsedMs` |
|
|
230
340
|
|
|
231
341
|
Progress is observational and is not included in the returned result or its
|
|
@@ -238,6 +348,47 @@ object enters an AI context. Implement the same bounded behavior by saving the
|
|
|
238
348
|
rendered report and returning only `status`, `summary`, and the saved path to
|
|
239
349
|
the agent.
|
|
240
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
|
+
|
|
241
392
|
## Renderers
|
|
242
393
|
|
|
243
394
|
Use the matching renderer to obtain the CLI-compatible wire format:
|
|
@@ -272,7 +423,18 @@ Command/render pairs are:
|
|
|
272
423
|
| `scanOrganization` | `renderOrganizationScan` |
|
|
273
424
|
|
|
274
425
|
Lower-level formatters are also exported: `format`, `renderToon`, `renderJson`,
|
|
275
|
-
`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.
|
|
276
438
|
|
|
277
439
|
Every renderer applies credential redaction. See [output contracts](./OUTPUTS.md)
|
|
278
440
|
before depending on the serialized structure.
|
|
@@ -298,12 +460,16 @@ import {
|
|
|
298
460
|
Additional exports include baseline helpers, organization GitHub readers
|
|
299
461
|
(`listOrganizationRepositories`, `fetchRepositoryWorkflowTree`, and
|
|
300
462
|
`fetchRepositoryWorkflows`), redaction, the live rule catalog, and organization
|
|
301
|
-
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
|
|
302
467
|
`fetchRepositoryWorkflows` to avoid a duplicate tree request. See
|
|
303
468
|
[src/index.js](../src/index.js) for the exact export list in the checked-out
|
|
304
469
|
version.
|
|
305
470
|
|
|
306
|
-
|
|
471
|
+
The [package entry-point table](#package-entry-points) is exhaustive. Example
|
|
472
|
+
subpath imports:
|
|
307
473
|
|
|
308
474
|
```js
|
|
309
475
|
import { audit } from 'actions-warden/commands/audit';
|