# AI Security Knowledge Base (`secure-kb`)

**An AI security knowledge base — security check cards an AI coding agent can search.**

> Keywords: AI security · AI agent security · OWASP ASVS · WSTG · MASTG · Top 10 · LLM security · prompt injection · secure code review · AppSec · DevSecOps · MCP · Claude · Cursor

2,052 atomic check cards distilled from 67 **tracked sources** — cards are drawn from 15 public
repositories plus 5 official-doc sources — each traceable to a real
file, anchor and commit.

> **Status: public beta (v0.9.16).** The build is reproducible — the same pinned sources produce the
> same `content_hash` on any day, verified in CI against `CORPUS_DATE`; retrieval targets are
> **not yet met**, so this is deliberately not v1.0.0. See [Benchmarks](#benchmarks) and
> [Known limitations](#known-limitations).

[**Website →**](https://pavnxet.github.io/ai-security-knowledge-base/) ·
[Releases](https://github.com/pavnxet/ai-security-knowledge-base/releases) ·
[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)

---

## What it is — and what it is not

**It is** a retrieval layer for AI agents: a merged, normalised corpus of security *checks* with
provenance, a platform router, a fast gate, and a zero-dependency SQLite FTS5 index.

**It is not** a scanner, and it does not replace a professional security audit. It tells an agent
*what to verify*; tool adapters only describe how to invoke external scanners.

## Install in 60 seconds

Zero required dependencies (standard-library Python only). `index/` and `index/kb.sqlite` build
themselves on first use.

```bash
git clone https://github.com/pavnxet/ai-security-knowledge-base.git
cd ai-security-knowledge-base

python3 cli/secure_kb.py detect /path/to/project
python3 cli/secure_kb.py profile web --gate fast --format brief
python3 cli/secure_kb.py search "how do I stop sql injection" --k 5
python3 cli/secure_kb.py get SKB-ASVS-V1-2-4 --format md
```

**No-build fallback** — the index ships as shards, so plain tooling works with no build step:

```bash
cat index/checks/*.jsonl | jq -c 'select(.severity=="critical")'
cat index/checks/*.jsonl | grep -c "SKB-ASVS"
```

## The five-step agent workflow

1. **Detect** the stack (`detect`) → ranked platforms.
2. **Profile** it (`profile <platform> --gate fast`).
3. **Gate** — the top checks by priority, domain-balanced, in a small token budget.
4. **Drill down** (`get <id>`, or by CWE / ASVS / MASVS ref).
5. **Report** — pass / fail / n-a / unknown, with evidence. No “pass” without evidence.

## MCP setup

The MCP server exposes `detect_stack`, `get_profile`, `search_checks`, `get_check`, `start_report`,
`submit_result`, `list_tools`, **`attest`**, **`verify_attestation`** (9 tools — run `list_tools` to enumerate).

**Claude Code**

```bash
claude mcp add secure-kb -- python3 /abs/path/to/secure-kb/mcp/server.py
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{ "mcpServers": { "secure-kb": {
  "command": "python3",
  "args": ["/abs/path/to/secure-kb/mcp/server.py"] } } }
```

**Generic MCP client** — JSON-RPC 2.0 over stdio; `initialize` then `tools/call`.

## Use it as an agent skill (new)

`secure-kb` ships as an **Agent Skills** bundle, so Claude Code, Codex, OpenCode, Pi and any other
harness that follows the spec can use it directly. A skill is just a folder with a `SKILL.md`, so
installing it means placing (or symlinking) it where your harness looks for skills:

```bash
git clone https://github.com/pavnxet/ai-security-knowledge-base && cd ai-security-knowledge-base
./skills/secure-kb-audit/scripts/install.sh --claude     # ~/.claude/skills/
./skills/secure-kb-audit/scripts/install.sh --agents     # ~/.agents/skills/  (Codex/OpenCode/Pi)
./skills/secure-kb-audit/scripts/install.sh              # auto-detect every harness present
```

Then invoke it either way:

- **Automatically** — ask *"audit this repo for security bugs"* and the skill loads on its own.
- **Directly with a slash command** — a skill's `name` becomes the command, so in Claude Code type
  **`/secure-kb-audit ./my-app`** (or `/` to pick it from the menu). Whatever you type after the
  command is passed to the skill as `$ARGUMENTS`. Codex/OpenCode match on the description or invoke
  the `skill` tool by name; Pi uses `/skill:secure-kb-audit`.

Either way the agent runs the detect → gate → check → report → attest workflow and returns a
severity-grouped report where every finding carries `file:line` evidence. See
[`skills/secure-kb-audit/SKILL.md`](skills/secure-kb-audit/SKILL.md).

## Verifiable Security Attestation (new)

An agent's security claim is normally unfalsifiable prose. `secure-kb` can instead emit a
**Verifiable Security Attestation** — a deterministic, tamper-evident record of *which checks were
run, against which KB build, on which exact code fingerprint* — that anyone can verify **offline**:

```bash
secure-kb attest ./my-app --gate fast --key "$KEY" --out attestation.json
secure-kb verify-attestation attestation.json --key "$KEY" --path ./my-app   # -> VALID, exit 0
```

Any edit to the checks, a different KB build, or a changed target all make verification **fail**.
See [`docs/ATTESTATION.md`](docs/ATTESTATION.md). Also available over MCP as `attest` /
`verify_attestation`.

## What's in it

| Source | Cards | Licence |
|---|---|---|
| OWASP Cheat Sheet Series | 1,032 | CC BY-SA 4.0 |
| yesmayank/secure-coding-baseline (Tier-2) | 353 | MIT |
| OWASP ASVS 5.0 | 339 | CC BY-SA 4.0 |
| OWASP WSTG | 112 | CC BY-SA 4.0 |
| raroque/vibe-security-skill (Tier-2) | 40 | see `LICENSES/` |
| kadenzipfel/smart-contract-vulnerabilities | 38 | see `LICENSES/` |
| OWASP MASTG (Android/iOS tests) | 32 | CC BY-SA 4.0 |
| OWASP MASVS | 20 | CC BY-SA 4.0 |
| OWASP ISTG (IoT) | 15 | CC BY-SA 4.0 |
| shieldfy/API-Security-Checklist (Tier-2) | 13 | see `LICENSES/` |
| crytic/not-so-smart-contracts | 11 | see `LICENSES/` |
| OWASP Top 10 / LLM Top 10 / API Top 10 | 10 / 10 / 9 | CC BY-SA 4.0 |
| mgreiler/secure-code-review-checklist (Tier-2) | 8 | see `LICENSES/` |
| Authored (Telegram, Chrome, Electron — official docs) | 15 | CC BY-SA 4.0 |
| **Total** | **2,052** | |

Cards use **source-identity IDs** — `SKB-<SRC>-<official-id>` (e.g. `SKB-ASVS-V3-4-5`,
`SKB-WSTG-INFO-01`) or a short hash of `repo|path|anchor`. Merged cards keep every member id in
`aliases[]`, so any historical id still resolves. See [`docs/PIPELINE.md`](docs/PIPELINE.md).

## Benchmarks

Held-out sets, frozen. **Strict** metrics (mapped refs only) — reported as measured.

| Set | n | recall@5 | Target | Status |
|---|---|---|---|---|
| Held-out (all) | 154 | **0.70** | ≥ 0.70 | ~met |
| Curated v2 (standards-derived) | 59 | **0.48** | ≥ 0.60 | below |
| v2_dev (developer vocabulary) | 40 | **0.53** | ≥ 0.60 | below |
| Curated v1 | 59 | **0.25** | — | reference |
| Templated | 95 | **0.92** | ≥ 0.90 | met |
| Fast-gate recall (strict) | 30 | **46.7%** | ≥ 0.70 | below |

Determinism: two consecutive rebuilds — and a rebuild with **shuffled** staging input — produce the
identical `manifest.content_hash` `a57da404205eada6`. Reproduce with
`python3 scripts/fetch_sources.py && python3 scripts/ingest_from_cache.py && python3 scripts/build_cards_v2.py`.

## Known limitations

The honest list lives in **[`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md)**, with the measured numbers
and a test that keeps them in sync with `bench/results.json`. The headlines:

- **Retrieval is below target on paraphrase** — held-out 0.695 (target 0.70), `curated_v2` 0.475 and
  `v2_dev` 0.525 (target 0.60); `templated` 0.916 meets its target. Retrieval is lexical, not semantic.
- **The `fast` gate covers 14 of 30 lab classes (46.7%)**, against a 70% target — use `--gate full`.
- **99% of cards' `fix` field is a pointer, not guidance** — a card reliably says *what to check*,
  rarely *how to fix it*.
- **It does not scan anything**, and an attestation proves what was claimed, not that it is true.

## Security posture

This project holds itself to the standard it asks of you. Four documents, all short, all
machine-checked where it matters:

| Document | What it settles |
|---|---|
| [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) | Assets, trust boundaries, assumptions, and 17 risks (`R-001`–`R-017`) each with a mitigation *and* a verification |
| [`risk-register.yaml`](risk-register.yaml) | Every accepted, deferred or open risk with its reason and review date — CI fails if an accepted risk has no reason, if a mitigation points at a test that doesn't exist, or if a review date lapses |
| [`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md) | The measured limits, checked against `bench/results.json` so the page cannot drift |
| [`SECURITY.md`](SECURITY.md) | How to report a problem here, and what to expect |

## Licence & attribution

- **Content:** CC BY-SA 4.0, where provenance and upstream terms permit; attribution and ShareAlike
  preserved. Unlicensed / reference-only sources are not redistributed.
- **Code:** MIT.
- **Human legal review recommended.** No OWASP endorsement is implied.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). New cards require provenance: source repo, path, anchor,
commit, licence.

## Security

See [SECURITY.md](SECURITY.md) for private vulnerability reporting, and
[`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md) for this project's own threat model — what it
protects, what it assumes, and which risks it knowingly accepts. The decisions behind it live in
[`risk-register.yaml`](risk-register.yaml), which CI checks: an "accepted" risk must carry a reason
and a review date, and a "mitigated" one must point at a test or CI job that actually exists.

## Citation

See [CITATION.cff](CITATION.cff).