{
  "markdown": "<!-- mcp-name: io.github.Varpost/scout -->\n# Scout\n\n**AI security team in a CLI.** Find vulnerabilities before hackers do — free, local, no signup.\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/scout-security)](https://pypi.org/project/scout-security/)\n\n---\n\n## Why Scout?\n\nAI coding assistants write insecure code constantly — hardcoded secrets, SQL injection, missing auth. Solo developers ship it because they don't have a security team.\n\n**Scout is that team.** Static analysis catches the most common mistakes AI assistants make — leaked keys, string-built SQL, `shell=True`, missing security headers. No API keys, no config, no cost.\n\n## Install\n\nZero-install — try it in one command with [uv](https://docs.astral.sh/uv/) (no venv, ~1s cold start):\n\n```bash\nuvx scout-security scan ./my-project\n```\n\nOr install it permanently:\n\n```bash\npip install scout-security\n```\n\n> **Using NCC ScoutSuite too?** It also installs a `scout` command, and whichever package you installed last owns the name. Scout additionally installs **`scoutsec`** — same tool, collision-proof name: `scoutsec scan ./my-project`.\n\n## Usage\n\n```bash\n# Scan a project — deterministic static analysis: no API keys, no tokens, no signup\nscout scan ./my-project\n\n# Turn the findings into ready-to-paste fix prompts for your AI assistant\nscout scan ./my-project --format ai-prompt\n```\n\n## Output Formats\n\nOne scan, four views — choose with `--format` (`-f`):\n\n```bash\n# Layer 1 — human-readable Markdown report (default)\nscout scan ./my-app\nscout scan ./my-app -o security-report.md\n\n# Layer 2 — ready-to-paste prompts for your own AI (Cursor, Claude, Copilot…)\nscout scan ./my-app --format ai-prompt          # writes security-prompts.md\nscout scan ./my-app --format ai-prompt -o prompts.md\n\n# Layer 3 — machine-readable JSON for piping into agentic tooling / CI\nscout scan ./my-app --format json               # prints JSON to stdout\nscout scan ./my-app --format json -o report.json\nscout scan ./my-app --format json | jq '.findings[]'\n\n# Layer 4 — SARIF 2.1.0 for GitHub Code Scanning (PR annotations)\nscout scan ./my-app --format sarif -o scout.sarif\n```\n\nThe same engine powers all of them — Scout finds the problem; your own AI (which already knows your codebase) applies the fix.\n\n## Use as a CI Gate\n\n`scout scan` exits **1** when findings at or above `--fail-on` (default: `high`) exist, so your pipeline fails on real problems:\n\n```bash\nscout scan . --fail-on high        # default — fail on HIGH or CRITICAL findings\nscout scan . --fail-on critical    # fail only on CRITICAL\nscout scan . --fail-on never       # report-only mode — always exit 0\n```\n\nThe GitHub Action wraps install + scan + SARIF upload, so findings show up as PR annotations via GitHub Code Scanning:\n\n```yaml\njobs:\n  scout:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      security-events: write\n    steps:\n      - uses: actions/checkout@v4\n      - uses: Varpost/Scout@v0.1.16\n        with:\n          fail-on: high            # also: path, format, upload-sarif\n```\n\nPrefer plain steps? The same thing by hand (the job still needs `security-events: write`):\n\n```yaml\n- run: |\n    pip install scout-security\n    scout scan . --no-ai --format sarif -o scout.sarif --fail-on never\n- uses: github/codeql-action/upload-sarif@v4\n  with:\n    sarif_file: scout.sarif\n```\n\n## Pre-commit Hook\n\nCatch findings before they're ever committed:\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n  - repo: https://github.com/Varpost/Scout\n    rev: v0.1.16        # use the latest tag\n    hooks:\n      - id: scout\n```\n\nThe hook runs `scout scan . --no-ai --fail-on high` from your repo root on every commit, so your `[tool.scout]` config applies. Tune the threshold with `args: [\"--fail-on\", \"critical\"]`. When it fails, Scout writes `security-report.md` with the details — worth adding to your `.gitignore`.\n\n## Suppressing Findings\n\nSilence a false positive with a trailing comment on the flagged line:\n\n```python\nresult = eval(trusted_expression)  # scout: ignore\nresult = eval(trusted_expression)  # scout: ignore[injection]\n```\n\nBare `scout: ignore` silences every finding on that line. The scoped form silences only the named scanner (`secrets`, `injection`, `headers`, `deps`, `custom`) or finding id (e.g. `injection/eval_usage` — the `id` field in `--format json`). Findings that can't carry an inline comment — the app-wide CSRF check has no meaningful line, and lockfile findings live in generated JSON — are handled by turning the scanner off via `[tool.scout] scanners` (below) or accepting them into a baseline (below).\n\n## Configuration\n\nSkip paths with `--exclude` (repeatable; relative to the scan root, globs allowed):\n\n```bash\nscout scan . --exclude tests/fixtures --exclude \"*.min.js\"\n```\n\nOr set project defaults in `pyproject.toml` — Scout reads `[tool.scout]` from the scanned project:\n\n```toml\n[tool.scout]\nexclude = [\"tests/fixtures\", \"vendor\"]   # paths or glob patterns to skip\nscanners = [\"secrets\", \"injection\"]      # run a subset: secrets, injection, headers, deps, custom\nengines = [\"semgrep\"]                    # external engines to run and merge (optional)\nrules = [\"scout-rules.yml\"]              # your own YAML detection rules (optional)\nfail_on = \"medium\"                       # default threshold for --fail-on\n```\n\nCLI flags win: `--exclude` replaces the config list, `--engine` replaces `engines`, and `--fail-on` overrides `fail_on`.\n\n## Custom Rules (optional)\n\nTeach Scout project-specific patterns with a YAML file — an id, a regex, a message, a severity:\n\n```yaml\n# scout-rules.yml — referenced from [tool.scout] rules\nrules:\n  - id: internal-api-host\n    pattern: \"internal\\\\.corp\\\\.example\"\n    message: \"Internal hostname committed to source.\"\n    severity: HIGH          # CRITICAL | HIGH | MEDIUM | LOW\n    fix_phase: 1            # optional, 1-5 (default 3)\n    suffixes: [\".py\", \".ts\"] # optional — default: every scanned file\n    fix: \"Move the hostname to configuration.\"\n```\n\nRules are deliberately grep-with-metadata — need metavariables or taint analysis? That's what `--engine semgrep` is for. A malformed rule warns on stderr and is skipped; it can never break the scan. Custom findings work everywhere native ones do: `scout: ignore[custom]`, baselines, severity gating, JSON/SARIF.\n\n## External Engines (optional)\n\nScout can orchestrate industrial OSS engines and merge their findings into its report, JSON, and SARIF output — same phased remediation plan, wider coverage:\n\n```bash\npip install semgrep                # or brew install semgrep\nscout scan . --engine semgrep      # native scanners + semgrep, merged & deduped\n\n# CodeQL — GitHub's semantic analysis engine (CLI from\n# https://github.com/github/codeql-cli-binaries, on PATH as `codeql`)\nscout scan . --engine codeql       # builds a CodeQL DB per language (python/js),\n                                   # runs the official security queries, merges the SARIF\n```\n\n`--engine codeql` runs the same query suite GitHub code scanning uses, so a Scout report can carry full semantic-analysis findings — expect it to take minutes, not seconds (database extraction is CodeQL's design, not Scout overhead).\n\nEngines are strictly opt-in: the default scan stays zero-dependency and fully deterministic. A requested engine that isn't installed is skipped with a one-line note — never a crash. Engine findings that land on a line a native scanner already flagged are dropped in favor of Scout's own fix guidance.\n\n## VS Code Extension\n\n[scout-vscode/](scout-vscode/) wraps the CLI as a VS Code extension: saving a Python/JS/TS file scans just that file (sub-second) and shows findings as inline squiggles, with taint-traced ones marked *reachable from user input*. A **Scout: Scan Workspace** command fills the Problems panel for the whole project. It shells out to `scoutsec`, so your `[tool.scout]` config applies unchanged.\n\n## Adopting Scout on an Existing Codebase (Baseline)\n\nDon't want to fix years of findings before turning the CI gate on? Accept the current state, then fail only on new findings:\n\n```bash\nscout scan . --write-baseline                   # accept current findings → .scout-baseline.json\nscout scan . --baseline .scout-baseline.json   # report and fail only on NEW findings\n```\n\nCommit `.scout-baseline.json`. Finding identity is content-based — the rule, the file, and a hash of the flagged line, deliberately **no line numbers** — so baselined findings stay accepted when unrelated edits shift them up or down a file. Changing the flagged line itself brings the finding back for review.\n\n## Scanning Git History for Secrets\n\nA secret committed and later removed is still compromised — a scan of today's code can't see it:\n\n```bash\nscout scan . --git-history        # secrets in every added line of every commit, all branches\n```\n\nFindings are anchored to the commit that introduced them (`config.py @ 1a2b3c4d5e6f`) — **rotate anything it reports**; deleting the line doesn't un-leak the credential. Needs `git` on PATH; scans history *instead of* the working tree.\n\nHonest scope: [Gitleaks](https://github.com/gitleaks/gitleaks) and [TruffleHog](https://github.com/trufflesecurity/trufflehog) do deep, fast history auditing as their core job — Scout's pass is the built-in convenience, not a replacement.\n\n## What It Finds\n\n| Scanner | Detects | Severity |\n|---------|---------|----------|\n| `secrets` | AWS/Google keys, GitHub/GitLab tokens, Anthropic & OpenAI keys, Slack/npm/PyPI tokens, Stripe keys, DB URLs, private keys, passwords | CRITICAL |\n| `injection` | SQL injection, NoSQL operator injection, command injection, eval()/Function/vm, XSS | CRITICAL |\n| `injection` (taint-gated) | Path traversal (file reads/writes, `sendFile`), SSRF (`fetch`/`requests`/`axios`), insecure deserialization (`pickle`/`yaml.load`/`unserialize`), open redirect (`redirect(...)`) — fire only when user input reaches the sink | HIGH |\n| `injection` (keyword-gated) | Weak randomness for tokens/secrets (`Math.random`/`random.*` used for a token/password/OTP) | MEDIUM |\n| `headers` | Missing security headers (Express/Flask/Django/FastAPI), wildcard CORS, missing CSRF | LOW–MEDIUM |\n| `deps` | Known vulnerabilities in pip + npm dependencies (via OSV.dev) | HIGH |\n\n### Language scope\n\nDeep analysis — **injection** (SQL/command/XSS) and **security headers** — targets **Python and JS/TS**, where the detection patterns are idiom-specific. Both languages get intra-file **taint tracking** (Python via the stdlib AST, JS/TS via a lexical pass): findings carry a `reachable` verdict when a sink traces back to user input (`request.*`, `req.body`, `location.hash`, …), ORM/NoSQL sinks fire *only* on taint evidence, and XSS sinks fed by provable in-file constants are dropped instead of reported. The same taint engine powers **path traversal** (`open`/`fs.readFile`/`sendFile`), **SSRF** (`requests`/`fetch`/`axios`), **insecure deserialization** (`pickle`/`yaml.load`/`unserialize`), and **open redirect** (`redirect(...)`) detection — all gated on reachability, so `open(\"config.json\")` and `axios.get(\"https://api.example.com\")` never fire. **Weak randomness** for tokens/secrets (`Math.random`/`random.*`) is keyword-gated instead — flagged only alongside a token/password/OTP name. **Secret detection is language-agnostic**: it runs on every common source and config file Scout collects (Go, Java, Ruby, PHP, C/C++, Rust, shell, `.env`, `Dockerfile`, `docker-compose`, Terraform, …), so a hardcoded key is caught whatever language leaked it. Dependency scanning covers `requirements.txt` and `package-lock.json`.\n\n### Measured accuracy\n\nScout's injection scanner is measured against 104 real CVEs from the [OpenSSF CVE Benchmark](https://github.com/ossf-cve-benchmark/ossf-cve-benchmark) — real vulnerable commits in real JS/TS projects, no synthetic test cases. Full methodology, caveats, and reproduction steps live in [benchmarks/](benchmarks/); results are versioned per release, and this README only ever cites numbers present in a committed results file.\n\nHonest reading of the [v0.1.16 results](benchmarks/results/0.1.16/summary-native.md): overall recall is **27.4%** at **3.2%** precision — both up release over release (16.5% / 1.3% in v0.1.9). Command injection is the standout at **41.7%** recall, now edging past CodeQL's published 40% on this corpus, from recognizing `child_process.exec(cmd, callback)` member calls — including commands built as `[a, b].join(' ')` (a v0.1.16 regex-correctness fix that also stopped mis-flagging `regexp.exec()`, so recall and precision rose together); SQL/NoSQL injection holds at 25% (matching CodeQL) via the JS taint pass. Precision also benefits from skipping minified/bundled files — a vuln in a generated bundle is the dependency scanner's job. Adding `--engine semgrep` lifts overall recall further (see the [semgrep results](benchmarks/results/0.1.16/summary-native-semgrep.md)). The false-positive counts are an upper bound by benchmark convention — every unlabeled real `exec()`/sink call counts against Scout. These numbers are published to invite fair comparison and to be improved release over release, not to impress. For how these figures sit against CodeQL, ESLint, and published research on the same corpus, see [benchmarks/COMPARISON.md](benchmarks/COMPARISON.md).\n\nThe path-traversal + SSRF (v0.1.12) and deserialization + open-redirect + weak-randomness (v0.1.13) detectors are new vulnerability *classes* (CWE-22/918/502/601/330). The injection figures above are unchanged by them (verified: identical TP/FP/FN). These classes are scored separately against 39 added CVEs. Path traversal went from a 0% baseline (v0.1.13) to **46.9% recall** (v0.1.14) after two first-principles broadenings — the request URL/path (`req.url`) joined the taint sources, and `fs.stat`/`access`/`exists` joined the file-path sinks — now ahead of even the semgrep pass on this class. SSRF, open redirect, and deserialization stay at an honest 0%: reading their CVE flows, the blocker is unrecognized sinks/sources (a `res.setHeader('Location', …)` redirect, a bare `request({uri})` client) and taint through object literals — not function boundaries — and chasing an 11-CVE tail with that breadth would risk more false positives than it's worth. See [benchmarks/COMPARISON.md](benchmarks/COMPARISON.md).\n\nv0.1.15 adds **cross-function taint tracking for Python** (intra-file): a tainted argument to a local helper now taints that helper's parameter, so a `request.args` value flowing through a route handler into `os.system` in a service function is tracked to the sink. This is a real-world win for layered Python apps that the JS-only OpenSSF corpus can't measure — like weak randomness, it stays proven by unit tests rather than a benchmark number.\n\n## Example Output\n\n```\n$ scout scan ./my-app\n\nScout v0.1.16 scanning: ./my-app\n\n  Scanning 47 files...\n\nFound 6 issues:\n\n  🔴 2 critical\n  🟠 3 high\n  🟡 1 medium\n\nReport written to: ./my-app/security-report.md\n```\n\nThe report includes:\n- Every vulnerability explained in plain English\n- Severity ratings with context (why it's dangerous)\n- Exact fix instructions for each issue\n- Phased remediation plan (zero-risk fixes first)\n\n## Optional: AI Confirmation Pass\n\n**The core scan is always static, deterministic, offline, and zero-token — same scan, same findings, no API key.** That is the default and it never changes.\n\nIf you want an extra false-positive filter, Scout can optionally send *only the flagged snippet* (never whole files) of each heuristic finding to an AI provider, which can **downgrade** its severity or **dismiss** it as a false positive. Dependency (OSV) and project-level findings are deterministic facts and are never second-guessed. Any provider error leaves findings untouched — the pass fails open, so it can never hide a real issue.\n\nIt is **off by default**. Enable it per run:\n\n```bash\n# Anthropic (needs ANTHROPIC_API_KEY) — uses the cheap Haiku tier by default\nscout scan . --model anthropic\n\n# OpenAI (needs OPENAI_API_KEY)\nscout scan . --model openai\n\n# Local Ollama (no key, no cloud) — nothing leaves your machine\nscout scan . --model ollama --ollama-model llama3\n```\n\nProvider resolution is `--model` > `SCOUT_AI_PROVIDER` env > `none`. Override the model per provider with `SCOUT_AI_MODEL`. `--no-ai` forces the pass off regardless of config. Install the SDKs with `pip install \"scout-security[ai]\"` (Ollama needs no extra).\n\n## MCP Server (agent verifier)\n\nRun Scout as an [MCP](https://modelcontextprotocol.io) tool your coding agent can call in a scan → fix → rescan loop — deterministic, offline, zero-token, no inference cost. Scout finds it; your agent fixes it; Scout re-verifies.\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Scout_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=scout&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22scout-security%5Bmcp%5D%22%2C%22scout-mcp%22%5D%7D)\n[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_Scout_MCP-111111?style=flat-square&logoColor=white)](https://varpost.github.io/Scout/#ai-assistant)\n\n*(GitHub strips `cursor://` deep links, so the Cursor badge goes via the site's one-click button.)*\n\n### Install as a Claude Code plugin\n\nThe one-command path — the plugin bundles the MCP server, so no separate `claude mcp add` is needed:\n\n```text\n/plugin marketplace add Varpost/Scout\n/plugin install scout@scout\n```\n\nThat registers the `scan_path` tool and a `/scout-scan [path]` command. Requires [uv](https://docs.astral.sh/uv/) on your PATH — the plugin launches the server with `uvx` (first run downloads the package; later runs hit the cache). No uv? Use the manual setup below with `pip install \"scout-security[mcp]\"` and `\"command\": \"scout-mcp\"` instead.\n\n### Manual setup (any MCP host)\n\nEvery MCP host takes the same server definition — zero-install via [uv](https://docs.astral.sh/uv/):\n\n```json\n{\n  \"mcpServers\": {\n    \"scout\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"scout-security[mcp]\", \"scout-mcp\"]\n    }\n  }\n}\n```\n\nNo uv? `pip install \"scout-security[mcp]\"`, then use `\"command\": \"scout-mcp\"` with no `args`.\n\nWhere that definition goes:\n\n| Host | Where |\n|------|-------|\n| **Claude Code** | The [plugin](#install-as-a-claude-code-plugin) above, or `claude mcp add scout -- uvx --from \"scout-security[mcp]\" scout-mcp` |\n| **Cursor** | `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects |\n| **Claude Desktop** | `claude_desktop_config.json` (Settings → Developer → Edit Config) |\n| **Cline** | `cline_mcp_settings.json` (MCP Servers → Configure MCP Servers) |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n| **VS Code** (native MCP) | `.vscode/mcp.json` — same server object, but under a `\"servers\"` key instead of `\"mcpServers\"` |\n\nIt exposes one tool — **`scan_path(path)`** — returning the same Layer-3 JSON as `--format json` (findings with file, line, severity, stable id, explanation, and fix guidance). Point the agent's fix loop at it and call again to confirm the issue is gone.\n\n## Using Scout with Your AI Assistant\n\nThe whole idea in one line: **Scout finds deterministically → your AI fixes → Scout re-verifies.** Same scan, same findings, zero tokens on every pass — so re-checking a fix never costs inference. Pick the surface that matches how you work; all three run the same engine.\n\n### 1. You + a chat assistant (Claude, Cursor, Copilot Chat)\n\n```bash\nscout scan . --format ai-prompt      # writes security-prompts.md\n```\n\nOpen `security-prompts.md` and paste a block into your assistant. Each one is self-contained — the finding, the fix, and an instruction to sweep the rest of your code for the same class of issue. After it edits, re-verify:\n\n```bash\nscout scan .                         # clean? the loop is closed\n```\n\n### 2. An agent that calls Scout itself (Claude Code, Cursor Agent)\n\nWire up the [MCP server](#mcp-server-agent-verifier), then hand the agent the loop:\n\n> Scan this project with Scout, fix every finding, then scan again — repeat until it reports zero.\n\nThe agent calls `scan_path`, applies fixes, and calls again. Scout is the deterministic, zero-token verifier *inside* the loop, so each re-check is free.\n\n### 3. CI / pre-commit (make the loop mandatory)\n\nTurn the loop into a gate — the build fails until findings are fixed:\n\n```bash\nscout scan . --fail-on high          # exit 1 on HIGH+ findings\n```\n\nSee [Use as a CI Gate](#use-as-a-ci-gate) for the GitHub Action and [Pre-commit Hook](#pre-commit-hook) to catch findings before they're committed. Adopting on an existing repo? A [baseline](#adopting-scout-on-an-existing-codebase-baseline) accepts today's findings and fails only on new ones.\n\n## Add a Custom Scanner\n\n```python\nfrom scout.scanners import register_scanner\nfrom scout.scanners.base import BaseScanner\nfrom scout.models import Finding\nfrom pathlib import Path\n\n@register_scanner\nclass MyScanner(BaseScanner):\n    name = \"my-scanner\"\n    description = \"Detects my custom pattern\"\n\n    def scan_file(self, file_path: Path, content: str) -> list[Finding]:\n        findings = []\n        # detection logic here\n        return findings\n```\n\nAdd one import in `scout/scanners/__init__.py` → done.\n\n## Development\n\n```bash\ngit clone https://github.com/Varpost/Scout.git\ncd Scout\npip install -e \".[dev,ai]\"\npytest\nruff check scout/ tests/\n```\n\n## Documentation\n\nFull docs and interactive guide: [https://varpost.github.io/Scout/](https://varpost.github.io/Scout/)\n\n## License\n\nMIT — free forever.",
  "bytes": 21766,
  "sha": "383cca1f14e15190d7599f406ae4dd5b0376486a4c8ce5455e1f66a977893122",
  "repo_slug": "varpost/scout",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_varpost_scout_69999bf0/readme"
}