# SecAgent AI

**Autonomous AI Security Agent** — scan, verify, and auto-fix security vulnerabilities in your codebase using xAI Grok.

```bash
pip install secagent-ai
```

---

## What is SecAgent?

SecAgent is a CLI tool that acts as an autonomous security engineer. Point it at a file or directory and it will:

- **Scan** for secrets, vulnerabilities, and insecure code patterns
- **Verify** each finding with AI to eliminate false positives
- **Fix** real vulnerabilities by generating and applying secure patches
- **Report** everything in a readable Markdown report with cost tracking

All AI reasoning is powered by [xAI Grok](https://x.ai).

---

## Installation

**Requirements:** Python 3.11+

```bash
pip install secagent-ai
```

On first run, SecAgent will walk you through a one-time setup to save your Grok API key:

```
secagent scan ./myproject
```

```
╔══════════════════════════════════════════╗
║           S E C A G E N T  AI            ║
║    Autonomous AI Security Agent v0.1.0   ║
╚══════════════════════════════════════════╝
──────────────── First-Time Setup ─────────

Welcome to SecAgent!
To get started, enter your xAI Grok API key.
Get one at: https://console.x.ai/

Grok API Key: ********************************
Setup complete! Config saved to: C:\Users\you\.secagent\config.json
```

Your key is saved locally and never sent anywhere except the xAI API.

---

## Usage

### Scan a file or directory

```bash
secagent scan ./myproject
secagent scan ./app/auth.py
```

Scans for vulnerabilities and saves results. Does **not** modify any files.

### Scan and auto-fix

```bash
secagent fix ./myproject
secagent fix ./app/auth.py
```

Verifies findings, generates patches, applies fixes, and writes a `fix.md` report.

### Re-configure your API key

```bash
secagent configure
```

### Check version

```bash
secagent version
```

### Verbose mode

```bash
secagent scan ./myproject --verbose
secagent fix ./myproject --verbose
```

---

## Optional Tools

SecAgent works out of the box with its built-in scanners. Installing these tools unlocks additional scanning capabilities:

| Tool | Purpose | Install |
|------|---------|---------|
| [Gitleaks](https://github.com/gitleaks/gitleaks) | Secret & credential scanning | `brew install gitleaks` |
| [Trivy](https://github.com/aquasecurity/trivy) | Dependency vulnerability scanning | `brew install trivy` |

> SecAgent degrades gracefully — if a tool isn't installed, it's skipped automatically. The built-in scanner and AI scanner always run regardless.

---

## How It Works

SecAgent runs a 9-stage pipeline:

```
Stage 1  │ Planner Agent    │ Analyzes your codebase, selects the right scanners
Stage 2  │ Scanner Executor │ Runs all selected scanners in parallel
Stage 3  │ Result Parser    │ Normalizes findings into a unified format
Stage 4  │ Deduplicator     │ Merges duplicate findings across scanners
Stage 5  │ Verifier Agent   │ AI classifies True Positive vs False Positive
Stage 6  │ Fixer Agent      │ AI generates a secure patch for each real finding
Stage 7  │ Validator Agent  │ AI confirms the patch is correct and safe
Stage 8  │ Patch Applier    │ Applies the patch to your file (with backup)
Stage 9  │ Report Builder   │ Generates fix.md + token usage cost report
```

All AI stages use xAI Grok. Stages 1, 5 use the fast non-reasoning model. Stages 6, 7 use the reasoning model for higher accuracy.

---

## Output

After a `fix` run, SecAgent creates:

- **`fix.md`** — full report of findings, verification results, patches applied, and skipped fixes
- **`.secagent/logs/cost.md`** — token usage and estimated API cost per stage
- **`.secagent/data/*.vulns.json`** — cached scan results (reused on subsequent `fix` runs)

---

## Configuration

Your API key and model settings are stored at:

| Platform | Path |
|----------|------|
| Windows | `C:\Users\<you>\.secagent\config.json` |
| Linux / Mac | `~/.secagent/config.json` |

To update your key at any time:

```bash
secagent configure
```

---

## Example Output

```
SecAgent v0.1.0
Scanning /home/user/myapp (directory)

[Stage 1] Planner selected: builtin-secrets, ai-scanner, gitleaks
[Stage 2] Running 3 scanners...
[Stage 3] Parsed 5 findings
[Stage 4] Deduplicated to 4 unique findings

[Stage 5] Verifying findings...  4 TP  |  0 FP
[Stage 6] Fixing 4 vulnerabilities...
[Stage 7] Validating patches...  4 valid
[Stage 8] Applying 4 patches...

──────────────────────────────────────────────────
Findings: 4  TP: 4  FP: 0  Fixed: 4

Report generated: fix.md

┌─ Token Usage & Estimated Cost ──────────────────┐
│ Stage     │ Model     │ Tokens  │ Cost (USD)     │
│ planner   │ fast      │  1,240  │ $0.0002        │
│ scanner   │ reasoning │  8,430  │ $0.0042        │
│ verifier  │ fast      │  2,100  │ $0.0004        │
│ fixer     │ reasoning │ 12,800  │ $0.0064        │
│ validator │ reasoning │  6,300  │ $0.0032        │
│ Total     │           │ 30,870  │ $0.0144        │
└─────────────────────────────────────────────────┘
```

---

## License

MIT — free to use, modify, and distribute.

---

## Links

- [PyPI](https://pypi.org/project/secagent-ai/)
- [GitHub](https://github.com/Mr-Vicky-01/secagent)
- [xAI Console](https://console.x.ai/) — get your Grok API key
