Most static analysis tools make a trade-off: fast pattern matching that misses indirect flows, or expensive whole-program analysis that takes minutes to configure. VulnHunter takes a different approach. It layers three deterministic engines -- AST pattern rules, interprocedural taint flow, and supply-chain analysis -- then optionally hands uncertain findings to a multi-model LLM pipeline for deeper investigation. The result is a scanner that found a real CVE blind, benchmarks at 95.2% detection against Semgrep's 58.7% and Bandit's 50.8%, and runs its static engines without an API key.
What VulnHunter Is
VulnHunter is a ground-truth-blind repository vulnerability scanner. "Ground-truth-blind" means it receives no hints about what vulnerabilities exist in a codebase. It does not rely on CVE databases, advisory feeds, or prior knowledge of known issues. Instead, it examines the source code directly and reports what it finds through static analysis, interprocedural data-flow tracking, and -- when configured -- LLM-assisted investigation.
The scanner supports four languages for deep analysis: Python, JavaScript, TypeScript, and Go. It reads a repository's source tree, builds per-language program indexes, and runs three detection engines in parallel before deduplicating and ranking the merged findings.
# Quick static scan -- no API key required
pip install vulnhunter
vulnhunter scan /path/to/repo --mode quick
# Full scan with default Grok provider
export XAI_API_KEY=your-key
vulnhunter scan /path/to/repo
# Anthropic multi-model pipeline
export ANTHROPIC_API_KEY=your-key
vulnhunter scan /path/to/repo --model anthropic
Output formats include plaintext, JSON, and SARIF for CI/CD integration.
Detection Engine 1: AST Pattern Rules (VH100--VH128)
The first engine walks each Python module's abstract syntax tree, resolving import aliases through the module's binding table. When you write import requests as r, VulnHunter's _qualified_name() resolver maps r.get back to requests.get, so aliased calls never escape detection.
28 rules cover the following vulnerability classes:
Injection
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH100 | Command injection -- runtime data in shell calls | CWE-78 | Critical |
| VH101 | SQL injection -- string interpolation in database statements | CWE-89 | High |
| VH103 | Server-side template injection -- user data compiled as template source | CWE-1336 | Critical |
| VH111 | Code injection -- eval() / exec() with runtime data | CWE-95 | Critical |
| VH127 | NoSQL injection -- interpolation in MongoDB operator expressions | CWE-943 | High |
Deserialization and XML
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH102 | Unsafe deserialization -- pickle.loads(), yaml.load() on untrusted data | CWE-502 | Critical |
| VH104 | XML external entity -- DTD loading and entity resolution enabled | CWE-611 | High |
Network and Request Handling
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH105 | Server-side request forgery -- runtime data selects HTTP destinations | CWE-918 | High |
| VH109 | TLS verification disabled -- verify=False in requests/httpx | CWE-295 | High |
| VH122 | CSRF protection disabled -- @csrf_exempt, disabled middleware | CWE-352 | High |
| VH123 | CORS misconfiguration -- wildcard origins, escalated with credentials | CWE-942 | High |
Path and File Handling
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH106 | Archive path traversal -- zip/tar member names escaping extraction root | CWE-22 | High |
| VH107 | Path traversal -- uncontained path joins below a trusted root | CWE-22 | High |
| VH119 | Insecure file permissions -- world-writable or world-executable modes | CWE-732 | Medium |
| VH120 | Predictable temp paths -- manual /tmp construction vs. tempfile | CWE-377 | Medium |
| VH128 | Unrestricted file upload -- no content-type, extension, or size validation | CWE-434 | High |
Authentication and Authorization
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH108 | Missing object authorization -- IDOR via caller-controlled ID without ownership check | CWE-639 | High |
| VH115 | Route authorization outlier -- a state-changing route lacks its siblings' auth guard | CWE-862 | Medium |
| VH117 | Mass assignment -- setattr() with attacker-controlled keys | CWE-915 | Medium |
Cryptography
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH112 | Weak hash -- MD5/SHA-1 without usedforsecurity=False | CWE-328 | Low |
| VH113 | Insecure randomness -- random.choice() for tokens/secrets | CWE-330 | Medium |
| VH116 | Weak cipher -- DES, Blowfish, RC4, ECB mode | CWE-327 | Medium |
| VH118 | Timing attack -- non-constant-time comparison of hashes/tokens | CWE-208 | Medium |
| VH121 | JWT none algorithm -- algorithm="none" or verify_signature=False | CWE-347 | Critical |
| VH124 | Hardcoded IV/nonce -- static constants in AES-CBC/GCM | CWE-329 | High |
Configuration and Information Disclosure
| Rule | Class | CWE | Severity |
|---|---|---|---|
| VH110 | Debug mode enabled -- Flask/Django debug=True in production | CWE-489 | Medium |
| VH114 | Insecure cookies -- missing Secure, HttpOnly, SameSite attributes | CWE-614 | Low |
| VH125 | Insecure framework config -- ALLOWED_HOSTS=["*"], weak session settings | CWE-16 | Medium |
| VH126 | Stack trace exposure -- exception details in HTTP responses | CWE-209 | Medium |
How the AST Engine Works
Each rule receives a _Module object that includes the parsed AST, resolved import bindings, top-level constant assignments, and the raw source lines. The engine walks function definitions, class methods, and module-level statements, applying rule-specific visitors that understand framework conventions.
For example, the SQL injection rule (VH101) does not simply grep for f-strings containing SELECT. It checks whether:
- The call target resolves to a known database execution method (
execute,executemany,raw,from_statement,text,read_sql) - The first argument is an f-string,
%-format, or.format()call (not a constant) - The interpolated values include at least one runtime variable (not a module-level constant or integer literal)
# VH101 flags this -- f-string with runtime variable in SQL context
cursor.execute(f"SELECT * FROM users WHERE id = '{user_id}'")
# VH101 does NOT flag this -- parameterized query
cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
# VH101 does NOT flag this -- f-string but only constants
cursor.execute(f"SELECT * FROM {TABLE_NAME} WHERE active = 1")
This matters because naive pattern matchers produce false positives on parameterized queries and f-strings that build SQL from constants. VulnHunter's constant-tracking propagation resolves top-level assignments at parse time, so TABLE_NAME = "users" followed by an f-string referencing TABLE_NAME is correctly identified as safe.
Detection Engine 2: Interprocedural Native Flow (VHNF100--VHNF116)
The AST rules work within a single function body. To catch vulnerabilities where tainted data flows across function boundaries -- through helper functions, middleware, decorators, and class hierarchies -- VulnHunter runs a second engine: the native flow analyzer.
This engine operates across Python, JavaScript, TypeScript, and Go. It uses tree-sitter parsers to build a language-agnostic intermediate representation, then tracks data flow from sources to sinks through an interprocedural analysis.
Sources and Sinks
Sources are entry points where attacker-controlled data enters the program:
- HTTP request parameters, headers, body, and cookies
- URL path segments and query strings
- Environment variables (conservative: treated as untrusted)
- File reads from user-specified paths
- WebSocket messages and form submissions
Sinks are operations where tainted data causes damage. The native flow engine covers 17 sink categories:
| Rule | Sink | CWE |
|---|---|---|
| VHNF100 | Command shell execution | CWE-78 |
| VHNF101 | SQL statement execution | CWE-89 |
| VHNF102 | Dynamic code evaluation | CWE-94 |
| VHNF103 | Outbound HTTP request destination (SSRF) | CWE-918 |
| VHNF104 | Filesystem path operation | CWE-22 |
| VHNF105 | Object-capable deserialization | CWE-502 |
| VHNF106 | Template source compilation | CWE-1336 |
| VHNF107 | Command-line argument injection | CWE-88 |
| VHNF108 | HTML response without escaping (XSS) | CWE-79 |
| VHNF109 | Redirect destination (open redirect) | CWE-601 |
| VHNF110 | LDAP search filter | CWE-90 |
| VHNF111 | XPath expression | CWE-643 |
| VHNF112 | Server-side session storage (trust boundary) | CWE-501 |
| VHNF113 | Filesystem path existence probe | CWE-22 |
| VHNF114 | HTTP response header | CWE-113 |
| VHNF115 | Application log output | CWE-117 |
| VHNF116 | Regular expression compilation | CWE-1333 |
Cross-Function Tracking
The flow engine builds a call graph and propagates taint through function parameters, return values, and assignments. Consider a typical pattern where the actual vulnerability is three function calls away from the HTTP handler:
# routes.py
@app.route("/export")
def export_report():
filename = request.args.get("file")
content = load_report(filename) # taint enters helper
return content
# helpers.py
def load_report(name):
path = build_path(name) # taint propagates
return open(path).read()
def build_path(name):
return f"/var/reports/{name}" # VHNF104: path traversal sink
Bandit and Semgrep miss this because they analyze each function in isolation. VulnHunter's native flow engine traces request.args.get("file") through load_report() and build_path() to the open() call, reporting it as VHNF104 with the full call chain in the evidence.
Language-Specific Flow Modules
Beyond the core taint engine, VulnHunter includes specialized flow analyzers:
- Go path flow (
go_path_flow.py) -- tracks path manipulation in Go'sfilepath.Join,os.Open, andhttp.ServeFilewith awareness of Go's path normalization semantics - Go resource flow (
go_resource_flow.py) -- tracks attacker-controlled data reaching resource allocation calls - JavaScript persisted path flow (
js_persisted_path_flow.py) -- detects path traversal where tainted data is stored (in a database, cache, or file) and later used in a filesystem operation - JavaScript prototype pollution (
js_prototype_flow.py) -- tracks property assignments that reach__proto__orconstructor.prototype - JavaScript HTML response flow (
js_html_response.py) -- detects unescaped user data in dynamically built HTML responses
Path Guard Recognition
A common source of false positives in taint analysis is ignoring sanitization. VulnHunter's path_guards.py module recognizes common path-safety patterns:
os.path.realpath()followed bystartswith()containment checkpathlib.Path.resolve()with parent directory comparison- Framework-specific sanitizers like Django's
SafeDatawrapper - Manual prefix checks that establish a trusted root boundary
When a tainted value passes through a recognized guard before reaching a sink, the finding is suppressed or downgraded.
Detection Engine 3: Supply-Chain Analysis (VHSCA100--VHSCA109)
VulnHunter integrates ca9 for supply-chain analysis. ca9 parses dependency manifests (requirements.txt, pyproject.toml, Pipfile.lock, poetry.lock, package.json, package-lock.json) and evaluates each package against malware feeds, provenance attestations, and supply-chain policy rules.
10 rules cover the supply-chain attack surface:
| Rule | Signal | Severity |
|---|---|---|
| VHSCA100 | Dependency confusion -- internal package name resolvable on public registry | Critical |
| VHSCA101 | Untrusted registry -- package installed from an unknown index | High |
| VHSCA102 | Git dependency without pinned commit SHA | Medium |
| VHSCA103 | Direct URL dependency without integrity hash | Medium |
| VHSCA104 | Mutable local or file source | Low |
| VHSCA105 | Missing integrity hash in lockfile entry | Low |
| VHSCA106 | Known malware package match | Critical |
| VHSCA107 | Newly published package version (not yet verified) | Low |
| VHSCA108 | Provenance regression -- attestation present in earlier version, absent now | High |
| VHSCA109 | Suspicious release flagged by automated sentinel analysis | High |
How SCA Integration Works
The run_sca() function in sca.py calls ca9's discover_declared_dependency_inventory() to enumerate packages from manifest files, then passes them to evaluate_packages() for signal analysis. Each ca9 signal maps to a VHSCA rule, and the results merge into VulnHunter's standard ScanFinding format with evidence, location, and remediation guidance.
# ca9 signals map directly to VulnHunter rules
_SIGNAL_TO_RULE = {
"dependency_confusion": "VHSCA100",
"untrusted_registry": "VHSCA101",
"malware": "VHSCA106",
"provenance_regression": "VHSCA108",
# ...
}
SCA runs automatically when ca9>=0.9.0 is installed. It can be disabled with --no-sca for repositories where dependency analysis is not relevant.
Multi-Model LLM Pipeline
Static analysis finds patterns. LLM investigation answers questions that patterns cannot -- whether a tainted value is actually reachable at runtime, whether a sanitizer is correctly applied, whether a finding's severity should be escalated based on the surrounding business logic.
VulnHunter's LLM pipeline operates on the findings produced by the static engines. It does not replace static analysis; it refines it.
Default Provider: xAI Grok
The default model is Grok 4.7 via xAI's API. Grok handles the investigation and verification pipeline in full scan mode, evaluating each static finding for reachability, exploitability, and severity accuracy.
export XAI_API_KEY=your-key
vulnhunter scan /path/to/repo
Anthropic Multi-Model Pipeline
When using --model anthropic, VulnHunter assigns different Claude models to different roles, each operating in an independent conversation context:
Controller -- Claude Opus 4.6: Orchestrates the investigation. Decides which static findings warrant deeper analysis, assigns investigation tasks to workers, and synthesizes the final report. The controller sees the full scan output and the repository's module index.
Workers -- Claude Opus 5.5: Perform deep code analysis on individual findings. Each worker receives a focused context: the finding, the relevant source files, the call graph neighborhood, and instructions to determine exploitability. Workers do not see each other's output.
Verifier -- Claude Mythos 5.1: Independently verifies findings in a completely separate conversation context. The verifier has no access to the investigator's reasoning or the controller's prioritization. This cross-model validation catches confirmation bias -- when an investigator talks itself into believing a finding is exploitable, the verifier evaluates the same evidence from scratch.
export ANTHROPIC_API_KEY=your-key
vulnhunter scan /path/to/repo --model anthropic
This architecture means a finding must survive three independent evaluations before it reaches the final report at full confidence.
Quick Mode
For CI/CD pipelines or environments without API keys, --mode quick runs only the static engines:
# No API key required -- static analysis only
vulnhunter scan /path/to/repo --mode quick
Quick mode produces the same deterministic findings as the static layer of a full scan. The blind CVE test results reported below used this mode.
Blind CVE Test: CVE-2025-55156
To validate VulnHunter against real-world vulnerabilities, we ran it against pyLoad -- a 559-file Python project built on Flask -- at the commit immediately before the fix for CVE-2025-55156, a SQL injection rated High (CVSS 7.8).
Setup: Checkout commit a123accec (parent of fix 134edcdf6e). Run vulnhunter scan with --mode quick. No CVE ID, no file path, no hints.
Result: VulnHunter reported 99 findings across 17 vulnerability categories. The CVE appeared as finding #10, correctly classified as SQL injection (VH101) with HIGH confidence.
The Vulnerable Code
# file_database.py:271 -- CVE-2025-55156
def update_link_info(self, data):
# This parameterized call is safe:
self.c.executemany(
"UPDATE links SET name=?, size=?, status=? "
"WHERE url=? AND status IN (1,2,3,14)",
data,
)
# This string interpolation is not:
statuses = "','".join(x[3] for x in data)
self.c.execute(
f"SELECT id FROM links WHERE url IN ('{statuses}')"
)
VulnHunter's VH101 rule detected that statuses is built from data tuple elements and interpolated directly into a SQL string via f-string formatting, while the executemany call above it correctly uses parameterized queries. The fix replaced the interpolation with parameter placeholders.
Beyond the CVE, VulnHunter also found critical code injection in pyLoad's captcha handler, missing authentication on the /render/ endpoint, open redirects in the login flow, path traversal in file upload APIs, SSRF in captcha resolution, and 12 hardcoded credentials. The false positive rate was 2% (2 out of 99 findings), both involving parameterized queries where an f-string generates placeholder counts rather than interpolated values.
Benchmark: VulnHunter vs. Semgrep vs. Bandit
We tested all three scanners on 63 planted vulnerabilities across 6 synthetic Flask repositories, covering injection, cryptography, authentication, file handling, denial of service, and logic vulnerability categories.
| Scanner | Detected | Detection Rate |
|---|---|---|
| VulnHunter | 60 / 63 | 95.2% |
| Semgrep | 37 / 63 | 58.7% |
| Bandit | 32 / 63 | 50.8% |
Where the Difference Comes From
Import alias resolution. Semgrep and Bandit match on raw source-level names. When a developer writes import requests as r, followed by r.get(url, verify=False), those tools do not recognize r.get as requests.get. VulnHunter resolves every import alias through the module's binding table before rule matching begins.
Interprocedural flow. Pattern matchers analyze each function in isolation. When tainted data passes through a helper function before reaching a dangerous sink, Semgrep and Bandit do not track it across the call boundary. VulnHunter's native flow engine follows the data through the full call chain.
Dual-engine deduplication. When both the AST engine and the flow engine detect the same vulnerable sink, VulnHunter merges them into a single "multi-engine" finding with elevated confidence. This both reduces noise and strengthens the evidence: a finding confirmed by two independent detection methods is more likely to be a true positive.
The Three Misses
VulnHunter missed three vulnerabilities in the benchmark:
- Broken access control requiring business logic understanding. A route that should check ownership but does not -- detecting this requires understanding the application's authorization model, which static analysis cannot infer.
- Taint through ORM model attributes. A value assigned to a model field in one function, then read from the database in another. Static taint analysis loses track at the persistence boundary.
- Timing attack with non-obvious digest target. The comparison target was not visibly a hash or token, so the timing attack rule's heuristic did not trigger.
These limitations are inherent to static analysis and are documented rather than hidden.
Architecture Overview
VulnHunter's scan pipeline runs the following stages:
Repository
|
v
Snapshot.create() -- index every file, detect languages, flag generated/vendored
|
v
PythonProgramIndex.build() -- resolve imports, build call graph, track constants
|
+----> PythonRuleEngine.scan() -- 28 AST rules (VH100-VH128)
|
+----> run_native_flow() -- interprocedural taint (VHNF100-VHNF116)
| |
| +----> go_path_flow -- Go filesystem path tracking
| +----> go_resource_flow -- Go resource allocation tracking
| +----> js_persisted_path_flow -- JS stored path traversal
| +----> js_prototype_flow -- JS prototype pollution
| +----> js_html_response -- JS unescaped HTML output
|
+----> run_secret_scan() -- hardcoded credentials and API keys
|
+----> run_sca() -- supply-chain analysis via ca9
|
v
Deduplicate + Rank -- merge multi-engine findings, assign confidence
|
v
ScanReport -- findings, summary, receipt, detected languages
|
v
[Optional] LLM investigation pipeline -- Grok or Anthropic multi-model
Each engine writes its findings into a common ScanFinding format that includes:
- Rule ID, name, and vulnerability class
- CWE identifiers
- Severity (critical / high / medium / low)
- Location (file path, start line, end line)
- Evidence (the specific code fragment and why it was flagged)
- Remediation guidance
The scan receipt records the exact engine versions, rule set hashes, and file checksums, making every scan reproducible.
Additional Capabilities
Committed-Change Review
Beyond full-repository scanning, VulnHunter supports reviewing committed changes:
vulnhunter review /path/to/repo --base main
This runs the full scanning pipeline against the target revision but filters findings to those with a primary or supporting evidence location touching changed lines. It is designed for pull request gates where a full-repository scan is too broad.
Secret Detection
A dedicated secret scanner (separate from the AST rules) detects:
- Provider-specific API key patterns (AWS, GCP, Stripe, GitHub, and others)
- PEM-encoded private keys
- High-entropy strings in assignment contexts
- Weak credential patterns like
SECRET_KEY = "dev"
Inline Suppression
Findings can be suppressed per-line with a comment:
os.system(cmd) # vulnhunter: ignore VH100
The suppression format accepts specific rule IDs or a bare vulnhunter: ignore to suppress all rules on that line. Suppressed findings are excluded from the report but recorded in the receipt for audit purposes.
Opengrep and CodeQL Integration
VulnHunter can optionally run Opengrep rules and CodeQL queries alongside its native engines. Opengrep is enabled by default when the binary is available; CodeQL requires explicit opt-in with --codeql. Both produce findings in the same ScanFinding format, deduplicated against the native engines.
Getting Started
Install from PyPI:
pip install vulnhunter
For supply-chain analysis, ca9 is included as a dependency. For optional model providers:
pip install "vulnhunter[xai]" # Grok via xAI (default)
pip install "vulnhunter[anthropic]" # Claude multi-model pipeline
Run a static-only scan on any repository:
vulnhunter scan /path/to/repo --mode quick
Check runtime readiness (installed tools, available providers):
vulnhunter doctor
VulnHunter requires Python 3.11 or later. The tree-sitter parsers for Python, JavaScript, TypeScript, Go, C, C#, C++, Java, PHP, Ruby, and Rust are installed automatically.
The source code is available on GitHub. Contributions, bug reports, and benchmark reproductions are welcome.