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/AGENTS.md
CHANGED
|
@@ -34,7 +34,8 @@ network behavior, deterministic output, and no-remote-code-execution model.
|
|
|
34
34
|
- Begin with read-only inspection. Preserve unrelated user changes in a dirty
|
|
35
35
|
worktree.
|
|
36
36
|
- Use `rg` or `rg --files` for discovery.
|
|
37
|
-
-
|
|
37
|
+
- Make hand edits with your editor's patch or edit tool, not by regenerating
|
|
38
|
+
whole files.
|
|
38
39
|
- Do not add `--write`, change policy, create a baseline, suppress a finding,
|
|
39
40
|
or broaden a GitHub organization scan without explicit authorization.
|
|
40
41
|
- Do not print tokens. Prefer `GITHUB_TOKEN` or `GH_TOKEN` over a CLI token.
|
|
@@ -54,25 +55,39 @@ out of the model transcript by default:
|
|
|
54
55
|
actions-warden org-scan ORG --agent-mode
|
|
55
56
|
```
|
|
56
57
|
|
|
57
|
-
-
|
|
58
|
-
checkpoint
|
|
58
|
+
- Every organization scan defaults to JSON file output, a guarded scope-keyed
|
|
59
|
+
checkpoint, compatible automatic resume, and a bounded JSON receipt. This is
|
|
60
|
+
the fallback even if a caller forgets agent mode.
|
|
61
|
+
- `--agent-mode` additionally disables implicit progress and selects the agent
|
|
62
|
+
receipt kind. It shares `.actions-warden-org-scan.*` artifacts with normal
|
|
63
|
+
execution so a context switch retains compatible resume state. The packaged
|
|
59
64
|
skill should pass the flag; an integration may instead set
|
|
60
|
-
`
|
|
61
|
-
- Automatic artifact names are derived from the
|
|
62
|
-
An exact-scope later run resumes its checkpoint
|
|
63
|
-
|
|
64
|
-
|
|
65
|
+
`ACTIONS_WARDEN_CONTEXT=agent` once.
|
|
66
|
+
- Automatic artifact names are derived from the checkpoint compatibility
|
|
67
|
+
identity. An exact-scope later run resumes its checkpoint across compatible
|
|
68
|
+
package versions; a changed filter, severity, policy, baseline, analysis
|
|
69
|
+
generation, or rule catalog receives a different path. Compatibility
|
|
70
|
+
validation still fails closed.
|
|
65
71
|
- Preserve the scope the user requested. Reducing LLM context use is not
|
|
66
72
|
permission to omit repositories, severities, findings, or errors.
|
|
67
73
|
- Explicit CLI choices override agent defaults. If the user asks to watch live
|
|
68
|
-
progress, add `--progress=
|
|
74
|
+
progress, add `--progress=plain`; use `--progress=json` only when the caller
|
|
75
|
+
will parse JSON Lines. The report path from the receipt, rather
|
|
69
76
|
than stdout or progress lines, is the complete evidence contract.
|
|
77
|
+
- Repeat the same command to resume. An explicit `--checkpoint` also resumes
|
|
78
|
+
when its file exists; use `--fresh` to replace state, `--resume` when a
|
|
79
|
+
restored file must exist, and `--no-auto-checkpoint` only for an intentional
|
|
80
|
+
stateless scan.
|
|
70
81
|
- Omit `--explain` on a broad first pass unless remediation prose was
|
|
71
82
|
requested. Add it to a targeted follow-up when needed.
|
|
72
83
|
- Inspect the saved JSON locally in bounded passes: first `status`, `scope`,
|
|
73
84
|
`summary`, and error counts; then error details and severity/rule aggregates;
|
|
74
85
|
finally only the finding batches needed for the task. Do not paste or read an
|
|
75
86
|
unbounded organization report into model context.
|
|
87
|
+
- For a broad report that will be inspected repository by repository, prefer
|
|
88
|
+
`--report-dir=<dedicated-directory>`. Read its compact aggregate and manifest
|
|
89
|
+
first, then only the relevant complete repository artifacts. The manifest is
|
|
90
|
+
authoritative; this layout bounds downstream reads, not scanner memory.
|
|
76
91
|
- The scanner process itself uses GitHub API quota and local compute; it does
|
|
77
92
|
not call a language model. The surrounding agent still uses inference tokens
|
|
78
93
|
to plan, monitor, and summarize, and large command output or report excerpts
|
|
@@ -112,8 +127,13 @@ deprecating a package. A release request does not authorize those actions.
|
|
|
112
127
|
## Non-negotiable invariants
|
|
113
128
|
|
|
114
129
|
- `pin` and `upgrade` are dry-run by default.
|
|
130
|
+
- CLI usage errors return `2`; numeric limits and change IDs are parsed
|
|
131
|
+
strictly, and contradictory flags fail before command work begins.
|
|
115
132
|
- Writes remain within the real repository root, reject symlink escapes, are
|
|
116
133
|
atomic, preserve permissions, and reparse modified YAML.
|
|
134
|
+
- CLI report, baseline, and checkpoint destinations are preflighted before
|
|
135
|
+
network or workflow mutation and cannot replace workflow or policy-control
|
|
136
|
+
files.
|
|
117
137
|
- GitHub ref resolution and commit ownership fail closed.
|
|
118
138
|
- Credentials are redacted in every format, annotation, and top-level error.
|
|
119
139
|
- Finding IDs are clone-independent; pin findings and plans share an ID.
|
|
@@ -121,9 +141,22 @@ deprecating a package. A release request does not authorize those actions.
|
|
|
121
141
|
- Organization scans never clone, check out, import, or execute remote code.
|
|
122
142
|
- Incomplete organization coverage produces visible errors and status `FAIL`.
|
|
123
143
|
- Organization resume requires fresh discovery and matching default-branch tree
|
|
124
|
-
SHAs; never reuse failed results. Checkpoints remain guarded,
|
|
125
|
-
of tokens
|
|
144
|
+
SHAs; never reuse failed results or parse errors. Checkpoints remain guarded,
|
|
145
|
+
atomic, and free of tokens, raw YAML, commits, and links; each run rebuilds
|
|
146
|
+
permalinks and `revision.commitSha` from the live default-branch commit.
|
|
147
|
+
- Organization ref resolution is pinned: the default-branch commit is resolved
|
|
148
|
+
first, the tree is read by that commit's tree SHA and must match it, and
|
|
149
|
+
permalinks point at that commit. Only an HTTP 409 on the commit request means
|
|
150
|
+
an empty repository; every other non-200 is a repository error.
|
|
151
|
+
- `ORGANIZATION_ANALYSIS_GENERATION` is the organization-result compatibility
|
|
152
|
+
boundary. Increment it whenever discovery, parser, finding identity, rule
|
|
153
|
+
evaluation, or persisted result semantics can change; do not increment it
|
|
154
|
+
for a version-only compatible release.
|
|
126
155
|
- CLI progress stays on stderr and never corrupts structured report stdout.
|
|
156
|
+
- Organization CLI and Action defaults keep complete reports in guarded files,
|
|
157
|
+
generate scope-keyed checkpoint state, and automatically resume only after
|
|
158
|
+
the full compatibility and fresh-revision checks pass. Explicit stdout,
|
|
159
|
+
fresh, and checkpoint opt-outs remain available.
|
|
127
160
|
- Attacker-controlled text cannot forge output records or workflow commands.
|
|
128
161
|
|
|
129
162
|
## Validate proportionally
|
|
@@ -142,6 +175,21 @@ npm run check:docs
|
|
|
142
175
|
npm run check:yaml
|
|
143
176
|
```
|
|
144
177
|
|
|
178
|
+
`check:docs` must report 100% coverage. It derives the inventory from package
|
|
179
|
+
exports, live CLI help, Action metadata, the rule catalog, focused guides, and
|
|
180
|
+
examples; every exported runtime function/class and package-root export also
|
|
181
|
+
requires direct JSDoc. Do not bypass the check with a stale manual allowlist.
|
|
182
|
+
|
|
183
|
+
HTML reporting changes must preserve redaction, escaping, the no-external-asset
|
|
184
|
+
content security policy, safe HTTPS links, deterministic bytes, and the report
|
|
185
|
+
size bound. Organization comparison must never classify an unmatched prior
|
|
186
|
+
finding as resolved when the current repository is missing or has a coverage
|
|
187
|
+
error; analysis identity mismatches fail closed.
|
|
188
|
+
|
|
189
|
+
CSV reporting changes must preserve deterministic columns, CRLF records,
|
|
190
|
+
credential redaction, control-character escaping, spreadsheet-formula
|
|
191
|
+
neutralization, one physical line per record, and the explicit status row.
|
|
192
|
+
|
|
145
193
|
For dependency or version metadata:
|
|
146
194
|
|
|
147
195
|
```sh
|
|
@@ -179,7 +227,7 @@ relevant surfaces:
|
|
|
179
227
|
2. CLI and exit semantics;
|
|
180
228
|
3. package exports;
|
|
181
229
|
4. Action adapter and `action.yml`;
|
|
182
|
-
5. annotations and all
|
|
230
|
+
5. annotations and all supported formats;
|
|
183
231
|
6. tests;
|
|
184
232
|
7. CLI, output, Action, API, and AI documentation;
|
|
185
233
|
8. Claude skill;
|
package/CONTRIBUTING.md
CHANGED
|
@@ -58,6 +58,7 @@ npm run verify-deps
|
|
|
58
58
|
npm run check:yaml
|
|
59
59
|
npm run check:docs
|
|
60
60
|
npm run lint
|
|
61
|
+
npm run typecheck
|
|
61
62
|
npm test
|
|
62
63
|
npm run audit
|
|
63
64
|
```
|
|
@@ -75,11 +76,14 @@ responses and use temporary directories for filesystem cases.
|
|
|
75
76
|
## Documentation expectations
|
|
76
77
|
|
|
77
78
|
Behavior changes are incomplete until their user and integration contracts are
|
|
78
|
-
updated.
|
|
79
|
+
updated. `npm run check:docs` enforces 100% coverage across exported runtime
|
|
80
|
+
function/class comments, public JavaScript exports, package entry points, CLI
|
|
81
|
+
commands/options, Action inputs/outputs, rules, guide indexing, and example
|
|
82
|
+
reachability.
|
|
79
83
|
|
|
80
84
|
- CLI flags and semantics: `docs/CLI.md`
|
|
81
85
|
- policy or rule behavior: `docs/CONFIGURATION.md`
|
|
82
|
-
- records, JSON, SARIF, status, or exit codes: `docs/OUTPUTS.md`
|
|
86
|
+
- records, JSON, CSV, SARIF, HTML, comparison, status, or exit codes: `docs/OUTPUTS.md`
|
|
83
87
|
- Action inputs and outputs: `docs/GITHUB-ACTION.md` and `action.yml`
|
|
84
88
|
- public exports: `docs/JAVASCRIPT-API.md`
|
|
85
89
|
- agent workflows: `docs/AI-AGENTS.md` and the Claude skill
|
package/README.md
CHANGED
|
@@ -8,79 +8,108 @@
|
|
|
8
8
|
[](https://www.npmjs.com/package/actions-warden)
|
|
9
9
|
[](./LICENSE)
|
|
10
10
|
|
|
11
|
-
Audit GitHub Actions in
|
|
11
|
+
Audit GitHub Actions in a single repository or across an entire organization, then
|
|
12
12
|
pin, verify, and safely upgrade workflow dependencies.
|
|
13
13
|
|
|
14
14
|
`actions-warden` is available as a CLI, a bundled GitHub Action, and a
|
|
15
|
-
JavaScript API. It finds supply-chain
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
JavaScript API. It finds supply-chain risks, excessive permissions, script
|
|
16
|
+
injections, cross-run artifact executions, secret leaks, unpinned container
|
|
17
|
+
images, and privileged container settings without ever executing the
|
|
18
|
+
workflows it inspects.
|
|
19
|
+
|
|
20
|
+
### Why do you need this?
|
|
21
|
+
|
|
22
|
+
In GitHub Actions, most workflows reference third-party actions using version tags,
|
|
23
|
+
such as `uses: actions/checkout@v4`.
|
|
24
|
+
|
|
25
|
+
However, Git tags are mutable—anyone with write access to an action's repository
|
|
26
|
+
can change what `@v4` points to at any time. If an action maintainer's account is
|
|
27
|
+
compromised, an attacker can secretly push malicious code under the existing `@v4`
|
|
28
|
+
tag, and your next build or deployment pipeline will execute it automatically.
|
|
29
|
+
|
|
30
|
+
At the same time, common workflow mistakes like granting `permissions: write-all`
|
|
31
|
+
or directly interpolating untrusted input (such as pull request titles or comments)
|
|
32
|
+
into `run:` scripts can expose your production secrets or give attackers shell access.
|
|
33
|
+
|
|
34
|
+
`actions-warden` protects your pipelines with a clean, safety-first approach:
|
|
35
|
+
- **Catches risks early**: Audits your workflow YAML for vulnerabilities and gives plain-English remediation advice.
|
|
36
|
+
- **Locks dependencies permanently**: Pins external actions to immutable 40-character commit SHAs while preserving the original version in a helpful comment (e.g. `uses: actions/checkout@08c6903... # actions-warden-ref: v4.0.0`).
|
|
37
|
+
- **Safe by default**: Operates as a dry-run preview; it never modifies your workflow files unless you explicitly add `--write` to `pin` or `upgrade` (reports, baselines, and organization checkpoints are written only when their options or automatic artifacts are enabled).
|
|
38
|
+
- **Zero remote code execution**: Inspects workflow files in memory; it never clones repositories or runs untrusted scripts.
|
|
39
|
+
|
|
40
|
+
---
|
|
18
41
|
|
|
19
42
|
## Start here
|
|
20
43
|
|
|
21
44
|
| I want to… | Start with |
|
|
22
45
|
|---|---|
|
|
23
|
-
| Check this repository | `actions-warden audit --explain` |
|
|
46
|
+
| Check this repository for security issues | `actions-warden audit --explain` |
|
|
24
47
|
| See every proposed security and dependency change | `actions-warden report` |
|
|
25
|
-
| Scan
|
|
26
|
-
| Pin mutable action refs | `actions-warden pin`, review, then add `--write` |
|
|
27
|
-
| Verify existing
|
|
28
|
-
| Upgrade pinned actions | `actions-warden upgrade`, review, then add `--write` |
|
|
29
|
-
| Run in GitHub Actions | [GitHub Action guide](./docs/GITHUB-ACTION.md) |
|
|
30
|
-
| Integrate from
|
|
31
|
-
| Use it
|
|
32
|
-
| Contribute | [Contributing guide](./CONTRIBUTING.md) |
|
|
48
|
+
| Scan an entire GitHub organization | `actions-warden org-scan ORG` |
|
|
49
|
+
| Pin mutable action refs to immutable commit SHAs | `actions-warden pin`, review, then add `--write` |
|
|
50
|
+
| Verify that existing commit SHAs belong to the repo | `actions-warden verify` |
|
|
51
|
+
| Upgrade pinned actions with cooldown protection | `actions-warden upgrade`, review, then add `--write` |
|
|
52
|
+
| Run security checks in GitHub Actions CI | [GitHub Action guide](./docs/GITHUB-ACTION.md) |
|
|
53
|
+
| Integrate from Node.js or scripts | [JavaScript API](./docs/JAVASCRIPT-API.md) |
|
|
54
|
+
| Use it with AI coding agents (Claude, Copilot, etc.) | [AI and agent guide](./docs/AI-AGENTS.md) |
|
|
55
|
+
| Contribute to actions-warden | [Contributing guide](./CONTRIBUTING.md) |
|
|
56
|
+
|
|
57
|
+
---
|
|
33
58
|
|
|
34
59
|
## Quick start
|
|
35
60
|
|
|
36
61
|
Node.js 20 or newer is required.
|
|
37
62
|
|
|
63
|
+
### 1. Install actions-warden
|
|
64
|
+
|
|
65
|
+
You can install it globally, or run it directly without installing using `npx`:
|
|
66
|
+
|
|
38
67
|
```sh
|
|
39
68
|
npm install --global actions-warden
|
|
40
69
|
|
|
41
|
-
#
|
|
42
|
-
actions-warden audit --explain
|
|
70
|
+
# Or use npx for a quick one-off run without installing:
|
|
71
|
+
npx --yes actions-warden@0.6.0 audit --explain
|
|
72
|
+
```
|
|
43
73
|
|
|
44
|
-
|
|
45
|
-
|
|
74
|
+
### 2. Follow the 3-step security workflow
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
# Step 1: Audit your workflows (completely local and read-only)
|
|
78
|
+
actions-warden audit --explain
|
|
46
79
|
|
|
47
|
-
# Preview
|
|
80
|
+
# Step 2: Preview how mutable tags will be pinned (safe preview; no files are modified)
|
|
48
81
|
actions-warden pin
|
|
49
82
|
|
|
50
|
-
#
|
|
83
|
+
# Step 3: Review the plan, then apply the changes to your workflow files
|
|
51
84
|
actions-warden pin --write
|
|
52
85
|
|
|
53
|
-
# Confirm
|
|
86
|
+
# Bonus: Confirm that all pinned commit SHAs truly belong to their GitHub repositories
|
|
54
87
|
actions-warden verify
|
|
55
88
|
```
|
|
56
89
|
|
|
57
|
-
|
|
90
|
+
> [!NOTE]
|
|
91
|
+
> **Understanding exit codes:**
|
|
92
|
+
> When `audit` detects security issues, it completes with exit code `1`. This is completely normal and means findings were reported—just like a linter or compiler flagging issues in CI. Exit code `0` means no unsuppressed findings were detected at or above the configured severity threshold (accounting for baselines and ignored paths). Exit code `2` indicates an invocation error (such as an invalid argument or conflicting flags). See [outputs and exit behavior](./docs/OUTPUTS.md).
|
|
58
93
|
|
|
59
|
-
|
|
60
|
-
npx --yes actions-warden@0.3.0 audit --explain
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
`audit` returns exit code `1` when it finds issues. That is a completed scan,
|
|
64
|
-
not a malformed command; its JSON, TOON, text, or SARIF output remains the
|
|
65
|
-
report to inspect. Exit code `2` means the command could not be used as
|
|
66
|
-
requested. See [outputs and exit behavior](./docs/OUTPUTS.md).
|
|
94
|
+
---
|
|
67
95
|
|
|
68
96
|
## Scan a GitHub organization
|
|
69
97
|
|
|
70
|
-
Set a token that can see the repositories you intend to scan, then
|
|
71
|
-
versioned JSON report:
|
|
98
|
+
Set a token that can see the repositories you intend to scan, then run:
|
|
72
99
|
|
|
73
100
|
```sh
|
|
74
101
|
export GITHUB_TOKEN="$(gh auth token)"
|
|
75
102
|
|
|
76
103
|
actions-warden org-scan my-org \
|
|
77
|
-
--severity=high
|
|
78
|
-
--checkpoint=.actions-warden-org-checkpoint.json \
|
|
79
|
-
--format=json \
|
|
80
|
-
--output=file \
|
|
81
|
-
--output-path=actions-warden-org.json
|
|
104
|
+
--severity=high
|
|
82
105
|
```
|
|
83
106
|
|
|
107
|
+
Organization scans default to a guarded, scope-keyed JSON report and
|
|
108
|
+
checkpoint under the working directory. Stdout contains only a compact JSON
|
|
109
|
+
receipt with their paths and summary. Running the same command again safely
|
|
110
|
+
resumes compatible repository results. Use `--fresh` to rescan everything or
|
|
111
|
+
`--no-auto-checkpoint` when resumable state is not wanted.
|
|
112
|
+
|
|
84
113
|
The scanner:
|
|
85
114
|
|
|
86
115
|
- paginates every repository visible to the token;
|
|
@@ -88,26 +117,65 @@ The scanner:
|
|
|
88
117
|
- reads workflow and composite-action YAML from each default branch;
|
|
89
118
|
- applies the same rules, policy, and baseline model as a local audit;
|
|
90
119
|
- returns per-repository findings, source links, coverage counts, and errors;
|
|
91
|
-
- checkpoints each completed repository
|
|
120
|
+
- checkpoints each completed repository by default and can safely resume;
|
|
92
121
|
- shows live repository and retry progress on stderr without corrupting reports;
|
|
93
122
|
- never clones, checks out, or executes repository code.
|
|
94
123
|
|
|
95
|
-
Resume an interrupted scan
|
|
124
|
+
Resume an interrupted scan by repeating the same command:
|
|
96
125
|
|
|
97
126
|
```sh
|
|
98
127
|
actions-warden org-scan my-org \
|
|
99
|
-
--severity=high
|
|
100
|
-
--resume=.actions-warden-org-checkpoint.json \
|
|
101
|
-
--format=json \
|
|
102
|
-
--output=file \
|
|
103
|
-
--output-path=actions-warden-org.json
|
|
128
|
+
--severity=high
|
|
104
129
|
```
|
|
105
130
|
|
|
131
|
+
For caller-managed state, `--checkpoint=path` also creates or automatically
|
|
132
|
+
resumes that path. `--resume=path` is the strict form for a restored checkpoint
|
|
133
|
+
that must already exist.
|
|
134
|
+
|
|
106
135
|
Resume still performs fresh organization discovery and checks every selected
|
|
107
136
|
default-branch tree SHA. Only unchanged, error-free repository results are
|
|
108
137
|
reused; changed and previously failed repositories are scanned again. Progress
|
|
109
|
-
defaults to interactive terminals; use `--progress=
|
|
110
|
-
or `--progress=
|
|
138
|
+
defaults to interactive terminals; use `--progress=plain` for redirected logs,
|
|
139
|
+
`--progress=json` for JSON Lines events, or `--progress=none` to disable it.
|
|
140
|
+
|
|
141
|
+
Compatible package upgrades reuse the same checkpoint. The producing package
|
|
142
|
+
version is recorded as metadata, while an explicit analysis generation plus
|
|
143
|
+
the rule catalog controls compatibility. A parser, discovery, or rule behavior
|
|
144
|
+
change advances that generation and requires a fresh scan. The next checkpoint
|
|
145
|
+
write records the current package version.
|
|
146
|
+
|
|
147
|
+
Each repository in an organization report lists every workflow file that was
|
|
148
|
+
inspected, including clean ones, with its blob SHA, size, and status. Findings
|
|
149
|
+
and errors carry a `permalink` pinned to the exact commit that was scanned, so
|
|
150
|
+
a reviewer can open the evidence even after the default branch moves.
|
|
151
|
+
|
|
152
|
+
Compare a fresh scan with a compatible previous JSON report (reports made by
|
|
153
|
+
an earlier release must be regenerated once; they carry no commit or file
|
|
154
|
+
inventory and are refused):
|
|
155
|
+
|
|
156
|
+
```sh
|
|
157
|
+
actions-warden org-scan my-org \
|
|
158
|
+
--severity=high \
|
|
159
|
+
--previous-report=actions-warden-org.previous.json \
|
|
160
|
+
--format=json \
|
|
161
|
+
--output-path=actions-warden-org.current.json
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The comparison reports new, resolved, unchanged, and unknown findings.
|
|
165
|
+
Resolution fails closed: a finding is `unknown`, not `resolved`, when its
|
|
166
|
+
repository disappeared or the current scan could not cover it successfully.
|
|
167
|
+
|
|
168
|
+
For large retained JSON evidence, split the report into a compact aggregate,
|
|
169
|
+
complete per-repository files, and an integrity manifest:
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
actions-warden org-scan my-org \
|
|
173
|
+
--report-dir=reports/actions-warden-org
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
This layout keeps downstream inspection and artifact uploads bounded. The
|
|
177
|
+
manifest is the authoritative current file set; the scanner still builds the
|
|
178
|
+
result in memory before writing the directory.
|
|
111
179
|
|
|
112
180
|
When a coding agent initiates the scan, use the explicit bounded mode:
|
|
113
181
|
|
|
@@ -115,9 +183,12 @@ When a coding agent initiates the scan, use the explicit bounded mode:
|
|
|
115
183
|
actions-warden org-scan my-org --agent-mode
|
|
116
184
|
```
|
|
117
185
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
186
|
+
The regular safe report/checkpoint defaults still apply. Agent mode disables
|
|
187
|
+
implicit progress and uses an agent-specific receipt kind, unless explicit CLI
|
|
188
|
+
options override it. It deliberately shares the normal
|
|
189
|
+
`.actions-warden-org-scan.*` paths, so switching execution context does not
|
|
190
|
+
discard compatible resume state. `ACTIONS_WARDEN_CONTEXT=agent` is the
|
|
191
|
+
preferred integration-wide equivalent.
|
|
121
192
|
|
|
122
193
|
Limit scope with repository globs and visibility:
|
|
123
194
|
|
|
@@ -138,6 +209,17 @@ failed blob read is reported as an error so incomplete coverage cannot appear
|
|
|
138
209
|
clean. See the [organization-scan reference](./docs/CLI.md#org-scan) and the
|
|
139
210
|
[scheduled workflow example](./examples/org-scan.yml).
|
|
140
211
|
|
|
212
|
+
For a self-contained human review artifact, select HTML:
|
|
213
|
+
|
|
214
|
+
```sh
|
|
215
|
+
actions-warden org-scan my-org \
|
|
216
|
+
--format=html \
|
|
217
|
+
--output-path=actions-warden-org.html
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
The offline report includes coverage warnings, summary metrics, rule and
|
|
221
|
+
repository breakdowns, filters, source links, findings, and operational errors.
|
|
222
|
+
|
|
141
223
|
## Safe by default
|
|
142
224
|
|
|
143
225
|
The write boundary is deliberately explicit:
|
|
@@ -150,8 +232,14 @@ audit/report/pin/upgrade plan → review IDs and diffs → --fix=<id> --write
|
|
|
150
232
|
- `pin` and `upgrade` are dry-runs unless `--write` is present.
|
|
151
233
|
- `--write --dry-run` is rejected instead of guessing intent.
|
|
152
234
|
- `--fix=<id>` limits a pin or upgrade to one exact source occurrence.
|
|
235
|
+
- Numeric limits and change IDs are parsed strictly; partial, fractional, and
|
|
236
|
+
imprecise values fail before network or write work begins.
|
|
153
237
|
- Rewrites preserve surrounding YAML and are reparsed before an atomic write.
|
|
154
|
-
-
|
|
238
|
+
- `--output-path` implies file output. Repository commands still require a path
|
|
239
|
+
for file output; `org-scan` generates a safe path when one is omitted.
|
|
240
|
+
- Paths, output files, and symlinks are constrained to the selected repository,
|
|
241
|
+
and report/baseline/checkpoint destinations cannot replace workflows or
|
|
242
|
+
policy controls.
|
|
155
243
|
- Credential-like values are recursively redacted from every output format.
|
|
156
244
|
- Repository policy is strictly validated; unknown keys and rule IDs fail.
|
|
157
245
|
- Remote organization source is kept in memory and is not persisted in cache.
|
|
@@ -245,7 +333,9 @@ actions-warden rules --format=json
|
|
|
245
333
|
| `toon` | Compact terminal and LLM context; the default |
|
|
246
334
|
| `json` | Versioned programmatic integrations |
|
|
247
335
|
| `text` | Human-readable line-oriented logs |
|
|
336
|
+
| `csv` | Spreadsheet, data-warehouse, and compliance exports |
|
|
248
337
|
| `sarif` | Code scanning and SARIF-compatible systems |
|
|
338
|
+
| `html` | Self-contained, searchable human review artifact |
|
|
249
339
|
|
|
250
340
|
TOON output is one labeled record per line:
|
|
251
341
|
|
|
@@ -257,8 +347,11 @@ STATUS: FAIL
|
|
|
257
347
|
```
|
|
258
348
|
|
|
259
349
|
Findings and proposed changes have stable, clone-independent IDs. JSON payloads
|
|
260
|
-
carry `schemaVersion: "1.0"`;
|
|
261
|
-
|
|
350
|
+
carry `schemaVersion: "1.0"`; CSV is deterministic and spreadsheet-safe; SARIF
|
|
351
|
+
is 2.1.0. HTML is deterministic, offline, credential-redacted, and capped at
|
|
352
|
+
32 MiB. See
|
|
353
|
+
[output contracts](./docs/OUTPUTS.md) for schemas, record labels, redaction,
|
|
354
|
+
status, and shell/CI handling.
|
|
262
355
|
|
|
263
356
|
## GitHub Action
|
|
264
357
|
|
|
@@ -291,8 +384,19 @@ jobs:
|
|
|
291
384
|
```
|
|
292
385
|
|
|
293
386
|
The committed bundle runs on GitHub's managed Node 24 runtime and installs no
|
|
294
|
-
consumer-side dependencies. Findings become native annotations and a
|
|
295
|
-
|
|
387
|
+
consumer-side dependencies. Findings become native annotations and a bounded
|
|
388
|
+
structured job summary with severity, rule, remediation, error, and
|
|
389
|
+
organization-coverage and comparison views. Stable numeric outputs expose
|
|
390
|
+
finding, coverage, and comparison counts to later workflow steps, while an
|
|
391
|
+
optional saved JSON, CSV, SARIF, or HTML report retains evidence in the format
|
|
392
|
+
appropriate to its consumer.
|
|
393
|
+
The copyable
|
|
394
|
+
[CI violation-reporting example](./examples/ci-violation-reporting/README.md)
|
|
395
|
+
shows how to retain a JSON artifact before a separate policy gate fails the
|
|
396
|
+
job. CSV export, bounded webhook/ProjectDiscovery Notify delivery,
|
|
397
|
+
baseline-adoption, SARIF, HTML organization, organization-scan, and remediation
|
|
398
|
+
variants are listed in the [examples index](./examples/README.md). See the
|
|
399
|
+
[Action inputs, outputs, permissions, and examples](./docs/GITHUB-ACTION.md).
|
|
296
400
|
|
|
297
401
|
## AI-assisted use
|
|
298
402
|
|
|
@@ -310,10 +414,10 @@ actions-warden audit --format=json
|
|
|
310
414
|
Use JSON when the caller has a parser and TOON when context size matters.
|
|
311
415
|
Agents should treat policy changes, baselines, `--write`, and organization
|
|
312
416
|
tokens as security-sensitive boundaries. For an agent-initiated organization
|
|
313
|
-
scan, use `actions-warden org-scan ORG --agent-mode`.
|
|
314
|
-
scope-keyed report and checkpoint,
|
|
315
|
-
|
|
316
|
-
|
|
417
|
+
scan, use `actions-warden org-scan ORG --agent-mode`. Organization scans already
|
|
418
|
+
write a scope-keyed report and checkpoint, resume compatible state, and return
|
|
419
|
+
a compact receipt; agent mode additionally disables implicit progress while
|
|
420
|
+
retaining the same artifact identity. The agent then reads bounded summaries and relevant finding batches
|
|
317
421
|
instead of placing the full report in model context. This preserves requested
|
|
318
422
|
coverage while controlling LLM token use. The
|
|
319
423
|
[AI and agent guide](./docs/AI-AGENTS.md#default-for-an-ai-initiated-scan)
|
|
@@ -343,7 +447,25 @@ const organization = await scanOrganization({
|
|
|
343
447
|
```
|
|
344
448
|
|
|
345
449
|
See the [JavaScript API guide](./docs/JAVASCRIPT-API.md) for command options,
|
|
346
|
-
result shapes, renderers, lower-level exports,
|
|
450
|
+
result shapes, renderers, lower-level exports, error handling, and the
|
|
451
|
+
`auditSources` ownership boundary for broader organization scanners.
|
|
452
|
+
|
|
453
|
+
## Frequently asked questions (FAQ)
|
|
454
|
+
|
|
455
|
+
#### 1. Why should I pin actions to commit SHAs instead of using tags like `@v4`?
|
|
456
|
+
Git tags like `@v4` or `@main` can be modified or re-pointed by anyone who has write access to that action's repository. If an attacker compromises an action maintainer's account, they can push malicious code under the existing tag without anyone noticing. A 40-character commit SHA (such as `08c6903...`) is permanent and immutable—it can never be altered.
|
|
457
|
+
|
|
458
|
+
#### 2. Will `actions-warden pin` break my YAML comments or indentation?
|
|
459
|
+
No. `actions-warden` uses precise scalar range replacement instead of re-serializing the entire document. Your existing indentation, spacing, and comments are preserved. It also appends an inline comment (e.g. `# actions-warden-ref: v4.0.0`) so you and your team always know which version you are running.
|
|
460
|
+
|
|
461
|
+
#### 3. Do I need a GitHub Token for local audits?
|
|
462
|
+
No. The `audit` command runs completely offline on your computer without any network calls or tokens. Similarly, `report --offline` generates reports locally without network access. You only need a GitHub token for commands that query the GitHub API (`pin`, `verify`, `upgrade`, `org-scan`, and the default network-backed `report`).
|
|
463
|
+
|
|
464
|
+
#### 4. Why did `audit` return exit code 1? Did the command fail?
|
|
465
|
+
No, the command did not crash or fail unexpectedly. Exit code `1` means the scan completed successfully and detected unsuppressed findings at or above your configured severity threshold. This allows you to use `actions-warden` as a quality gate in your CI/CD pipelines to fail the job when actionable security issues are found. Exit code `0` means the scan completed with no unsuppressed findings at or above the threshold. Exit code `2` indicates CLI usage errors, invalid options, or syntax issues with command arguments.
|
|
466
|
+
|
|
467
|
+
#### 5. How does automatic resume work in organization scans?
|
|
468
|
+
During an organization scan, `actions-warden` saves a guarded checkpoint containing the scan state for every inspected repository. When you resume the scan by running the exact same command, `actions-warden` performs fresh repository discovery and checks the live default-branch tree SHA. Only completed, error-free repositories without parse errors whose tree SHA has not changed are reused; repositories that previously failed or encountered parse errors are never reused and are always rescanned. This saves significant time and API rate limits while ensuring any failing repository is retried.
|
|
347
469
|
|
|
348
470
|
## Documentation
|
|
349
471
|
|
package/RELEASING.md
CHANGED
|
@@ -154,7 +154,8 @@ git diff --cached
|
|
|
154
154
|
```
|
|
155
155
|
|
|
156
156
|
`release:check` verifies registry version monotonicity, version synchronization,
|
|
157
|
-
exact dependencies, YAML, documentation links
|
|
157
|
+
exact dependencies, YAML, documentation links and public-surface coverage,
|
|
158
|
+
lint, tests, dependency audit,
|
|
158
159
|
the exact npm tarball manifest, and the staged/working Action bundle against a
|
|
159
160
|
clean rebuild. On a workflow retry, the registry guard also requires the local
|
|
160
161
|
tarball integrity to equal the already-published immutable artifact. The gate
|
|
@@ -223,7 +224,7 @@ validate -> release-draft -> publish-npm -> release
|
|
|
223
224
|
|
|
224
225
|
| Job | Responsibility |
|
|
225
226
|
|---|---|
|
|
226
|
-
| `validate` | Stable tag, package match, `main` ancestry, npm monotonicity/retry integrity, tests, lint, YAML/docs, exact dependencies, version sync, audit, tarball inspection, and bundle reproduction |
|
|
227
|
+
| `validate` | Stable tag, package match, `main` ancestry, npm monotonicity/retry integrity, tests, lint, type check, YAML/docs, exact dependencies, version sync, audit, tarball inspection, and bundle reproduction |
|
|
227
228
|
| `release-draft` | Create or reuse a draft GitHub release for the immutable tag |
|
|
228
229
|
| `publish-npm` | Publish with npm OIDC and provenance, or safely skip an already-published retry |
|
|
229
230
|
| `release` | Make the GitHub release final only after npm succeeds |
|
package/SECURITY.md
CHANGED
|
@@ -12,7 +12,7 @@ Please include:
|
|
|
12
12
|
|
|
13
13
|
- A clear description of the issue.
|
|
14
14
|
- A minimal reproduction (workflow YAML, command line, expected vs. actual).
|
|
15
|
-
- The version of `actions-warden` (`npx --yes actions-warden@0.
|
|
15
|
+
- The version of `actions-warden` (`npx --yes actions-warden@0.6.0 --version`).
|
|
16
16
|
- Any disclosure constraints on your side.
|
|
17
17
|
|
|
18
18
|
We aim to acknowledge within **3 business days** and to ship a fix or a
|
|
@@ -50,19 +50,34 @@ Out of scope:
|
|
|
50
50
|
install dependencies in consumer workflows.
|
|
51
51
|
- Repository policy and baseline files should be protected with CODEOWNERS or
|
|
52
52
|
branch rules; changes to them can intentionally alter which findings fail CI.
|
|
53
|
+
- CLI report, baseline, and checkpoint destinations are guarded and preflighted;
|
|
54
|
+
they cannot replace selected/default-discovery workflows or reserved policy
|
|
55
|
+
paths, and active control-file collisions are rejected before output writes.
|
|
53
56
|
- Parser failures are operational errors and cannot be suppressed by a finding
|
|
54
57
|
baseline.
|
|
55
58
|
- Organization scans read count- and size-bounded Git blobs in memory and never
|
|
56
59
|
clone, check out, or execute code from scanned repositories. Truncated trees,
|
|
57
60
|
exceeded limits, and unreadable blobs are operational errors.
|
|
58
61
|
- Organization checkpoints are opt-in, guarded atomic writes. They omit tokens
|
|
59
|
-
and raw workflow YAML, validate
|
|
60
|
-
error-free result only after a fresh
|
|
61
|
-
match. They
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
62
|
+
and raw workflow YAML, validate analysis-generation/rule/scope/policy
|
|
63
|
+
identity, and reuse an error-free result only after a fresh
|
|
64
|
+
repository/default-branch tree-SHA match. They omit commits and links, which
|
|
65
|
+
each run rebuilds from the live default-branch commit. The producing package version is
|
|
66
|
+
metadata rather than a compatibility boundary. They still contain redacted
|
|
67
|
+
repository and finding evidence and should be protected like organization
|
|
68
|
+
reports.
|
|
69
|
+
- Explicit CLI agent mode shares the normal scope-keyed report and checkpoint
|
|
70
|
+
identity, uses the same guarded writer and `0600` creation mode, and changes
|
|
71
|
+
only presentation defaults plus the bounded receipt kind.
|
|
72
|
+
- `--report-dir` accepts only a dedicated directory inside the working tree,
|
|
73
|
+
rejects symbolic-link and control-file overlap, creates directories with
|
|
74
|
+
mode `0700` and files with mode `0600`, and writes its integrity manifest
|
|
75
|
+
last. Existing unrelated regular files are preserved, so consumers must use
|
|
76
|
+
the manifest as the authoritative artifact set.
|
|
77
|
+
- The scanner itself sends runtime requests only to `api.github.com`.
|
|
78
|
+
Webhook and ProjectDiscovery Notify examples run as separate, explicitly
|
|
79
|
+
configured CI steps and receive bounded summaries by default; their
|
|
80
|
+
destinations and credentials are owned by the calling workflow.
|
|
66
81
|
|
|
67
82
|
## Responsible-disclosure timeline
|
|
68
83
|
|