OWASP Guard CLI

Professional OWASP Top 10 (2021) code security scanner powered by LLM analysis.
Scans repositories or individual files and generates structured JSON + Markdown reports.

Prerequisites

Installation

From PyPI (recommended):

pip install owasp-guard-cli

From source:

git clone https://github.com/your-org/owasp-guard
cd owasp-guard
pip install -r requirements.txt
pip install -e .

Quick Start

1 — Add your API key

owasp-guard init

Or pass it directly:

owasp-guard init --api-key gsk_xxxxxxxxxxxx

2 — Scan your code

# Scan a full repository
owasp-guard scan ./my-project --output-dir outputs

# Scan a single file
owasp-guard scan ./src/app.py --output-dir outputs

3 — Review the reports

outputs/
├── report.json   ← for pipelines and automation
└── report.md     ← for human review and audit

Common Commands

# Scan a repo
owasp-guard scan ./my-project --output-dir outputs

# Limit to first 10 files (useful for large repos)
owasp-guard scan ./my-project --max-files 10 --output-dir outputs

# Use a specific model
owasp-guard scan ./my-project --model llama-3.1-8b-instant --output-dir outputs

# Scan a single file
owasp-guard scan ./src/auth.py --output-dir outputs

CLI Reference

owasp-guard --help          Show help
owasp-guard help scan       Scan command options
owasp-guard help init       Init command options
owasp-guard help reports    Report format details
owasp-guard help errors     Error codes reference

Alias: owasp works the same as owasp-guard.

Report Contents

report.json includes:

• Tool metadata and report version
• Scope metrics: total_files, total_chunks, total_findings
• Summary metrics: risk_score_10, severity and OWASP category distributions
• Full findings list with evidence and line references

report.md includes:

• Executive summary and risk score
• OWASP category and file impact breakdown
• Findings index with detailed evidence and fix guidance
• Priority action plan and remediation roadmap

Exit Codes

Troubleshooting

How It Works

Collect files → Chunk code → LLM analysis → Verification pass → Deduplicate → Report

1. File collection — gathers source files from the target path
2. Chunking — splits large files into context-sized chunks
3. LLM analysis — each chunk is analyzed against OWASP Top 10 categories
4. Verification pass — findings are re-checked to reduce false positives
5. Deduplication — repeated findings across chunks are merged
6. Reporting — outputs report.json and report.md

Project Layout

src/owasp_guard/
├── cli.py            # Entry point — commands: init, scan, help
├── scanner.py        # Main pipeline orchestrator
├── llm_utils.py      # Groq API calls and response parsing
├── prompts.py        # OWASP analysis prompts sent to the LLM
├── chunking.py       # Splits files into LLM-sized chunks
├── file_collector.py # Finds and filters files for scanning
├── reporting.py      # Generates report.json and report.md
├── models.py         # Data models for findings and scan results
├── config.py         # API key storage (~/.owasp_guard/config.json)
├── constants.py      # Model names, file extensions, OWASP categories
└── errors.py         # Custom exception types