mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-10-16 03:49:26 +00:00
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]>
71 lines
3.5 KiB
Markdown
71 lines
3.5 KiB
Markdown
# 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
|
|
|
|
1. Install the hook in a repo: `ousast pre-push install`.
|
|
2. Push normally. Findings print at push time.
|
|
3. 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=blocking`
|
|
turns 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`.
|