owasp-guard-cli 0.2.2

OWASP Guard CLI: secure code inspector

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

Requirement	Version
Python	3.11+
Groq API Key	Get one free →

---

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

Code	Meaning
0	Scan complete — no findings
1	Scan complete — findings detected
2	Invalid CLI usage
3	Runtime error

---

Troubleshooting

Error	Fix
Invalid API Key	Run owasp-guard init again with a valid Groq key
Path not found	Make sure the target path exists before scanning
Configuration Error	Delete ~/.owasp_guard/config.json and re-run init

---

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