diff --git a/.github/agent-guides/workflows.md b/.github/agent-guides/workflows.md index 06fc2c77..e5656c6e 100644 --- a/.github/agent-guides/workflows.md +++ b/.github/agent-guides/workflows.md @@ -15,7 +15,7 @@ restored without a new ownership decision; immutable historical releases remain 1. **Use the `workflow_call` trigger** โ€” this is what makes them reusable. 2. **Pin all remote actions to commit SHAs** โ€” `uses: owner/repo@ # `; same-source self-references use native `$/` binding to the defining file's exact commit (see the catalogue reference rules). -3. **Include `step-security/harden-runner`** as the first step of every job (`egress-policy: audit`). +3. **Include `step-security/harden-runner`** as the first step of every job (`egress-policy: audit`). The one opt-in exception is `create-release.yaml`'s two release jobs: a caller that sets `block-egress` switches them to `block` with their measured allow-list, and `.github/tests/test-create-release-config.sh` keeps that list identical in both jobs and in the fixture-mode `egress-probe` job, which must reach every listed host, be refused an unlisted one in block mode, with harden-runner's denial record for that attempt, and reach that host in audit mode (#912). 4. **Set `permissions: {}` at the workflow top level** โ€” grant per-job. 5. **Set `persist-credentials: false`** on `actions/checkout` unless the job pushes. 6. **Conventional commits.** Releases follow the rules under *Releases* above. A workflow/action change consumers must receive promptly is committed as `fix:` (or `feat:`), not `ci:`/`refactor:`. The reusable `create-release.yaml` product runs semantic-release with each consumer's own configuration. diff --git a/.github/tests/test-create-release-config.sh b/.github/tests/test-create-release-config.sh index 09500700..549961c3 100755 --- a/.github/tests/test-create-release-config.sh +++ b/.github/tests/test-create-release-config.sh @@ -447,5 +447,109 @@ refs/heads/main|main|false|fail refs/heads/main||true|fail EOF +# Opt-in egress blocking (#912). Both release jobs select block mode only through block-egress and +# share one measured allow-list (#628); the credential-free offline fixture job keeps plain audit. +# The CI fixtures exercise the default and the opted-in input state. +check_block_egress() { + local wf="$1" ci_file="$2" job policy endpoints probe_run refusal + local expected_policy="\${{ inputs.block-egress && 'block' || 'audit' }}" + local expected_endpoints='api.github.com:443 github.com:443 registry.npmjs.org:443' + [[ "$(yq -r '.on.workflow_call.inputs."block-egress" | [.type, .default] | join(" ")' "$wf")" == "boolean false" ]] || + return 1 + for job in release release-protected; do + policy="$(JOB="$job" yq -r '.jobs[strenv(JOB)].steps[0].with."egress-policy" // ""' "$wf")" + endpoints="$(JOB="$job" yq -r '.jobs[strenv(JOB)].steps[0].with."allowed-endpoints" // ""' "$wf")" + [[ "$policy" == "$expected_policy" && "$endpoints" == "$expected_endpoints" ]] || return 1 + done + [[ "$(yq -o=json -I=0 '.jobs."offline-test".steps[0].with' "$wf")" == '{"egress-policy":"audit"}' ]] || return 1 + # The fixture-mode probe executes both states: the release jobs' exact hardening step, a fatal + # check of every listed host, a refused connection to an unlisted one in block mode and the same + # host reached in audit mode, so the refusal is attributable to the policy, and no credentials. + local hardening='.steps[0] | {"uses": .uses, "with": .with}' hosts="${expected_endpoints//:443/}" + [[ "$(yq -o=json -I=0 ".jobs.\"egress-probe\" | $hardening" "$wf")" == \ + "$(yq -o=json -I=0 ".jobs.release | $hardening" "$wf")" ]] || return 1 + [[ "$(yq -r '.jobs."egress-probe".if // ""' "$wf")" == "inputs.offline-test" ]] || return 1 + [[ "$(yq -o=json -I=0 '.jobs."egress-probe".steps[1].env' "$wf")" == \ + "{\"BLOCK_EGRESS\":\"\${{ inputs.block-egress }}\"}" ]] || return 1 + [[ "$(yq -o=json -I=0 '.jobs."egress-probe" | [.permissions, (."continue-on-error" // false), (.steps | length)]' "$wf")" == \ + '[{},false,2]' ]] || return 1 + [[ "$(yq -o=json -I=0 '.jobs."egress-probe".steps[1] | [(.if // "none"), (."continue-on-error" // false)]' "$wf")" == \ + '["none",false]' ]] || return 1 + probe_run="$(yq -r '.jobs."egress-probe".steps[1].run' "$wf")" + # Block mode accepts only a refused connection (curl exit 7) with harden-runner's denial record. + refusal="$( + cat <<'EOF_REFUSAL' + agent_log=/home/agent/agent.log + [[ -r "$agent_log" ]] || { + echo "::error::harden-runner's agent log $agent_log is unreadable, so a refusal cannot be attributed to the policy" >&2 + exit 1 + } + before=$(wc -l <"$agent_log") + status=0 + probe example.com || status=$? + case "$status" in + 0) + echo '::error::block mode reached unlisted host example.com' >&2 + exit 1 + ;; + 7) ;; + *) + echo "::error::the example.com probe failed with curl exit $status, not a refused connection, so it proves nothing about the policy" >&2 + exit 1 + ;; + esac + denied=false + for _ in 1 2 3 4 5; do + if tail -n "+$((before + 1))" "$agent_log" | grep -F 'domain not allowed: example.com.' >/dev/null; then + denied=true + break + fi + sleep 1 + done + [[ "$denied" == true ]] || { + echo '::error::curl was refused, but harden-runner recorded no denial of example.com for this attempt' >&2 + exit 1 + } + echo 'Block mode reached every listed host, and harden-runner denied the connection to example.com.' +EOF_REFUSAL + )" + [[ "$probe_run" == *"for host in $hosts; do"* && "$probe_run" == *"if [[ \"\$BLOCK_EGRESS\" == true ]]; then"* && + "$probe_run" == *"$refusal"* && "$probe_run" == *" probe example.com || {"* ]] || return 1 + [[ "$(yq -r '.jobs."test-create-release".with."block-egress" // "unset"' "$ci_file")" == "unset" ]] || return 1 + [[ "$(yq -r '.jobs."test-create-release-no-issue-side-effects".with."block-egress" // "unset"' "$ci_file")" == "true" ]] || + return 1 +} + +if ! check_block_egress "$workflow" "$ci"; then + echo "create-release must block egress only when opted in, with one measured allow-list in both release jobs" >&2 + exit 1 +fi + +# Controls: the check must refuse each regression below. +while IFS='|' read -r label target expression; do + cp "$workflow" "$tmp_dir/egress-workflow.yaml" + cp "$ci" "$tmp_dir/egress-ci.yaml" + yq -i "$expression" "$tmp_dir/egress-$target.yaml" + if check_block_egress "$tmp_dir/egress-workflow.yaml" "$tmp_dir/egress-ci.yaml"; then + echo "egress control was accepted: $label" >&2 + exit 1 + fi +done <<'EOF_CONTROLS' +block mode unconditional|workflow|.jobs.release.steps[0].with."egress-policy" = "block" +extra host in the protected job only|workflow|.jobs["release-protected"].steps[0].with."allowed-endpoints" += " example.com:443" +input defaults to on|workflow|.on.workflow_call.inputs."block-egress".default = true +offline fixture job blocks too|workflow|.jobs["offline-test"].steps[0].with."egress-policy" = "block" +opted-in CI state removed|ci|del(.jobs["test-create-release-no-issue-side-effects"].with."block-egress") +probe allow-list drifts from the release jobs|workflow|.jobs["egress-probe"].steps[0].with."allowed-endpoints" += " example.com:443" +probe drops the audit-mode reachability control|workflow|.jobs["egress-probe"].if = "inputs.offline-test && inputs.block-egress" +probe ignores the input|workflow|del(.jobs["egress-probe"].steps[1].env) +probe audit mode tolerates an unreachable host|workflow|.jobs["egress-probe"].steps[1].run |= sub(" probe example.com [|][|] [{]"; " true || {") +probe treats any failure as a refusal|workflow|.jobs["egress-probe"].steps[1].run |= sub(" 7[)] ;;"; " *) ;;") +probe skips the denial record|workflow|.jobs["egress-probe"].steps[1].run |= sub(" denied=false"; " denied=true") +probe skips a listed host|workflow|.jobs["egress-probe"].steps[1].run |= sub(" registry.npmjs.org; do"; "; do") +probe failure tolerated|workflow|.jobs["egress-probe"]."continue-on-error" = true +EOF_CONTROLS + echo "semantic-release issue side effects are opt-in disabled at least privilege" echo "protected-source guard accepts the protected default branch and rejects four invalid contexts" +echo "release egress blocking is opt-in, probed in both states by an executed job and rejects thirteen regressions" diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 081cd878..2c7cfe7a 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -3093,6 +3093,7 @@ jobs: with: disable-issue-side-effects: true warn-missing-breaking-bang: true + block-egress: true dry-run: true offline-test: true diff --git a/.github/workflows/create-release.yaml b/.github/workflows/create-release.yaml index 20008f02..41194f44 100644 --- a/.github/workflows/create-release.yaml +++ b/.github/workflows/create-release.yaml @@ -27,6 +27,11 @@ on: required: false default: false type: boolean + block-egress: + description: "Refuse every outbound host except the release jobs' measured allow-list (opt-in)" + required: false + default: false + type: boolean secrets: RELEASE_APP_PRIVATE_KEY: description: Named binding for the protected release environment's key; keep its value only in that environment. @@ -54,7 +59,14 @@ jobs: - name: ๐Ÿ›ก๏ธ Harden runner uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3 with: - egress-policy: audit + # Opt-in block mode (#912) refuses every host not listed here. The list is this job's + # measured egress (#628): checkout and tags, the App token and release API, and npm for + # semantic-release. Audit mode records traffic and ignores the list. + egress-policy: ${{ inputs.block-egress && 'block' || 'audit' }} + allowed-endpoints: >- + api.github.com:443 + github.com:443 + registry.npmjs.org:443 - name: ๐Ÿ”‘ Get GitHub App Token uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0 @@ -354,7 +366,14 @@ jobs: - name: ๐Ÿ›ก๏ธ Harden runner uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3 with: - egress-policy: audit + # Opt-in block mode (#912) refuses every host not listed here. The list is this job's + # measured egress (#628): checkout and tags, the App token and release API, and npm for + # semantic-release. Audit mode records traffic and ignores the list. + egress-policy: ${{ inputs.block-egress && 'block' || 'audit' }} + allowed-endpoints: >- + api.github.com:443 + github.com:443 + registry.npmjs.org:443 - name: Verify protected release source if: inputs.protected-release @@ -716,3 +735,84 @@ jobs: DISABLE_ISSUE_SIDE_EFFECTS: ${{ inputs.disable-issue-side-effects }} WARN_MISSING_BREAKING_BANG: ${{ inputs.warn-missing-breaking-bang }} run: bash .github/tests/create-release-fixture.sh + + egress-probe: + name: Release egress probe + # Fixture mode never runs the release jobs, so this job proves their egress policy instead. It + # reads the input through the same policy and allow-list and must reach every listed host. In + # block mode it must be refused an unlisted host, with harden-runner's own denial record for that + # attempt; in audit mode it must reach that same host (#912). It holds no credentials and never + # runs for a real release. + if: inputs.offline-test + timeout-minutes: 5 + runs-on: ubuntu-latest + permissions: {} + steps: + - name: ๐Ÿ›ก๏ธ Harden runner + uses: step-security/harden-runner@46b06cea07f9e64621fdf066ba77ac6915163d43 # v2.22.3 + with: + # Exactly the release jobs' policy and list; test-create-release-config.sh keeps them equal. + egress-policy: ${{ inputs.block-egress && 'block' || 'audit' }} + allowed-endpoints: >- + api.github.com:443 + github.com:443 + registry.npmjs.org:443 + + - name: ๐Ÿงช Reach listed hosts and check an unlisted one + shell: bash + env: + BLOCK_EGRESS: ${{ inputs.block-egress }} + run: | + probe() { + env -i PATH="$PATH" curl --disable --silent --show-error --output /dev/null \ + --proto '=https' --connect-timeout 10 --max-time 20 "https://$1/" + } + for host in api.github.com github.com registry.npmjs.org; do + probe "$host" || { + echo "::error::the egress policy refused listed host $host" >&2 + exit 1 + } + done + if [[ "$BLOCK_EGRESS" == true ]]; then + # The refusal counts only when curl's connection is rejected (exit 7) and harden-runner's + # agent log, which its post step reads from this path, records denying example.com after + # this attempt began. Anything else cannot be attributed to the policy and fails the probe. + agent_log=/home/agent/agent.log + [[ -r "$agent_log" ]] || { + echo "::error::harden-runner's agent log $agent_log is unreadable, so a refusal cannot be attributed to the policy" >&2 + exit 1 + } + before=$(wc -l <"$agent_log") + status=0 + probe example.com || status=$? + case "$status" in + 0) + echo '::error::block mode reached unlisted host example.com' >&2 + exit 1 + ;; + 7) ;; + *) + echo "::error::the example.com probe failed with curl exit $status, not a refused connection, so it proves nothing about the policy" >&2 + exit 1 + ;; + esac + denied=false + for _ in 1 2 3 4 5; do + if tail -n "+$((before + 1))" "$agent_log" | grep -F 'domain not allowed: example.com.' >/dev/null; then + denied=true + break + fi + sleep 1 + done + [[ "$denied" == true ]] || { + echo '::error::curl was refused, but harden-runner recorded no denial of example.com for this attempt' >&2 + exit 1 + } + echo 'Block mode reached every listed host, and harden-runner denied the connection to example.com.' + else + probe example.com || { + echo '::error::audit mode could not reach example.com, so a block-mode refusal would prove nothing' >&2 + exit 1 + } + echo 'Audit mode reached every listed host and example.com.' + fi diff --git a/README.md b/README.md index a5cbfd29..ab7f3632 100644 --- a/README.md +++ b/README.md @@ -361,6 +361,7 @@ jobs: | `dry-run` | Input (boolean) | `false` | No | Run semantic-release in dry-run mode (no tags or publishes) | | `offline-test` | Input (boolean) | `false` | No | Run secret-free catalogue release-decision fixtures; requires dry-run | | `protected-release` | Input (boolean) | `false` | No | Use the caller's protected `release` environment and dedicated App credentials; see [setup and acceptance](.github/agent-guides/protected-releases.md) | +| `block-egress` | Input (boolean) | `false` | No | Refuse every outbound host from the release job except `github.com`, `api.github.com` and `registry.npmjs.org`, the hosts it was measured to reach ([#912](https://github.com/devantler-tech/.github/issues/912)) | The protected mode obtains `RELEASE_APP_CLIENT_ID` and `RELEASE_APP_PRIVATE_KEY` from the caller's `release` environment. Explicitly bind `RELEASE_APP_PRIVATE_KEY` in the caller's