From c49f33465139c6aaf5b0c9fb681cab4b529d3c55 Mon Sep 17 00:00:00 2001 From: Marius Ciepluch <11855163+norandom@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:28:49 +0200 Subject: [PATCH] docs: developer-facing pre-push security guide + mcp-shift-left-agent brief [skip ci] 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 --- .kiro/specs/mcp-shift-left-agent/brief.md | 63 +++++++++++++++++++ .kiro/specs/mcp-shift-left-agent/spec.json | 10 ++++ docs/pre-push-for-developers.md | 70 ++++++++++++++++++++++ 3 files changed, 143 insertions(+) create mode 100644 .kiro/specs/mcp-shift-left-agent/brief.md create mode 100644 .kiro/specs/mcp-shift-left-agent/spec.json create mode 100644 docs/pre-push-for-developers.md diff --git a/.kiro/specs/mcp-shift-left-agent/brief.md b/.kiro/specs/mcp-shift-left-agent/brief.md new file mode 100644 index 0000000..43aa19b --- /dev/null +++ b/.kiro/specs/mcp-shift-left-agent/brief.md @@ -0,0 +1,63 @@ +# Brief: MCP shift-left agent + skills + +Status: brief / not yet specced. Proposed 2026-10-07. Delivery surface for the +qualified safety net; builds on the existing `ousast mcp` server and the product +skills. Related: `proof-arm-opencode` (the proof model), `pre-push-safety-net` +(the gate), `unseen-repo-evaluation` (the qualification). + +## Motivation + +The pre-push hook is the gate. Developers and their coding agents want the same +security feedback **earlier**, while the code is still being written, not only at +push. And in an agent-driven workflow, a mandatory security check is how a human +oversees agents: the agent's output has to clear it before it ships. + +Proposal: expose the safety net through an MCP agent and a small set of skills so +an editor or a coding agent can ask for a security read of the changed code on +demand, shift-left, and so a coding agent can be required to pass it before it +proposes a push. + +## Shape + +- **Transport:** extend the existing narrow MCP server (`ousast mcp`, stdio) that + OpenCode and other agents already speak. No new network surface; same + no-secret, bounded contract. +- **What the agent offers:** + 1. Scan the current diff with the static arm (fast, no model, no cluster) and + return findings scoped to the change, with location and a concrete repair + direction, not a confidence label. + 2. Triage a finding: explain it in plain terms and whether it is reachable. + 3. Prove on demand: hand the top candidate to the proof arm when a runnable + harness exists, and return the demonstrated proof-of-concept. +- **Skills:** the existing `openultrasast-scan` and `openultrasast-triage` + product skills, plus shift-left additions (scan-the-diff, explain-a-finding, + suggest-a-fix-direction) that a coding agent invokes mid-task. +- **Oversight mode:** a coding agent can be configured to call the scan as a + required step before it finalizes a change, so security review is automatic + rather than remembered. + +## Control (same model as the hook) + +Advisory by default; blocking is opt-in. Budget and a push/call deadline bound +the work. The inline path runs the fast static arm only; heavy proof is explicit +and lane-selected. Models and spend caps stay in `.env`. + +## Open questions for the spec + +1. Inline latency budget: in-editor feedback must return in seconds, so the + static arm must be fast on a single diff. What is the time contract, and does + the large-repo latency problem block it? +2. Return contract: exactly what a coding agent gets back (findings, locations, + repair direction, optional proof) and how it decides pass/fail in oversight mode. +3. Does oversight mode need a signed/attestable result so a reviewer can trust + that the agent actually ran the check? +4. Reuse: the `ousast mcp` tool set already exists; which tools are enough and + what is genuinely new. + +## Scope and sequencing + +This is a delivery and adoption surface, correctly **after** the safety net is +qualified on unseen repositories (G0 through G5). It is not a detection change; +it is how developers and agents consume the detection early. The proof model +improvement lives in `proof-arm-opencode`; this brief is the dev- and +agent-facing feedback channel. diff --git a/.kiro/specs/mcp-shift-left-agent/spec.json b/.kiro/specs/mcp-shift-left-agent/spec.json new file mode 100644 index 0000000..c59158a --- /dev/null +++ b/.kiro/specs/mcp-shift-left-agent/spec.json @@ -0,0 +1,10 @@ +{ + "feature_name": "mcp-shift-left-agent", + "created_at": "2026-10-07T15:10:00Z", + "updated_at": "2026-10-07T15:10:00Z", + "language": "en", + "phase": "brief", + "approvals": {"requirements": {"generated": false, "approved": false}, "design": {"generated": false, "approved": false}, "tasks": {"generated": false, "approved": false}}, + "ready_for_implementation": false, + "summary": "MCP agent + skills so developers and coding agents get the safety net's feedback early (shift-left, in-editor) and so a coding agent can be required to pass a security check before it ships. Delivery surface after G0-G5 qualification; builds on the existing ousast mcp server." +} diff --git a/docs/pre-push-for-developers.md b/docs/pre-push-for-developers.md new file mode 100644 index 0000000..ab8d20c --- /dev/null +++ b/docs/pre-push-for-developers.md @@ -0,0 +1,70 @@ +# 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`.