Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/agent-guides/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -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@<sha> # <version>`; 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.
Expand Down
104 changes: 104 additions & 0 deletions .github/tests/test-create-release-config.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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"
1 change: 1 addition & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3093,6 +3093,7 @@ jobs:
with:
disable-issue-side-effects: true
warn-missing-breaking-bang: true
block-egress: true
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
dry-run: true
offline-test: true

Expand Down
104 changes: 102 additions & 2 deletions .github/workflows/create-release.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Comment thread
devantler marked this conversation as resolved.
Resolved

- name: 🔑 Get GitHub App Token
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)) |
Comment thread
devantler marked this conversation as resolved.
Resolved

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
Expand Down
Loading