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.
- package/AGENTS.md +46 -8
- package/CONTRIBUTING.md +6 -2
- package/README.md +171 -61
- package/RELEASING.md +3 -2
- package/SECURITY.md +15 -5
- package/docs/AI-AGENTS.md +109 -29
- package/docs/CLI.md +284 -60
- package/docs/CONFIGURATION.md +34 -11
- package/docs/DEVELOPMENT.md +97 -24
- package/docs/GITHUB-ACTION.md +157 -27
- package/docs/JAVASCRIPT-API.md +172 -8
- package/docs/OUTPUTS.md +399 -36
- 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 +78 -35
- package/src/action.js +351 -174
- package/src/cli.js +191 -177
- package/src/commands/audit.js +17 -30
- package/src/commands/org-scan.js +451 -280
- 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 +137 -96
- 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/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/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 -174
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,26 +33,30 @@ 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
58
|
Useful shared command flags: `--workflow <path-or-glob>` (repeatable),
|
|
55
|
-
`--cwd <dir>`, `--format toon|json|text|sarif`, `--output stdout|file`, and
|
|
59
|
+
`--cwd <dir>`, `--format toon|json|text|csv|sarif|html`, `--output stdout|file`, and
|
|
56
60
|
`--output-path <path>`. An output path implies file output; never combine it
|
|
57
61
|
with explicit `--output=stdout`, and create its parent directory first.
|
|
58
62
|
Network-backed commands accept `--token <gh-token>` and also read
|
|
@@ -62,14 +66,30 @@ Audit, report, and org-scan also accept `--config <path>` and `--baseline <path>
|
|
|
62
66
|
`.actions-warden.yml` is loaded automatically when present.
|
|
63
67
|
Organization scans accept `--repository <glob...>`, `--visibility`,
|
|
64
68
|
`--include-archived`, `--include-disabled`, `--include-forks`, `--max-repos`,
|
|
65
|
-
`--concurrency`, `--checkpoint` or `--resume`,
|
|
66
|
-
`--
|
|
67
|
-
|
|
68
|
-
`--
|
|
69
|
-
|
|
70
|
-
|
|
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
|
|
71
81
|
precedence.
|
|
72
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
|
+
|
|
73
93
|
Exit codes: `0` for a normal `OK` result, `1` for a normal structured `FAIL`
|
|
74
94
|
result (findings or operational errors), and `2` for an invocation-level error.
|
|
75
95
|
For code `1`, inspect the report. For code `2`, read stderr and do not assume
|
|
@@ -124,27 +144,30 @@ authorized workflow mutation whenever the needed path information is known.
|
|
|
124
144
|
|
|
125
145
|
7. **Report organization coverage before risk.** For `org-scan`, state the
|
|
126
146
|
discovered, eligible, selected, scanned, and failed repository counts before
|
|
127
|
-
summarizing findings.
|
|
128
|
-
|
|
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`.
|
|
129
150
|
|
|
130
151
|
8. **Keep organization reports out of model context by default.** An
|
|
131
152
|
agent-initiated broad scan must use the explicit agent mode:
|
|
132
153
|
|
|
133
154
|
```sh
|
|
134
|
-
npx --yes actions-warden@0.
|
|
155
|
+
npx --yes actions-warden@0.6.0 org-scan my-org \
|
|
135
156
|
--agent-mode
|
|
136
157
|
```
|
|
137
158
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
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
|
|
141
163
|
inspect only status, scope, summary, error counts, and severity/rule
|
|
142
164
|
aggregates from the saved report. Read error details and findings afterward
|
|
143
165
|
in bounded, task-relevant batches. Do not emit or ingest the whole report
|
|
144
166
|
merely to summarize it. Do not narrow the user's requested repositories,
|
|
145
167
|
severities, policy, or baseline to reduce context. Omit `--explain` on a
|
|
146
|
-
broad first pass unless remediation was requested. Add `--progress=
|
|
147
|
-
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
|
|
148
171
|
agent defaults.
|
|
149
172
|
|
|
150
173
|
The scanner does not call a language model, but the surrounding agent uses
|
|
@@ -155,6 +178,20 @@ authorized workflow mutation whenever the needed path information is known.
|
|
|
155
178
|
package upgrades retain the same key and resume state; an analysis-behavior
|
|
156
179
|
change receives a new key.
|
|
157
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.
|
|
194
|
+
|
|
158
195
|
## Audit rules
|
|
159
196
|
|
|
160
197
|
| id | severity | catches |
|
|
@@ -216,7 +253,8 @@ const orgResult = await scanOrganization({
|
|
|
216
253
|
Other exports include `listRules`, `discoverWorkflows`, `parseWorkflowFile`,
|
|
217
254
|
`parseWorkflowSource`, `collectUses`, `collectImages`, `parseActionRef`,
|
|
218
255
|
`renderAudit`, `renderPin`, `renderUpgrade`, `renderVerify`, `renderReport`,
|
|
219
|
-
`renderOrganizationScan`, `renderSarif`, `format`, `redact`,
|
|
256
|
+
`renderOrganizationScan`, `renderSarif`, `renderHtml`, `format`, `redact`,
|
|
257
|
+
`compareOrganizationReports`, `loadOrganizationReport`, and
|
|
220
258
|
`parseIgnoreDirectives`.
|
|
221
259
|
|
|
222
260
|
## Notes
|
|
@@ -230,11 +268,16 @@ Other exports include `listRules`, `discoverWorkflows`, `parseWorkflowFile`,
|
|
|
230
268
|
- Private organization scans require a token that can list repositories and
|
|
231
269
|
read their contents. Organization scans never clone or execute repository
|
|
232
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.
|
|
233
274
|
- Organization checkpoints are atomic and contain redacted report data plus
|
|
234
|
-
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
|
|
235
276
|
identity, rechecks fresh tree SHAs, reuses only unchanged error-free results,
|
|
236
|
-
and retries changed or failed repositories.
|
|
237
|
-
|
|
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.
|
|
238
281
|
- Treat `.actions-warden.yml`, baselines, ignore directives, and
|
|
239
282
|
`fail-on-findings` as security controls. Do not weaken them merely to make a
|
|
240
283
|
scan pass.
|