Aditya Kuniyil Kattil
The Archive4 min read
securitysoliditypythondeterministic

TrustGraph

Deterministic trust-boundary analysis for Solidity contracts with executable PoC generation.

Status
Shipped
Role
Solo project
Stack
Python · LangGraph · Foundry · Gemini 2.5 Flash

01Problem

Trust-boundary vulnerabilities — externally callable functions that accept unverified input and mutate critical state without a caller guard — are a recurring source of smart contract exploits. The CrossCurve exploit pattern illustrates this: an external function modifies protocol state based on caller-supplied data, with no check on who is calling. The result is arbitrary state manipulation by any address.

Manual auditing is slow and doesn't scale to CI. LLM-based static analysis is fast but non-deterministic — it can miss the same vulnerability on one run and flag a non-issue on another. Neither gives a CI pipeline what it needs: a reproducible signal that produces the same result on every run.

02Predicate model

The scanner records four pattern-based signals: E — exposure, meaning public or external visibility; P — payload, detected through parameter keywords or abi.decode in the body; V — mutation, detected through configured call and state-access patterns; G — guard, detected through configured patterns in modifier tokens or the function body. These are text matches, not proofs that input is unvalidated or that a guard is effective.

The source assigns Critical when E ∧ P ∧ V ∧ ¬G holds. Otherwise, E ∧ V ∧ ¬G is Medium; all remaining combinations are Informational. Medium is not a general three-of-four rule. The labels describe this scanner’s screening policy, not a complete assessment of exploitability.

03Scanner architecture

An eight-node LangGraph workflow loads contracts, runs the static scan, infers trust assumptions, validates guard signals, generates exploit tests, runs Foundry tests when configured, recommends patches, and emits a report.

The Python scanner uses regular expressions to extract function signatures and brace-based traversal to collect function bodies. It checks visibility, parameter and body keywords, mutation patterns, and guard patterns deterministically. It does not use solidity-parser-antlr or build a Solidity AST.

04Foundry exploit generation

The graph generates Foundry exploit-test candidates for Critical findings and can run them when Foundry execution is configured. The generated test attempts to exercise the flagged function and demonstrate the suspected state-changing behavior.

The README demo reports two findings and a passing Foundry exploit test. A successful generated test adds evidence for that particular scenario; it does not establish exploit coverage for every finding or contract.

05VS Code diagnostics

A VS Code extension surfaces findings as inline diagnostics — flagged functions are underlined in the editor, and the hover tooltip shows the predicate match, severity, and a link to the generated PoC test.

The extension reads the JSON report emitted by the scanner. It does not re-run the analysis — the editor view is a display layer over the deterministic output.

06Optional AI explanations

Gemini 2.5 Flash is optionally invoked after severity scoring to generate a trust-assumption explanation: given the flagged function and the predicate match, it explains what trust the function incorrectly assumes and what an attacker could do.

Gemini receives the completed severity assessment as input. It cannot add or remove findings, raise or lower severity, or modify predicate scores. Its output is explanation text only — the finding is already determined.

07Tradeoffs

The four-signal model makes the screening rules inspectable and repeatable. Its Critical and Medium conditions cover selected exposure and mutation patterns; findings still need review in the contract’s actual context.

Pattern matching does not resolve guard semantics or control flow. A matching modifier name or body keyword can suppress a finding without proving effective access control, while an unfamiliar guard or mutation pattern can produce a false positive or miss. Brace-based extraction also has less language awareness than a Solidity parser.

08Limitations

No symbolic execution. The scanner cannot reason about value flows, integer overflow conditions, or reentrancy paths. These require dedicated tools (Slither, Echidna, Halmos).

No cross-file reasoning. Cross-contract trust relationships — proxy patterns, delegatecall chains, inherited permission models — are out of scope. The scanner analyses a single Solidity file.

Heuristic scope. Pattern lists determine what is detected and can produce both false positives and missed risks. There is no measured coverage or false-positive guarantee for arbitrary contracts.