Metadata-Version: 2.4
Name: CVEPaladin
Version: 0.2.0a1
Summary: Evidence-grounded vulnerability prevention for coding agents
Author: Jun Tae Kim
License: Apache-2.0
Project-URL: Homepage, https://github.com/gnrkr789/Paladin
Project-URL: Issues, https://github.com/gnrkr789/Paladin/issues
Keywords: security,cve,coding-agents,mcp,claude-code,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: mcp==2.3.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: onnxruntime<2,>=1.20
Requires-Dist: packaging>=24
Requires-Dist: pymilvus==2.6.17
Requires-Dist: tokenizers<1,>=0.21
Dynamic: license-file

<p align="center">
  <img src="https://github.com/gnrkr789/Paladin/raw/main/docs/assets/paladin-hero.svg" alt="Paladin: CVE-grounded prevention and proof for AI coding agents" width="100%">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/version-0.2.0a1-3451d1" alt="version 0.2.0a1">
  <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="python 3.11+">
  <img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache-2.0">
  <img src="https://img.shields.io/badge/tests-384%20passing-2fbf71" alt="384 unit tests passing">
</p>

Paladin stops AI coding agents from reintroducing known CVE patterns. It tells
the agent what the problem is and how to avoid it; the agent writes its own fix.

- **Prevention cards** for 524 Python web CVEs, searchable by the agent over MCP
  (e5 + BM25 hybrid). 501 are checked against the fix diff; 23 remain
  `candidate`.
- **Edit-time hook** for Claude Code and Codex, with no model or network call:
  125 rules drafted from the cards block the turn when their CVE is MEDIUM,
  HIGH or CRITICAL (104 rules), advise for LOW (7; `hook install --block-low`
  makes those block too), and advise for 14 broad rules that showed no real risk
  in sampled real code; two exact CVE rules also block. Each block names the CVE,
  line and fix.
- **Dependency check** (`paladin deps check`, MCP `check_dependencies`, and the hook
  when an agent edits a dependency file): pinned versions against the PyPI affected
  ranges of 520 collected CVEs, most of which are library-internal and have no code rule.
- **Proof loop**: reproduces a CVE and verifies a repair inside an isolated
  Docker observer before a case is recorded.

## Tested

<p align="center">
  <img src="https://github.com/gnrkr789/Paladin/raw/main/docs/assets/evaluation.svg" alt="Measured results" width="100%">
</p>

| Test | Result |
|---|---|
| Proof loop on real CVEs (Cookiecutter CVE-2022-24065, pip CVE-2023-5752) | reproduced, repaired, verified; 0 false alarms on fixed versions |
| Claude Code and Codex sessions, ported vulnerable code | blocked, agent fixed it |
| Search, fresh held-out questions (hit@5 / MRR) | 0.831 / 0.697 and 0.873 / 0.736 |
| Unit tests | 384 pass |

## How it works

<p align="center">
  <img src="https://github.com/gnrkr789/Paladin/raw/main/docs/assets/case-loop.svg" alt="Scan, reproduce, repair, verify, promote" width="100%">
</p>

## Quick start

Windows, Python 3.12, [uv](https://docs.astral.sh/uv/) and Docker Desktop.

**1. Install and build the search database (once per machine)**

```powershell
uv tool install CVEPaladin
paladin setup --json           # starts a local Milvus in Docker
paladin model prepare --json   # downloads the search model (487 MB)
paladin patterns index --json  # loads the CVE cards into Milvus
```

The package has no database. `setup` starts Milvus in Docker under
`%USERPROFILE%\.paladin` and `patterns index` fills it; every project shares it.
Only search needs it: the hook and the checks work without Docker. Run
`patterns index` again after upgrading Paladin. To work on Paladin itself, clone
the repository, run `uv sync --locked` and use `.\.venv\Scripts\paladin.exe`.

**2. Add Paladin to Claude Code and Codex (once per user)**

```powershell
paladin mcp install --user                 # Claude Code
paladin mcp install --user --host codex    # Codex
```

Open any project in a new session and run `/paladin` (Claude Code) or `$paladin`
(Codex). It checks the whole project and its pinned dependencies, explains each
finding and edits nothing until you ask. It runs only when you call it.

**3. Optional: block unsafe edits in a project**

```powershell
paladin hook install --workspace C:/projects/app                # Claude Code
paladin hook install --host codex --workspace C:/projects/app   # Codex
```

The hook checks every edit the agent makes in that project and blocks known CVE
patterns. Codex runs it after you trust it with `/hooks`. Remove the user install
with `paladin mcp uninstall --user` (add `--host codex` for Codex).

## Limits

Card rules block by CVE severity on the lines an edit writes; they are static
pattern matches, so a block can be a false positive. Single-file static checks. Patch checks are model reviews, not human review. A clean result is
not a security verdict. Project text is English ASCII.

## Docs

[Hook](https://github.com/gnrkr789/Paladin/blob/main/docs/hook.md) | [Case loop](https://github.com/gnrkr789/Paladin/blob/main/docs/case-loop.md) | [MCP](https://github.com/gnrkr789/Paladin/blob/main/docs/mcp.md) |
[Setup](https://github.com/gnrkr789/Paladin/blob/main/docs/setup.md) | [Plans](https://github.com/gnrkr789/Paladin/blob/main/docs/plans/)

## License

Apache-2.0. Bundled CVE records, patches and advisory data keep their own
licenses: [data/THIRD_PARTY.md](https://github.com/gnrkr789/Paladin/blob/main/data/THIRD_PARTY.md), [NOTICE](https://github.com/gnrkr789/Paladin/blob/main/NOTICE).
