Support Development

If this project helps your work, support ongoing maintenance and new features.

ETH Donation Wallet
0x11282eE5726B3370c8B480e321b3B2aA13686582

Scan the QR code or copy the wallet address above.

Smart Contract Pattern Finder (SCPF)

🔍 High-performance tool for detecting security vulnerabilities and patterns in Ethereum smart contracts.

How it works: Define patterns in YAML templates → SCPF scans smart contracts → Finds matching patterns → Reports vulnerabilities

Tags: rust smart-contracts security scanner ethereum blockchain vulnerability-detection pattern-matching defi web3 solidity static-analysis open-source mit

---

📑 Table of Contents

• Smart Contract Pattern Finder (SCPF)
  • 📑 Table of Contents
  • ✨ Features
  • 💡 Use Cases
    • Security Auditing
    • DeFi Research
    • Bug Bounty Hunting
    • Development & CI/CD
    • Education & Training
  • 🚀 Quick Start
    • How It Works
    • Installation
    • Initialize Project
    • Scan a Contract
  • 📋 Template Example
  • 🏗️ Architecture
    • Module Overview
  • 🛠️ CLI Commands
    • scpf scan
    • scpf init
  • 🎯 Supported Chains
  • 🔧 Configuration
    • Getting API Keys
  • 📊 Output Formats
  • 🧪 Development
    • Desktop Build
  • 📝 Creating Templates
    • How Templates Work
    • Creating a Template
  • 🤝 Contributing
    • Contribution Guidelines
  • 📄 License
  • 👤 Author
  • 🔗 Links

---

✨ Features

• 🌐 Ethereum Support - Mainnet contract scanning via Etherscan API
• 📁 Local Project Scanning - Scan .sol files in your workspace
• 🔄 Git Diff Scanning - Only scan changed files in PRs
• 🤖 CI/CD Integration - GitHub Actions, GitLab CI, Bitbucket Pipelines
• 📝 YAML Templates - Easy-to-write pattern definitions
• ✅ ERC Compliance - Detect ERC-20/721/1155 implementations
• 📊 Size-Weighted Risk Scoring - Normalized per 100KB to eliminate size bias
• 🧠 Context-Aware Filtering - Reduce obvious false positives with semantic and contextual filters
• ⚡ Chunked Scanning - Handle larger sources without exhausting memory
• 💾 Smart Caching - Avoid redundant API calls
• 🔑 Cascade API Key System - Up to 6 keys with automatic rolling fallback
• 🎯 Modular Architecture - CLI, core engine, server, and web UI components
• 🔒 Security Focused - Built for vulnerability triage, reporting, and SARIF-based code scanning
• 🚀 High Performance - Built with Rust for speed
• 🔧 Extensible - Easy to add custom patterns
• 🌐 Optional Web UI - scpf-server and frontend/ provide a dashboard-driven workflow

---

💡 Use Cases

Security Auditing

• Automated Vulnerability Detection - Scan contracts for common vulnerabilities (reentrancy, delegatecall, unchecked calls)
• Pre-deployment Checks - Validate contracts before mainnet deployment
• Continuous Monitoring - Watch for newly deployed vulnerable contracts

DeFi Research

• Pattern Analysis - Identify common patterns in DeFi protocols
• Protocol Comparison - Compare security implementations across projects
• Risk Assessment - Evaluate smart contract risk profiles

Bug Bounty Hunting

• Automated Reconnaissance - Quickly scan multiple contracts for vulnerabilities
• Pattern Discovery - Find recurring vulnerability patterns
• Batch Analysis - Scan entire protocols at once

Development & CI/CD

• Pre-commit Hooks - Validate contracts before commits
• CI/CD Integration - Automated security checks in pipelines
• Code Review - Assist manual code reviews with automated findings

Education & Training

• Learning Tool - Understand common smart contract vulnerabilities
• Template Library - Study real-world vulnerability patterns
• Security Training - Train developers on secure coding practices

---

🚀 Quick Start

How It Works

1. Create Templates - Define vulnerability patterns in YAML files
2. Load Templates - SCPF reads your pattern definitions
3. Fetch Contracts - Retrieves smart contract source code from blockchain explorers
4. Scan & Match - Applies regex patterns to find vulnerabilities
5. Report Results - Displays findings with severity levels and context

Installation

git clone https://github.com/Teycir/smartcontractpatternfinder.git
cd smartcontractpatternfinder
cargo build --release

Initialize Project

scpf init

Scan a Contract

# Scan blockchain contract
scpf scan 0x1234567890abcdef --chains ethereum

# Scan local project (auto-detects .sol files)
scpf scan

# Scan only changed files (for PRs)
scpf scan --diff main..HEAD

# Scan with custom templates
scpf scan --templates ./my-templates

# Scan multiple contracts
scpf scan 0xabc... 0xdef... 0x123... --chains ethereum

# Export to JSON/SARIF
scpf scan --output json > results.json
scpf scan --output sarif > results.sarif

# Restrict results to critical findings
scpf scan --min-severity critical

---

📋 Template Example

Templates define patterns to search for in smart contracts. SCPF loads these templates and matches them against contract source code.

id: reentrancy-basic
name: Basic Reentrancy Pattern
description: Detects potential reentrancy vulnerabilities
severity: high
tags:
  - security
  - reentrancy
patterns:
  - id: external-call-with-value
    pattern: '\.call\{value:'
    message: External call with value transfer detected
  - id: delegatecall-usage
    pattern: '\.delegatecall\('
    message: Delegatecall usage detected

What happens:

1. SCPF loads this template from templates/reentrancy.yaml
2. Fetches contract source code from blockchain explorer
3. Searches for .call{value: and .delegatecall( patterns
4. Reports any matches with line numbers and context

---

🏗️ Architecture

smartcontractpatternfinder/
├── crates/
│   ├── scpf-types/     # Core types and data structures
│   ├── scpf-core/      # Scanning, semantic analysis, caching
│   ├── scpf-cli/       # Command-line interface
│   └── scpf-server/    # Web server and scan orchestration
├── frontend/           # Optional web dashboard
├── templates/          # Pattern detection templates
├── benchmarks/         # Accuracy and SARIF benchmark tooling
├── scripts/            # Utility scripts (.sh, .py)
├── docs/               # Project documentation
├── sol/                # Solidity test files
└── action.yml          # GitHub Marketplace action definition

Module Overview

• scpf-types: Core data structures (Template, Pattern, Match, ScanResult)
• scpf-core: Business logic (Scanner, TemplateLoader, ContractFetcher, Cache, AST and semantic validation)
• scpf-cli: User interface (CLI commands, output formatting)
• scpf-server: HTTP server for orchestrating scans and streaming progress
• frontend: Browser UI for starting scans and reviewing results

---

🛠️ CLI Commands

scpf scan

Scan smart contracts for patterns.

scpf scan [OPTIONS] [ADDRESSES]...

Options:
  -n, --chains <CHAINS>            Comma-separated chain list
  -t, --templates <TEMPLATES>      Templates directory
  -o, --output <OUTPUT>            Output format [default: console]
      --concurrency <CONCURRENCY>  Concurrent requests [default: 2]
      --pages <PAGES>              Number of explorer pages to fetch [default: 5]
      --diff <DIFF>                Only scan changed files (e.g., main..HEAD)
      --min-severity <LEVEL>       Minimum severity to report [default: high]
      --only-templates <IDS>       Restrict scan to specific template IDs
      --exclude-templates <IDS>    Exclude specific template IDs
      --contract-type <TYPE>       Filter by contract type (erc20, erc721, erc1155, proxy, defi)
      --fast                       Skip semantic analysis for speed
      --fetch-zero-day <DAYS>      Pull recent exploit patterns before scanning
      --extract-sources <N>        Save the top N riskiest sources into the report directory
  -v, --verbose...                 Increase verbosity (-v, -vv, -vvv)
  -h, --help                       Print help

Examples:

# Scan local project
scpf scan

# Scan blockchain contract
scpf scan 0x1234567890abcdef --chains ethereum

# Scan only changed files
scpf scan --diff main..HEAD

# Scan with custom templates
scpf scan --templates ./custom-templates

# Scan with more pages
scpf scan --chains ethereum --pages 10

# Restrict findings to selected templates
scpf scan --only-templates reentrancy,delegatecall-user-input

# Export to SARIF for CI/CD
scpf scan --output sarif > results.sarif

Other Commands

• scpf audit runs the broader audit workflow using the same scan arguments
• scpf templates lists, shows, installs, updates, and browses template collections
• scpf fetch-zero-day imports recent exploit intelligence into templates
• scpf pattern-builder launches the interactive pattern helper

scpf init

Initialize a new SCPF project.

scpf init [PATH]

Options:
  -y, --yes  Skip interactive prompts
  -h, --help Print help

Examples:

# Initialize in current directory
scpf init

# Initialize in specific directory
scpf init ./my-project

# Skip prompts
scpf init --yes

---

🎯 Supported Chains

Chain	Network	API Provider	Status
Ethereum	Mainnet	Etherscan API	✅ Active
BSC	BNB Smart Chain	BscScan API	🚧 Planned
Polygon	Polygon PoS	PolygonScan API	🚧 Planned
Arbitrum	Arbitrum One	Arbiscan API	🚧 Planned
Optimism	OP Mainnet	Optimistic Etherscan API	🚧 Planned
Base	Base Mainnet	BaseScan API	🚧 Planned
Avalanche	Avalanche C-Chain	SnowTrace API	🚧 Planned
Fantom	Fantom Opera	FtmScan API	🚧 Planned
Linea	Linea Mainnet	LineaScan API	🚧 Planned
Scroll	Scroll Mainnet	ScrollScan API	🚧 Planned

Note: Currently only Ethereum mainnet is fully supported. Multi-chain support is planned for future releases. See Chain Support Status for implementation details.

---

🔧 Configuration

API Key Setup

SCPF uses Etherscan API for fetching contract source code. Configure API keys via environment variables:

# Single key (required)
export ETHERSCAN_API_KEY="your-key"

# Optional: Add up to 6 keys for automatic cascade fallback
export ETHERSCAN_API_KEY_2="your-key-2"
export ETHERSCAN_API_KEY_3="your-key-3"
export ETHERSCAN_API_KEY_4="your-key-4"
export ETHERSCAN_API_KEY_5="your-key-5"
export ETHERSCAN_API_KEY_6="your-key-6"

For the packaged desktop app on Linux, you can also create:

~/.local/share/com.teycir.scpf.desktop/.env

with:

ETHERSCAN_API_KEY=your-key

If explorer keys are missing, recent-contract discovery will fail and the desktop app will fall back to generating only the 0-day summary.

Cascade API Key System

SCPF implements a rolling cascade fallback system for API keys:

1. Primary Key - Tries ETHERSCAN_API_KEY first
2. Automatic Rotation - If rate limited or failed, automatically tries next key
3. Up to 6 Keys - Supports ETHERSCAN_API_KEY through ETHERSCAN_API_KEY_6
4. Smart Retry - 50ms delay between key attempts
5. Rate Limiting - Built-in semaphore (5 concurrent requests)

Benefits:

• ✅ Avoid rate limit errors (Etherscan free tier: 5 calls/sec)
• ✅ Increased throughput with multiple keys
• ✅ Automatic failover if one key fails
• ✅ Zero configuration - just add more keys

Getting API Keys

• Etherscan: https://etherscan.io/apis (free tier: 5 calls/sec)

Tip: Create multiple free Etherscan accounts to get 6 API keys for maximum throughput (30 calls/sec).

---

📊 Output Formats

• console - Human-readable terminal output (default)
• json - Machine-readable JSON
• sarif - SARIF format for CI/CD integration

---

🤖 CI/CD Integration

GitHub Actions

Add to .github/workflows/security.yml:

name: Security Scan

on: [push, pull_request]

jobs:
  scpf:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: teycir/smartcontractpatternfinder@v1
        with:
          severity: high
          output-format: sarif
          fail-on-findings: true

Features:

• ✅ Zero configuration
• ✅ SARIF integration (results in Security tab)
• ✅ Cached installation
• ✅ Customizable severity threshold via --min-severity

📖 Full GitHub Action Documentation

GitLab CI

scpf-scan:
  image: rust:latest
  script:
    - cargo install scpf-cli
    - scpf scan --output sarif > results.sarif
  artifacts:
    reports:
      sast: results.sarif

📖 Full GitLab/Bitbucket Documentation

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
scpf scan --diff HEAD || exit 1

---

🧪 Development

# Run tests
cargo test --all

# Check code
cargo check

# Format code
cargo fmt

# Lint
cargo clippy

# Build release
cargo build --release

Desktop Build

The desktop app lives under frontend/ and is packaged with Tauri.

cd frontend
npm install
cargo install tauri-cli --version '^2'
npm run desktop:build
npm run desktop:install-shortcut

Build artifacts are written to frontend/src-tauri/target/release/bundle/.

On Linux, npm run desktop:build produces .deb, .rpm, and .AppImage bundles. The AppImage step runs through linuxdeploy, so it can fail inside restricted sandboxes even when the project itself is healthy. If that happens, rerun the desktop build from a normal host shell instead of a locked-down sandbox.

npm run desktop:install-shortcut installs a local launcher in ~/.local/share/applications/scpf-desktop.desktop, copies the icon set into ~/.local/share/icons/hicolor, and creates a ~/Desktop/SCPF Desktop.desktop shortcut when a Desktop folder exists.

The desktop shell now targets a dedicated local backend address, http://127.0.0.1:32145, to avoid collisions with unrelated services that may already be using 8080.

On first launch, the desktop app also seeds ~/.local/share/com.teycir.scpf.desktop/.env.example so the expected API key format is easy to discover.

---

📝 Creating Templates

Templates are the core of SCPF - they define what patterns to find in smart contracts.

How Templates Work

1. Define Patterns - Write regex patterns that match vulnerable code
2. Set Severity - Classify findings (info, low, medium, high, critical)
3. Add Context - Provide descriptions and messages for findings
4. Save as YAML - Store in templates/ directory
5. SCPF Loads & Scans - Tool automatically uses your templates

Creating a Template

1. Create a .yaml file in templates/
2. Define patterns with regex
3. Set severity level (info, low, medium, high, critical)
4. Add descriptive tags

Template Structure:

id: unique-template-id
name: Human Readable Name
description: Detailed description of what this detects
severity: high  # info | low | medium | high | critical
tags:
  - category
  - subcategory
patterns:
  - id: pattern-id
    pattern: 'regex-pattern'
    message: Description of what was found

---

🤝 Contributing

Contributions welcome! Please follow:

• Amazon Q rules in .amazonq/rules/
• Modular architecture principles
• Test-driven development
• Clean, documented code

Contribution Guidelines

1. Fork the repository
2. Create a feature branch
3. Follow coding standards
4. Add tests for new features
5. Submit a pull request

---

📄 License

MIT License - see LICENSE for details.

---

👤 Author

Teycir Ben Soltane

• Website: teycirbensoltane.tn
• GitHub: @Teycir

---

🔗 Links

• GitHub Repository
• Quick Wins Features - ERC Compliance, L2 Support, Risk Scoring
• Ecosystem & Extensibility - Template Registry, Plugin System
• Project Roadmap - Future plans and status
• Template Changelog - Template version history
• GitHub Action Documentation
• Issue Tracker
• Author Website

---

Built with ❤️ using Rust by Teycir Ben Soltane