Scout Security

Scout

AI security team in a CLI. Find vulnerabilities before hackers do — free, local, no signup.

---

Why Scout?

AI coding assistants write insecure code constantly — hardcoded secrets, SQL injection, missing auth. Solo developers ship it because they don't have a security team.

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.

Install

Zero-install — try it in one command with uv (no venv, ~1s cold start):

uvx scout-security scan ./my-project

Or install it permanently:

pip install scout-security

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.

Usage

# Scan a project — deterministic static analysis: no API keys, no tokens, no signup

scout scan ./my-project

Turn the findings into ready-to-paste fix prompts for your AI assistant

scout scan ./my-project --format ai-prompt

Output Formats

One scan, four views — choose with --format (-f):

# Layer 1 — human-readable Markdown report (default)

scout scan ./my-app scout scan ./my-app -o security-report.md

Layer 2 — ready-to-paste prompts for your own AI (Cursor, Claude, Copilot…)

scout scan ./my-app --format ai-prompt # writes security-prompts.md scout scan ./my-app --format ai-prompt -o prompts.md

Layer 3 — machine-readable JSON for piping into agentic tooling / CI

scout scan ./my-app --format json # prints JSON to stdout scout scan ./my-app --format json -o report.json scout scan ./my-app --format json | jq '.findings[]'

Layer 4 — SARIF 2.1.0 for GitHub Code Scanning (PR annotations)

scout scan ./my-app --format sarif -o scout.sarif

The same engine powers all of them — Scout finds the problem; your own AI (which already knows your codebase) applies the fix.

Use as a CI Gate

scout scan exits 1 when findings at or above --fail-on (default: high) exist, so your pipeline fails on real problems:

scout scan . --fail-on high        # default — fail on HIGH or CRITICAL findings

scout scan . --fail-on critical # fail only on CRITICAL scout scan . --fail-on never # report-only mode — always exit 0

The GitHub Action wraps install + scan + SARIF upload, so findings show up as PR annotations via GitHub Code Scanning:

jobs:

scout: runs-on: ubuntu-latest permissions: contents: read security-events: write steps:

• uses: actions/checkout@v4
• uses: Varpost/Scout@v0.1.16 with: fail-on: high # also: path, format, upload-sarif

Prefer plain steps? The same thing by hand (the job still needs security-events: write):

- run: |

pip install scout-security scout scan . --no-ai --format sarif -o scout.sarif --fail-on never

• uses: github/codeql-action/upload-sarif@v4 with: sarif_file: scout.sarif

Pre-commit Hook

Catch findings before they're ever committed:

# .pre-commit-config.yaml

repos:

• repo: https://github.com/Varpost/Scout rev: v0.1.16 # use the latest tag hooks:
• id: scout

The 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.

Suppressing Findings

Silence a false positive with a trailing comment on the flagged line:

result = eval(trusted_expression)  # scout: ignore

result = eval(trusted_expression) # scout: ignore[injection]

Bare 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).

Configuration

Skip paths with --exclude (repeatable; relative to the scan root, globs allowed):

scout scan . --exclude tests/fixtures --exclude "*.min.js"

Or set project defaults in pyproject.toml — Scout reads [tool.scout] from the scanned project:

[tool.scout]

exclude = ["tests/fixtures", "vendor"] # paths or glob patterns to skip scanners = ["secrets", "injection"] # run a subset: secrets, injection, headers, deps, custom engines = ["semgrep"] # external engines to run and merge (optional) rules = ["scout-rules.yml"] # your own YAML detection rules (optional) fail_on = "medium" # default threshold for --fail-on

CLI flags win: --exclude replaces the config list, --engine replaces engines, and --fail-on overrides fail_on.

Custom Rules (optional)

Teach Scout project-specific patterns with a YAML file — an id, a regex, a message, a severity:

# scout-rules.yml — referenced from [tool.scout] rules

rules:

• id: internal-api-host pattern: "internal\\.corp\\.example" message: "Internal hostname committed to source." severity: HIGH # CRITICAL | HIGH | MEDIUM | LOW fix_phase: 1 # optional, 1-5 (default 3) suffixes: [".py", ".ts"] # optional — default: every scanned file fix: "Move the hostname to configuration."

Rules 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.

External Engines (optional)

Scout can orchestrate industrial OSS engines and merge their findings into its report, JSON, and SARIF output — same phased remediation plan, wider coverage:

pip install semgrep                # or brew install semgrep

scout scan . --engine semgrep # native scanners + semgrep, merged & deduped

CodeQL — GitHub's semantic analysis engine (CLI from

https://github.com/github/codeql-cli-binaries, on PATH as codeql)

scout scan . --engine codeql # builds a CodeQL DB per language (python/js),

runs the official security queries, merges the SARIF

--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).

Engines 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.

VS Code Extension

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.

Adopting Scout on an Existing Codebase (Baseline)

Don't want to fix years of findings before turning the CI gate on? Accept the current state, then fail only on new findings:

scout scan . --write-baseline                   # accept current findings → .scout-baseline.json

scout scan . --baseline .scout-baseline.json # report and fail only on NEW findings

Commit .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.

Scanning Git History for Secrets

A secret committed and later removed is still compromised — a scan of today's code can't see it:

scout scan . --git-history        # secrets in every added line of every commit, all branches

Findings 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.

Honest scope: Gitleaks and TruffleHog do deep, fast history auditing as their core job — Scout's pass is the built-in convenience, not a replacement.

What It Finds

Language scope

Deep 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.

Measured accuracy

Scout's injection scanner is measured against 104 real CVEs from the OpenSSF CVE Benchmark — real vulnerable commits in real JS/TS projects, no synthetic test cases