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.
Files changed (76) hide show
  1. package/AGENTS.md +46 -8
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +171 -61
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +15 -5
  6. package/docs/AI-AGENTS.md +109 -29
  7. package/docs/CLI.md +284 -60
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +97 -24
  10. package/docs/GITHUB-ACTION.md +157 -27
  11. package/docs/JAVASCRIPT-API.md +172 -8
  12. package/docs/OUTPUTS.md +399 -36
  13. package/docs/README.md +1 -1
  14. package/examples/README.md +21 -0
  15. package/examples/baseline-adoption/README.md +79 -0
  16. package/examples/baseline-adoption/github-actions.yml +56 -0
  17. package/examples/baseline-adoption/policy.yml +7 -0
  18. package/examples/ci-violation-reporting/README.md +82 -0
  19. package/examples/ci-violation-reporting/github-actions.yml +55 -0
  20. package/examples/ci-violation-reporting/policy.yml +7 -0
  21. package/examples/ci-violation-reporting/violating-workflow.yml +17 -0
  22. package/examples/csv-reporting/README.md +50 -0
  23. package/examples/csv-reporting/github-actions.yml +59 -0
  24. package/examples/html-organization-report/README.md +35 -0
  25. package/examples/html-organization-report/github-actions.yml +61 -0
  26. package/examples/notifications/README.md +67 -0
  27. package/examples/notifications/github-actions.yml +163 -0
  28. package/examples/org-scan.yml +24 -5
  29. package/examples/sarif-code-scanning/README.md +42 -0
  30. package/examples/sarif-code-scanning/github-actions.yml +66 -0
  31. package/examples/upgrade-pr.yml +1 -1
  32. package/llms.txt +14 -5
  33. package/package.json +8 -4
  34. package/skills/actions-warden/SKILL.md +78 -35
  35. package/src/action.js +351 -174
  36. package/src/cli.js +191 -177
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +451 -280
  39. package/src/commands/pin.js +9 -5
  40. package/src/commands/report.js +7 -2
  41. package/src/commands/upgrade.js +9 -5
  42. package/src/commands/verify.js +24 -4
  43. package/src/index.js +5 -1
  44. package/src/lib/action-summary.js +656 -0
  45. package/src/lib/annotations.js +4 -6
  46. package/src/lib/baseline.js +11 -1
  47. package/src/lib/config.js +10 -5
  48. package/src/lib/destination.js +98 -0
  49. package/src/lib/execution.js +5 -1
  50. package/src/lib/formats/csv.js +125 -0
  51. package/src/lib/formats/html.js +394 -0
  52. package/src/lib/formats/json.js +17 -0
  53. package/src/lib/formats/sarif.js +229 -0
  54. package/src/lib/formats/text.js +30 -0
  55. package/src/lib/formats/toon.js +50 -0
  56. package/src/lib/formatter.js +25 -192
  57. package/src/lib/github-org.js +208 -102
  58. package/src/lib/org-artifacts.js +211 -0
  59. package/src/lib/org-checkpoint.js +137 -96
  60. package/src/lib/org-progress.js +182 -4
  61. package/src/lib/org-report-comparison.js +505 -0
  62. package/src/lib/org-report-directory.js +251 -0
  63. package/src/lib/org-report.js +223 -0
  64. package/src/lib/org-run.js +305 -0
  65. package/src/lib/org-schema.js +89 -0
  66. package/src/lib/org-source-links.js +39 -0
  67. package/src/lib/parser.js +5 -0
  68. package/src/lib/paths.js +18 -1
  69. package/src/lib/redact.js +58 -7
  70. package/src/lib/resolver.js +66 -9
  71. package/src/lib/types.js +137 -0
  72. package/src/rules/pull-request-target-checkout.js +5 -0
  73. package/src/rules/unpinned-action.js +2 -3
  74. package/src/rules/workflow-structure.js +2 -4
  75. package/src/version.js +1 -1
  76. package/src/lib/agent-mode.js +0 -174
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
- - Use `apply_patch` for hand edits.
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,10 +55,14 @@ out of the model transcript by default:
54
55
  actions-warden org-scan ORG --agent-mode
55
56
  ```
56
57
 
57
- - `--agent-mode` defaults to JSON file output, no progress, and a guarded
58
- checkpoint. It emits only a bounded JSON receipt to stdout. The packaged
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
- `ACTIONS_WARDEN_MODE=agent` once.
65
+ `ACTIONS_WARDEN_CONTEXT=agent` once.
61
66
  - Automatic artifact names are derived from the checkpoint compatibility
62
67
  identity. An exact-scope later run resumes its checkpoint across compatible
63
68
  package versions; a changed filter, severity, policy, baseline, analysis
@@ -66,14 +71,23 @@ actions-warden org-scan ORG --agent-mode
66
71
  - Preserve the scope the user requested. Reducing LLM context use is not
67
72
  permission to omit repositories, severities, findings, or errors.
68
73
  - Explicit CLI choices override agent defaults. If the user asks to watch live
69
- progress, add `--progress=always`. The report path from the receipt, rather
74
+ progress, add `--progress=plain`; use `--progress=json` only when the caller
75
+ will parse JSON Lines. The report path from the receipt, rather
70
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.
71
81
  - Omit `--explain` on a broad first pass unless remediation prose was
72
82
  requested. Add it to a targeted follow-up when needed.
73
83
  - Inspect the saved JSON locally in bounded passes: first `status`, `scope`,
74
84
  `summary`, and error counts; then error details and severity/rule aggregates;
75
85
  finally only the finding batches needed for the task. Do not paste or read an
76
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.
77
91
  - The scanner process itself uses GitHub API quota and local compute; it does
78
92
  not call a language model. The surrounding agent still uses inference tokens
79
93
  to plan, monitor, and summarize, and large command output or report excerpts
@@ -127,13 +141,22 @@ deprecating a package. A release request does not authorize those actions.
127
141
  - Organization scans never clone, check out, import, or execute remote code.
128
142
  - Incomplete organization coverage produces visible errors and status `FAIL`.
129
143
  - Organization resume requires fresh discovery and matching default-branch tree
130
- SHAs; never reuse failed results. Checkpoints remain guarded, atomic, and free
131
- of tokens or raw YAML.
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.
132
151
  - `ORGANIZATION_ANALYSIS_GENERATION` is the organization-result compatibility
133
152
  boundary. Increment it whenever discovery, parser, finding identity, rule
134
153
  evaluation, or persisted result semantics can change; do not increment it
135
154
  for a version-only compatible release.
136
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.
137
160
  - Attacker-controlled text cannot forge output records or workflow commands.
138
161
 
139
162
  ## Validate proportionally
@@ -152,6 +175,21 @@ npm run check:docs
152
175
  npm run check:yaml
153
176
  ```
154
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
+
155
193
  For dependency or version metadata:
156
194
 
157
195
  ```sh
@@ -189,7 +227,7 @@ relevant surfaces:
189
227
  2. CLI and exit semantics;
190
228
  3. package exports;
191
229
  4. Action adapter and `action.yml`;
192
- 5. annotations and all four formats;
230
+ 5. annotations and all supported formats;
193
231
  6. tests;
194
232
  7. CLI, output, Action, API, and AI documentation;
195
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
  [![node](https://img.shields.io/node/v/actions-warden)](https://www.npmjs.com/package/actions-warden)
9
9
  [![license: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
10
10
 
11
- Audit GitHub Actions in one repository or across an entire organization, then
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, permission, injection, artifact, secret,
16
- container, reusable-workflow, and runner risks without executing the workflows
17
- it inspects.
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 a GitHub organization | `actions-warden org-scan ORG --format=json` |
26
- | Pin mutable action refs | `actions-warden pin`, review, then add `--write` |
27
- | Verify existing SHA pins | `actions-warden verify` |
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 JavaScript | [JavaScript API](./docs/JAVASCRIPT-API.md) |
31
- | Use it from a coding agent | [AI and agent guide](./docs/AI-AGENTS.md) |
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
- # Local and read-only
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
+ ```
73
+
74
+ ### 2. Follow the 3-step security workflow
43
75
 
44
- # Network-backed, but still read-only
45
- actions-warden report --format=json
76
+ ```sh
77
+ # Step 1: Audit your workflows (completely local and read-only)
78
+ actions-warden audit --explain
46
79
 
47
- # Preview pins; this does not change files
80
+ # Step 2: Preview how mutable tags will be pinned (safe preview; no files are modified)
48
81
  actions-warden pin
49
82
 
50
- # Apply the reviewed pin plan
83
+ # Step 3: Review the plan, then apply the changes to your workflow files
51
84
  actions-warden pin --write
52
85
 
53
- # Confirm the pins against GitHub
86
+ # Bonus: Confirm that all pinned commit SHAs truly belong to their GitHub repositories
54
87
  actions-warden verify
55
88
  ```
56
89
 
57
- For a one-off run without a global install:
58
-
59
- ```sh
60
- npx --yes actions-warden@0.4.0 audit --explain
61
- ```
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).
62
93
 
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 write a
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,32 +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 when requested and can safely resume;
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 with the same scope and policy:
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=always` for redirected logs
110
- or `--progress=never` to disable it.
138
+ defaults to interactive terminals; use `--progress=plain` for redirected logs,
139
+ `--progress=json` for JSON Lines events, or `--progress=none` to disable it.
111
140
 
112
141
  Compatible package upgrades reuse the same checkpoint. The producing package
113
142
  version is recorded as metadata, while an explicit analysis generation plus
114
143
  the rule catalog controls compatibility. A parser, discovery, or rule behavior
115
- change advances that generation and requires a fresh scan. Compatible older
116
- checkpoints are rewritten atomically on their first successful resume.
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.
117
179
 
118
180
  When a coding agent initiates the scan, use the explicit bounded mode:
119
181
 
@@ -121,9 +183,12 @@ When a coding agent initiates the scan, use the explicit bounded mode:
121
183
  actions-warden org-scan my-org --agent-mode
122
184
  ```
123
185
 
124
- It writes a scope-keyed JSON report and checkpoint, resumes compatible state,
125
- disables progress, and returns only a compact JSON receipt with the report path
126
- unless explicit CLI options override those defaults.
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.
127
192
 
128
193
  Limit scope with repository globs and visibility:
129
194
 
@@ -144,6 +209,17 @@ failed blob read is reported as an error so incomplete coverage cannot appear
144
209
  clean. See the [organization-scan reference](./docs/CLI.md#org-scan) and the
145
210
  [scheduled workflow example](./examples/org-scan.yml).
146
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
+
147
223
  ## Safe by default
148
224
 
149
225
  The write boundary is deliberately explicit:
@@ -159,8 +235,8 @@ audit/report/pin/upgrade plan → review IDs and diffs → --fix=<id> --write
159
235
  - Numeric limits and change IDs are parsed strictly; partial, fractional, and
160
236
  imprecise values fail before network or write work begins.
161
237
  - Rewrites preserve surrounding YAML and are reparsed before an atomic write.
162
- - `--output-path` implies file output; contradictory or incomplete output flags
163
- are rejected before a scan or authorized mutation begins.
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.
164
240
  - Paths, output files, and symlinks are constrained to the selected repository,
165
241
  and report/baseline/checkpoint destinations cannot replace workflows or
166
242
  policy controls.
@@ -257,7 +333,9 @@ actions-warden rules --format=json
257
333
  | `toon` | Compact terminal and LLM context; the default |
258
334
  | `json` | Versioned programmatic integrations |
259
335
  | `text` | Human-readable line-oriented logs |
336
+ | `csv` | Spreadsheet, data-warehouse, and compliance exports |
260
337
  | `sarif` | Code scanning and SARIF-compatible systems |
338
+ | `html` | Self-contained, searchable human review artifact |
261
339
 
262
340
  TOON output is one labeled record per line:
263
341
 
@@ -269,8 +347,11 @@ STATUS: FAIL
269
347
  ```
270
348
 
271
349
  Findings and proposed changes have stable, clone-independent IDs. JSON payloads
272
- carry `schemaVersion: "1.0"`; SARIF is 2.1.0. See [output contracts](./docs/OUTPUTS.md)
273
- for schemas, record labels, redaction, status, and shell/CI handling.
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.
274
355
 
275
356
  ## GitHub Action
276
357
 
@@ -303,8 +384,19 @@ jobs:
303
384
  ```
304
385
 
305
386
  The committed bundle runs on GitHub's managed Node 24 runtime and installs no
306
- consumer-side dependencies. Findings become native annotations and a job
307
- summary. See the [Action inputs, outputs, permissions, and examples](./docs/GITHUB-ACTION.md).
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).
308
400
 
309
401
  ## AI-assisted use
310
402
 
@@ -322,10 +414,10 @@ actions-warden audit --format=json
322
414
  Use JSON when the caller has a parser and TOON when context size matters.
323
415
  Agents should treat policy changes, baselines, `--write`, and organization
324
416
  tokens as security-sensitive boundaries. For an agent-initiated organization
325
- scan, use `actions-warden org-scan ORG --agent-mode`. It automatically writes a
326
- scope-keyed report and checkpoint, resumes compatible state, disables progress,
327
- and returns only a compact JSON receipt unless explicit flags override those
328
- defaults. The agent then reads bounded summaries and relevant finding batches
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
329
421
  instead of placing the full report in model context. This preserves requested
330
422
  coverage while controlling LLM token use. The
331
423
  [AI and agent guide](./docs/AI-AGENTS.md#default-for-an-ai-initiated-scan)
@@ -355,7 +447,25 @@ const organization = await scanOrganization({
355
447
  ```
356
448
 
357
449
  See the [JavaScript API guide](./docs/JAVASCRIPT-API.md) for command options,
358
- result shapes, renderers, lower-level exports, and error handling.
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.
359
469
 
360
470
  ## Documentation
361
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, lint, tests, dependency audit,
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.4.0 --version`).
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
@@ -61,13 +61,23 @@ Out of scope:
61
61
  - Organization checkpoints are opt-in, guarded atomic writes. They omit tokens
62
62
  and raw workflow YAML, validate analysis-generation/rule/scope/policy
63
63
  identity, and reuse an error-free result only after a fresh
64
- repository/default-branch tree-SHA match. The producing package version is
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
65
66
  metadata rather than a compatibility boundary. They still contain redacted
66
67
  repository and finding evidence and should be protected like organization
67
68
  reports.
68
- - Explicit CLI agent mode creates scope-keyed report and checkpoint files with
69
- the same guarded writer and `0600` creation mode. Its stdout receipt contains
70
- only paths and bounded counts; the artifact files remain sensitive.
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.
71
81
 
72
82
  ## Responsible-disclosure timeline
73
83