How eth-sri/securify2 works
1. What this repository is
- Securify v2 is a Solidity smart-contract security scanner.
- The architecture is split into a Python orchestration layer and a Datalog-based analysis engine executed by Soufflé.
- It targets Solidity >= 0.5.8 and analyzes flat contracts only, meaning no import graph resolution.
2. Primary entry points
- securify/__main__.py and securify package modules provide the CLI entry point.
- The CLI accepts either:
- a local .sol file, or
- a contract address fetched via the Etherscan API.
- CLI options filter which patterns/severities to run, or list available checks.
3. Solidity front-end boundary
- The securify/solidity package contains the compiler-facing front end:
- solidity_ast_compiler.py
- solidity_cfg_compiler.py
- version-specific grammar/rules under v_0_5_x/
- This layer is responsible for converting source Solidity into internal representations used by later analyses.
- External tooling here matters: it depends on the system solc compiler.
4. Grammar and semantic-analysis subsystem
- The securify/grammar package implements an attribute grammar framework used to model and validate language structure.
- It includes:
- transformers,
- dependency tracking,
- evaluators for static/demand-driven execution,
- visualization support.
- This is an internal analysis foundation, not the main scanner itself, but it supports structured AST processing and validation.
5. Intermediate representation and graph layer
- The securify/ir package defines the repository’s internal graph-based IR and CFG utilities.
- Key pieces:
- cfg_ir.py for control-flow graph representation,
- graph.py and cfgutils.py for graph operations,
- visualizers for AST and CFG.
- This IR forms the bridge between parsed Solidity and both pattern checks and Datalog fact generation.
6. Static-analysis pipeline
- The securify/staticanalysis package is the core vulnerability-analysis engine.
- The flow is:
1. encode IR/contract facts,
2. emit Soufflé-compatible inputs,
3. run Datalog programs in souffle_analysis/,
4. parse the results back into Python.
- factencoder.py, facts.py, and the souffle/ wrapper modules are the main integration boundary between Python and Soufflé.
7. Soufflé analysis model
- The .dl files in securify/staticanalysis/souffle_analysis/ define the actual program logic for:
- control/data flow,
- call graphs,
- storage reasoning,
- context sensitivity,
- security patterns.
- This directory is effectively the analysis specification.
- The libfunctors/ folder contains compiled helper functors used by Soufflé, making the Datalog runtime dependent on native code support.
8. Pattern system
- securify/analyses/patterns/ contains a Python-side pattern abstraction layer grouped by source of evidence:
- AST patterns: naming conventions, shadowed vars, version issues, visibility, etc.
- IR patterns: ERC20/ERC721 interface conformance, base signatures.
- Source patterns: direct source-text checks like RTLO.
- Static patterns: higher-level checks backed by the static-analysis engine.
- all_patterns.py appears to aggregate available checks into a single registry for CLI selection and reporting.
9. Security findings produced by different layers
- The repository deliberately mixes lightweight syntactic checks and deep semantic analyses.
- Simple issues like naming or visibility are caught at the AST/source level.
- Vulnerabilities requiring data/control-flow reasoning, such as reentrancy, delegatecall, unchecked calls, or TOD-style issues, are modeled in Soufflé and reported via the static-analysis layer.
10. Visualization and inspection
- securify/ir/visualizer and securify/grammar/attributes/visualization.py support rendering internal structures.
- securify/staticanalysis/visualization.py is used for analysis-result presentation.
- These components are auxiliary, but they show that the repo is designed to inspect both the program model and the resulting analysis graph.
11. External runtime dependencies
- The architecture depends on three key external tools:
- solc for Solidity parsing/compilation,
- Soufflé for Datalog execution,
- Graphviz/Dot for graph visualization.
- A Dockerfile is provided to package the required environment, including a pinned Solidity compiler version.
12. Supporting utilities
- securify/utils/ contains small shared helpers, including blockchain access and text styling.
- The blockchain helper supports the Etherscan-based input path, which is separate from the local-file analysis flow.
13. Tests as an architecture map
- The test suite mirrors the major subsystems:
- grammar/attribute evaluation,
- Solidity parsing and AST handling,
- static-analysis facts and Soufflé integration,
- pattern-specific vulnerability checks,
- CLI behavior.
- This is a good indicator of the system boundaries: grammar, Solidity front end, static analysis, and user-facing CLI are all distinct modules.
14. Overall data flow to draw
- A good architecture diagram should show:
- Input: Solidity source or Etherscan-fetched contract
- Front end: solc + Solidity compiler modules
- Modeling: grammar/AST/CFG/IR layers
- Analysis: fact encoding → Soufflé Datalog rules → findings
- Pattern checks: AST/IR/source/static pattern registry
- Output: vulnerability report and optional graph visualizations
- The main architectural boundary is between the Python orchestration/representation layer and the Soufflé-based static-analysis engine.
Main entry points: all_patterns.py Pattern registry · analysis.py Analysis API · solidity_ast_compiler.py AST compiler · cfg_ir.py CFG IR
Components 23
CLI & orchestration
User entry points and top-level control flow.
- CLI · Command-line interface for scanning local Solidity files or Etherscan-sourced contracts.
securify/__main__.py - Analysis API · Top-level Python analysis orchestration and scan control.
securify/analyses/analysis.py - Etherscan helper · Fetches contract source data for the address-based input path.
securify/utils/ethereum_blockchain.py
Solidity front end
Compiler-facing translation from Solidity source into internal models.
- AST compiler · Builds internal AST-facing structures from Solidity source using solc.
securify/solidity/solidity_ast_compiler.py - CFG compiler · Transforms Solidity into control-flow oriented intermediate representations.
securify/solidity/solidity_cfg_compiler.py - 0.5.x grammar · Version-specific grammar, rules, modifiers, and builtins for Solidity >= 0.5.x.
securify/solidity/v_0_5_x/solidity_grammar.py
Modeling core
Grammar, AST/CFG, and internal IR structures.
- Attr grammar · Dependency tracking, transformation, and evaluation framework for structured language analysis.
securify/grammar/transformer.py - Evaluators · Static and demand-driven attribute evaluation strategies.
securify/grammar/attributes/evaluators/evaluator_static.py - Grammar viz · Renders grammar and attribute structures for inspection.
securify/grammar/attributes/visualization.py - CFG IR · Core control-flow graph representation used as the bridge into later analysis.
securify/ir/cfg_ir.py - Graph utils · Generic graph helpers, CFG utilities, and graph algorithms.
securify/ir/graph.py - IR viz · AST and CFG visualization helpers for internal representations.
securify/ir/visualizer/cfg_visualizer.py
Static analysis
Fact encoding, Soufflé execution, and result parsing.
- Fact encoder · Encodes IR and contract facts into Soufflé-compatible relations.
securify/staticanalysis/factencoder.py - Soufflé wrapper · Runs Soufflé, manages relations, and parses analysis output back into Python.
securify/staticanalysis/souffle/wrapper.py - Datalog analysis · Analysis specification: dataflow, call graph, storage, contexts, and security patterns.
securify/staticanalysis/souffle_analysis/analysis.dl
Pattern checks
Lightweight AST, IR, source, and static vulnerability checks.
- Pattern registry · Collects available checks and exposes them for CLI selection and reporting.
securify/analyses/patterns/all_patterns.py - AST checks · Syntactic and semantic source-level checks such as naming, visibility, shadowing, and version issues.
securify/analyses/patterns/ast/naming_convention_pattern.py - IR checks · IR-level conformance checks such as ERC20/ERC721 interfaces and base signatures.
securify/analyses/patterns/ir/erc20_interface_pattern.py - Source checks · Direct source-text checks such as RTLO detection.
securify/analyses/patterns/source/rtlo_pattern.py - Static checks · Higher-level vulnerability checks backed by the static-analysis engine.
securify/analyses/patterns/static/static_analysis_patterns.py
External tools
Non-Python executables and runtime dependencies.
- solc · System Solidity compiler used by the front end.
- Soufflé · Datalog runtime executing the security analysis programs.
- Graphviz · Graph rendering backend for grammar, IR, and analysis visualizations.
Connections 25
- CLI → Analysis API: starts scan · CLI dispatches into the orchestration layer.
- CLI → Etherscan helper: address input · Fetches contract source when the user provides an address.
- Analysis API → AST compiler: compile source · Sends Solidity source into the compiler-facing front end.
- AST compiler → 0.5.x grammar: uses grammar · Version-specific parsing and rule definitions guide front-end processing.
- AST compiler → solc: invokes · Depends on the system solc compiler.
- AST compiler → CFG compiler: produces IR · Builds CFG-oriented internal structures for later analysis.
- CFG compiler → CFG IR: builds · Materializes control-flow graph representation.
- CFG IR → Graph utils: uses · Relies on graph utilities for CFG operations.
- Attr grammar → Evaluators: executes · Attribute definitions are evaluated through static or demand-driven strategies.
- Attr grammar → Grammar viz: renders · Grammar structures can be inspected visually.
- CFG IR → IR viz: renders · IR and CFG structures can be visualized.
- Analysis API → Pattern registry: selects checks · CLI/options resolve which checks to run.
- Pattern registry → AST checks: includes · Registers AST-level checks.
- Pattern registry → IR checks: includes · Registers IR-level checks.
- Pattern registry → Source checks: includes · Registers source-text checks.
- Pattern registry → Static checks: includes · Registers static-analysis-backed checks.
- Static checks → Fact encoder: needs facts · Static checks consume encoded facts from the analysis pipeline.
- Fact encoder → CFG IR: reads IR · Encodes IR and contract structure as relations.
- Fact encoder → Soufflé wrapper: emit facts · Produces Soufflé-compatible inputs and relation data.
- Soufflé wrapper → Datalog analysis: runs program · Executes the Datalog analysis specification.
- Soufflé wrapper → Soufflé: invokes · Depends on the Soufflé runtime.
- Datalog analysis → Static checks: reports findings · Security patterns are encoded in Datalog and surfaced back as findings.
- Analysis API → Static checks: aggregates results · Collects and formats checks from all pattern layers.
- Grammar viz → Graphviz: renders with · Visualization output relies on Graphviz/Dot.
- IR viz → Graphviz: renders with · Graph rendering relies on Graphviz/Dot.