{
  "markdown": "<p align=\"center\">\n  <h1 align=\"center\">Sentinel-KB</h1>\n  <p align=\"center\">\n    Security vulnerability scanner backed by real audit data from professional firms.\n  </p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/dolfrin/Sentinel-KB/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-AGPL--3.0-blue.svg\" alt=\"License\"></a>\n  <a href=\"https://github.com/dolfrin/Sentinel-KB/releases\"><img src=\"https://img.shields.io/badge/version-0.1.0-brightgreen.svg\" alt=\"Version\"></a>\n  <a href=\"https://github.com/dolfrin/Sentinel-KB/actions\"><img src=\"https://img.shields.io/badge/tests-passing-brightgreen.svg\" alt=\"Tests\"></a>\n  <a href=\"https://github.com/dolfrin/Sentinel-KB\"><img src=\"https://img.shields.io/badge/rules-287-orange.svg\" alt=\"Rules\"></a>\n</p>\n\n---\n\nSentinel-KB scans codebases for security vulnerabilities using **287 static analysis rules** and a **knowledge base of 15,800+ real findings** extracted from 920+ audit reports published by 85 professional security firms -- Trail of Bits, Cure53, NCC Group, QuarksLab, and more.\n\nUnlike synthetic rule sets, every pattern in the knowledge base traces back to a vulnerability that was found, reported, and fixed in a real-world audit. When Sentinel-KB flags something in your code, it can tell you which firm found the same class of bug, in what context, and how it was remediated.\n\nWorks as a **Claude Code plugin**, a **CLI tool**, and an **MCP server**.\n\n### Pipeline\n\nSentinel-KB chains four engines, each one cutting false positives further:\n\n1. **Regex** (always) -- 287 OWASP-aligned patterns, instant, offline\n2. **Triage** (always) -- drops findings on config files (`google-services.json`, lockfiles, `*.example`), downgrades severity in test paths and inline `#[cfg(test)]` blocks, applies per-rule context checks (Axum extractors, Android `LAUNCHER` activities, `withSessionLock` wrappers, etc.)\n3. **Semgrep** (optional) -- AST-based analysis when `semgrep` CLI is installed\n4. **AI triage** (optional) -- Claude Sonnet judges each finding against the knowledge base when `ANTHROPIC_API_KEY` is set\n\nAuto mode picks engines based on what's available -- no setup, no flags.\n\nMarketplace note: this repository can be installed locally as a Claude Code plugin. If an official marketplace listing is published later, installation can use the marketplace flow instead.\n\n## Quick Start\n\n### Claude Code Plugin (recommended)\n\n```bash\n# Clone the repo and install the plugin locally\ngit clone https://github.com/dolfrin/Sentinel-KB.git\ncd Sentinel-KB\nclaude plugin add .\n\n# Run a security audit on any project\nclaude> /sentinel-kb:audit /path/to/project\n\n# Search the knowledge base\nclaude> /sentinel-kb:search \"nonce reuse AES-GCM\"\n\n# Scan a single file\nclaude> /sentinel-kb:scan-file src/auth/login.ts\n\n# Show KB statistics\nclaude> /sentinel-kb:stats\n```\n\n### CLI\n\n```bash\ngit clone https://github.com/dolfrin/Sentinel-KB.git\ncd Sentinel-KB\nnpm install\n\n# Auto mode -- picks the best engines available (recommended)\nnpx tsx src/cli.ts scan /path/to/project --auto\n\n# Plain regex scan (fastest)\nnpx tsx src/cli.ts scan /path/to/project\n\n# Search the knowledge base\nnpx tsx src/cli.ts search \"SQL injection parameterized\"\n\n# View KB statistics\nnpx tsx src/cli.ts stats\n\n# SARIF output for GitHub Code Scanning\nnpx tsx src/cli.ts scan /path/to/project --auto --sarif > findings.sarif\n```\n\n## What Makes It Different\n\n| Feature | Sentinel-KB | Typical linters |\n|---------|------------|-----------------|\n| **Rule source** | Extracted from real audit reports | Written by tool authors |\n| **Coverage** | 33 categories, 287 rules | Usually 5-10 categories |\n| **Languages** | TypeScript, Java, Kotlin, Rust, Go, PHP, Ruby, Python, Solidity, Swift, C/C++ | Usually 1-3 |\n| **AI analysis** | Claude analyzes code with KB context | Pattern matching only |\n| **Knowledge base** | 15,800+ findings from 85 firms | None |\n| **False positive rate** | Tuned against real codebases | Often high |\n\n## Static Scan Categories\n\nThe 287 rules cover 33 security categories:\n\n| Category | Category | Category |\n|----------|----------|----------|\n| Injection | XSS | SSRF/CSRF |\n| Authentication | Secrets | Cryptography |\n| Session & Cookie Security | API Security | Database Security |\n| E2E Encryption | WebRTC/P2P | Messenger |\n| Android | iOS Security | Memory Safety |\n| Concurrency | Deserialization | File & Path Security |\n| Network Security | Configuration Security | Error Handling & Logging |\n| Cloud & Infrastructure | Privacy & Data Protection | Supply Chain & Dependencies |\n| Smart Contracts | Go Security | PHP Security |\n| Ruby Security | Python Security | CI/CD Security |\n| Infrastructure as Code | Input Validation | Backend |\n\nEvery rule includes CWE identifiers, severity ratings, and targeted file patterns.\n\n## Slash Commands\n\nWhen installed as a Claude Code plugin, Sentinel-KB exposes four slash commands:\n\n| Command | Description |\n|---------|-------------|\n| `/sentinel-kb:audit [path]` | Comprehensive audit in auto mode -- runs all available engines (regex + triage + Semgrep + AI triage + KB precedents), groups findings by category, links each to similar real-world audits |\n| `/sentinel-kb:search <query>` | Full-text search the knowledge base by pattern, CWE, category, or attack type |\n| `/sentinel-kb:scan-file <path>` | Quick scan of a single file with automatic triage |\n| `/sentinel-kb:stats` | Knowledge base statistics: total findings, reports, firms, severity breakdown |\n\n## MCP Tools\n\nThe MCP server exposes six tools for programmatic access:\n\n| Tool | Description | Tier |\n|------|-------------|------|\n| `audit` | Full project scan; pass `auto: true` to enable Semgrep / AI triage when available | Free |\n| `ai-audit` | AI-powered scan with KB context, batched | Requires API key |\n| `list-rules` | List all 287 detection rules | Free |\n| `scan-file` | Scan a single file | Free |\n| `kb-stats` | Knowledge base statistics | Free |\n| `search-kb` | Full-text search across 15,800+ findings | Free |\n\n## CLI Usage\n\n```bash\n# Auto mode -- picks the best engines available (recommended)\nnpx tsx src/cli.ts scan /path/to/project --auto\n\n# Plain static scan -- instant, offline, no API key needed\nnpx tsx src/cli.ts scan /path/to/project\n\n# Force-enable Semgrep (needs `pip install semgrep`)\nnpx tsx src/cli.ts scan /path/to/project --semgrep\n\n# Force-enable AI triage (needs ANTHROPIC_API_KEY)\nANTHROPIC_API_KEY=sk-... npx tsx src/cli.ts scan /path/to/project --ai-triage\n\n# Disable triage layer (raw regex output, useful for debugging)\nnpx tsx src/cli.ts scan /path/to/project --no-triage\n\n# Attach KB precedents (real-world audit findings) to each result\nnpx tsx src/cli.ts scan /path/to/project --with-kb\n\n# SARIF 2.1.0 output for GitHub Code Scanning\nnpx tsx src/cli.ts scan /path/to/project --auto --sarif > findings.sarif\n\n# JSON output\nnpx tsx src/cli.ts scan /path/to/project --json\n\n# Search the knowledge base\nnpx tsx src/cli.ts search \"buffer overflow heap\"\n\n# Show knowledge base statistics\nnpx tsx src/cli.ts stats\n\n# Update the knowledge base\nnpx tsx src/update.ts\n```\n\n### Scan flags\n\n| Flag | Effect |\n|------|--------|\n| `--auto` | Pick engines automatically based on what's available |\n| `--severity <level>` | Threshold: `high` includes `high + critical` |\n| `--category <cat>` | Filter to a single category |\n| `--include-all-dirs` | Scan dirs that are normally skipped (tests, docs, etc.) |\n| `--no-triage` | Disable path/context triage |\n| `--semgrep` | Force-enable Semgrep (needs `semgrep` CLI) |\n| `--ai-triage` | Force-enable AI judging (needs `ANTHROPIC_API_KEY`) |\n| `--min-confidence <n>` | Minimum AI confidence to keep a finding (default 60) |\n| `--with-kb` | Attach KB precedents to each finding |\n| `--sarif` | Emit SARIF 2.1.0 (GitHub Code Scanning native) |\n| `--json` | Emit structured JSON |\n\n## How It Works\n\n```\n   +-------------------+\n   |    Source code    |\n   +---------+---------+\n             |\n             v\n   +-------------------+      +-------------------+\n   |   Regex engine    +----->|   Triage layer    |\n   |  (287 rules)      |      | path & context    |\n   |  always runs      |      | always runs       |\n   +-------------------+      +---------+---------+\n                                        |\n                            optional    |\n   +-------------------+      +---------+---------+\n   |   Semgrep AST     +----->|                   |\n   | if CLI installed  |      |    AI triage      |\n   +-------------------+      |  (Claude Sonnet)  |\n                              |  if API key set   |\n                              +---------+---------+\n                                        |\n                                        v\n   +---------------------------------------------+\n   |      Findings + KB precedents               |\n   |   Severity, CWE, real-audit attribution     |\n   |   Output: text / JSON / SARIF               |\n   +---------------------------------------------+\n```\n\n**Regex** scans every source file locally for OWASP-aligned vulnerability patterns. Each finding carries severity, CWE, category, and a snippet from real audits.\n\n**Triage** post-processes findings to drop false positives:\n\n- Config files like `google-services.json`, lockfiles, and `*.example` are dropped entirely\n- Findings inside test paths or inline `#[cfg(test)]` / `mod tests` blocks are downgraded\n- Per-rule context filters check for Axum extractors, `withSessionLock` wrappers, Android `LAUNCHER` activities, generic notification strings, and other shapes regex alone can't see\n\n**Semgrep** (optional) adds AST-based analysis from the Semgrep community ruleset (~2,000 rules). Runs only when `semgrep` is on the PATH; otherwise silently skipped.\n\n**AI triage** (optional) sends each finding -- with 30 lines of code context and the top 3 KB matches by category -- to Claude Sonnet. The model returns a confidence score (0-100), `isReal` verdict, and a one-line reason. Findings below the confidence threshold are filtered; the rest get severity recalibrated based on confidence.\n\n**KB precedents** attach real-world audit findings to each result: `Cure53 -> Silencelabs: hardcoded creds [CWE-798]`. This grounds every finding in actual prior incidents.\n\n**Output formats** include human-readable text (default), structured JSON, and SARIF 2.1.0 for GitHub Code Scanning.\n\n## Knowledge Base\n\nThe knowledge base is built by crawling and extracting findings from publicly available security audit reports:\n\n- **15,800+ findings** from **920+ PDF reports** by **85 audit firms**\n- Firms include Trail of Bits, Cure53, NCC Group, QuarksLab, Consensys Diligence, OpenZeppelin, and more\n- Findings are stored in SQLite with FTS5 full-text search\n- Each finding has: severity, category, CWE mapping, description, firm attribution\n- Cross-report deduplication identifies the same vulnerability class found independently by multiple firms\n\n### Updating the KB\n\n```bash\n# Auto-detect mode: uses AI extraction if ANTHROPIC_API_KEY is set, regex otherwise\nnpx tsx src/update.ts\n\n# Force regex extraction (free, offline)\nnpx tsx src/update.ts --regex\n\n# Use a specific model for extraction\nnpx tsx src/update.ts --ai-model claude-opus-4-20250514\n\n# Show current stats\nnpx tsx src/update.ts --stats\n```\n\n## Self-Hosting\n\nSentinel-KB can run as a standalone MCP server:\n\n```bash\ngit clone https://github.com/dolfrin/Sentinel-KB.git\ncd Sentinel-KB\nnpm install\nnpm run build\n\n# Start the MCP server\nnpm start\n```\n\nData is stored locally at `~/.security-audit-kb/`:\n- `audit.db` -- SQLite database (WAL mode, FTS5)\n- `reports/` -- cached PDF audit reports\n\n## Building\n\n```bash\nnpm install       # install dependencies\nnpm test          # run test suite\nnpx tsc           # compile TypeScript\nnpm run build     # alias for tsc\n```\n\n## Contributing\n\nContributions are welcome. Areas where help is especially useful:\n\n- **New detection rules** -- add rules to `src/rules.ts` with tests\n- **Audit report sources** -- add URLs to `src/sources.ts`\n- **False positive tuning** -- add filters to `src/triage.ts` and a regression test in `src/__tests__/triage.test.ts`\n- **Per-rule context checks** -- extend `RULE_FILTERS` in `src/triage.ts` to teach the scanner about idiomatic patterns it currently flags by mistake\n- **Output formats** -- additional report formats can live alongside `formatText` / `formatJSON` / `formatSARIF` in `src/report.ts`\n- **Language support** -- extend file patterns and regex for additional languages\n\nPlease open an issue before submitting large changes.\n\n## License\n\n[AGPL-3.0](LICENSE) -- Sentinel-KB is free and open source. If you modify and distribute it, you must share your changes under the same license.\n",
  "bytes": 12697,
  "sha": "8886d912aee42d69b3a0fb51cb5fa8757d05d25ccee1501fbf9e79394faf9afc",
  "repo_slug": "dolfrin/sentinel-kb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dolfrin_sentinel_kb_sentinel_kb_9c093db4/readme"
}