# eth-sri/securify2 architecture

> Architecture diagram of the GitHub repository eth-sri/securify2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eth-sri/securify2
- Repository: https://github.com/eth-sri/securify2

## Overview

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: [`securify/analyses/patterns/all_patterns.py`](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/all_patterns.py) (Pattern registry), [`securify/analyses/analysis.py`](https://github.com/eth-sri/securify2/blob/master/securify/analyses/analysis.py) (Analysis API), [`securify/solidity/solidity_ast_compiler.py`](https://github.com/eth-sri/securify2/blob/master/securify/solidity/solidity_ast_compiler.py) (AST compiler), [`securify/ir/cfg_ir.py`](https://github.com/eth-sri/securify2/blob/master/securify/ir/cfg_ir.py) (CFG IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI & orchestration"]
  node_entrypoint["CLI<br/>Python entrypoint<br/>[__main__.py]"]
  node_analysis_api["Analysis API<br/>orchestration<br/>[analysis.py]"]
  node_eth_helper["Etherscan helper<br/>blockchain util"]
end

subgraph group_solidity["Solidity front end"]
  node_solc_compiler["AST compiler<br/>solidity front end"]
  node_cfg_compiler["CFG compiler<br/>solidity front end"]
  node_sol_grammar["0.5.x grammar<br/>versioned Solidity grammar"]
end

subgraph group_model["Modeling core"]
  node_grammar_core["Attr grammar<br/>attribute-grammar framework<br/>[transformer.py]"]
  node_grammar_eval["Evaluators<br/>grammar execution"]
  node_grammar_viz["Grammar viz<br/>visualization<br/>[visualization.py]"]
  node_cfg_ir["CFG IR<br/>graph IR<br/>[cfg_ir.py]"]
  node_graph_utils["Graph utils<br/>graph ops<br/>[graph.py]"]
  node_ir_viz["IR viz<br/>visualization<br/>[cfg_visualizer.py]"]
end

subgraph group_analysis["Static analysis"]
  node_fact_encoder["Fact encoder<br/>fact generation<br/>[factencoder.py]"]
  node_souffle_wrap["Soufflé wrapper<br/>runtime bridge<br/>[wrapper.py]"]
  node_souffle_dl["Datalog analysis<br/>soufflé program<br/>[analysis.dl]"]
end

subgraph group_patterns["Pattern checks"]
  node_patterns_registry["Pattern registry<br/>pattern aggregation<br/>[all_patterns.py]"]
  node_ast_patterns["AST checks<br/>pattern suite"]
  node_ir_patterns["IR checks<br/>pattern suite"]
  node_source_patterns["Source checks<br/>pattern suite<br/>[rtlo_pattern.py]"]
  node_static_patterns["Static checks<br/>pattern suite"]
end

subgraph group_external["External tools"]
  node_solc_tool["solc<br/>external compiler"]
  node_souffle_tool["Soufflé<br/>external dlog engine"]
  node_graphviz_tool["Graphviz<br/>external renderer"]
end

node_entrypoint -->|"starts scan"| node_analysis_api
node_entrypoint -->|"address input"| node_eth_helper
node_analysis_api -->|"compile source"| node_solc_compiler
node_solc_compiler -->|"uses grammar"| node_sol_grammar
node_solc_compiler -->|"invokes"| node_solc_tool
node_solc_compiler -->|"produces IR"| node_cfg_compiler
node_cfg_compiler -->|"builds"| node_cfg_ir
node_cfg_ir -->|"uses"| node_graph_utils
node_grammar_core -->|"executes"| node_grammar_eval
node_grammar_core -->|"renders"| node_grammar_viz
node_cfg_ir -->|"renders"| node_ir_viz
node_analysis_api -->|"selects checks"| node_patterns_registry
node_patterns_registry -->|"includes"| node_ast_patterns
node_patterns_registry -->|"includes"| node_ir_patterns
node_patterns_registry -->|"includes"| node_source_patterns
node_patterns_registry -->|"includes"| node_static_patterns
node_static_patterns -->|"needs facts"| node_fact_encoder
node_fact_encoder -->|"reads IR"| node_cfg_ir
node_fact_encoder -->|"emit facts"| node_souffle_wrap
node_souffle_wrap -->|"runs program"| node_souffle_dl
node_souffle_wrap -->|"invokes"| node_souffle_tool
node_souffle_dl -->|"reports findings"| node_static_patterns
node_analysis_api -->|"aggregates results"| node_static_patterns
node_grammar_viz -->|"renders with"| node_graphviz_tool
node_ir_viz -->|"renders with"| node_graphviz_tool

click node_entrypoint "https://github.com/eth-sri/securify2/blob/master/securify/__main__.py"
click node_analysis_api "https://github.com/eth-sri/securify2/blob/master/securify/analyses/analysis.py"
click node_eth_helper "https://github.com/eth-sri/securify2/blob/master/securify/utils/ethereum_blockchain.py"
click node_solc_compiler "https://github.com/eth-sri/securify2/blob/master/securify/solidity/solidity_ast_compiler.py"
click node_cfg_compiler "https://github.com/eth-sri/securify2/blob/master/securify/solidity/solidity_cfg_compiler.py"
click node_sol_grammar "https://github.com/eth-sri/securify2/blob/master/securify/solidity/v_0_5_x/solidity_grammar.py"
click node_grammar_core "https://github.com/eth-sri/securify2/blob/master/securify/grammar/transformer.py"
click node_grammar_eval "https://github.com/eth-sri/securify2/blob/master/securify/grammar/attributes/evaluators/evaluator_static.py"
click node_grammar_viz "https://github.com/eth-sri/securify2/blob/master/securify/grammar/attributes/visualization.py"
click node_cfg_ir "https://github.com/eth-sri/securify2/blob/master/securify/ir/cfg_ir.py"
click node_graph_utils "https://github.com/eth-sri/securify2/blob/master/securify/ir/graph.py"
click node_ir_viz "https://github.com/eth-sri/securify2/blob/master/securify/ir/visualizer/cfg_visualizer.py"
click node_fact_encoder "https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/factencoder.py"
click node_souffle_wrap "https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/souffle/wrapper.py"
click node_souffle_dl "https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/souffle_analysis/analysis.dl"
click node_patterns_registry "https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/all_patterns.py"
click node_ast_patterns "https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/ast/naming_convention_pattern.py"
click node_ir_patterns "https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/ir/erc20_interface_pattern.py"
click node_source_patterns "https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/source/rtlo_pattern.py"
click node_static_patterns "https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/static/static_analysis_patterns.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_analysis_api,node_eth_helper toneBlue
class node_solc_compiler,node_cfg_compiler,node_sol_grammar toneAmber
class node_grammar_core,node_grammar_eval,node_grammar_viz,node_cfg_ir,node_graph_utils,node_ir_viz toneMint
class node_fact_encoder,node_souffle_wrap,node_souffle_dl toneRose
class node_patterns_registry,node_ast_patterns,node_ir_patterns,node_source_patterns,node_static_patterns toneIndigo
class node_solc_tool,node_souffle_tool,node_graphviz_tool toneTeal
```

## Components

### CLI & orchestration

User entry points and top-level control flow.

- [CLI](https://github.com/eth-sri/securify2/blob/master/securify/__main__.py): Python entrypoint · Command-line interface for scanning local Solidity files or Etherscan-sourced contracts. · `securify/__main__.py`
- [Analysis API](https://github.com/eth-sri/securify2/blob/master/securify/analyses/analysis.py): orchestration · Top-level Python analysis orchestration and scan control. · `securify/analyses/analysis.py`
- [Etherscan helper](https://github.com/eth-sri/securify2/blob/master/securify/utils/ethereum_blockchain.py): blockchain util · 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](https://github.com/eth-sri/securify2/blob/master/securify/solidity/solidity_ast_compiler.py): solidity front end · Builds internal AST-facing structures from Solidity source using solc. · `securify/solidity/solidity_ast_compiler.py`
- [CFG compiler](https://github.com/eth-sri/securify2/blob/master/securify/solidity/solidity_cfg_compiler.py): solidity front end · Transforms Solidity into control-flow oriented intermediate representations. · `securify/solidity/solidity_cfg_compiler.py`
- [0.5.x grammar](https://github.com/eth-sri/securify2/blob/master/securify/solidity/v_0_5_x/solidity_grammar.py): versioned Solidity 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](https://github.com/eth-sri/securify2/blob/master/securify/grammar/transformer.py): attribute-grammar framework · Dependency tracking, transformation, and evaluation framework for structured language analysis. · `securify/grammar/transformer.py`
- [Evaluators](https://github.com/eth-sri/securify2/blob/master/securify/grammar/attributes/evaluators/evaluator_static.py): grammar execution · Static and demand-driven attribute evaluation strategies. · `securify/grammar/attributes/evaluators/evaluator_static.py`
- [Grammar viz](https://github.com/eth-sri/securify2/blob/master/securify/grammar/attributes/visualization.py): visualization · Renders grammar and attribute structures for inspection. · `securify/grammar/attributes/visualization.py`
- [CFG IR](https://github.com/eth-sri/securify2/blob/master/securify/ir/cfg_ir.py): graph IR · Core control-flow graph representation used as the bridge into later analysis. · `securify/ir/cfg_ir.py`
- [Graph utils](https://github.com/eth-sri/securify2/blob/master/securify/ir/graph.py): graph ops · Generic graph helpers, CFG utilities, and graph algorithms. · `securify/ir/graph.py`
- [IR viz](https://github.com/eth-sri/securify2/blob/master/securify/ir/visualizer/cfg_visualizer.py): visualization · 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](https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/factencoder.py): fact generation · Encodes IR and contract facts into Soufflé-compatible relations. · `securify/staticanalysis/factencoder.py`
- [Soufflé wrapper](https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/souffle/wrapper.py): runtime bridge · Runs Soufflé, manages relations, and parses analysis output back into Python. · `securify/staticanalysis/souffle/wrapper.py`
- [Datalog analysis](https://github.com/eth-sri/securify2/blob/master/securify/staticanalysis/souffle_analysis/analysis.dl): soufflé program · 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](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/all_patterns.py): pattern aggregation · Collects available checks and exposes them for CLI selection and reporting. · `securify/analyses/patterns/all_patterns.py`
- [AST checks](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/ast/naming_convention_pattern.py): pattern suite · Syntactic and semantic source-level checks such as naming, visibility, shadowing, and version issues. · `securify/analyses/patterns/ast/naming_convention_pattern.py`
- [IR checks](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/ir/erc20_interface_pattern.py): pattern suite · IR-level conformance checks such as ERC20/ERC721 interfaces and base signatures. · `securify/analyses/patterns/ir/erc20_interface_pattern.py`
- [Source checks](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/source/rtlo_pattern.py): pattern suite · Direct source-text checks such as RTLO detection. · `securify/analyses/patterns/source/rtlo_pattern.py`
- [Static checks](https://github.com/eth-sri/securify2/blob/master/securify/analyses/patterns/static/static_analysis_patterns.py): pattern suite · 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**: external compiler · System Solidity compiler used by the front end.
- **Soufflé**: external dlog engine · Datalog runtime executing the security analysis programs.
- **Graphviz**: external renderer · Graph rendering backend for grammar, IR, and analysis visualizations.

## Connections

- 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.
