Metadata-Version: 2.4
Name: aina-scan
Version: 2.0.0
Summary: AI-powered Python security scanner — 13 vuln types, AINA L3 causal chains, 100% recall
Project-URL: Homepage, https://github.com/Moonsehwan/aina-scan
Project-URL: Repository, https://github.com/Moonsehwan/aina-scan
Project-URL: Issues, https://github.com/Moonsehwan/aina-scan/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-scan

[![PyPI](https://img.shields.io/pypi/v/aina-scan)](https://pypi.org/project/aina-scan/)
[![Python](https://img.shields.io/pypi/pyversions/aina-scan)](https://pypi.org/project/aina-scan/)
[![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.

![AINA Scan 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-scan
aina-scan config --key YOUR_KEY
aina-scan scan agent.py
```

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

---

## Usage

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

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

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

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

# View scan history
aina-scan history

# Report false positive (auto-suppressed in next scan)
aina-scan feedback STUB_SKELETON --verdict fp --file agent.py

# Pattern statistics
aina-scan 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-scan 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.

---

## FP Feedback Loop

Report a false positive once → suppressed in all future scans for that file:

```bash
# 1. Scan → BLOCK found
aina-scan scan token_usage.py
#  🔴 BLOCKED  HARDCODED_SECRET  L47

# 2. Report as FP (e.g. it's a test fixture, not a real secret)
aina-scan feedback HARDCODED_SECRET --verdict fp --file token_usage.py
#  ✅ Feedback recorded: FALSE POSITIVE
#  → token_usage.py × HARDCODED_SECRET → next scan will downgrade BLOCK → WARN

# 3. Re-scan → BLOCK gone
aina-scan scan token_usage.py
#  🟡 WARN  HARDCODED_SECRET [FP suppressed]
```

Per-user learning. Your FP profile stays with your API key.

---

## 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-scan | 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/aina-scan.yml
name: AINA Scan Security Check

on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install aina-scan
        run: pip install aina-scan
      - name: Scan Python files
        env:
          AINA_SCAN_API_KEY: ${{ secrets.AINA_SCAN_KEY }}
        run: |
          find . -name "*.py" | head -20 | while read f; do
            aina-scan scan "$f" || exit 1
          done
```

Add `AINA_SCAN_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 FP feedback loop (`--verdict fp`) suppresses them per-user immediately.

**Q: How is it different from `bandit`?**  
A: bandit uses regex patterns. aina-scan 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.

**Q: Migrating from aina-vibeguard?**  
A: `pip install aina-scan`. Your old `VIBEGUARD_API_KEY` env var still works. Config key is auto-migrated.

---

## Contact

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

---

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