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

RuleClassCWESeverity
VH100Command injection -- runtime data in shell callsCWE-78Critical
VH101SQL injection -- string interpolation in database statementsCWE-89High
VH103Server-side template injection -- user data compiled as template sourceCWE-1336Critical
VH111Code injection -- eval() / exec() with runtime dataCWE-95Critical
VH127NoSQL injection -- interpolation in MongoDB operator expressionsCWE-943High

Deserialization and XML

RuleClassCWESeverity
VH102Unsafe deserialization -- pickle.loads(), yaml.load() on untrusted dataCWE-502Critical
VH104XML external entity -- DTD loading and entity resolution enabledCWE-611High

Network and Request Handling

RuleClassCWESeverity
VH105Server-side request forgery -- runtime data selects HTTP destinationsCWE-918High
VH109TLS verification disabled -- verify=False in requests/httpxCWE-295High
VH122CSRF protection disabled -- @csrf_exempt, disabled middlewareCWE-352High
VH123CORS misconfiguration -- wildcard origins, escalated with credentialsCWE-942High

Path and File Handling

RuleClassCWESeverity
VH106Archive path traversal -- zip/tar member names escaping extraction rootCWE-22High
VH107Path traversal -- uncontained path joins below a trusted rootCWE-22High
VH119Insecure file permissions -- world-writable or world-executable modesCWE-732Medium
VH120Predictable temp paths -- manual /tmp construction vs. tempfileCWE-377Medium
VH128Unrestricted file upload -- no content-type, extension, or size validationCWE-434High

Authentication and Authorization

RuleClassCWESeverity
VH108Missing object authorization -- IDOR via caller-controlled ID without ownership checkCWE-639High
VH115Route authorization outlier -- a state-changing route lacks its siblings' auth guardCWE-862Medium
VH117Mass assignment -- setattr() with attacker-controlled keysCWE-915Medium

Cryptography

RuleClassCWESeverity
VH112Weak hash -- MD5/SHA-1 without usedforsecurity=FalseCWE-328Low
VH113Insecure randomness -- random.choice() for tokens/secretsCWE-330Medium
VH116Weak cipher -- DES, Blowfish, RC4, ECB modeCWE-327Medium
VH118Timing attack -- non-constant-time comparison of hashes/tokensCWE-208Medium
VH121JWT none algorithm -- algorithm="none" or verify_signature=FalseCWE-347Critical
VH124Hardcoded IV/nonce -- static constants in AES-CBC/GCMCWE-329High

Configuration and Information Disclosure

RuleClassCWESeverity
VH110Debug mode enabled -- Flask/Django debug=True in productionCWE-489Medium
VH114Insecure cookies -- missing Secure, HttpOnly, SameSite attributesCWE-614Low
VH125Insecure framework config -- ALLOWED_HOSTS=["*"], weak session settingsCWE-16Medium
VH126Stack trace exposure -- exception details in HTTP responsesCWE-209Medium

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:

  1. The call target resolves to a known database execution method (execute, executemany, raw, from_statement, text, read_sql)
  2. The first argument is an f-string, %-format, or .format() call (not a constant)
  3. 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:

RuleSinkCWE
VHNF100Command shell executionCWE-78
VHNF101SQL statement executionCWE-89
VHNF102Dynamic code evaluationCWE-94
VHNF103Outbound HTTP request destination (SSRF)CWE-918
VHNF104Filesystem path operationCWE-22
VHNF105Object-capable deserializationCWE-502
VHNF106Template source compilationCWE-1336
VHNF107Command-line argument injectionCWE-88
VHNF108HTML response without escaping (XSS)CWE-79
VHNF109Redirect destination (open redirect)CWE-601
VHNF110LDAP search filterCWE-90
VHNF111XPath expressionCWE-643
VHNF112Server-side session storage (trust boundary)CWE-501
VHNF113Filesystem path existence probeCWE-22
VHNF114HTTP response headerCWE-113
VHNF115Application log outputCWE-117
VHNF116Regular expression compilationCWE-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's filepath.Join, os.Open, and http.ServeFile with 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__ or constructor.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 by startswith() containment check
  • pathlib.Path.resolve() with parent directory comparison
  • Framework-specific sanitizers like Django's SafeData wrapper
  • 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:

RuleSignalSeverity
VHSCA100Dependency confusion -- internal package name resolvable on public registryCritical
VHSCA101Untrusted registry -- package installed from an unknown indexHigh
VHSCA102Git dependency without pinned commit SHAMedium
VHSCA103Direct URL dependency without integrity hashMedium
VHSCA104Mutable local or file sourceLow
VHSCA105Missing integrity hash in lockfile entryLow
VHSCA106Known malware package matchCritical
VHSCA107Newly published package version (not yet verified)Low
VHSCA108Provenance regression -- attestation present in earlier version, absent nowHigh
VHSCA109Suspicious release flagged by automated sentinel analysisHigh

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.

ScannerDetectedDetection Rate
VulnHunter60 / 6395.2%
Semgrep37 / 6358.7%
Bandit32 / 6350.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:

  1. 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.
  2. 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.
  3. 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.