{
  "markdown": "# SENTINEL\n\n**AI-powered contextual security auditing platform. Thinks like a red team operator, not a linter.**\n\n[![CI](https://github.com/Wembie/Sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/Wembie/Sentinel/actions/workflows/ci.yml)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io)\n\n---\n\nSENTINEL is a security auditing engine that combines AST analysis, taint flow tracking, call graph traversal, and LLM-powered contextual reasoning to surface realistic vulnerabilities and exploit chains — not just grep hits.\n\n**Basic SAST finds `eval(user_input)`. SENTINEL finds the full path: HTTP param → deserialization → `eval` → RCE, explains why it's exploitable, and shows the attack chain.**\n\n---\n\n## Install\n\n```bash\n# macOS / Linux / WSL / Git Bash\ncurl -fsSL https://raw.githubusercontent.com/Wembie/Sentinel/main/install.sh | bash\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/Wembie/Sentinel/main/install.ps1 | iex\n```\n\nDetects 30+ agents and registers for each automatically. One-line install, no manual config.\n\n**Install flags:**\n\n```bash\nbash install.sh --all          # install + hooks + init\nbash install.sh --with-hooks   # add Claude Code SessionStart hook\nbash install.sh --with-init    # write agent rules to current project\nbash install.sh --minimal      # plugin/skills only, no hooks\nbash install.sh --dry-run      # preview without writing\nbash install.sh --list         # show detected agents\n```\n\n**What gets installed:**\n- SENTINEL as MCP server registered with your agents\n- Agent rule files (`.cursor/rules/`, `.windsurf/rules/`, `.clinerules/`)\n- Skills CLI entries for 30+ additional agents\n- Claude Code hooks (with `--with-hooks`) for auto-activation at session start\n\n**No API key required.** All structural analysis (AST, rules, graph) works offline. LLM enrichment is opt-in.\n\n---\n\n## Quick Start\n\n```bash\n# Audit a codebase — no configuration needed\nsentinel audit ./my-project --no-llm\n\n# With LLM enrichment (Claude)\nSENTINEL_LLM_API_KEY=sk-ant-... sentinel audit ./my-project\n\n# Output SARIF for GitHub Code Scanning\nsentinel audit ./my-project -f sarif -o results.sarif\n\n# Audit only the security diff on a PR\nsentinel diff ./my-project --base main\n\n# List all detection rules\nsentinel rules\n```\n\nFirst run works with zero setup. No `.env` to copy, no config to write.\n\n---\n\n## MCP Integration\n\nSENTINEL runs as an MCP server — a local process your agent connects to and invokes as tools. Once registered, your agent calls `sentinel_audit`, `sentinel_trace`, and the rest exactly like any built-in tool.\n\n```bash\n# Start the MCP server manually (usually handled by your agent)\nsentinel-mcp\n\n# Or via uv (development)\nuv run python -m sentinel.mcp\n```\n\n**Automatic registration** — the installer writes the MCP server config for each detected agent. For Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"sentinel\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--project\", \"~/.sentinel\", \"python\", \"-m\", \"sentinel.mcp\"]\n    }\n  }\n}\n```\n\n**Supported agents and runtimes:**\n\n| Category | Agents |\n|----------|--------|\n| Claude family | Claude Code, Claude Desktop |\n| IDE agents | Cursor, Windsurf, Cline, Continue, Roo |\n| Terminal | Codex, Aider, Aider-Desk |\n| Web | Copilot, Devin, OpenHands, v0 |\n| Skills CLI | 30+ additional agents via `npx -y skills add` |\n\nConfiguration is portable — one install works across all agents without per-agent manual setup.\n\n---\n\n## MCP Tools\n\nThirteen tools covering the full offensive analysis lifecycle:\n\n| Tool | Purpose |\n|------|---------|\n| `sentinel_audit` | Full deep audit — AST, call graph, all rules, LLM enrichment |\n| `sentinel_surface` | Fast attack surface map: endpoints, auth entry points, exposed data |\n| `sentinel_trace` | Taint flow: user input → dangerous sinks (SQLi, RCE, SSRF) |\n| `sentinel_attack_graph` | Trust boundary and privilege escalation graph (Mermaid output) |\n| `sentinel_logic` | IDOR, BAC, unvalidated redirects, business logic flaws |\n| `sentinel_review` | Deep single-file security review |\n| `sentinel_verify` | Confirm or dismiss a specific finding |\n| `sentinel_diff` | Security impact of a git diff — PR and commit auditing |\n| `sentinel_harden` | Hardening checklist generated from live codebase scan |\n| `sentinel_exploit_chain` | Full exploitation chain narrative for a specific finding |\n| `sentinel_hunt` | Tag-focused scan: `injection`, `auth`, `secrets` |\n| `sentinel_rules` | List all registered detection rules with metadata |\n| `sentinel_report` | Retrieve a stored audit as markdown / json / sarif |\n\n**Typical workflows:**\n\n```\n# Full audit → taint trace → exploit chain → SARIF export\nsentinel_audit(target=\"./\")\nsentinel_trace(audit_id=\"<id>\")\nsentinel_exploit_chain(audit_id=\"<id>\", finding_id=\"<top finding>\")\nsentinel_report(audit_id=\"<id>\", format=\"sarif\")\n\n# PR security review\nsentinel_diff(repo_path=\"./\", base=\"main\")\nsentinel_verify(audit_id=\"<id>\", finding_id=\"<finding>\")\n\n# Targeted injection hunt\nsentinel_hunt(target=\"./\", tags=\"injection,sqli\")\nsentinel_logic(audit_id=\"<id>\")\nsentinel_attack_graph(audit_id=\"<id>\")\n```\n\n---\n\n## Skills\n\nSENTINEL ships nine skills — structured prompts that give agents deep context on how to use each tool effectively.\n\n| Skill | Trigger |\n|-------|---------|\n| `sentinel-audit` | Full codebase security audit workflow |\n| `sentinel-surface` | Attack surface enumeration |\n| `sentinel-trace` | Taint flow and injection path analysis |\n| `sentinel-attack-graph` | Trust boundary and privilege escalation |\n| `sentinel-logic` | IDOR, BAC, business logic analysis |\n| `sentinel-review` | Single-file deep review |\n| `sentinel-diff` | PR / git diff security review |\n| `sentinel-exploit-chain` | Exploitation chain narrative |\n| `sentinel-harden` | Hardening recommendations |\n\nSkills are discovered automatically by the Skills CLI and compatible agents. Install via:\n\n```bash\nnpx -y skills add https://github.com/Wembie/Sentinel\n```\n\nIn agents that support slash commands, invoke as `/sentinel-audit`, `/sentinel-diff`, etc.\n\n---\n\n## Claude Code Hooks\n\nSENTINEL ships a `SessionStart` hook that auto-injects tool availability context at the start of every session — no slash command needed.\n\n```bash\n# Install once\nbash ~/.sentinel/hooks/install.sh\n\n# Windows\n& \"$HOME\\.sentinel\\hooks\\install.ps1\"\n```\n\nThe hook checks if SENTINEL is registered as an MCP server and injects a tool reminder into the system prompt. A `🛡 SENTINEL` badge appears in the statusline when active.\n\n```bash\n# Uninstall\nbash ~/.sentinel/hooks/uninstall.sh\n```\n\n---\n\n## Per-Project Setup\n\nWrite SENTINEL agent rules into any project root:\n\n```bash\nsentinel init\n# or with uv:\nuv run sentinel init\n```\n\nWrites:\n- `.cursor/rules/sentinel.mdc`\n- `.windsurf/rules/sentinel.md`\n- `.clinerules/sentinel.md`\n- Appends to `AGENTS.md`\n- Appends to `.github/copilot-instructions.md`\n\nSafe to re-run (idempotent). Use `--force` to overwrite existing files.\n\n---\n\n## Configuration\n\nAll config via environment variables — no config file required. Sensible defaults work out of the box.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SENTINEL_LLM_PROVIDER` | `none` | `claude` \\| `openai` \\| `none` |\n| `SENTINEL_LLM_MODEL` | `claude-sonnet-4-6` | Model identifier |\n| `SENTINEL_LLM_API_KEY` | — | API key (optional, LLM enrichment only) |\n| `SENTINEL_LOG_LEVEL` | `INFO` | `DEBUG` \\| `INFO` \\| `WARNING` |\n| `SENTINEL_MAX_FILE_SIZE_KB` | `512` | Per-file size cap |\n| `SENTINEL_MAX_FILES_PER_AUDIT` | `1000` | File count cap per audit |\n| `SENTINEL_RULES_DIRS` | — | Extra rule directories (colon-separated) |\n| `SENTINEL_PLUGIN_DIRS` | — | Extra plugin directories |\n\n**Config file** (optional, higher priority than env vars):\n`~/.config/sentinel/config.json` or `~/.sentinel/config.json`\n\n```json\n{\n  \"llm_provider\": \"claude\",\n  \"llm_api_key\": \"sk-ant-...\",\n  \"log_level\": \"INFO\"\n}\n```\n\n---\n\n## REST API\n\n```bash\n# Start server\nsentinel serve --port 8000\n\n# Submit audit\ncurl -X POST http://localhost:8000/audit/ \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"target\": \"/path/to/project\", \"llm_enabled\": false}'\n\n# Get result\ncurl http://localhost:8000/audit/{id}\n\n# Get report\ncurl \"http://localhost:8000/audit/{id}/report?fmt=sarif\"\n```\n\n---\n\n## Adding Rules\n\nDrop a Python file in `sentinel/rules/builtin/` or any directory in `SENTINEL_RULES_DIRS`:\n\n```python\nfrom sentinel.rules.base import BaseRule, RuleMetadata\nfrom sentinel.models.finding import Finding, Severity, Confidence\n\nclass MyRule(BaseRule):\n    metadata = RuleMetadata(\n        id=\"CUSTOM-001\",\n        title=\"Unsafe deserialization\",\n        severity=\"critical\",\n        confidence=\"high\",\n        cwe_ids=[\"CWE-502\"],\n        languages=[\"python\"],\n    )\n\n    async def match(self, ctx):\n        findings = []\n        for path, content in ctx.file_contents.items():\n            if \"pickle.loads\" in content:\n                findings.append(Finding(...))\n        return findings\n```\n\nRules implement a `Protocol` — no imports from sentinel base classes required at runtime.\n\n---\n\n## Architecture\n\n```\nsentinel/\n├── core/\n│   ├── engine.py       # Orchestrator — wires subsystems, drives pipeline\n│   ├── pipeline.py     # Composable async stage runner\n│   ├── context.py      # AuditContext — accumulation bus across all stages\n│   └── registry.py     # Generic plugin registry with @register decorator\n├── models/             # Finding, AuditRequest/Result, GraphNode/Edge (Pydantic)\n├── graph/              # NetworkX call graph — trust boundaries, taint paths\n├── llm/                # LLMProvider Protocol + Claude and OpenAI backends\n├── parsers/            # File ingestion + tree-sitter AST extraction\n├── rules/              # Rule Protocol + builtin rules (injection, auth)\n├── reporting/          # Markdown, JSON, SARIF 2.1.0 reporters\n├── api/                # FastAPI REST API with lifespan engine init\n├── tracing/            # AuditTracer with async span context manager\n├── plugins/            # External plugin discovery from directories\n└── mcp.py              # MCP server — all 13 tools exposed as MCP endpoints\n```\n\n**Design principles:**\n\n- **Protocol-based interfaces** — every boundary (Rule, Parser, Analyzer, LLMProvider, ReportFormatter) is a structural `Protocol`. Plugins implement the interface without importing from sentinel.\n- **AuditContext as accumulation bus** — single mutable object flows through every stage. No shared class state, no threading issues.\n- **LLM as oracle, not driver** — AST + rule analysis pre-filters candidates first. LLM enrichment is opt-in and cost-predictable.\n- **Graph as first-class citizen** — functions, classes, endpoints, and data flows are nodes. Trust levels annotate nodes. Edges carry taint markers.\n\n---\n\n## Audit Pipeline\n\n| Stage | What happens |\n|-------|-------------|\n| `ingest` | Reads source files into `ctx.file_contents` |\n| `parse_ast` | Runs tree-sitter, stores ASTs in `ctx.parsed_files` |\n| `build_graph` | Builds call graph of files/functions/classes |\n| `run_rules` | Runs all rules concurrently, collects findings |\n| `llm_enrich` | (opt-in) LLM contextual reasoning over top findings |\n\n---\n\n## Development\n\n```bash\n# Clone and install with dev dependencies\ngit clone https://github.com/Wembie/Sentinel\ncd Sentinel\nuv sync --group dev\n\n# Run tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=sentinel\n\n# Lint\nuv run ruff check sentinel/\nuv run black --check sentinel/\nuv run mypy sentinel/\n\n# List builtin rules\nuv run sentinel rules\n```\n\nPython 3.11+ required. All tooling managed via [uv](https://docs.astral.sh/uv/).\n\n---\n\n## Contributing\n\n1. Fork → branch → PR to `main`\n2. New rules go in `sentinel/rules/builtin/` or as a documented pattern in the PR\n3. New MCP tools: add to `sentinel/mcp.py` + add a corresponding `skills/<name>/SKILL.md`\n4. CI runs ruff, mypy, black, and pytest on every PR\n\nIssues and PRs welcome. Keep diffs small, findings clear, and test coverage honest.\n\n---\n\n## License\n\nMIT — audit freely, ship securely.\n",
  "bytes": 12258,
  "sha": "2f751fa49fb7a98baf07f5a0a8e667e7a1a910ca562599d9c80c8a38f12c4e74",
  "repo_slug": "wembie/sentinel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_wembie_sentinel_ca24bbd2/readme"
}