Skip to main content

owasp-scanner

CI License: MIT

MCP server for OWASP Top 10 (2025) security scanning of Python and Next.js codebases.

Uses regex pre-filtering + optional LLM reasoning to find vulnerabilities that pattern-matching tools miss, with a persistent finding workflow that makes security knowledge accumulate instead of evaporate.

88 rules. 20 tools. Local SQLite persistence. LLM is optional.

Installation

# With pip
pip install owasp-scanner

# With uv
uv tool install owasp-scanner

# With LLM support (optional)
pip install owasp-scanner[llm]

MCP Setup

Add to your Claude configuration:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "owasp-scanner": {
      "command": "uvx",
      "args": ["owasp-scanner"]
    }
  }
}

Claude Code (project or user settings):

{
  "mcpServers": {
    "owasp-scanner": {
      "command": "uvx",
      "args": ["owasp-scanner"]
    }
  }
}

With LLM scanning enabled:

{
  "mcpServers": {
    "owasp-scanner": {
      "command": "uvx",
      "args": ["owasp-scanner[llm]"],
      "env": {
        "OWASP_LLM_ENABLED": "true",
        "OWASP_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Quick Start

CLI mode:

# Scan a project directory
owasp-scanner --scan /path/to/project

# Fail CI if high-severity issues found
owasp-scanner --scan /path/to/project --fail-on=high
Scanned: /path/to/project
Findings: 7 (7 new)
  critical: 1
  high: 2
  medium: 4

FAIL: 3 findings at high or above.

MCP mode (via Claude):

"Scan this project for security issues"

The scanner runs automatically when loaded as an MCP server. Claude can call any of the 20 tools directly.

Tools

Scanning

Tool Description
scan_directory(path, mode, exclude, git_diff_base) Scan a directory. Set git_diff_base="main" to scan only changed files.
scan_file(path, mode) Scan a single file. Modes: regex, deep, llm, hybrid.
scan_config(path, framework) Scan config files (Django, FastAPI, Next.js).
scan_dependencies(path) Check dependencies for known CVEs via pip-audit.
scan_boundary(path) Analyze Next.js Server-to-Client Component prop crossings for data leaks.

Findings

Tool Description
list_findings(status, severity, category) List findings with filters.
get_finding(id) Full detail + audit trail for a finding.
create_finding(...) Manually create a finding from review or pentesting.
update_finding(id, status, notes) Triage: mark as fixed, accepted, or false positive.
delete_finding(id) Remove a finding.
verify_fix(id) Re-check if the pattern that triggered a finding is gone.

LLM

Tool Description
llm_triage(finding_ids, auto_update) Batch LLM triage — identifies true/false positives.

Reporting

Tool Description
get_summary() Dashboard: counts by status, category, severity.
export_report(scan_id, output_path) Markdown report with executive summary.
export_sarif(scan_id, output_path) SARIF 2.1.0 for GitHub/VS Code/CI integration.
get_trends(days) Open/closed over time, mean time to remediation.

Utility

Tool Description
list_scans(limit) Scan history.
create_baseline(path) Snapshot current findings as the baseline.
health_check() Server status, rule count, database info.
get_errors(error_id, tool_name) Recent scanner errors for debugging.

Scanning Modes

Mode What happens Cost
regex 88 regex patterns, instant Free
deep Framework detection, endpoint extraction, security checklist for LLM reasoning Free
llm LLM scans each file with framework-specific context ~$0.01-0.02/project
hybrid Regex first, LLM triage (marks false positives), then LLM design review ~$0.02-0.05/project

Default is regex. The scanner works fully offline without an API key.

OWASP 2025 Rule Coverage

Category Python Next.js LLM focus
A01 Broken Access Control 4 (auth, path traversal, SSRF) 5 (route handler, server action, mass assignment) Missing auth, IDOR
A02 Security Misconfiguration 7 (DEBUG, ALLOWED_HOSTS, CORS, XXE) 3 (NEXT_PUBLIC secrets, image SSRF) Config gaps
A03 Supply Chain 2 (unpinned deps, git installs) -- Dep hygiene, SBOM
A04 Cryptographic Failures 7 (MD5, SHA-1, random, ECB, DES) 2 (Math.random, cookies) Key management
A05 Injection 8 (SQL, pickle, eval, yaml, subprocess) 6 (XSS, Prisma, command injection) ORM injection
A06 Insecure Design -- 1 (middleware matcher) Primary LLM category
A07 Authentication 9 (secrets detection across all file types) 2 (DB strings, API keys) Missing MFA
A08 Integrity Failures 4 (CDN SRI, marshal, shelve, jsonpickle) -- Mass assignment
A09 Logging Failures 2 (sensitive data in logs, log injection) -- Missing audit logging
A10 Exceptional Conditions 5 (bare except, fail-open, timeout) 2 (empty catch, error leak) Fail-open, transactions

Environment Variables

Variable Default Description
OWASP_DATA_DIR ~/.owasp-scanner Database and logs directory
OWASP_MAX_FILE_SIZE_KB 500 Skip files larger than this
OWASP_LLM_ENABLED false Enable LLM scanning modes
OWASP_OPENAI_API_KEY -- OpenAI API key for LLM modes
OWASP_LLM_MODEL gpt-5.4-nano Model for LLM scanning
OWASP_LLM_BASE_URL -- Override for Ollama, Azure, or vLLM

LLM Setup

LLM scanning is optional. The scanner works fully with regex mode (free, no API key needed).

To enable LLM modes (llm, hybrid, llm_triage):

export OWASP_LLM_ENABLED=true
export OWASP_OPENAI_API_KEY=sk-...

For local models via Ollama:

export OWASP_LLM_ENABLED=true
export OWASP_LLM_BASE_URL=http://localhost:11434/v1
export OWASP_OPENAI_API_KEY=ollama  # any non-empty string
export OWASP_LLM_MODEL=llama3.1

Troubleshooting

No findings on a scan:

  • Check OWASP_MAX_FILE_SIZE_KB (default 500 KB) — large files are skipped
  • Check exclude patterns — .owaspignore in the project root can suppress matches
  • Run health_check() to verify the scanner is working

LLM mode not working:

  • Verify OWASP_LLM_ENABLED=true and OWASP_OPENAI_API_KEY are set
  • Run health_check() — it reports whether the LLM is available
  • Check get_errors() for API errors

Permission errors:

  • The data directory (~/.owasp-scanner/) must be writable
  • The database file is created with mode 0600 (owner-only read/write)

Adding Custom Rules

Rules are regex patterns with OWASP metadata. To add a new rule:

  1. Add a Rule(...) entry to src/owasp_scanner/rules/patterns.py (Python) or nextjs_patterns.py (Next.js)
  2. Add a positive match test + negative match test to tests/test_rules.py
  3. Run uv run python -m pytest tests/test_rules.py -v

For external rules without modifying source, place YAML files in ~/.owasp-scanner/rules/:

- id: CUSTOM-001
  owasp_category: A05
  severity: high
  title: "Custom injection pattern"
  description: "Description of the vulnerability"
  pattern: "dangerous_function\\("
  file_glob: "*.py"
  suggested_fix: "Use safe_function() instead"

Development

git clone https://github.com/mfbaig35r/owasp-scanner.git
cd owasp-scanner
uv sync --all-extras
uv run python -m pytest tests/ -v --tb=short   # 370 tests
uv run ruff check src/ tests/                   # lint

License

MIT

Metadata

Release files for owasp-scanner 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for owasp-scanner 0.2.0
File Size Uploaded Provenance Actions
owasp_scanner-0.2.0.tar.gz 116.6 kB With provenance Details for owasp_scanner-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for owasp-scanner 0.2.0
File Interpreter ABI Platform Actions
owasp_scanner-0.2.0-py3-none-any.whl Python 3 none any Details for owasp_scanner-0.2.0-py3-none-any.whl

Total release size: 193.3 kB

Release files / owasp_scanner-0.2.0.tar.gz

Download URL owasp_scanner-0.2.0.tar.gz
Size 116.6 kB
Tags Source
SHA-256 checksum
How to use checksums
f03d87034412485f0526933619836fffa45506d3f25db105e68bb246758e3166
BLAKE2b-256 checksum
How to use checksums
d2f4db7920f908d7dfdc74eb112dbee26082f4c12236ffd5981569a911bdf0a6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.

Transparency log

Release files / owasp_scanner-0.2.0-py3-none-any.whl

Download URL owasp_scanner-0.2.0-py3-none-any.whl
Size 76.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e0b0e8c2bd5ac8d7198dd216a5b5b0b861b1812969df215e37f512fa91e71d7a
BLAKE2b-256 checksum
How to use checksums
198051c9dcf2132d73fc58b8d148515fc78bb25fb08b002e078c2ccec43315a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.

Transparency log

Security for owasp-scanner 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for owasp_scanner-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page