Metadata-Version: 2.4
Name: aina-scan
Version: 2.3.6
Summary: AI-powered Python security scanner — 32 patterns, AINA L3 causal chains, i18n (en/ko), 6-report output
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

# AINAScan

[![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)

**결정론적 AI 코드 품질 게이트 — LLM 없이, 환각 없이, 항상 같은 결과.**

> Deterministic AI code quality gate. No LLM. No hallucinations. Always the same result.

[한국어](#korean) · [English](#english)

---

## 🎉 3일 무료 프로모션 (2026-06-19 ~ 2026-06-22)

**지금 바로 시작하세요 — 키 신청 없이 복붙하면 됩니다.**

```bash
pip install aina-scan
aina-scan config --key vg_free_demo001
aina-scan scan .
```

프로모 기간 중 `vg_free_demo001` 키는 **Pro 기능 전체 무료**입니다.

- 무제한 스캔
- 설계 스멜 10종 탐지
- L3 인과 공격 체인 (133K+ 관계)
- 에이전트 요청서 자동 생성 (`--agent-friendly`)

> 프로모 종료 후 개인 키가 필요하면 Issues 탭에서 `key request`로 요청.  
> 얼리버드 **100명 한정 30% 영구 할인** — 선착순.

---

<a name="english"></a>

## What is AINAScan?

AINAScan is a **deterministic AI** code quality gate — the opposite of LLM-based tools.

| | AINAScan | LLM-based tools (Claude, GPT) | Semgrep | Bandit |
|--|:---:|:---:|:---:|:---:|
| Same input → Same output | ✅ Always | ❌ Varies | ✅ | ✅ |
| Hallucination risk | ✅ Zero | ❌ High | ✅ Zero | ✅ Zero |
| Causal attack chain | ✅ L3 graph (133K) | ❌ Guesses | ❌ | ❌ |
| Agent auto-fix JSON | ✅ Structured | ❌ | ❌ | ❌ |
| SHA256 audit trail | ✅ Every scan | ❌ | ❌ | ❌ |
| Vibe-coding + Design-smell | ✅ 19 kinds (9+10) | ❌ | ❌ | ❌ |
| Interproc taint (3-hop) | ✅ | ❌ | partial | ❌ |
| CVE auto-sync (NVD) | ✅ | ❌ | manual | manual |
| Formula verification | ✅ sympy | ❌ | ❌ | ❌ |
| FP feedback loop | ✅ per-user | ❌ | ❌ | ❌ |
| Abstract Interpretation | ✅ value-flow tracking | ❌ | ❌ | ❌ |
| String literal FP prevention | ✅ tokenize filter | ❌ | partial | ❌ |
| BLOCK/WARN auto-classification | ✅ FP-rate based | ❌ | ❌ | ❌ |
| Taint Flow Tracking | ✅ user-input → sink path | ❌ | partial | ❌ |
| Exception classifier (internal vs external) | ✅ AST-based | ❌ | ❌ | ❌ |
| Context-sensitive FP reduction | ✅ endpoint vs internal | ❌ | ❌ | ❌ |

**AINAScan finds what LLMs miss — deterministically.**

---


## Quick Start (30 seconds)

```bash
pip install aina-scan
aina-scan config --key vg_free_demo001
aina-scan scan .
```

That's it. `vg_free_demo001` works during the promo period (until June 22) — no signup required.

After June 22, get a personal key → **[github.com/Moonsehwan/aina-scan/issues](https://github.com/Moonsehwan/aina-scan/issues)**

---

## What It Can Do

### 1. Security Scanning (13+ patterns)

| Pattern | Severity | Description |
|---------|----------|-------------|
| `COMMAND_INJECTION` | CRITICAL | subprocess + user input / f-string / shell=True |
| `PATH_TRAVERSAL` | CRITICAL | open(user_path) without sanitization |
| `SQL_INJECTION_RISK` | CRITICAL | f-string SQL / %-format SQL |
| `PROMPT_SQL_INJECTION` | CRITICAL | LLM prompt input → SQL f-string chain |
| `HARDCODED_SECRET` | HIGH | api_key = "sk-..." in source / git history |
| `EVAL_EXEC_RISK` | HIGH | eval()/exec() with dynamic input |
| `INSECURE_RANDOM` | HIGH | random.random() in security context |
| `WEAK_CRYPTO` | HIGH | MD5/SHA1/DES usage |
| `IDOR_MISSING_AUTH_CHECK` | HIGH | resource access without ownership check |
| `CSRF_MISSING_PROTECTION` | HIGH | state-changing endpoint with no CSRF token |
| `BOUNDARY_MISSING` | MEDIUM | no decision_permission gate on agent action |
| `DEEP_NESTING` | MEDIUM | 5+ levels of nested if/for |
| `TRIVIAL_IF_CHAIN` | MEDIUM | 7+ elif chain without DB lookup |

CVE auto-sync: NVD feed updated automatically. New CVE patterns available within 24h.

### 2. Code Quality Gate (9 patterns — vibe-coding specific)

Patterns that appear specifically in AI-generated (vibe-coded) code:

| Pattern | Description |
|---------|-------------|
| `STUB_SKELETON` | Empty function body — AI wrote the signature, skipped the logic |
| `DEAD_CALL_RESULT` | Module called, result ignored — AI connected nothing |
| `DEAD_DB_RESULT` | DB query result fetched but never used in return path |
| `MISSING_WRITE` | save()/store() function with no actual INSERT/UPDATE/DELETE |
| `INPUT_OUTPUT_DISCONNECTED` | Parameters don't affect return value (12+ line function) |
| `MOCK_PATTERN` | MagicMock/unittest.mock left in production code |
| `HARDCODED_TABLE` | 8+ key dict × 2+ instead of DB query (AI shortcuts) |
| `RECURSIVE_WITHOUT_BASE` | Recursive call with no base-case branch — stack overflow risk |
| `DUPLICATE_FUNCTION` | Same logic written twice by AI in different sessions |

### 3. Design Smell Detection (10 patterns — Pro)

Martin Fowler 22 + SOLID 5 principles, AST-based static analysis:

**BLOCK (must fix):**
- `GOD_OBJECT` — class with 15+ methods, no single responsibility
- `LARGE_CLASS` — 300+ lines, needs decomposition
- `REFUSED_BEQUEST` — subclass ignores inherited methods
- `CIRCULAR_IMPORT` — A imports B, B imports A (runtime crash risk)
- `SINGLE_RESPONSIBILITY_VIOLATION` — class handles 3+ unrelated concerns

**WARN (review recommended):**
- `LONG_PARAMETER_LIST` — function with 7+ params (hard to call correctly)
- `ATTRIBUTE_CHAIN` — a.b.c.d.e chaining (fragile, Law of Demeter violation)
- `DUPLICATE_CODE_BLOCK` — near-identical 10+ line blocks
- `SPECULATIVE_GENERALITY` — unused abstractions / dead interface
- `DATA_CLUMP` — same 3+ params always appear together (extract to class)

### 4. Causal Attack Chain (L3 Knowledge Graph — 133,647 relations)

Every finding includes the **full attack path** with probability:

```
config_tamper  → shell_injection → server_compromise  (p=97%)
user_input     → sql_injection   → data_exfiltration  (p=94%)
path_traverse  → file_read       → credential_leak    (p=88%)
prompt_input   → sql_f_string    → db_dump            (p=91%)
```

Not just "this is dangerous" — **how the attack actually unfolds, step by step**.

Built from 133,647 causal relations across OWASP Top 10 + CWE database.

### 4b. Taint Flow Analysis — 3 Directions (v2.3.5+)

Beyond name-matching: AINAScan tracks **actual data flow** to eliminate false positives.

**Direction 1 — Taint Flow Tracking:**
Traces data from external sources to external exposure points. Automatically distinguishes internal control-flow from actual leaks — dramatically reduces false positives without missing real vulnerabilities.

**Direction 2 — Exception Classifier:**
AST-based classification of exception classes. Identifies which exceptions propagate externally vs. stay internal, so only real exposures are flagged.

**Direction 3 — Context-Sensitive Analysis:**
Analyzes the function context (HTTP endpoint vs. internal method) to apply the right severity level automatically.

### 5. Interprocedural Taint Analysis (3-hop, Team)

Tracks tainted data across function boundaries — up to 3 call hops:

```
request.py:14  [user_input enters]
  → parser.py:87   [passed as argument]
    → db_query.py:203  [used in SQL f-string]
                        → SQL_INJECTION_RISK ← found here
```

Single-file scanners miss this entirely. AINAScan traces the full path.

### 6. Agent Auto-Fix Request

```bash
aina-scan scan agent.py --agent-friendly
```

Output (paste directly into Claude Code):

```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, run the verify command. Report when all blocks are 0."
}
```

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

### 7. SHA256 Audit Trail

Every scan result is hash-chained and tamper-proof:

```
scan_id:   abc123-def456
sha256:    e3b0c44298fc1c149afbf4c8996fb924...
prev_hash: 0000000000000000...
timestamp: 2026-06-19T09:26:18Z
```

Prove that findings were reported **before** a breach, not after.  
Immutable record for compliance (SOC2, ISO 27001).

### 8. CVE Auto-Sync (NVD)

Automatically syncs with NVD (National Vulnerability Database):

- New CVE patterns available within 24 hours of publication
- Seed database: 15+ hand-curated high-impact CVE patterns
- AST pattern detection — not regex string matching

No manual rule updates needed. Always current.

### 9. Formula Verification (15 formulas — Team)

sympy-based mathematical correctness checking:

- Physics: Newton's laws, Maxwell equations, thermodynamics
- Statistics: Bayes theorem, variance, Pearson correlation
- Cryptography: RSA key size, entropy bounds
- Finance: compound interest, Black-Scholes, VaR

Catches `p = m * v` used where `E = mc²` was needed.  
AI agents frequently substitute similar-looking formulas — this catches it.

### 10. FP Feedback Loop

Report a false positive once → suppressed in all future scans, per-user:

```bash
aina-scan feedback STUB_SKELETON --verdict fp --file token_usage.py
# ✅ Feedback recorded. BLOCK → WARN in next scan for this file.
```

Per-user learning. Adapts to your codebase without affecting other users.

---

## vs Competitors

| | **AINAScan** | Semgrep (free) | Semgrep (Team $49) | Snyk ($25/dev) | Claude inline |
|--|:---:|:---:|:---:|:---:|:---:|
| Deterministic | ✅ | ✅ | ✅ | ❌ | ❌ |
| Hallucination risk | Zero | Zero | Zero | Low | **High** |
| Vibe-coding (19 kinds) | ✅ | ❌ | ❌ | ❌ | varies |
| Causal chain (L3) | ✅ 133K rel | ❌ | ❌ | partial | ❌ |
| Interproc taint (3-hop) | ✅ Team | ❌ | ✅ | ✅ | varies |
| Agent auto-fix JSON | ✅ | ❌ | ❌ | ❌ | manual |
| SHA256 audit trail | ✅ | ❌ | ❌ | ❌ | ❌ |
| CVE auto-sync | ✅ | manual | manual | ✅ | ❌ |
| Formula verification | ✅ Team | ❌ | ❌ | ❌ | ❌ |
| FP feedback loop | ✅ per-user | ❌ | ❌ | ❌ | ❌ |
| CI exit code | ✅ | ✅ | ✅ | ✅ | ❌ |
| Price (unlimited) | **$29/mo** | free | $49/mo | $25/dev | API cost |
| Earlybird | **$19/mo** | — | — | — | — |

---

## Usage

### Setup

```bash
# Install
pip install aina-scan

# Set API key — use this key during promo (until June 22, free)
aina-scan config --key vg_free_demo001

# Or via environment variable (CI/CD)
export AINA_SCAN_API_KEY=vg_free_demo001
```

### Scanning

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

# Scan an entire folder (all .py files, recursive)
aina-scan scan src/
aina-scan scan .        # current directory

# Verbose: show L3 causal chains per finding
aina-scan scan agent.py -v

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

# 📑 6 Markdown reports — generated automatically to aina-reports/
aina-scan scan agent.py

# Save reports to a custom directory instead
aina-scan scan agent.py --full-report my-reports/

# Suppress report generation
aina-scan scan agent.py --no-report

# Agent-friendly output — paste into Claude Code for auto-fix loop
aina-scan scan agent.py --agent-friendly
aina-scan scan src/ --agent-friendly
```

### 📑 6 Markdown Reports (자동 생성)

스캔하면 **6개 리포트가 자동으로 `aina-reports/` 디렉터리에 생성됩니다** — 별도 플래그 필요 없음.

```bash
aina-scan scan agent.py
# Generates in ./aina-reports/:
#   agent_aina_overview.md    ← Full dashboard (everyone reads this first)
#   agent_aina_summary.md     ← CTO / PM — 1-page risk brief
#   agent_aina_fixes.md       ← Developer — Before/After code per BLOCK/WARN
#   agent_aina_audit.md       ← Security / Compliance — all 32 patterns logged
#   agent_aina_structure.md   ← Architect — function map + Mermaid call graph
#   agent_aina_agent.md       ← AI Agent (Claude Code/Cursor) — paste & fix

# Custom output directory:
aina-scan scan agent.py --full-report my-reports/

# Suppress report generation:
aina-scan scan agent.py --no-report
```

**Report roles:**

| File | Audience | Contents |
|------|----------|----------|
| `_overview.md` | Everyone | Verdict, score, all issues with L3 chains + confidence, senior analysis, code structure |
| `_summary.md` | CTO / PM | Risk level, top 5 critical issues, 4-step action plan |
| `_fixes.md` | Developer | Ordered task list, Before/After code with **actual detected class/function names**, verify commands |
| `_audit.md` | Security / Compliance | All 32 patterns: result + reason with **BLOCK/WARN threshold distinction** (audit trail) |
| `_structure.md` | Architect / Reviewer | **Complete** function table (no truncation), class list, Mermaid call graph |
| `_agent.md` | Claude Code / Cursor | Copy-paste fix instructions, accurate confidence display, **full undocumented function list** |

**The `_agent.md` file:**  
Paste into Claude Code or Cursor — no reformatting needed.  
Each task is a self-contained fix instruction with attack path, before/after code, and a verify command.

### AINA + Agent Workflow

AINA detects deterministically. AI agents fix. Neither replaces the other.

```
AINA scan (no LLM, always same result)
    ↓
_aina_agent.md (paste into Claude Code / Cursor)
    ↓
Agent fixes code (LLM-powered, context-aware)
    ↓
aina-scan scan again → verify 0 BLOCK
    ↓
Commit / PR
```

**AINA can't do — agent must do:**
- Understand semantic context to decide if a flag is FP
- Rewrite code to fix the issue (AINA points, agent fixes)
- Write security docstrings for sink functions
- Generate test cases for detected vulnerability patterns
- Refactor God Object / Circular Import (structural redesign)

**Agent can't do reliably — AINA must do:**
- Deterministic pattern match (no hallucinations, same result always)
- L3 causal chain lookup (133K relations, not invented)
- SHA256 audit trail (tamper-proof, before-breach proof)
- Interprocedural taint tracing across files

### Where Results Are Saved

| What | Where | How |
|---|---|---|
| API key / config | `~/.aina_scan/config.json` | auto (on `aina-scan config`) |
| 6 Markdown reports | `aina-reports/<stem>_aina_*.md` (6 files) | 자동 생성 (억제: `--no-report`, 경로 변경: `--full-report DIR`) |
| Scan report (JSON) | path you specify | `--report result.json` |
| Agent-fix JSON | path you specify | `--agent-friendly > fix.json` |
| Scan history | server (your account) | `aina-scan history` to view |

```bash
# 6-report full analysis (aina-reports/ 자동 생성)
aina-scan scan agent.py

# Save full JSON report to a file
aina-scan scan agent.py --report result.json

# Save agent-friendly fix instructions to a file
aina-scan scan agent.py --agent-friendly > agent_fix.json

# Save folder scan report
aina-scan scan src/ --report src_report.json

# View scan history (stored server-side)
aina-scan history
aina-scan history --limit 50
```

**Terminal scan output sections:**
```
💎 [PRO]  agent.py
  🔴 BLOCKED  blocks=2  warns=3  verdict=FAIL

  ════ 패턴별 검사 결과 ════
  🔴 보안 (Security)  (11/13 PASS)
  🔴 BLOCK  COMMAND_INJECTION     subprocess + shell=True with variable cmd
  ✅ PASS   PATH_TRAVERSAL        open() with unvalidated user path
  ...

  ════ 발견된 문제 상세 ════
  🔴 BLOCK: COMMAND_INJECTION  (line 42)
     shell=True with variable cmd — use shlex.split(cmd) + shell=False
     AINA confidence=87%  L3_chains=3  verdict=TRUE_POSITIVE

  ════ 시니어 코드 분석 ════
  🟡 종합 판정: WARN
  🟡 Magic Number (하드코딩 상수): 3건
  🟡 Missing Error Handling: 1건

  ════ 코드 구조 분석 ════
  함수: 12개 | 클래스: 2개 | 위험 함수(Sink): 3개 | 검증 함수: 2개
  get_user_input      라인 15   source      📥 SOURCE
  validate_path       라인 28   validator   ✅ VALIDATE
  execute_command     라인 45   sink        ⚠️ SINK
  ...
  📊 호출 그래프 (Mermaid — GitHub에 붙여넣기):
  graph TD
      get_user_input -->|⚠️ SINK| execute_command
      validate_path -->|✅ VALIDATE| safe_open
```

**Report JSON structure:**
```json
{
  "scan_id": "abc123",
  "filename": "agent.py",
  "tier": "pro",
  "verdict": "FAIL",
  "blocks": 2,
  "warns": 3,
  "checks": [
    {"kind": "COMMAND_INJECTION", "category": "SECURITY", "result": "BLOCK",
     "description": "subprocess + shell=True with variable cmd"}
  ],
  "issues": [
    {"kind": "COMMAND_INJECTION", "severity": "BLOCK", "line": 42,
     "detail": "...", "aina_advisor": {
       "confidence": 0.87, "l3_causal_chains": 3,
       "combined_confidence": 0.87,
       "memory_verification": {"verdict": "TRUE_POSITIVE", "confidence": 0.91,
                                "cause_found": true, "protected": false}
     }}
  ],
  "senior_analysis": {
    "verdict": "WARN",
    "summary": {"magic_number": 3, "missing_error_handling": 1},
    "issues": [...]
  },
  "structure": {
    "total_functions": 12, "sinks_count": 3, "validators_count": 2,
    "functions": [...],
    "call_graph_mermaid": "graph TD\n    ...",
    "detected_libraries": ["subprocess", "sqlite3"]
  },
  "advisor_version": "AINA-Phase3",
  "scan_mode": "full"
}
```

### Managing Results

```bash
# Report a false positive (suppressed in future scans)
aina-scan feedback STUB_SKELETON --verdict fp --file agent.py

# Confirm a true positive
aina-scan feedback COMMAND_INJECTION --verdict tp --file agent.py

# Per-pattern statistics (Pro)
aina-scan stats
```

### Other

```bash
# Check API status and knowledge base
aina-scan status

# Check earlybird slot availability
aina-scan slots

# Export learned patterns as JSON
aina-scan docs -o patterns.json
```

### Folder scan example output

```
📁  Found 47 Python files in src/

🔍  Scanning src/agent.py (1,417 lines) …
💎 [PRO]  agent.py
  🔴 BLOCKED  blocks=10  warns=13
  ────────────────────────────────────────────────────
  KIND                   SEVERITY LINE   DETAIL
  ────────────────────────────────────────────────────
  🔴 COMMAND_INJECTION   BLOCK    1222   subprocess call with variable 'cmd' …
  🔴 GOD_OBJECT          BLOCK    538    SerenaAgent: 47 non-dunder methods …
  🔴 LARGE_CLASS         BLOCK    538    SerenaAgent: 49 methods (threshold 15+)
  🔴 SSRF_RISK           BLOCK    ?      get_tool_description_override: unvalidated URL …
  🔴 EVAL_EXEC_RISK      BLOCK    ?      CVE-2022-21699: IPython arbitrary code exec …
  🔴 TEMPLATE_INJECTION  BLOCK    ?      CVE-2024-22195: Jinja2 SSTI via Template() …

🔍  Scanning src/utils.py (1,204 bytes) …
💎 [PRO]  utils.py
  🟢 CLEAN  blocks=0  warns=1

... (45 more files)

──────────────────────────────────────────────────
🔴 BLOCKED  3 file(s) with BLOCK issues out of 47 scanned
  ⚠️  src/agent.py
  ⚠️  src/commands.py
  ⚠️  src/db.py
```

---

## GitHub Actions

```yaml
# .github/workflows/aina-scan.yml
name: AINAScan Security Gate

on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install aina-scan
      - name: Scan changed Python files
        env:
          AINA_SCAN_API_KEY: ${{ secrets.AINA_SCAN_KEY }}
        run: |
          git diff --name-only origin/main HEAD | grep '\.py$' | while read f; do
            aina-scan scan "$f" || exit 1
          done
```

Add `AINA_SCAN_KEY` to **Settings → Secrets → Actions**.  
PR fails automatically if CRITICAL/HIGH blocks are found. Changed files only — fast.

---

## Pricing

> **3-day promo active (ends June 22, 2026):** All keys → Pro features free

| | Free | **Pro** | Team |
|--|:---:|:---:|:---:|
| Price | $0 | **$29/mo** | $79/mo |
| Earlybird (100 users only) | — | **$19/mo forever** | **$49/mo forever** |
| Files/day | 50 | Unlimited | Unlimited |
| Security (13+ patterns) | ✅ | ✅ | ✅ |
| Vibe-coding (9 patterns) | ✅ | ✅ | ✅ |
| Causal attack chain (L3) | ✅ | ✅ | ✅ |
| Agent auto-fix JSON | ✅ | ✅ | ✅ |
| CVE auto-sync | ✅ | ✅ | ✅ |
| SHA256 audit trail | limited | ✅ | ✅ |
| Design smell (10 patterns) | ❌ | ✅ | ✅ |
| FP feedback loop | ❌ | ✅ | ✅ |
| Interproc taint (3-hop) | ❌ | ❌ | ✅ |
| Formula verification (15) | ❌ | ❌ | ✅ |
| Priority support | ❌ | email | Slack |

**Earlybird:** First 100 users → Pro $19/mo or Team $49/mo **locked forever**.  
3-day promo users qualify automatically.  
Register → [github.com/Moonsehwan/aina-scan/issues](https://github.com/Moonsehwan/aina-scan/issues)

---

## Why Deterministic AI?

LLMs generate different outputs for the same input. They hallucinate. They miss the same bug twice. They can't give you a CI exit code.

**AINAScan is different:**

- **AST-based** — parses actual Python syntax tree, not text
- **L3 Knowledge Graph** — 133,647 causal relations, same every time
- **sympy formulas** — mathematical proofs, not guesses
- **SHA256 chains** — every judgment recorded and verifiable
- **NVD CVE sync** — pattern database always current

Same file + same version = same result. Always.

This means:
- CI gates don't fail randomly
- Security findings are reproducible and provable in court
- AI agents loop on findings until zero — no moving target
- Compliance teams get immutable scan history

---

## FAQ

**Q: Does it send my code to a server?**  
A: Only the scanned file is sent over HTTPS. Code is not stored permanently. Scan metadata is SHA256-chained for audit.

**Q: False positive rate?**  
A: ~3% on abstract base class patterns (`STUB_SKELETON` on ABC methods). FP feedback loop suppresses per-user immediately.

**Q: How is it different from `bandit`?**  
A: bandit uses regex. AINAScan uses AST + L3 causal graph + interproc taint. bandit missed the serena and aider critical vulnerabilities above.

**Q: How is it different from Semgrep?**  
A: Semgrep has no causal attack chains, no vibe-coding patterns, no agent-friendly output, no formula verification, no FP feedback. AINAScan is designed for the AI coding era.

**Q: How is it different from Claude inline review?**  
A: Claude varies per run. AINAScan is deterministic — same input, same output. Claude can't give you a CI exit code, an audit trail, or a structured fix JSON for your agent.

**Q: Core algorithm open source?**  
A: CLI is MIT-licensed (this repo). Core engine runs server-side (proprietary). No algorithm download possible.

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

**Q: Migrating from aina-vibeguard?**  
A: `pip install aina-scan`. Your old `VIBEGUARD_API_KEY` still works.

---

## Roadmap

### Language Support
Currently Python only. Expanding via `tree-sitter` (same AST engine, different grammar):

| Language | Status | ETA |
|---|---|---|
| Python | ✅ Live | — |
| TypeScript / JavaScript | 🔜 Next | Q3 2026 |
| Java | 🔜 Planned | Q3 2026 |
| Go | 🔜 Planned | Q4 2026 |
| Rust | 🔜 Planned | Q4 2026 |
| C# (Unity / .NET) | 🔜 Planned | Q4 2026 |

### Domain Expansion
The L3 causal knowledge graph is domain-agnostic. Planned vertical packs:

| Domain | Patterns | ETA |
|---|---|---|
| **Healthcare** | HIPAA violations, FDA 21 CFR Part 11, PHI exposure, audit trail gaps | Q3 2026 |
| **Legal / LegalTech** | PII retention, GDPR right-to-erasure, data minimization, consent chain | Q3 2026 |
| **Finance / FinTech** | SOX controls, PCI-DSS card data, insider trading data flows, VaR formula errors | Q4 2026 |
| **Game Dev** | Unity C# memory leaks, input validation bypass, save-file tampering, seed predictability | Q4 2026 |
| **AI/ML pipelines** | Prompt injection chains, model poisoning paths, embedding leakage | Q4 2026 |

### Platform
- VS Code extension (inline scan on save) — Q3 2026
- JetBrains plugin — Q4 2026
- GitHub App (auto-comment on PR) — Q3 2026

> The core engine (AST + L3 causal graph + sympy) is already built.  
> Each new language/domain is a grammar + knowledge pack — not a rewrite.

---

## Contact

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

---

<a name="korean"></a>

## AINAScan — 한국어

**결정론적 AI 코드 품질 게이트.** LLM 없음. 환각 없음. 항상 동일한 결과.

### AINAScan이란?

AI 코딩 도구(Claude, Cursor, GitHub Copilot)가 생성한 코드의 품질과 보안 문제를 **결정론적으로** 탐지합니다.

- **LLM이 아님** — AST(구문 트리) + L3 인과 지식 그래프 기반
- **동일 입력 → 동일 출력** — CI/CD 게이트에 적합
- **환각 없음** — 있는 것만 보고, 없는 것을 만들어내지 않음
- **에이전트 자동 수정** — `--agent-friendly` 출력을 Claude Code에 붙여넣으면 자동 수정 루프 실행

### AINAScan의 차별점

1. **결정론적 AI** — 동일한 파일, 항상 동일한 결과. CI 게이트가 랜덤하게 실패하지 않음
2. **19종 바이브코딩 패턴** — AI가 생성한 코드 특화: STUB_SKELETON, DEAD_CALL_RESULT, MISSING_WRITE, RECURSIVE_WITHOUT_BASE 등
3. **L3 인과 공격 체인 (133,647건)** — "이 취약점이 어떻게 서버 침해로 이어지는지" 경로 + 확률
4. **인터프로시저 taint 분석** (Team) — 파일 간 3홉 오염 데이터 추적
5. **CVE 자동 동기화** — NVD 데이터베이스 24시간 내 자동 반영
6. **SHA256 감사 체인** — 모든 스캔 결과 해시 연결, 위변조 탐지 / 법적 증거
7. **에이전트 요청서 자동 생성** — 수정 방법 + 검증 명령이 포함된 JSON → Claude Code 자동 수정 루프
8. **FP 피드백 루프** — 오탐 한 번 신고하면 이후 스캔에서 자동 억제 (사용자별)
9. **수식 검증** (Team) — sympy로 물리/수학/금융 공식 정확성 검증

### 지금 바로 시작 (30초)

```bash
pip install aina-scan
aina-scan config --key vg_free_demo001
aina-scan scan .
```

`vg_free_demo001` 키는 프로모 기간(~6월 22일) 동안 **Pro 전체 기능 무료**입니다. 가입 불필요.

```bash
# 단일 파일 스캔
aina-scan scan 파일.py

# 폴더 전체 스캔 (.py 파일 전부)
aina-scan scan src/
aina-scan scan .

# AI 에이전트 자동 수정 (출력을 Claude Code에 붙여넣기)
aina-scan scan . --agent-friendly

# 결과 JSON 저장
aina-scan scan 파일.py --report 결과.json

# L3 인과 공격 체인 상세 보기
aina-scan scan 파일.py -v

# 오탐 신고 (이후 자동 억제)
aina-scan feedback STUB_SKELETON --verdict fp --file 파일.py
```

6월 22일 이후 개인 키 요청 → **[Issues 탭 `key request`](https://github.com/Moonsehwan/aina-scan/issues)**

### 가격

| | 무료 | **Pro** | Team |
|--|:---:|:---:|:---:|
| 정가 | $0 | **월 $29** | 월 $79 |
| 얼리버드 (100명 한정) | — | **월 $19 영구** | **월 $49 영구** |
| 일일 파일 수 | 50개 | 무제한 | 무제한 |
| 보안 패턴 13종+ | ✅ | ✅ | ✅ |
| 바이브코딩 패턴 9종 | ✅ | ✅ | ✅ |
| L3 인과 공격 체인 | ✅ | ✅ | ✅ |
| CVE 자동 동기화 | ✅ | ✅ | ✅ |
| 에이전트 요청서 JSON | ✅ | ✅ | ✅ |
| SHA256 감사 체인 | 제한 | ✅ | ✅ |
| 설계 스멜 10종 | ❌ | ✅ | ✅ |
| FP 피드백 루프 | ❌ | ✅ | ✅ |
| 인터프로시저 taint (3홉) | ❌ | ❌ | ✅ |
| 수식 검증 15종 | ❌ | ❌ | ✅ |

**얼리버드 100명 한정:** Pro $19/월 또는 Team $49/월 **평생 유지**  
3일 프로모 기간 중 키를 받은 분 모두 자동 얼리버드 적용

### 로드맵

#### 언어 확장
현재 Python 전용. `tree-sitter` 기반으로 동일 엔진에 문법만 추가하는 방식:

| 언어 | 상태 | 예정 |
|---|---|---|
| Python | ✅ 운영 중 | — |
| TypeScript / JavaScript | 🔜 다음 | 2026 Q3 |
| Java | 🔜 예정 | 2026 Q3 |
| Go | 🔜 예정 | 2026 Q4 |
| Rust | 🔜 예정 | 2026 Q4 |
| C# (Unity / .NET) | 🔜 예정 | 2026 Q4 |

#### 도메인 확장
L3 인과 지식 그래프는 도메인 독립적 구조 — 지식 팩만 추가:

| 도메인 | 탐지 패턴 | 예정 |
|---|---|---|
| **의료 / 헬스케어** | HIPAA 위반, FDA CFR Part 11, PHI 노출, 감사 체인 누락 | 2026 Q3 |
| **법률 / 리걸테크** | PII 보존, GDPR 삭제권, 데이터 최소화, 동의 체인 | 2026 Q3 |
| **금융 / 핀테크** | SOX 통제, PCI-DSS 카드 데이터, VaR 공식 오류 | 2026 Q4 |
| **게임 개발** | Unity C# 메모리 누수, 입력 검증 우회, 세이브 파일 변조, 시드 예측 가능성 | 2026 Q4 |
| **AI/ML 파이프라인** | 프롬프트 인젝션 체인, 모델 포이즈닝, 임베딩 유출 | 2026 Q4 |

> 코어 엔진(AST + L3 인과 그래프 + sympy)은 이미 완성됨.  
> 새 언어/도메인 추가 = 문법 + 지식 팩 추가. 엔진 재작성 불필요.

---

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