Metadata-Version: 2.4
Name: owasp-guard-cli
Version: 0.2.2
Summary: OWASP Guard CLI: secure code inspector
Author: Jean Claude Geagea
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeanclaudegeagea/owasp-guard
Project-URL: Issues, https://github.com/jeanclaudegeagea/owasp-guard/issues
Keywords: security,owasp,sast,cli,code-scanner
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: langchain>=0.3.0
Requires-Dist: langchain-groq>=0.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: rich>=13.7.0

# 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 →](https://console.groq.com) |

---

## Installation

**From PyPI (recommended):**

```bash
pip install owasp-guard-cli
```

**From source:**

```bash
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

```bash
owasp-guard init
```

Or pass it directly:

```bash
owasp-guard init --api-key gsk_xxxxxxxxxxxx
```

### 2 — Scan your code

```bash
# 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

```bash
# 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
```
