security-floor: the server-side check that --no-verify can't skip
Contents · 8 sections
Everything local can be skipped. Git hooks don’t run with --no-verify, in a repo with its own core.hooksPath (husky, lefthook), on another machine, for a cloud agent, or for an edit made in the GitHub web editor. Agent guardrails only see their own agent. So the checks that must hold go on the server too.
security-floor is a reusable GitHub Actions workflow that every repo calls, pinned to a commit SHA, and that main requires before anything merges. It is deliberately small and boring:
- Deterministic only. No LLM, no secrets,
contents: read, every action pinned by SHA. - Secrets: gitleaks (pinned by sha256) with its default rules plus a canary rule, over the PR’s own commits or the pushed range.
- Repo-local escape hatches are ignored. A repo’s
.gitleaks.toml,.gitleaksignoreand inlinegitleaks:allowcomments don’t count. Otherwise a PR could whitelist its own secret. - Guarded paths. A PR that changes CI, scanner, git-hook or agent-review config fails on purpose. Someone with admin rights merges it past the check, knowingly.
Part of my Claude Code setup. Code: andreasheige/security-floor (public). The local half, with the same rule classes, is review-loop.
Where it sits
- agent guardrails
- pre-commit / pre-push review-loop scan + gate
- web edit / other machine / cloud agent / --no-verify
- security-floor required check on main
- main
- blocked: fix, or admin merge on purpose
- pre-commit / pre-push review-loop scan + gate leads to security-floor required check on main: push
- web edit / other machine / cloud agent / --no-verify leads to security-floor required check on main: push
- security-floor required check on main leads to main: green
- security-floor required check on main leads to blocked: fix, or admin merge on purpose: red
- agent guardrails leads to pre-commit / pre-push review-loop scan + gate
- Local: fast, but skippable
- agent guardrails
- pre-commit / pre-push review-loop scan + gate
- Server: can't be skipped
- security-floor required check on main
The local layers catch problems early, while they’re cheap to fix. The floor is the guarantee: whatever route a commit takes, it doesn’t reach main without passing the same deterministic checks.
Why a reusable workflow, pinned by SHA
If each repo kept its own copy of the checks, a PR could weaken the check and pass it in the same change. Instead:
- The rules live in one repo. The caller in each repo is a few lines that point at
security-floor’s workflow. - Callers pin a full commit SHA, never a branch or tag. A change to the floor reaches a repo only when that repo’s pin is bumped, in its own PR.
- Changing the caller is itself a guarded path, so weakening or unpinning it needs an admin merge.
The caller workflow, in each repo at .github/workflows/security-floor.yml:
name: security-floor
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
floor:
uses: andreasheige/security-floor/.github/workflows/floor.yml@<full commit SHA>
What it checks
Which commits. On a PR: from the merge base to the PR head, so only the PR’s own commits. On a push to main: from the previous main to the new one, or the whole history of a new branch.
Secrets. gitleaks’ default rules plus one extra rule for a canary token used to test the whole chain:
[extend]
useDefault = true
[[rules]]
id = "reviewloop-canary"
description = "review-loop canary"
regex = '''REVIEWLOOP_CANARY_[A-Z0-9]{20}'''
It runs with --ignore-gitleaks-allow, a separate empty ignore path and --redact, so a finding never prints the secret into the log.
Guarded paths (PRs only). The same classes review-loop treats as control-weakening:
| Class | Examples |
|---|---|
| CI config | .github/workflows/, .github/actions/, Azure Pipelines, GitLab CI, CircleCI, Buildkite, Jenkins, Bitbucket |
| Scanner config | .gitleaks.toml, .gitleaksignore, Semgrep, Trivy and osv-scanner config, .snyk, dependabot.yml |
| Repo plumbing | CODEOWNERS, .gitattributes, .gitmodules, .npmrc, .yarnrc, pip.conf |
| Git hooks | .husky/, .githooks/, lefthook.yml, .pre-commit-config.yaml |
| Review config | .review-loop.toml |
A hit fails with a clear message:
Error: This PR changes guarded config; it needs an admin merge past security-floor:
.github/workflows/security-floor.yml
Make it required
A check that only reports is advice. A ruleset on the default branch makes it a gate:
{
"name": "security-floor",
"target": "branch",
"enforcement": "active",
"conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
"bypass_actors": [
{ "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "pull_request" }
],
"rules": [{
"type": "required_status_checks",
"parameters": {
"strict_required_status_checks_policy": false,
"do_not_enforce_on_create": true,
"required_status_checks": [{ "context": "floor / floor", "integration_id": 15368 }]
}
}]
}
gh api -X POST repos/<owner>/<repo>/rulesets --input ruleset-floor.json
floor / flooris the check name a reusable workflow produces: caller job, then the called job.integration_id15368 is GitHub Actions, so a status posted by anything else can’t satisfy the check.- Admins bypass only through a PR (
bypass_mode: pull_request). They can merge a red PR on purpose, but they can’t push straight tomain.
Pair it with your normal main ruleset: no deletion, no force push, PRs required, linear history.
Prove it works
Don’t trust a security check you haven’t seen fail. After rollout I opened two PRs with a fresh canary, one each way a local check can be skipped:
echo "REVIEWLOOP_CANARY_$(LC_ALL=C tr -dc A-Z0-9 </dev/urandom | head -c20)" > canary.txt
git add canary.txt
git commit --no-verify -m "test: floor canary" # skips the local pre-commit scan
git push --no-verify -u origin test/floor-canary # skips the local pre-push gate
gh pr create --fill
The second added the same kind of line through the GitHub web editor, which no local hook ever sees. Both PRs went red on leaks found: 1 and showed as blocked. Then close them and delete the branches.
Rolling it out
- Activate the workflow in the floor repo itself.
- Add the caller to each repo, one PR per repo. Each of these PRs fails its own floor run, by design, because it adds a workflow file. Merge them as admin.
- Add the rulesets, and run the canary test.
A trap I hit: on a fork, gh pr create without -R owner/repo opens the PR against the upstream repo, someone else’s project. Always pass -R in scripts that open PRs across many repos.
Limits
- GitHub Free can’t require checks on private repos. The floor still runs there and shows red, but nothing stops a merge. My private repos rely on the local layers and a pre-push hook that refuses pushes to protected branches.
- Admins can merge past it. That’s intended, for guarded-path changes. It’s a recorded, deliberate act, not a silent one.
- Every workflow change needs an admin merge, including Dependabot PRs that bump pinned action SHAs. That’s the price of not letting a PR edit its own gate.
- It’s a floor, not a review. Secrets and guarded paths only. Code review, dependency checks and everything model-based happen earlier, in
review-loop. - An Azure DevOps version of the same step template exists as a draft for client pipelines; it isn’t published yet.
What didn’t work
- gitleaks read the repo’s ignore file anyway. gitleaks 8.30 picks up a
.gitleaksignorefrom the scanned folder even when--gitleaks-ignore-pathpoints somewhere else. The floor now deletes it from the throwaway checkout before scanning; history scanning doesn’t need the working tree. - Global hooks quietly didn’t run in some repos. Repos with husky set their own
core.hooksPath, so the machine-wide hooks never fired there. That’s the case the floor exists for. - The first rollout opened a PR in someone else’s repo. See the fork trap above.
Follows the thread to
- How this site works, part 3: deploy and guards
- How this site works, part 2: islands and the Ask Worker
- How this site works, part 1: from constants to pages
- Old knowledge into new work, part 1: the loop watched the wrong thing
- review-loop: a second model family reviews every ticket, and code decides what blocks
- My Claude Code setup: guardrails, a plan gate, shared memory and a wiki that dreams
- Throw away your IDE?