machin-secure — Vision & North Star

Source: VISION.md on GitHub

A security auditor where the tool owns no model — the calling agent is the LLM.

The problem

Static analysis tools fall into two camps, both broken for agent-first use:

  1. Heavyweight SAST (Semgrep, CodeQL, Strix): powerful, but they own the whole pipeline — the rules, the triage, sometimes the LLM call that filters false positives. They need a server, a database, a Docker sandbox, or an API key. An agent that already is an LLM ends up paying for a second LLM inside the tool, or fighting the tool's opinions about what matters.
  2. Grep-in-a-loop: cheap, but no structure — no stable finding IDs, no persisted verdicts, no CI integration, no severity taxonomy. Every run starts from zero; the agent re-triages the same false positives forever.

The north star

The tool owns the deterministic part. The agent owns the judgment.

rules.json (the moat) --> secure binary (the engine) --> JSONL / SARIF findings
                                                              |
                                          calling agent reads + reasons (its own LLM)
                                                              |
                                     secure verdict <id> keep|drop --> persisted store

secure is a regex engine with stable finding IDs and a persisted verdict store. It never calls an LLM, never holds an API key, never makes a network call to a model provider. The agent driving secure (Devin, Claude Code, any coding agent) already has a model — it reads the findings, reasons with its own context, and writes back a verdict that survives across scans.

What this means in practice

DecisionConsequence
No LLM client in the toolNo API key, no budget, no network call. The agent's own model is the filter.
rules.json is data, not codeAdd detections without recompiling. The rule pack is the actual product.
Stable finding IDs (sha256(rule|file|line))Verdicts persist across scans, across machines, across agents.
SARIF 2.1.0 outputDrops into GitHub Code Scanning, VS Code, any SARIF consumer. CI-native.
--diff / --diff-baseScans only changed files — 0.23s on a 10k-file repo with 8 changed files. The actual fix for CI latency.
No Docker, no browser, no sandboxRead-only static analysis. Never executes target code, never mutates the repo.

What it is NOT (on purpose)

The moat

The scanner is ~500 lines of MFL. rules.json is the actual product. The detection quality lives in the rule pack — the patterns, the CWE tags, the severity calibration, the language coverage. The engine is interchangeable; the rules are the accumulated knowledge. This is why the rules are plain data read fresh from disk every run: the moat must be editable without recompiling the engine.

Roadmap (only build what earns its keep)

Design principles

  1. KISS. The 15-lines-of-bash lesson: a deterministic regex engine over the filesystem finds most of what a heavyweight agent finds, with none of the infrastructure, cost, or attack surface. Complexity only when it earns its keep.
  2. Agent-first. Output is JSONL/SARIF, not prose. No TUI, no dashboard. The tool is shaped for an agent to pipe, parse, and act on — not for a human to stare at.
  3. BYOK. The tool never duplicates the LLM the operator already has. No model client, no API key, no network call to a provider. The agent is the LLM.
  4. Data over code. The rules are the moat; the engine is interchangeable. Edit detections without recompiling.
  5. Freshness over sophistication. No index, no database, no run journal. Scan the filesystem every time. The one persistent state is the agent's own verdict memory.