Marius CiepluchandClaude Opus 4.8
c49f334651
docs/pre-push-for-developers.md: COBESY-structured guide for engineers who are strong at dev but not security. Leads with the conclusion (zero-setup, no annotations, diff-scoped, proof-backed), frames the agent-era case (a pre-push check is how you oversee coding agents), states control (advisory vs blocking, budget, lane, models), and is honest about limits with an explicit disproof condition (coverage, large-repo latency, generalization being measured by G0). .kiro/specs/mcp-shift-left-agent/: follow-up brief for an MCP agent + skills that give devs and coding agents early shift-left feedback and a required pre-push security step for agent oversight; builds on the existing ousast mcp server; sequenced after the safety net is qualified. Co-Authored-By: Claude Opus 4.8 <[email protected]>
3.5 KiB
Pre-push security for developers
You push code. This checks it for security regressions first. You do not annotate anything, you do not need a security background, and you do not change how you work.
The short version
Install a git pre-push hook once. On every push it reads the code you changed, compares it against the known risks of the frameworks you already use, and warns you before the push leaves your machine. Where it can build and run your app, it goes further and proves an issue with a demonstration: a check that triggers the problem on your change and stops triggering once the problem is fixed. By default it only advises; it never blocks until you turn blocking on.
Why this matters now
You and your coding agents ship quickly. Security is not most engineers' day job, and an agent writing code does not pause to audit itself. A pre-push check is the place to catch a security regression that you, or an agent acting for you, introduced, before it reaches the remote. In an agent-driven workflow it is the oversight step: the gate that reviews what the agent wrote, every push, without you having to become the security reviewer.
What you do
- Install the hook in a repo:
ousast pre-push install. - Push normally. Findings print at push time.
- Optionally set model keys and a spend cap in
.env; nothing else is required.
No code annotations. No markup. No per-project security config.
How it decides, without annotations
- The tool brings the security knowledge. It ships framework facts: the sources, sinks, sanitizers, and guards for common frameworks. Your code does not declare any of this.
- It looks only at your change. It builds a graph of the changed code and checks it against those framework facts, scoped to the diff, not the whole repo.
- It can prove, not just warn. When the app is runnable, the proof arm builds and runs it and demonstrates the issue by execution, so a finding is a reproducible fact, not a confidence score.
What you control
- Advisory or blocking. Advisory by default;
OUSAST_PUSH_MODE=blockingturns it into a gate. Adopt in advisory mode, build trust, then block. - Budget and deadline. One budget covers the whole push; if it runs out you get an honest "incomplete coverage" notice, never a made-up verdict.
- Where proof runs. Local sandbox, a container, or a shared cluster.
- Models and spend. Keys and caps live in
.env.
Honest limits
- Coverage follows support. It helps where the tool has framework facts and a language grammar; outside that it is weak, and third-party or vendor code is not analyzed.
- Large repositories can be slow. On big codebases the deep analysis can exceed a comfortable push deadline today; that is an open engineering problem.
- Generalization is being measured, not asserted. Whether it reliably catches real regressions and stays quiet on ordinary changes in repositories it has never seen is under active measurement. We consider the tool wrong if it misses real regressions or alarms on ordinary changes on unseen repositories, and that is exactly the catch-rate and false-alarm number the unseen-repo evaluation is producing now. Treat the advisory output accordingly until that number exists.
Where this is going
An MCP agent and skills so your editor or your coding agent gets the same check
earlier, inline, before the push, so feedback arrives while you are still writing
rather than at the gate. See the follow-up spec mcp-shift-left-agent.