wraith 0.1.0

Deterministic linter for AI-generated Python code

wraith

Catches what your AI forgot to check.

Deterministic linter for AI-generated Python code. Detects hallucinated APIs, phantom packages, hardcoded secrets, AI artifacts, and supply chain risks.

Install

pip install wraith

Usage

wraith check .                          # scan current directory
wraith check . --fix --diff             # preview fixes
wraith check . --fix                    # apply fixes
wraith check . --select AG,VC001       # specific rules only
wraith check . --min-confidence 0.8    # high-confidence only
wraith check . --format sarif          # CI/CD output
wraith rules                           # list all 20 rules

What it catches

API Guard — hallucinated API detection

Rule	What	Example
AG001	Non-existent attribute	os.path.joinn() → did you mean join?
AG002	Non-existent kwarg	makedirs(exst_ok=True) → exist_ok
AG003	Deprecated API	PEP 702 + source analysis, zero false positives
AG004	Bare call without module	read_csv() → pd.read_csv()
AG005	Missing import	np.array() without import numpy
AG006	Contextual mismatch	pd.read_excel("data.csv") → wrong extension

Phantom — package validation

Rule	What
PH001	Package not found on PyPI (slopsquatting risk)
PH002	Package not installed in current environment
PH003	Suspicious package (typosquat, new, low downloads)

Vibe Check — AI artifact hygiene

Rule	What
VC001	Hardcoded secrets (entropy + prefix + bigram analysis)
VC002	AI comments (# Generated by Claude, # Copilot)
VC003	Debug code — print/breakpoint (pedantic, off by default)
VC004	Debug imports (pdb, ipdb)
VC005	Source map exposure
VC006	Unauthed debug/admin endpoints
VC007	Dangerous files in project (.env, .pem, credentials)
VC008	Unpinned dependencies
VC009	Missing lockfile
VC010	Source map with full source disclosure
VC011	Secret leaked to print/logging (taint analysis)

Inline suppression

print("debug")           # noqa: VC003
API_KEY = "sk-secret"    # noqa: VC001
import pdb               # noqa

Python API

import wraith

results = wraith.check_source('API_KEY = "sk-secret"')
fixed = wraith.fix('import pdb\nbreakpoint()')

How it works

• Tree-sitter AST parsing — no regex on source, proper syntax analysis
• Symbol table with scope tracking (PEP 227 LEGB) — distinguishes imports from local variables
• Python introspection — validates API calls against real installed modules
• Layered secret detection — known prefixes, Shannon entropy, bigram name classification, character class analysis
• Taint analysis — tracks data flow from secret sources to unsafe sinks
• TYPE_CHECKING awareness (PEP 484) — skips type-only imports

Research

Based on:

• AST Hallucination Guard (FORGE '26) — API validation via introspection
• Package Hallucinations in LLMs — phantom package detection
• Slopsquatting — supply chain attack via hallucinated names
• VibeGuard — AI code artifact hygiene
• Secrets in Source Code (Saha et al. 2020) — character class analysis
• Argus — hierarchical secret detection