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.
Files changed (78) hide show
  1. package/AGENTS.md +60 -12
  2. package/CONTRIBUTING.md +6 -2
  3. package/README.md +180 -58
  4. package/RELEASING.md +3 -2
  5. package/SECURITY.md +23 -8
  6. package/docs/AI-AGENTS.md +125 -29
  7. package/docs/CLI.md +346 -69
  8. package/docs/CONFIGURATION.md +34 -11
  9. package/docs/DEVELOPMENT.md +114 -18
  10. package/docs/GITHUB-ACTION.md +163 -29
  11. package/docs/JAVASCRIPT-API.md +177 -11
  12. package/docs/OUTPUTS.md +408 -40
  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 +91 -39
  35. package/src/action.js +353 -187
  36. package/src/cli.js +416 -209
  37. package/src/commands/audit.js +17 -30
  38. package/src/commands/org-scan.js +452 -286
  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 +159 -35
  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/path-equality.js +30 -0
  69. package/src/lib/paths.js +18 -1
  70. package/src/lib/redact.js +58 -7
  71. package/src/lib/resolver.js +66 -9
  72. package/src/lib/types.js +137 -0
  73. package/src/lib/writer.js +3 -0
  74. package/src/rules/pull-request-target-checkout.js +5 -0
  75. package/src/rules/unpinned-action.js +2 -3
  76. package/src/rules/workflow-structure.js +2 -4
  77. package/src/version.js +1 -1
  78. package/src/lib/agent-mode.js +0 -175
@@ -0,0 +1,163 @@
1
+ name: actions-warden webhook notification
2
+
3
+ on:
4
+ pull_request:
5
+ push:
6
+ branches: [main]
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ audit-and-notify:
14
+ runs-on: ubuntu-latest
15
+ timeout-minutes: 10
16
+ steps:
17
+ - name: Check out repository
18
+ uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
19
+ with:
20
+ persist-credentials: false
21
+
22
+ - name: Audit workflows
23
+ id: warden
24
+ uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
25
+ with:
26
+ command: audit
27
+ severity: high
28
+ explain: 'true'
29
+ format: json
30
+ output-path: actions-warden-report.json
31
+ annotations: 'true'
32
+ fail-on-findings: 'false'
33
+
34
+ - name: Upload complete report
35
+ if: always()
36
+ uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
37
+ with:
38
+ name: actions-warden-report-${{ github.run_id }}
39
+ path: actions-warden-report.json
40
+ if-no-files-found: warn
41
+ retention-days: 14
42
+
43
+ - name: Build bounded notification
44
+ id: notification
45
+ if: always()
46
+ shell: bash
47
+ env:
48
+ WARDEN_STATUS: ${{ steps.warden.outputs.status }}
49
+ WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
50
+ WARDEN_CRITICAL: ${{ steps.warden.outputs.critical }}
51
+ WARDEN_HIGH: ${{ steps.warden.outputs.high }}
52
+ WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
53
+ REPOSITORY: ${{ github.repository }}
54
+ SERVER_URL: ${{ github.server_url }}
55
+ RUN_ID: ${{ github.run_id }}
56
+ run: |
57
+ node <<'NODE'
58
+ const fs = require('node:fs');
59
+
60
+ const count = name => {
61
+ const value = Number(process.env[name] ?? 0);
62
+ return Number.isSafeInteger(value) && value >= 0 ? value : 0;
63
+ };
64
+ const status = ['OK', 'FAIL'].includes(process.env.WARDEN_STATUS)
65
+ ? process.env.WARDEN_STATUS
66
+ : 'FAIL';
67
+ const payload = {
68
+ schemaVersion: '1.0',
69
+ source: 'actions-warden',
70
+ repository: process.env.REPOSITORY,
71
+ status,
72
+ summary: {
73
+ findings: count('WARDEN_FINDINGS'),
74
+ critical: count('WARDEN_CRITICAL'),
75
+ high: count('WARDEN_HIGH'),
76
+ errors: count('WARDEN_ERRORS'),
77
+ },
78
+ runUrl: `${process.env.SERVER_URL}/${process.env.REPOSITORY}/actions/runs/${process.env.RUN_ID}`,
79
+ };
80
+ fs.writeFileSync(
81
+ 'actions-warden-notification.json',
82
+ `${JSON.stringify(payload)}\n`,
83
+ { mode: 0o600 },
84
+ );
85
+ NODE
86
+
87
+ - name: Send bounded webhook notification
88
+ if: always() && steps.notification.outcome == 'success'
89
+ shell: bash
90
+ env:
91
+ ACTIONS_WARDEN_WEBHOOK_URL: ${{ secrets.ACTIONS_WARDEN_WEBHOOK_URL }}
92
+ run: |
93
+ node <<'NODE'
94
+ const fs = require('node:fs');
95
+
96
+ const wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds));
97
+ const deliver = async () => {
98
+ let endpoint;
99
+ try {
100
+ endpoint = new URL(process.env.ACTIONS_WARDEN_WEBHOOK_URL);
101
+ } catch {
102
+ throw new Error('ACTIONS_WARDEN_WEBHOOK_URL must be a valid HTTPS URL');
103
+ }
104
+ if (endpoint.protocol !== 'https:' || endpoint.username || endpoint.password) {
105
+ throw new Error('ACTIONS_WARDEN_WEBHOOK_URL must use HTTPS without embedded credentials');
106
+ }
107
+ const body = fs.readFileSync('actions-warden-notification.json');
108
+ if (body.byteLength > 16 * 1024) {
109
+ throw new Error('notification payload exceeds 16 KiB');
110
+ }
111
+
112
+ for (let attempt = 1; attempt <= 3; attempt += 1) {
113
+ try {
114
+ const response = await fetch(endpoint, {
115
+ method: 'POST',
116
+ headers: { 'content-type': 'application/json' },
117
+ body,
118
+ redirect: 'error',
119
+ signal: AbortSignal.timeout(30_000),
120
+ });
121
+ await response.body?.cancel();
122
+ if (response.ok) return;
123
+ const error = new Error(`webhook rejected the payload with HTTP ${response.status}`);
124
+ error.retryable = response.status === 429 || response.status >= 500;
125
+ throw error;
126
+ } catch (error) {
127
+ if (attempt === 3 || error.retryable === false) throw error;
128
+ }
129
+ await wait(1_000 * attempt);
130
+ }
131
+ };
132
+
133
+ deliver().catch(error => {
134
+ const safeMessages = new Set([
135
+ 'ACTIONS_WARDEN_WEBHOOK_URL must be a valid HTTPS URL',
136
+ 'ACTIONS_WARDEN_WEBHOOK_URL must use HTTPS without embedded credentials',
137
+ 'notification payload exceeds 16 KiB',
138
+ ]);
139
+ const safeMessage = safeMessages.has(error.message)
140
+ || /^webhook rejected the payload with HTTP \d{3}$/.test(error.message)
141
+ ? error.message : 'webhook delivery failed';
142
+ process.stderr.write(`${safeMessage}\n`);
143
+ process.exitCode = 1;
144
+ });
145
+ NODE
146
+
147
+ - name: Enforce Actions Warden result
148
+ if: always()
149
+ shell: bash
150
+ env:
151
+ WARDEN_STATUS: ${{ steps.warden.outputs.status }}
152
+ WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
153
+ WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
154
+ run: |
155
+ if [ "$WARDEN_ERRORS" != '0' ]; then
156
+ printf 'actions-warden did not complete cleanly; review the retained report.\n' >&2
157
+ exit 1
158
+ fi
159
+ if [ "$WARDEN_STATUS" != 'OK' ] || [ "$WARDEN_FINDINGS" != '0' ]; then
160
+ printf 'actions-warden reported %s blocking finding(s).\n' \
161
+ "${WARDEN_FINDINGS:-unknown}" >&2
162
+ exit 1
163
+ fi
@@ -19,6 +19,7 @@ jobs:
19
19
  persist-credentials: false
20
20
 
21
21
  - name: Scan organization workflows
22
+ id: warden
22
23
  uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
23
24
  with:
24
25
  command: org-scan
@@ -26,17 +27,35 @@ jobs:
26
27
  token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
27
28
  severity: high
28
29
  explain: 'true'
29
- format: json
30
- output-path: actions-warden-org-report.json
31
- checkpoint-path: .actions-warden-org-checkpoint.json
32
30
  fail-on-findings: 'false'
33
31
 
32
+ - name: Show organization coverage
33
+ if: always()
34
+ shell: bash
35
+ env:
36
+ WARDEN_STATUS: ${{ steps.warden.outputs.status }}
37
+ WARDEN_DISCOVERED: ${{ steps.warden.outputs['repositories-discovered'] }}
38
+ WARDEN_SELECTED: ${{ steps.warden.outputs['repositories-selected'] }}
39
+ WARDEN_SCANNED: ${{ steps.warden.outputs['repositories-scanned'] }}
40
+ WARDEN_RESUMED: ${{ steps.warden.outputs['repositories-resumed'] }}
41
+ WARDEN_FAILED: ${{ steps.warden.outputs['repositories-failed'] }}
42
+ WARDEN_COVERAGE_COMPLETE: ${{ steps.warden.outputs['coverage-complete'] }}
43
+ WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
44
+ WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
45
+ run: |
46
+ printf 'status=%s coverage_complete=%s discovered=%s selected=%s scanned=%s resumed=%s failed=%s findings=%s errors=%s\n' \
47
+ "$WARDEN_STATUS" "$WARDEN_COVERAGE_COMPLETE" \
48
+ "$WARDEN_DISCOVERED" "$WARDEN_SELECTED" \
49
+ "$WARDEN_SCANNED" "$WARDEN_RESUMED" "$WARDEN_FAILED" \
50
+ "$WARDEN_FINDINGS" "$WARDEN_ERRORS"
51
+
34
52
  - name: Upload organization report
35
53
  if: always()
36
54
  uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
37
55
  with:
38
56
  name: actions-warden-org-report
39
57
  path: |
40
- actions-warden-org-report.json
41
- .actions-warden-org-checkpoint.json
58
+ ${{ steps.warden.outputs['report-path'] }}
59
+ ${{ steps.warden.outputs['checkpoint-path'] }}
60
+ include-hidden-files: true
42
61
  if-no-files-found: error
@@ -0,0 +1,42 @@
1
+ # Publish findings to GitHub Code Scanning
2
+
3
+ This example generates SARIF 2.1.0, preserves it as a workflow artifact, and
4
+ uploads it to GitHub Code Scanning before enforcing the result. Use it when
5
+ security findings should remain queryable in the repository's Security view in
6
+ addition to normal actions-warden annotations and job summaries.
7
+
8
+ ## Install the example
9
+
10
+ Copy [`github-actions.yml`](./github-actions.yml) to
11
+ `.github/workflows/actions-warden-sarif.yml` in the repository to protect.
12
+ The repository must permit SARIF uploads to Code Scanning.
13
+
14
+ The workflow deliberately runs only for trusted default-branch pushes,
15
+ scheduled scans, and manual dispatches. Its job needs `security-events: write`
16
+ to publish results; pull-request enforcement should use the separate
17
+ [least-privilege CI example](../ci-violation-reporting/README.md), which needs
18
+ only `contents: read` and still provides annotations plus a downloadable JSON
19
+ report.
20
+
21
+ ## What the workflow does
22
+
23
+ 1. Audit local workflows without a token input or code execution.
24
+ 2. Write high and critical findings to `actions-warden.sarif` while keeping
25
+ native annotations enabled.
26
+ 3. Upload the SARIF file as a retained workflow artifact.
27
+ 4. Upload the same file to Code Scanning under the `actions-warden` category.
28
+ 5. Fail the final gate when actions-warden reported `status: FAIL`.
29
+
30
+ The scan uses `fail-on-findings: 'false'` only to defer policy failure until
31
+ after both uploads. Operational scanner errors still fail directly. The SARIF
32
+ upload is skipped when an operational failure prevented creation of the file.
33
+
34
+ Change `severity: high` to `severity: low` to publish every finding. If the
35
+ repository uses a reviewed baseline, actions-warden omits suppressed findings
36
+ from SARIF while retaining suppression counts in JSON reports; use the
37
+ [baseline-adoption example](../baseline-adoption/README.md) for that rollout
38
+ model.
39
+
40
+ SARIF contains repository-relative paths, rule evidence, and stable finding
41
+ fingerprints. Apply an appropriate artifact retention period and repository
42
+ access policy.
@@ -0,0 +1,66 @@
1
+ name: publish Actions Warden SARIF
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ schedule:
7
+ - cron: '41 5 * * 1'
8
+ workflow_dispatch:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ actions-warden:
15
+ name: Publish Actions Warden findings
16
+ runs-on: ubuntu-latest
17
+ timeout-minutes: 10
18
+ permissions:
19
+ actions: read
20
+ contents: read
21
+ security-events: write
22
+ steps:
23
+ - name: Check out repository
24
+ uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
25
+ with:
26
+ persist-credentials: false
27
+
28
+ - name: Generate SARIF
29
+ id: warden
30
+ uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
31
+ with:
32
+ command: audit
33
+ severity: high
34
+ explain: 'true'
35
+ format: sarif
36
+ output-path: actions-warden.sarif
37
+ annotations: 'true'
38
+ # Defer finding failure until the SARIF evidence has been published.
39
+ fail-on-findings: 'false'
40
+
41
+ - name: Retain SARIF artifact
42
+ if: always()
43
+ uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
44
+ with:
45
+ name: actions-warden-sarif-${{ github.run_id }}
46
+ path: actions-warden.sarif
47
+ if-no-files-found: warn
48
+ retention-days: 14
49
+
50
+ - name: Upload SARIF to Code Scanning
51
+ if: always() && hashFiles('actions-warden.sarif') != ''
52
+ uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.4
53
+ with:
54
+ sarif_file: actions-warden.sarif
55
+ category: actions-warden
56
+
57
+ - name: Enforce Actions Warden result
58
+ if: always() && steps.warden.outputs.status == 'FAIL'
59
+ shell: bash
60
+ env:
61
+ ACTIONS_WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
62
+ run: |
63
+ printf 'actions-warden published %s blocking finding(s).\n' \
64
+ "${ACTIONS_WARDEN_FINDINGS:-unknown}" >&2
65
+ printf 'Review Code Scanning, annotations, and the SARIF artifact.\n' >&2
66
+ exit 1
@@ -26,7 +26,7 @@ jobs:
26
26
  - name: Apply eligible upgrades
27
27
  env:
28
28
  GITHUB_TOKEN: ${{ github.token }}
29
- run: npx --yes actions-warden@0.3.0 upgrade --mode=minor --min-age=7 --write
29
+ run: npx --yes actions-warden@0.6.0 upgrade --mode=minor --min-age=7 --write
30
30
 
31
31
  - name: Open or update pull request
32
32
  env:
package/llms.txt CHANGED
@@ -6,11 +6,17 @@
6
6
  Requires Node.js 20+. The CLI is non-interactive. `pin` and `upgrade` are
7
7
  dry-run by default. Normal JSON payloads use `schemaVersion: "1.0"`. Exit code
8
8
  1 is a completed `FAIL` result to inspect; exit code 2 is an invocation error.
9
- Organization scans support guarded `--checkpoint` / `--resume` state and
10
- stderr-only live progress while retaining fresh repository tree validation.
9
+ Organization scans default to a guarded scope-keyed JSON report, bounded stdout
10
+ receipt, compatible automatic checkpoint/resume state, and stderr-only live
11
+ progress while retaining fresh repository tree validation.
12
+ They can emit spreadsheet-safe CSV or self-contained HTML reports, split broad
13
+ JSON evidence into a compact aggregate plus integrity-manifested repository
14
+ artifacts, and compare a compatible prior JSON report without calling missing
15
+ or failed repository findings resolved.
11
16
  For agent-initiated organization scans, pass `--agent-mode` or set
12
- `ACTIONS_WARDEN_MODE=agent`. It defaults to scope-keyed JSON report and
13
- checkpoint files, compatible resume, no progress, and a bounded stdout receipt.
17
+ `ACTIONS_WARDEN_CONTEXT=agent`.
18
+ It disables implicit progress and uses the agent receipt kind while sharing the
19
+ normal artifact identity so compatible resume state survives context switches.
14
20
  Preserve requested scope; do not load the complete report into model context.
15
21
 
16
22
  ## Start
@@ -18,7 +24,7 @@ Preserve requested scope; do not load the complete report into model context.
18
24
  - [README](./README.md): product overview and quick start
19
25
  - [CLI reference](./docs/CLI.md): commands, options, organization scans, cache
20
26
  - [Configuration](./docs/CONFIGURATION.md): policy, rule IDs, ignores, baselines
21
- - [Output contracts](./docs/OUTPUTS.md): JSON shapes, TOON, SARIF, status, exits
27
+ - [Output contracts](./docs/OUTPUTS.md): JSON shapes, TOON, CSV, HTML, comparison, SARIF, status, exits
22
28
  - [GitHub Action](./docs/GITHUB-ACTION.md): workflow setup, inputs, outputs
23
29
  - [JavaScript API](./docs/JAVASCRIPT-API.md): public functions and renderers
24
30
 
@@ -34,5 +40,8 @@ Preserve requested scope; do not load the complete report into model context.
34
40
  ## Copyable examples
35
41
 
36
42
  - [Organization report workflow](./examples/org-scan.yml)
43
+ - [HTML organization report](./examples/html-organization-report/README.md)
44
+ - [CSV reporting](./examples/csv-reporting/README.md)
45
+ - [Webhook and ProjectDiscovery Notify](./examples/notifications/README.md)
37
46
  - [Upgrade pull request workflow](./examples/upgrade-pr.yml)
38
47
  - [Claude Code skill](./skills/actions-warden/SKILL.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "actions-warden",
3
- "version": "0.3.0",
3
+ "version": "0.6.0",
4
4
  "description": "Audit GitHub Actions across repositories and organizations; pin, verify, and upgrade dependencies.",
5
5
  "author": "Naveen Yagati",
6
6
  "homepage": "https://github.com/chiz0me/actions-warden#readme",
@@ -49,6 +49,7 @@
49
49
  "test": "vitest --run",
50
50
  "test:watch": "vitest",
51
51
  "lint": "eslint src scripts test",
52
+ "typecheck": "tsc --noEmit",
52
53
  "build:action": "ncc build src/action.js -o dist",
53
54
  "check:action-bundle": "node scripts/verify-action-bundle.js",
54
55
  "check:yaml": "node scripts/check-yaml.js",
@@ -59,8 +60,8 @@
59
60
  "verify-version-sync": "node scripts/verify-version-sync.js",
60
61
  "audit": "npm audit --audit-level=high",
61
62
  "release:prepare": "node scripts/set-version.js",
62
- "release:check": "npm run check:release-version && npm run verify-version-sync && npm run verify-deps && npm run check:yaml && npm run check:docs && npm run lint && npm test && npm audit --audit-level=high && npm run check:package && npm run check:action-bundle",
63
- "prepublishOnly": "npm run verify-version-sync && npm run verify-deps && npm run check:yaml && npm run check:docs && npm run lint && npm test && npm audit --audit-level=high && npm run check:package"
63
+ "release:check": "npm run check:release-version && npm run verify-version-sync && npm run verify-deps && npm run check:yaml && npm run check:docs && npm run lint && npm run typecheck && npm test && npm audit --audit-level=high && npm run check:package && npm run check:action-bundle",
64
+ "prepublishOnly": "npm run verify-version-sync && npm run verify-deps && npm run check:yaml && npm run check:docs && npm run lint && npm run typecheck && npm test && npm audit --audit-level=high && npm run check:package"
64
65
  },
65
66
  "dependencies": {
66
67
  "commander": "14.0.3",
@@ -70,10 +71,12 @@
70
71
  },
71
72
  "devDependencies": {
72
73
  "@eslint/js": "9.39.2",
74
+ "@types/node": "22.20.5",
73
75
  "@vercel/ncc": "0.44.1",
74
76
  "eslint": "9.39.2",
75
77
  "globals": "17.7.0",
76
- "vitest": "4.1.10"
78
+ "typescript": "7.0.2",
79
+ "vitest": "4.1.12"
77
80
  },
78
81
  "keywords": [
79
82
  "github-actions",
@@ -86,6 +89,7 @@
86
89
  "workflow",
87
90
  "supply-chain",
88
91
  "toon",
92
+ "csv",
89
93
  "sarif",
90
94
  "llm"
91
95
  ],
@@ -33,43 +33,70 @@ Invoke `actions-warden` when the user:
33
33
  The package is on npm as `actions-warden`. Invoke the reviewed version exactly:
34
34
 
35
35
  ```sh
36
- npx --yes actions-warden@0.3.0 audit
37
- npx --yes actions-warden@0.3.0 audit --severity=high --explain
38
- npx --yes actions-warden@0.3.0 audit --create-baseline=.actions-warden-baseline.json
39
- npx --yes actions-warden@0.3.0 audit --baseline=.actions-warden-baseline.json
40
- npx --yes actions-warden@0.3.0 audit --format=sarif
41
- npx --yes actions-warden@0.3.0 pin
42
- npx --yes actions-warden@0.3.0 pin --write
43
- npx --yes actions-warden@0.3.0 upgrade --mode=minor
44
- npx --yes actions-warden@0.3.0 upgrade --min-age=14 --write
45
- npx --yes actions-warden@0.3.0 verify
46
- npx --yes actions-warden@0.3.0 report --offline
47
- npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --format=json
48
- npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --agent-mode
49
- npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --checkpoint=.actions-warden-org-checkpoint.json
50
- npx --yes actions-warden@0.3.0 org-scan my-org --severity=high --resume=.actions-warden-org-checkpoint.json
51
- npx --yes actions-warden@0.3.0 rules
36
+ npx --yes actions-warden@0.6.0 audit
37
+ npx --yes actions-warden@0.6.0 audit --severity=high --explain
38
+ npx --yes actions-warden@0.6.0 audit --create-baseline=.actions-warden-baseline.json
39
+ npx --yes actions-warden@0.6.0 audit --baseline=.actions-warden-baseline.json
40
+ npx --yes actions-warden@0.6.0 audit --format=sarif
41
+ npx --yes actions-warden@0.6.0 audit --format=csv --output-path=actions-warden.csv
42
+ npx --yes actions-warden@0.6.0 pin
43
+ npx --yes actions-warden@0.6.0 pin --write
44
+ npx --yes actions-warden@0.6.0 upgrade --mode=minor
45
+ npx --yes actions-warden@0.6.0 upgrade --min-age=14 --write
46
+ npx --yes actions-warden@0.6.0 verify
47
+ npx --yes actions-warden@0.6.0 report --offline
48
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high
49
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --format=html --output-path=actions-warden-org.html
50
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --previous-report=previous.json --format=json
51
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --report-dir=reports/actions-warden-org
52
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --agent-mode
53
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --checkpoint=.actions-warden-org-checkpoint.json
54
+ npx --yes actions-warden@0.6.0 org-scan my-org --severity=high --resume=.actions-warden-org-checkpoint.json
55
+ npx --yes actions-warden@0.6.0 rules
52
56
  ```
53
57
 
54
- Useful global flags: `--workflow <path-or-glob>` (repeatable), `--cwd <dir>`,
55
- `--format toon|json|text|sarif`, `--output stdout|file`, `--output-path <path>`,
56
- `--token <gh-token>` (also reads `GITHUB_TOKEN` / `GH_TOKEN`).
58
+ Useful shared command flags: `--workflow <path-or-glob>` (repeatable),
59
+ `--cwd <dir>`, `--format toon|json|text|csv|sarif|html`, `--output stdout|file`, and
60
+ `--output-path <path>`. An output path implies file output; never combine it
61
+ with explicit `--output=stdout`, and create its parent directory first.
62
+ Network-backed commands accept `--token <gh-token>` and also read
63
+ `GITHUB_TOKEN` / `GH_TOKEN`; prefer the environment. Local `audit` does not
64
+ accept or need a token.
57
65
  Audit, report, and org-scan also accept `--config <path>` and `--baseline <path>`.
58
66
  `.actions-warden.yml` is loaded automatically when present.
59
67
  Organization scans accept `--repository <glob...>`, `--visibility`,
60
68
  `--include-archived`, `--include-disabled`, `--include-forks`, `--max-repos`,
61
- `--concurrency`, `--checkpoint` or `--resume`, and
62
- `--progress=auto|always|never`. Progress is stderr-only and never part of the
63
- selected report format. For an agent-initiated organization scan, pass
64
- `--agent-mode`; `ACTIONS_WARDEN_MODE=agent` is the integration-wide equivalent.
65
- The mode writes a scope-keyed report and checkpoint and emits a bounded JSON
66
- receipt. Explicit output, format, progress, and checkpoint options take
69
+ `--concurrency`, `--checkpoint` or `--resume`, `--fresh`,
70
+ `--no-auto-checkpoint`, `--previous-report <json-path>`, and
71
+ `--report-dir <dedicated-directory>`, plus
72
+ `--progress=auto|plain|json|none`.
73
+ Organization scans default to a scope-keyed JSON
74
+ report, bounded receipt, and compatible automatic checkpoint/resume. Progress
75
+ is stderr-only and never part of the selected report format. For an
76
+ agent-initiated organization scan, pass
77
+ `--agent-mode`; `ACTIONS_WARDEN_CONTEXT=agent` is the preferred
78
+ integration-wide equivalent. The mode disables implicit progress and uses the agent receipt kind, but
79
+ shares normal `.actions-warden-org-scan.*` artifacts so resume survives context
80
+ switches. Explicit output, format, progress, and checkpoint options take
67
81
  precedence.
68
82
 
83
+ CSV is a flat artifact format, not the lossless report schema. In the GitHub
84
+ Action it requires `output-path` for non-organization commands and is not
85
+ copied into step logs. Use JSON for
86
+ programmatic parsing and future organization comparison inputs.
87
+
88
+ For webhooks or ProjectDiscovery Notify, keep delivery in a separate CI step.
89
+ Send bounded Action outputs and a workflow-run link, retain the complete report
90
+ as a protected artifact, and source provider credentials only from masked
91
+ secrets. Use `examples/notifications/README.md` as the reviewed pattern.
92
+
69
93
  Exit codes: `0` for a normal `OK` result, `1` for a normal structured `FAIL`
70
94
  result (findings or operational errors), and `2` for an invocation-level error.
71
95
  For code `1`, inspect the report. For code `2`, read stderr and do not assume
72
- stdout contains a complete structured payload.
96
+ stdout contains a complete structured payload. Do not retry code `2` by
97
+ guessing alternative flags: fix the named conflict, integer, ID, working
98
+ directory, or destination. The CLI rejects those errors before network or
99
+ authorized workflow mutation whenever the needed path information is known.
73
100
 
74
101
  ## What to do when invoked
75
102
 
@@ -117,34 +144,53 @@ stdout contains a complete structured payload.
117
144
 
118
145
  7. **Report organization coverage before risk.** For `org-scan`, state the
119
146
  discovered, eligible, selected, scanned, and failed repository counts before
120
- summarizing findings. Any repository error means coverage is incomplete;
121
- never describe that result as a clean organization scan.
147
+ summarizing findings. Inspect `coverage.complete`: any repository error or
148
+ repository cap means eligible coverage is incomplete, even when a capped
149
+ selected scan otherwise returns `OK`.
122
150
 
123
151
  8. **Keep organization reports out of model context by default.** An
124
152
  agent-initiated broad scan must use the explicit agent mode:
125
153
 
126
154
  ```sh
127
- npx --yes actions-warden@0.3.0 org-scan my-org \
155
+ npx --yes actions-warden@0.6.0 org-scan my-org \
128
156
  --agent-mode
129
157
  ```
130
158
 
131
- Agent mode writes the complete report to a scope-keyed file, disables
132
- progress, creates or resumes a compatible scope-keyed checkpoint, and emits
133
- only a bounded JSON receipt. Read the report path from that receipt. First
159
+ Organization scans already write the complete report to a scope-keyed file,
160
+ create or resume a compatible checkpoint, and emit only a bounded JSON
161
+ receipt. Agent mode additionally disables implicit progress and selects the
162
+ agent receipt kind without changing artifact identity. Read the report path from that receipt. First
134
163
  inspect only status, scope, summary, error counts, and severity/rule
135
164
  aggregates from the saved report. Read error details and findings afterward
136
165
  in bounded, task-relevant batches. Do not emit or ingest the whole report
137
166
  merely to summarize it. Do not narrow the user's requested repositories,
138
167
  severities, policy, or baseline to reduce context. Omit `--explain` on a
139
- broad first pass unless remediation was requested. Add `--progress=always`
140
- only when the user requests live progress. Explicit CLI options override
168
+ broad first pass unless remediation was requested. Add `--progress=plain`
169
+ only when the user requests human-readable live progress, or
170
+ `--progress=json` for a JSON Lines integration. Explicit CLI options override
141
171
  agent defaults.
142
172
 
143
173
  The scanner does not call a language model, but the surrounding agent uses
144
174
  inference tokens to plan, monitor, and summarize; output admitted to its
145
175
  context adds to that usage. Resume primarily saves GitHub API/blob work and
146
176
  elapsed time. A changed scope or security control receives a different
147
- artifact key rather than overwriting an incompatible checkpoint.
177
+ artifact key rather than overwriting an incompatible checkpoint. Compatible
178
+ package upgrades retain the same key and resume state; an analysis-behavior
179
+ change receives a new key.
180
+
181
+ For a broad report that will be inspected per repository, use
182
+ `--report-dir=reports/actions-warden-org`, inspect its compact aggregate and
183
+ manifest first, and read only relevant repository artifacts. The directory
184
+ layout does not reduce scanner memory and is not a future
185
+ `--previous-report` input.
186
+
187
+ 9. **Use CSV/HTML as artifacts, not model context.** CSV is useful for flat
188
+ spreadsheet or warehouse export, and self-contained HTML is useful for
189
+ human review. Do not read either complete artifact into the conversation.
190
+ For change reporting, retain JSON and pass it with `--previous-report`;
191
+ a report from an older analysis generation must be regenerated once.
192
+ Report new, resolved, unchanged, and unknown counts; unmatched prior
193
+ findings are unknown when current repository coverage failed or disappeared.
148
194
 
149
195
  ## Audit rules
150
196
 
@@ -207,7 +253,8 @@ const orgResult = await scanOrganization({
207
253
  Other exports include `listRules`, `discoverWorkflows`, `parseWorkflowFile`,
208
254
  `parseWorkflowSource`, `collectUses`, `collectImages`, `parseActionRef`,
209
255
  `renderAudit`, `renderPin`, `renderUpgrade`, `renderVerify`, `renderReport`,
210
- `renderOrganizationScan`, `renderSarif`, `format`, `redact`, and
256
+ `renderOrganizationScan`, `renderSarif`, `renderHtml`, `format`, `redact`,
257
+ `compareOrganizationReports`, `loadOrganizationReport`, and
211
258
  `parseIgnoreDirectives`.
212
259
 
213
260
  ## Notes
@@ -221,11 +268,16 @@ Other exports include `listRules`, `discoverWorkflows`, `parseWorkflowFile`,
221
268
  - Private organization scans require a token that can list repositories and
222
269
  read their contents. Organization scans never clone or execute repository
223
270
  code and treat incomplete remote reads as errors.
271
+ - Organization reports list every inspected workflow file in each repository's
272
+ `fileDetails` and give each finding a `permalink` pinned to the scanned commit;
273
+ cite the permalink and treat an `unreadable` file as a coverage gap.
224
274
  - Organization checkpoints are atomic and contain redacted report data plus
225
- tree revisions, not tokens or raw YAML. Resume requires matching scan/policy
275
+ tree revisions, not tokens, commits, links, or raw YAML. Resume requires matching scan/policy
226
276
  identity, rechecks fresh tree SHAs, reuses only unchanged error-free results,
227
- and retries changed or failed repositories. Treat the checkpoint as a
228
- sensitive report artifact.
277
+ and retries changed or failed repositories. Repeating the same command or
278
+ explicit `--checkpoint` path resumes automatically; use `--fresh` to replace
279
+ it or strict `--resume` when restored state must exist. Treat the checkpoint
280
+ as a sensitive report artifact.
229
281
  - Treat `.actions-warden.yml`, baselines, ignore directives, and
230
282
  `fail-on-findings` as security controls. Do not weaken them merely to make a
231
283
  scan pass.