Open_Ultra_SAST/docs/pre-push-for-developers.md

# 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

Your backlog is full and your schedule is not yours. Security findings compete
with feature tickets, and a vague "possible vulnerability" loses that fight every
time: no one gets capacity to chase a maybe. Meanwhile you and your coding agents
ship quickly, and an agent writing code does not pause to audit itself. A
pre-push check is the place to catch a 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.

## From a finding to capacity

The point of the proof is the prioritization conversation, not just your terminal.

A theoretical warning dies in the backlog. A demonstrated proof does not: it is a
reproducible check that triggers the problem on the current code and stops once
the code is fixed. That is the thing you take to a product owner or to the
business when you need capacity. It turns "security thinks this might be a
problem" into "here is the exact input, the exact behavior, and the one-line
difference that stops it," which is something a product owner can weigh against a
feature with real information instead of fear.

So the output is built to drop into your ticket system as evidence: a location, a
concrete repair direction, and, where the app is runnable, the reproduction
itself. That is what gets a fix scheduled rather than deferred.

## 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`.