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
|
@@ -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
|
package/examples/org-scan.yml
CHANGED
|
@@ -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
|
-
|
|
41
|
-
.
|
|
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
|
package/examples/upgrade-pr.yml
CHANGED
|
@@ -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.
|
|
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
|
|
10
|
-
|
|
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
|
-
`
|
|
13
|
-
|
|
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
|
+
"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
|
-
"
|
|
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.
|
|
37
|
-
npx --yes actions-warden@0.
|
|
38
|
-
npx --yes actions-warden@0.
|
|
39
|
-
npx --yes actions-warden@0.
|
|
40
|
-
npx --yes actions-warden@0.
|
|
41
|
-
npx --yes actions-warden@0.
|
|
42
|
-
npx --yes actions-warden@0.
|
|
43
|
-
npx --yes actions-warden@0.
|
|
44
|
-
npx --yes actions-warden@0.
|
|
45
|
-
npx --yes actions-warden@0.
|
|
46
|
-
npx --yes actions-warden@0.
|
|
47
|
-
npx --yes actions-warden@0.
|
|
48
|
-
npx --yes actions-warden@0.
|
|
49
|
-
npx --yes actions-warden@0.
|
|
50
|
-
npx --yes actions-warden@0.
|
|
51
|
-
npx --yes actions-warden@0.
|
|
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
|
|
55
|
-
`--format toon|json|text|sarif`, `--output stdout|file`,
|
|
56
|
-
`--
|
|
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`,
|
|
62
|
-
`--
|
|
63
|
-
|
|
64
|
-
`--
|
|
65
|
-
|
|
66
|
-
|
|
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.
|
|
121
|
-
|
|
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.
|
|
155
|
+
npx --yes actions-warden@0.6.0 org-scan my-org \
|
|
128
156
|
--agent-mode
|
|
129
157
|
```
|
|
130
158
|
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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=
|
|
140
|
-
only when the user requests live progress
|
|
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`,
|
|
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.
|
|
228
|
-
|
|
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.
|