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,79 @@
|
|
|
1
|
+
# Adopt enforcement with a reviewed baseline
|
|
2
|
+
|
|
3
|
+
A baseline lets an existing repository record reviewed findings as accepted
|
|
4
|
+
debt while making every new matching violation fail CI. It is an adoption
|
|
5
|
+
mechanism, not an automatic allowlist: generating or expanding one accepts
|
|
6
|
+
security risk and should require the same review as a policy change.
|
|
7
|
+
|
|
8
|
+
## Files
|
|
9
|
+
|
|
10
|
+
| file | copy to | purpose |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| [`github-actions.yml`](./github-actions.yml) | `.github/workflows/actions-warden.yml` | Report unsuppressed findings, upload JSON, and enforce the result |
|
|
13
|
+
| [`policy.yml`](./policy.yml) | `.actions-warden.yml` | Load the reviewed baseline and define repository policy |
|
|
14
|
+
|
|
15
|
+
The baseline itself is deliberately not included because its IDs and
|
|
16
|
+
fingerprints must come from the repository being protected.
|
|
17
|
+
|
|
18
|
+
## One-time adoption
|
|
19
|
+
|
|
20
|
+
1. Install a reviewed actions-warden version and audit the current repository
|
|
21
|
+
without a baseline:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
actions-warden audit --format=json --explain
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
2. Investigate the findings. Fix what can be fixed immediately. For every
|
|
28
|
+
remaining finding, record the owner, justification, and remediation plan in
|
|
29
|
+
the repository's normal risk-tracking system.
|
|
30
|
+
3. Generate the deterministic baseline from the reviewed remaining findings:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
actions-warden audit \
|
|
34
|
+
--create-baseline=.actions-warden-baseline.json \
|
|
35
|
+
--format=json
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
4. Review `.actions-warden-baseline.json` before committing it. Copy
|
|
39
|
+
`policy.yml` to `.actions-warden.yml` and `github-actions.yml` to
|
|
40
|
+
`.github/workflows/actions-warden.yml` in the consuming repository.
|
|
41
|
+
5. Protect the workflow, policy, and baseline with `CODEOWNERS` and branch
|
|
42
|
+
rules. Make `Report new Actions violations` a required status check when it
|
|
43
|
+
is ready to block merging.
|
|
44
|
+
|
|
45
|
+
The JSON report exposes both `totalFindings` and `suppressed`; the Action also
|
|
46
|
+
provides `total-findings`, `suppressed`, and `findings` outputs for later steps.
|
|
47
|
+
The blocking `findings` count contains only unsuppressed violations. Moving an
|
|
48
|
+
unchanged finding to another line normally remains matched through its semantic
|
|
49
|
+
fingerprint.
|
|
50
|
+
|
|
51
|
+
## Prove that the ratchet works
|
|
52
|
+
|
|
53
|
+
Run the audit after the baseline and policy are installed:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
actions-warden audit --format=json --explain
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Reviewed legacy findings should be counted as suppressed. Introduce a
|
|
60
|
+
temporary unsafe reference such as `uses: owner/action@v1` on a throwaway
|
|
61
|
+
branch and run it again. The new occurrence should be reported and exit `1`.
|
|
62
|
+
Remove the temporary violation after the check.
|
|
63
|
+
|
|
64
|
+
Never regenerate or expand the baseline automatically in CI. Adding a record
|
|
65
|
+
accepts a finding; deleting a record causes a still-present finding to become
|
|
66
|
+
active again. Remove obsolete records as their underlying findings are fixed,
|
|
67
|
+
and review every baseline diff as a security-control change.
|
|
68
|
+
|
|
69
|
+
## CI behavior
|
|
70
|
+
|
|
71
|
+
The workflow runs actions-warden with `fail-on-findings: 'false'` so it can
|
|
72
|
+
upload `actions-warden-new-violations.json` before the final gate fails.
|
|
73
|
+
It passes `config: .actions-warden.yml` explicitly, so a missing policy or
|
|
74
|
+
referenced baseline fails closed instead of reverting to built-in defaults.
|
|
75
|
+
Operational errors still fail the audit step directly. To start in advisory
|
|
76
|
+
mode, omit the final gate until the baseline and ownership process are ready.
|
|
77
|
+
|
|
78
|
+
Baseline and report files contain repository paths and security evidence.
|
|
79
|
+
Restrict access and retention according to the repository's security policy.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: enforce new GitHub Actions violations
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
push:
|
|
6
|
+
branches: [main]
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
actions-warden:
|
|
14
|
+
name: Report new Actions violations
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
timeout-minutes: 10
|
|
17
|
+
steps:
|
|
18
|
+
- name: Check out repository
|
|
19
|
+
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
|
|
20
|
+
with:
|
|
21
|
+
persist-credentials: false
|
|
22
|
+
|
|
23
|
+
- name: Audit against reviewed baseline
|
|
24
|
+
id: warden
|
|
25
|
+
uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
|
|
26
|
+
with:
|
|
27
|
+
command: audit
|
|
28
|
+
config: .actions-warden.yml
|
|
29
|
+
severity: high
|
|
30
|
+
explain: 'true'
|
|
31
|
+
format: json
|
|
32
|
+
output-path: actions-warden-new-violations.json
|
|
33
|
+
annotations: 'true'
|
|
34
|
+
# The required policy loads .actions-warden-baseline.json.
|
|
35
|
+
# Defer finding failure so the evidence artifact is always attempted.
|
|
36
|
+
fail-on-findings: 'false'
|
|
37
|
+
|
|
38
|
+
- name: Upload new-violation report
|
|
39
|
+
if: always()
|
|
40
|
+
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
|
|
41
|
+
with:
|
|
42
|
+
name: actions-warden-new-violations-${{ github.run_id }}
|
|
43
|
+
path: actions-warden-new-violations.json
|
|
44
|
+
if-no-files-found: warn
|
|
45
|
+
retention-days: 14
|
|
46
|
+
|
|
47
|
+
- name: Enforce Actions Warden result
|
|
48
|
+
if: always() && steps.warden.outputs.status == 'FAIL'
|
|
49
|
+
shell: bash
|
|
50
|
+
env:
|
|
51
|
+
ACTIONS_WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
|
|
52
|
+
run: |
|
|
53
|
+
printf 'actions-warden reported %s new blocking finding(s).\n' \
|
|
54
|
+
"${ACTIONS_WARDEN_FINDINGS:-unknown}" >&2
|
|
55
|
+
printf 'Review the annotations and downloaded JSON report.\n' >&2
|
|
56
|
+
exit 1
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# CI violation reporting
|
|
2
|
+
|
|
3
|
+
This example adds an enforcing GitHub Actions check without giving the scan
|
|
4
|
+
write access or repository secrets. It reports high and critical workflow
|
|
5
|
+
violations as native annotations, saves the complete JSON report as a workflow
|
|
6
|
+
artifact, and then fails the job after the artifact step has had a chance to
|
|
7
|
+
run.
|
|
8
|
+
|
|
9
|
+
## Files
|
|
10
|
+
|
|
11
|
+
| file | copy to | purpose |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| [`github-actions.yml`](./github-actions.yml) | `.github/workflows/actions-warden.yml` | Run the audit, upload its report, and enforce the result |
|
|
14
|
+
| [`policy.yml`](./policy.yml) | `.actions-warden.yml` | Example reviewable repository policy |
|
|
15
|
+
| [`violating-workflow.yml`](./violating-workflow.yml) | Do not deploy; optionally scan it locally | Intentionally unsafe input for testing the reporting path |
|
|
16
|
+
|
|
17
|
+
## Install the example
|
|
18
|
+
|
|
19
|
+
1. Copy `github-actions.yml` to
|
|
20
|
+
`.github/workflows/actions-warden.yml` in the repository to protect.
|
|
21
|
+
2. Optionally copy `policy.yml` to `.actions-warden.yml` and adjust it through
|
|
22
|
+
normal code review.
|
|
23
|
+
3. Keep the workflow's third-party Actions pinned to reviewed full commit SHAs.
|
|
24
|
+
4. Make the `Report GitHub Actions violations` job a required status check in
|
|
25
|
+
the protected branch rules if violations must block merging.
|
|
26
|
+
|
|
27
|
+
No token input or secret is required for `command: audit`; it reads only the
|
|
28
|
+
checked-out repository. The workflow grants `contents: read` and uses
|
|
29
|
+
`pull_request`, not the privileged `pull_request_target` event.
|
|
30
|
+
|
|
31
|
+
## What happens on a violation
|
|
32
|
+
|
|
33
|
+
1. actions-warden scans workflows and composite actions with
|
|
34
|
+
`fail-on-findings: 'false'`. Findings still produce native annotations, a
|
|
35
|
+
structured job summary, and `status: FAIL`. The summary shows severity and
|
|
36
|
+
rule totals plus bounded top finding/remediation details; the JSON artifact
|
|
37
|
+
remains the complete report.
|
|
38
|
+
2. `actions/upload-artifact` runs with `if: always()` and retains
|
|
39
|
+
`actions-warden-report.json`, even when the scan found violations.
|
|
40
|
+
3. The final gate reads the Action's `status` output and exits nonzero when it
|
|
41
|
+
is `FAIL`, so branch protection can block the change.
|
|
42
|
+
|
|
43
|
+
`fail-on-findings: 'false'` does not hide or suppress findings. It only defers
|
|
44
|
+
the policy failure until after report upload. Invalid YAML, unsafe paths, and
|
|
45
|
+
other operational scanner errors still fail the scan step directly.
|
|
46
|
+
|
|
47
|
+
Later workflow steps can also read numeric outputs such as `findings`,
|
|
48
|
+
`critical`, `high`, `suppressed`, and `errors`. They are always emitted as
|
|
49
|
+
decimal strings, so a repository can add a more specific gate without parsing
|
|
50
|
+
the complete JSON report.
|
|
51
|
+
|
|
52
|
+
To make the check advisory, remove the final `Enforce Actions Warden result`
|
|
53
|
+
step. To report every severity, change `severity: high` to `severity: low`.
|
|
54
|
+
|
|
55
|
+
Reports can contain workflow paths and security evidence. Restrict workflow-log
|
|
56
|
+
and artifact access appropriately, and choose a retention period that matches
|
|
57
|
+
the repository's security policy.
|
|
58
|
+
|
|
59
|
+
## Exercise the reporting path locally
|
|
60
|
+
|
|
61
|
+
The included sample workflow is intentionally unsafe. From this repository,
|
|
62
|
+
scan it with the example policy:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
node src/cli.js audit \
|
|
66
|
+
--workflow=examples/ci-violation-reporting/violating-workflow.yml \
|
|
67
|
+
--config=examples/ci-violation-reporting/policy.yml \
|
|
68
|
+
--severity=high \
|
|
69
|
+
--format=text \
|
|
70
|
+
--explain
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The command should emit findings and exit `1`, which means the audit completed
|
|
74
|
+
and found policy violations. Exit `2` instead means the invocation or input was
|
|
75
|
+
invalid and should be fixed rather than treated as a clean result.
|
|
76
|
+
|
|
77
|
+
## Related examples
|
|
78
|
+
|
|
79
|
+
- [Baseline adoption](../baseline-adoption/README.md) accepts reviewed legacy
|
|
80
|
+
findings while blocking new ones.
|
|
81
|
+
- [SARIF Code Scanning](../sarif-code-scanning/README.md) publishes findings on
|
|
82
|
+
trusted branch and scheduled runs.
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
name: report GitHub Actions violations
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request:
|
|
5
|
+
push:
|
|
6
|
+
branches: [main]
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
permissions:
|
|
10
|
+
contents: read
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
actions-warden:
|
|
14
|
+
name: Report GitHub Actions violations
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
timeout-minutes: 10
|
|
17
|
+
steps:
|
|
18
|
+
- name: Check out repository
|
|
19
|
+
uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
|
|
20
|
+
with:
|
|
21
|
+
persist-credentials: false
|
|
22
|
+
|
|
23
|
+
- name: Audit workflows
|
|
24
|
+
id: warden
|
|
25
|
+
uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
|
|
26
|
+
with:
|
|
27
|
+
command: audit
|
|
28
|
+
severity: high
|
|
29
|
+
explain: 'true'
|
|
30
|
+
format: json
|
|
31
|
+
output-path: actions-warden-report.json
|
|
32
|
+
annotations: 'true'
|
|
33
|
+
# Defer the policy failure until after the report artifact is uploaded.
|
|
34
|
+
# Operational scanner errors still fail this step.
|
|
35
|
+
fail-on-findings: 'false'
|
|
36
|
+
|
|
37
|
+
- name: Upload violation report
|
|
38
|
+
if: always()
|
|
39
|
+
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
|
|
40
|
+
with:
|
|
41
|
+
name: actions-warden-report-${{ github.run_id }}
|
|
42
|
+
path: actions-warden-report.json
|
|
43
|
+
if-no-files-found: warn
|
|
44
|
+
retention-days: 14
|
|
45
|
+
|
|
46
|
+
- name: Enforce Actions Warden result
|
|
47
|
+
if: always() && steps.warden.outputs.status == 'FAIL'
|
|
48
|
+
shell: bash
|
|
49
|
+
env:
|
|
50
|
+
ACTIONS_WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
|
|
51
|
+
run: |
|
|
52
|
+
printf 'actions-warden reported %s blocking finding(s).\n' \
|
|
53
|
+
"${ACTIONS_WARDEN_FINDINGS:-unknown}" >&2
|
|
54
|
+
printf 'Review the annotations and downloaded JSON report.\n' >&2
|
|
55
|
+
exit 1
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# INTENTIONALLY UNSAFE: use only as scanner input in a test or throwaway branch.
|
|
2
|
+
name: intentionally unsafe workflow
|
|
3
|
+
|
|
4
|
+
on:
|
|
5
|
+
pull_request:
|
|
6
|
+
|
|
7
|
+
permissions: write-all
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
demonstrate-findings:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
steps:
|
|
13
|
+
- name: Mutable third-party Action reference
|
|
14
|
+
uses: actions/checkout@v5
|
|
15
|
+
|
|
16
|
+
- name: Unsafe pull-request data interpolation
|
|
17
|
+
run: echo "PR title is ${{ github.event.pull_request.title }}"
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# CSV reporting
|
|
2
|
+
|
|
3
|
+
This example produces a spreadsheet-friendly audit report, retains it as a
|
|
4
|
+
workflow artifact, and applies the policy gate only after the artifact step.
|
|
5
|
+
|
|
6
|
+
Copy [`github-actions.yml`](./github-actions.yml) to
|
|
7
|
+
`.github/workflows/actions-warden-csv.yml`, then replace `<FULL_COMMIT_SHA>`
|
|
8
|
+
with a reviewed actions-warden release commit that supports CSV.
|
|
9
|
+
|
|
10
|
+
CSV is useful for spreadsheet review, data warehouses, and simple compliance
|
|
11
|
+
imports. Its contract is intentionally flat:
|
|
12
|
+
|
|
13
|
+
- `record_type` is always the first column;
|
|
14
|
+
- the remaining columns are the deterministic union of fields used by the
|
|
15
|
+
command;
|
|
16
|
+
- each scanner record becomes one row;
|
|
17
|
+
- a final `STATUS` row preserves the semantic `OK` or `FAIL` result;
|
|
18
|
+
- nested values are encoded as compact JSON cells;
|
|
19
|
+
- control characters are escaped so one scanner record remains one physical
|
|
20
|
+
CSV row;
|
|
21
|
+
- cells beginning like spreadsheet formulas are prefixed with an apostrophe.
|
|
22
|
+
|
|
23
|
+
The file uses UTF-8 and CRLF row endings. It is RFC 4180-compatible, but it is
|
|
24
|
+
not the lossless actions-warden data model. Retain JSON instead when another
|
|
25
|
+
program needs nested repository metadata, a future organization comparison, or
|
|
26
|
+
the complete versioned schema.
|
|
27
|
+
|
|
28
|
+
CSV reports can expose repository paths and security findings. Restrict
|
|
29
|
+
artifact access and choose a retention period that matches the repository's
|
|
30
|
+
security policy.
|
|
31
|
+
|
|
32
|
+
For a local export:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
actions-warden audit \
|
|
36
|
+
--format=csv \
|
|
37
|
+
--output-path=actions-warden.csv
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
For organization reporting, the same format includes `REPOSITORY`, `FINDING`,
|
|
41
|
+
`ERROR`, `COVERAGE`, comparison, `SUMMARY`, and `STATUS` rows:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
actions-warden org-scan my-org \
|
|
45
|
+
--previous-report=actions-warden.previous.json \
|
|
46
|
+
--format=csv \
|
|
47
|
+
--output-path=actions-warden.current.csv
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The previous report must still be a compatible JSON organization report.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
name: actions-warden CSV report
|
|
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:
|
|
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: Generate CSV report
|
|
23
|
+
id: warden
|
|
24
|
+
uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
|
|
25
|
+
with:
|
|
26
|
+
command: audit
|
|
27
|
+
severity: high
|
|
28
|
+
explain: 'true'
|
|
29
|
+
format: csv
|
|
30
|
+
output-path: actions-warden.csv
|
|
31
|
+
annotations: 'true'
|
|
32
|
+
fail-on-findings: 'false'
|
|
33
|
+
|
|
34
|
+
- name: Upload CSV report
|
|
35
|
+
if: always()
|
|
36
|
+
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
|
|
37
|
+
with:
|
|
38
|
+
name: actions-warden-csv-${{ github.run_id }}
|
|
39
|
+
path: actions-warden.csv
|
|
40
|
+
if-no-files-found: warn
|
|
41
|
+
retention-days: 14
|
|
42
|
+
|
|
43
|
+
- name: Enforce policy after upload
|
|
44
|
+
if: always()
|
|
45
|
+
shell: bash
|
|
46
|
+
env:
|
|
47
|
+
WARDEN_STATUS: ${{ steps.warden.outputs.status }}
|
|
48
|
+
WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
|
|
49
|
+
WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
|
|
50
|
+
run: |
|
|
51
|
+
if [ "$WARDEN_ERRORS" != '0' ]; then
|
|
52
|
+
printf 'actions-warden did not complete cleanly; review the job summary.\n' >&2
|
|
53
|
+
exit 1
|
|
54
|
+
fi
|
|
55
|
+
if [ "$WARDEN_STATUS" != 'OK' ] || [ "$WARDEN_FINDINGS" != '0' ]; then
|
|
56
|
+
printf 'actions-warden reported %s blocking finding(s).\n' \
|
|
57
|
+
"${WARDEN_FINDINGS:-unknown}" >&2
|
|
58
|
+
exit 1
|
|
59
|
+
fi
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# HTML organization report
|
|
2
|
+
|
|
3
|
+
This example creates a self-contained organization security dashboard, uploads
|
|
4
|
+
it as a retained workflow artifact, and enforces findings only after the
|
|
5
|
+
artifact is available for review.
|
|
6
|
+
|
|
7
|
+
Copy [`github-actions.yml`](./github-actions.yml) to a trusted workflow such as
|
|
8
|
+
`.github/workflows/actions-warden-html.yml`, then replace
|
|
9
|
+
`<FULL_COMMIT_SHA>` with a reviewed actions-warden release commit.
|
|
10
|
+
|
|
11
|
+
Configure `ACTIONS_WARDEN_ORG_TOKEN` as a GitHub App installation token or
|
|
12
|
+
fine-grained token with metadata and contents read access to the repositories
|
|
13
|
+
that should be scanned. The workflow's normal `GITHUB_TOKEN` usually cannot
|
|
14
|
+
read every repository in an organization.
|
|
15
|
+
|
|
16
|
+
The generated HTML:
|
|
17
|
+
|
|
18
|
+
- works offline and loads no external assets;
|
|
19
|
+
- shows scan scope, repository coverage, severity and rule summaries;
|
|
20
|
+
- supports search and record, severity, and repository filters;
|
|
21
|
+
- includes source links, findings, remediation, and operational errors;
|
|
22
|
+
- redacts credentials, escapes untrusted values, and uses a restrictive
|
|
23
|
+
content security policy;
|
|
24
|
+
- is capped at 32 MiB.
|
|
25
|
+
|
|
26
|
+
The report may expose private repository names, paths, and security posture.
|
|
27
|
+
Use an appropriate artifact retention period and restrict workflow access.
|
|
28
|
+
|
|
29
|
+
This one-shot dashboard disables automatic checkpointing because the example
|
|
30
|
+
does not restore state across workflow runs. Remove `auto-checkpoint: 'false'`
|
|
31
|
+
and persist `${{ steps.warden.outputs['checkpoint-path'] }}` in protected storage
|
|
32
|
+
when repeat runs should resume compatible repository results.
|
|
33
|
+
|
|
34
|
+
HTML is a human-review view, not a future `previous-report` input. Retain a JSON
|
|
35
|
+
organization report when a later scan needs new/resolved/unchanged comparison.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
name: actions-warden HTML organization report
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_dispatch:
|
|
5
|
+
schedule:
|
|
6
|
+
- cron: '41 7 * * 1'
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
organization-report:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # actions-warden-ref: v5.0.0
|
|
16
|
+
with:
|
|
17
|
+
persist-credentials: false
|
|
18
|
+
|
|
19
|
+
- name: Generate HTML organization report
|
|
20
|
+
id: warden
|
|
21
|
+
uses: chiz0me/actions-warden@<FULL_COMMIT_SHA>
|
|
22
|
+
with:
|
|
23
|
+
command: org-scan
|
|
24
|
+
organization: ${{ github.repository_owner }}
|
|
25
|
+
token: ${{ secrets.ACTIONS_WARDEN_ORG_TOKEN }}
|
|
26
|
+
severity: high
|
|
27
|
+
explain: 'true'
|
|
28
|
+
format: html
|
|
29
|
+
output-path: actions-warden-org.html
|
|
30
|
+
auto-checkpoint: 'false'
|
|
31
|
+
fail-on-findings: 'false'
|
|
32
|
+
|
|
33
|
+
- name: Upload HTML report
|
|
34
|
+
if: always()
|
|
35
|
+
uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # actions-warden-ref: v5.0.0
|
|
36
|
+
with:
|
|
37
|
+
name: actions-warden-html-organization-report
|
|
38
|
+
path: actions-warden-org.html
|
|
39
|
+
if-no-files-found: error
|
|
40
|
+
retention-days: 14
|
|
41
|
+
|
|
42
|
+
- name: Enforce organization policy after upload
|
|
43
|
+
if: always()
|
|
44
|
+
shell: bash
|
|
45
|
+
env:
|
|
46
|
+
WARDEN_STATUS: ${{ steps.warden.outputs.status }}
|
|
47
|
+
WARDEN_FINDINGS: ${{ steps.warden.outputs.findings }}
|
|
48
|
+
WARDEN_ERRORS: ${{ steps.warden.outputs.errors }}
|
|
49
|
+
WARDEN_FAILED_REPOSITORIES: ${{ steps.warden.outputs['repositories-failed'] }}
|
|
50
|
+
WARDEN_COVERAGE_COMPLETE: ${{ steps.warden.outputs['coverage-complete'] }}
|
|
51
|
+
run: |
|
|
52
|
+
if [ "$WARDEN_COVERAGE_COMPLETE" != 'true' ] || \
|
|
53
|
+
[ "$WARDEN_ERRORS" != '0' ] || \
|
|
54
|
+
[ "$WARDEN_FAILED_REPOSITORIES" != '0' ]; then
|
|
55
|
+
printf 'Organization coverage is incomplete; review the HTML artifact.\n' >&2
|
|
56
|
+
exit 1
|
|
57
|
+
fi
|
|
58
|
+
if [ "$WARDEN_STATUS" != 'OK' ] || [ "$WARDEN_FINDINGS" != '0' ]; then
|
|
59
|
+
printf 'Organization findings require review; open the HTML artifact.\n' >&2
|
|
60
|
+
exit 1
|
|
61
|
+
fi
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Webhook and notification delivery
|
|
2
|
+
|
|
3
|
+
actions-warden deliberately does not send webhooks itself. This example keeps
|
|
4
|
+
outbound credentials and provider behavior in a separate CI step while the
|
|
5
|
+
scanner remains responsible for deterministic evidence and policy status.
|
|
6
|
+
|
|
7
|
+
Copy [`github-actions.yml`](./github-actions.yml) to
|
|
8
|
+
`.github/workflows/actions-warden-notify.yml`, replace `<FULL_COMMIT_SHA>` with
|
|
9
|
+
a reviewed actions-warden release commit, and create the repository or
|
|
10
|
+
organization secret `ACTIONS_WARDEN_WEBHOOK_URL` containing an HTTPS endpoint.
|
|
11
|
+
|
|
12
|
+
The workflow:
|
|
13
|
+
|
|
14
|
+
1. saves the complete JSON report as an artifact;
|
|
15
|
+
2. constructs a bounded notification containing only status, counts, repository
|
|
16
|
+
identity, and the workflow-run URL;
|
|
17
|
+
3. reads the secret from the environment, validates HTTPS, rejects embedded
|
|
18
|
+
credentials, and posts without following redirects;
|
|
19
|
+
4. caps the notification at 16 KiB and applies request timeouts plus bounded
|
|
20
|
+
retries;
|
|
21
|
+
5. enforces the actions-warden result after delivery has been attempted.
|
|
22
|
+
|
|
23
|
+
It does not send the complete report to the webhook. Reports may contain
|
|
24
|
+
private repository names, paths, and security evidence, and provider payload
|
|
25
|
+
limits are often much smaller than an organization report. Adapt the bounded
|
|
26
|
+
JSON object to the receiving service's schema if necessary.
|
|
27
|
+
|
|
28
|
+
## ProjectDiscovery Notify
|
|
29
|
+
|
|
30
|
+
[ProjectDiscovery Notify](https://docs.projectdiscovery.io/opensource/notify/running)
|
|
31
|
+
can read a file or stdin and route it to configured Slack, Discord, Microsoft
|
|
32
|
+
Teams, Telegram, and other providers. That makes it a good optional adapter for
|
|
33
|
+
the bounded payload rather than a runtime dependency of actions-warden.
|
|
34
|
+
|
|
35
|
+
Install a reviewed, pinned Notify release through your normal tool bootstrap,
|
|
36
|
+
store its provider configuration as a masked secret, and replace the generic
|
|
37
|
+
webhook step with:
|
|
38
|
+
|
|
39
|
+
```yaml
|
|
40
|
+
- name: Send through ProjectDiscovery Notify
|
|
41
|
+
if: always() && steps.notification.outcome == 'success'
|
|
42
|
+
shell: bash
|
|
43
|
+
env:
|
|
44
|
+
NOTIFY_PROVIDER_CONFIG: ${{ secrets.NOTIFY_PROVIDER_CONFIG }}
|
|
45
|
+
run: |
|
|
46
|
+
umask 077
|
|
47
|
+
provider_config="${RUNNER_TEMP}/actions-warden-notify-providers.yml"
|
|
48
|
+
trap 'rm -f "$provider_config"' EXIT
|
|
49
|
+
printf '%s' "$NOTIFY_PROVIDER_CONFIG" > "$provider_config"
|
|
50
|
+
|
|
51
|
+
node -e '
|
|
52
|
+
const fs = require("node:fs");
|
|
53
|
+
const report = JSON.parse(fs.readFileSync("actions-warden-notification.json", "utf8"));
|
|
54
|
+
const message = `actions-warden ${report.status}: ${report.summary.findings} finding(s), ${report.summary.errors} error(s) — ${report.runUrl}`;
|
|
55
|
+
fs.writeFileSync("actions-warden-notification.txt", `${message}\n`, { mode: 0o600 });
|
|
56
|
+
'
|
|
57
|
+
|
|
58
|
+
notify \
|
|
59
|
+
-data actions-warden-notification.txt \
|
|
60
|
+
-bulk \
|
|
61
|
+
-disable-update-check \
|
|
62
|
+
-silent \
|
|
63
|
+
-provider-config "$provider_config"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Do not enable self-update in a reproducible CI job. Rotate provider secrets and
|
|
67
|
+
restrict the provider configuration to the intended destinations.
|