Metadata-Version: 2.4
Name: aina-vibeguard
Version: 1.9.3
Summary: AI-powered Python security scanner — 13 vuln types, AINA L3 causal chains, 100% recall
Project-URL: Homepage, https://github.com/Moonsehwan/aina-vibeguard
Project-URL: Repository, https://github.com/Moonsehwan/aina-vibeguard
Project-URL: Issues, https://github.com/Moonsehwan/aina-vibeguard/issues
Author-email: AINA Sovereign <shanyshany3528@gmail.com>
License: MIT
License-File: LICENSE
Keywords: linter,python,sast,security,static-analysis,vulnerability
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# aina-vibeguard

[![PyPI](https://img.shields.io/pypi/v/aina-vibeguard)](https://pypi.org/project/aina-vibeguard/)
[![Python](https://img.shields.io/pypi/pyversions/aina-vibeguard)](https://pypi.org/project/aina-vibeguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**AST-based security scanner for AI-generated Python code.**

> May flag false positives. Never misses a real one.

![VibeGuard Demo](demo/demo_en.gif)

[한국어](README.ko.md) · [日本語](README.ja.md) · [中文](README.zh.md) · [Español](README.es.md) · [Deutsch](README.de.md)

---

## Real Findings

Scanned top open-source AI coding tools. Found what others missed.

**serena** (25K ⭐) — AI coding assistant:
```
CRITICAL  COMMAND_INJECTION  agent.py:1222
          subprocess.Popen(cmd, shell=True)
          Attack path: config_tamper → shell_injection → server_compromise (p=97%)
```

**aider** (27K ⭐) — AI pair programmer:
```
CRITICAL  COMMAND_INJECTION  commands.py:974
          subprocess.run("git " + user_input, shell=True)
          Attack path: user_input → shell_injection → repo_compromise (p=94%)
```

**35 true positives. 0 false positives.**  
Missed by Semgrep. Missed by the maintainers.

---

## Install

```bash
pip install aina-vibeguard
aina-vibeguard config --key YOUR_KEY
aina-vibeguard scan agent.py
```

Get a free API key → **[github.com/Moonsehwan/aina-vibeguard](https://github.com/Moonsehwan/aina-vibeguard)**

---

## Usage

```bash
# Scan a file
aina-vibeguard scan agent.py

# Agent-friendly output — paste into Claude Code to auto-fix
aina-vibeguard scan agent.py --agent-friendly

# Save full JSON report
aina-vibeguard scan agent.py --report report.json

# Verify a fix worked
aina-vibeguard scan agent.py
# ✅ 0 blocks found

# View scan history
aina-vibeguard history

# Report false positive
aina-vibeguard feedback STUB_SKELETON --verdict fp --file agent.py

# Pattern statistics
aina-vibeguard stats
```

### `--agent-friendly` output

```json
{
  "blocks": [{
    "type": "COMMAND_INJECTION",
    "severity": "CRITICAL",
    "file": "agent.py",
    "line": 1222,
    "before_code": "subprocess.Popen(cmd, shell=True)",
    "after_code": "subprocess.Popen(cmd.split(), shell=False)",
    "verify": "aina-vibeguard scan agent.py → 0 COMMAND_INJECTION",
    "l3_chain": "config_tamper → shell_injection → server_compromise (p=97%)"
  }],
  "agent_instruction": "Fix all BLOCK items above. After each fix, verify. Report when all blocks are 0."
}
```

Paste into Claude Code → automated fix loop. No manual steps.

---

## What It Detects

### Security (13 patterns)

| Pattern | Severity |
|---------|----------|
| `COMMAND_INJECTION` | CRITICAL |
| `PATH_TRAVERSAL` | CRITICAL |
| `SQL_INJECTION_RISK` | CRITICAL |
| `INSECURE_RANDOM` | CRITICAL |
| `WEAK_CRYPTO` | HIGH |
| `HARDCODED_SECRET` | HIGH |
| `EVAL_EXEC_RISK` | HIGH |
| `GOD_OBJECT` | HIGH |
| `BOUNDARY_MISSING` | MEDIUM |
| `STUB_SKELETON` | MEDIUM |
| `UNIFORM_RETURN` | MEDIUM |
| `DEEP_NESTING` | MEDIUM |
| `TRIVIAL_IF_CHAIN` | MEDIUM |

### Code Quality (7 patterns)

`DUPLICATE_FUNCTION` · `CIRCULAR_DEPENDENCY` · `N_PLUS_ONE_QUERY` · `MAGIC_NUMBER` · `MUTABLE_DEFAULT` · `EMPTY_EXCEPT` · `SHORT_PASSTHROUGH`

### Architecture (6 patterns — Pro)

`TAINT_FLOW` · `CROSS_FILE_INJECTION` · `UNSAFE_DESERIALIZATION` · `MISSING_ERROR_HANDLING` · `LOGIC_BOMB` · `RACE_CONDITION`

---

## vs Semgrep vs Claude

| | aina-vibeguard | Semgrep (free) | Claude (inline) |
|--|:---:|:---:|:---:|
| serena COMMAND_INJECTION | ✅ | ❌ | ❌ |
| aider COMMAND_INJECTION | ✅ | ❌ | ❌ |
| gpt-engineer PATH_TRAVERSAL | ✅ | ⚠️ partial | ❌ |
| Zero dependencies | ✅ | ❌ | ❌ |
| CI exit code | ✅ | ✅ | ❌ |
| Causal attack chain | ✅ | ❌ | ❌ |
| Agent-friendly output | ✅ | ❌ | ❌ |
| FP feedback loop | ✅ | ❌ | ❌ |

---

## GitHub Actions

```yaml
# .github/workflows/vibeguard.yml
name: VibeGuard Security Scan

on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Moonsehwan/aina-vibeguard-action@v1
        with:
          api-key: ${{ secrets.VIBEGUARD_KEY }}
```

Add `VIBEGUARD_KEY` to **Settings → Secrets → Actions**.  
PR fails automatically if security blocks are found.

---

## Pricing

| | Free | Pro | Premium |
|--|:---:|:---:|:---:|
| Price | $0 | $19/mo Early Bird | $99/mo Early Bird |
| Files/day | 50 | Unlimited | Unlimited |
| Security patterns | 13 | 13 | 13 |
| Causal attack chains | ❌ | ✅ | ✅ |
| Scan history | ❌ | ✅ | ✅ |
| FP feedback | ❌ | ✅ | ✅ |
| Project scan | ❌ | ❌ | ✅ |
| Taint flow analysis | ❌ | ❌ | ✅ |

---

## FAQ

**Q: Does it send my code to a server?**  
A: Only the scanned file is sent. No code is stored permanently.

**Q: False positive rate?**  
A: ~3% on abstract base class patterns. The feedback loop (`--verdict fp`) improves accuracy per user.

**Q: How is it different from `bandit`?**  
A: bandit uses regex patterns. aina-vibeguard uses AST analysis with causal chain tracing. Bandit missed both serena and aider findings.

**Q: Works offline?**  
A: Requires API call. Free tier: 50 files/day.

**Q: How does detection work?**  
A: Black-box API. Core logic runs server-side.

---

## Contact

- Issues: [github.com/Moonsehwan/aina-vibeguard/issues](https://github.com/Moonsehwan/aina-vibeguard/issues)  
- Email: Aina.vibeguard@gmail.com

---

MIT License · CLI source only · Core engine proprietary (server-side)
