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,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,7 @@
1
+ version: 1
2
+ baseline: .actions-warden-baseline.json
3
+
4
+ # This example promotes broad token permissions into the high-severity gate.
5
+ rules:
6
+ excessive-permissions:
7
+ severity: high
@@ -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,7 @@
1
+ version: 1
2
+
3
+ # Treat broadly writable GITHUB_TOKEN permissions as a blocking high-severity
4
+ # violation for this repository.
5
+ rules:
6
+ excessive-permissions:
7
+ severity: high
@@ -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.