Smart Contract Security Assistant
Static vulnerability screening with a local SQLite evidence database and grounded explanations.
WHERE IT STANDS
- Slither AST parsing across 27 mapped static analysis detection rules
- Deterministic CWE and SWC vulnerability taxonomy mapping
- Local SQLite Evidence Graph linking detector IDs, AST node references, and line spans
- React reviewer workbench with split-pane code exploration and diff review
- Constrained LLM explanation grounded strictly in verified AST nodes (zero freeform scanning)
- 4 false positives recorded in Slither50 v2 benchmark (reentrancy and delegatecall heuristics)
- Native compiler build scripts disabled by default for reviewer environment security
- Developer triage workbench only; cannot replace formal verification or manual security audits
01 · Problem & Tool Limitations
Language models are often used to review smart contracts, but they have well-known limitations: they can invent non-existent vulnerability types, hallucinate CVE numbers, or miss state machine bugs. Meanwhile, raw static analysis tools like Slither output hundreds of lines of technical logs that take time to interpret.
SCSA was built to combine the strengths of both tools. Static analysis identifies issues and code locations, normalized findings are stored in a local SQLite database, and the LLM is restricted to explaining and drafting fixes for those specific findings.
02 · System Constraints
The LLM cannot invent or report vulnerabilities independently. Findings must come from verified Slither static analysis rules.
Native build scripts (Foundry/Hardhat) are disabled by default to prevent untrusted repositories from executing scripts on the reviewer machine.
Every finding links to the exact source file, line numbers, and Slither detector rule.
03 · Architecture & Grounding
Solidity files pass through an ingestion check into Slither static analysis. Normalized findings populate a local SQLite database, which supplies the context for local LLM explanations.
Static Screening & Grounded Explanation Flow
01. Ingestion: Reads untrusted Solidity files with path protection; native compiler build scripts are turned off by default.
02. Static Analysis: Runs 27 mapped Slither rules, producing AST line spans and call graphs.
03. Normalization: Maps detector findings into unified schemas with standard CWE/SWC vulnerability IDs.
04. Local Database: Saves verified findings and code locations in SQLite as concrete reference records.
05. Explanations: The local LLM explains code issues and drafts fixes using only the confirmed findings from the database.
04 · Three Architecture Decisions
1. Static analysis rules define findings
FINDING ACCURACYContext: Asking an LLM to find bugs in raw code produces inconsistent results and imagined issues.
Decision: Only 27 curated Slither static detectors can record findings in the report. Unmapped output is stored as raw text. The LLM only explains confirmed findings.
Outcome: Achieved 100% recall on the 50-contract Slither50 v2 benchmark with exact code references.
2. Native compiler build scripts disabled by default
REVIEWER SAFETYContext: Running build scripts from untrusted Foundry or Hardhat projects can run malicious scripts on the reviewer computer.
Decision: Default to single-file AST parsing via solc-select with build scripts disabled. Full project compilation requires an explicit --allow-native-builds flag with warnings.
Outcome: Prevents unexpected script execution during automated triage scans.
3. Local LLM with static fallback
SYSTEM RELIABILITYContext: Not all developer machines have GPUs or Apple Silicon to run local LLMs smoothly.
Decision: Use Apple MLX when available for grounded walkthroughs. If offline or on CPU-only machines, fall back to static CWE guidance and pattern references.
Outcome: The CLI tool and React workbench work completely without an LLM runtime or external API keys.
05 · Hardest Technical Problem
Normalizing varied Slither outputs into a single database schema
Root Cause: Different Slither detectors produce completely different JSON outputs: some point to individual expressions, others to variable definitions, and reentrancy detectors return multi-step call traces across inherited contracts.
Engineering Approach: Built a Python normalization layer that maps diverse detector outputs into a single finding schema with source snippets, line numbers, and hash-based deduplication. Stored findings and contracts in SQLite.
Verification: Tested across 140 pytest cases, including complex Solidity patterns like Diamond Proxies and custom errors.
06 · Benchmark Results & Known Limitations
SCSA avoids marketing claims of "automated security." On the public Slither50 v2 test set, it caught all vulnerable cases (100% recall), but produced 4 false positives.
07 · Test Suites & Build Verification
Full backend test coverage for Slither parsers, solc version resolution, SQLite queries, and CLI commands.
Frontend test suite for the React reviewer workbench, filters, and diff viewer.
Packaged cleanly via Hatchling with valid source distributions and wheels.
Clear score difference between safe contracts (mean 8.2) and vulnerable contracts (mean 53.25).
08 · Retrospective & Learnings
Engineering Takeaway: Takeaway: In security tools, fluent text without verified backing data is dangerous. Separating detection (deterministic static analyzers) from explanation (LLMs) eliminated invented vulnerabilities while still making findings easier for developers to understand.
What I Would Do Differently: What I Would Do Differently: Integrate symbolic execution tools (like Manticore or Halmos) into the verification step to automatically check false positives before presenting them to the reviewer.