MIESC

50 security tools. 9 defense layers. One command.

Enterprise-grade smart contract security, free and open to everyone.

Quick Start • Why MIESC • GitHub Action • Docker • Espanol • Docs

Quick Start

pip install miesc
miesc scan MyContract.sol

That's it. MIESC runs Slither + Aderyn + Solhint, deduplicates findings, and gives you a unified report with confidence scores in seconds.

Full pipeline: detect → fix → verify → comply

miesc scan contract.sol -o results.json           # Detect + intelligence
miesc fix results.json -c contract.sol -o fixed.sol  # Auto-patch vulnerabilities
miesc remediate results.json -c contract.sol --compile --rescan  # Patch + evidence bundle
miesc verify fixed.sol --tool smtchecker           # Prove fix works
miesc compliance results.json --standard mica      # Map to MiCA/DORA/ISO 27001
miesc report results.json -t premium -f pdf        # Professional audit report

Current research pipeline: Intelligence Engine

miesc scan contract.sol --verbose                  # Per-finding confidence + fix
miesc scan contracts/ --recursive                  # Directory scanning
miesc scan . --diff origin/main                    # PR-level: only changed files
miesc scan contract.sol --verify-fp                # Recall-safe FP filter: drops only provably-benign, flags the rest

The intelligence engine automatically:

• Deduplicates cross-tool findings (Slither + Aderyn report same bug → 1 finding)
• Scores confidence via Bayesian multi-tool agreement (2 tools = 85%, 3 = 95%)
• Generates fix code — copy-pasteable Solidity patches for 10 vulnerability categories
• Reduces false positives — drops only type-deterministic benign (Solidity 0.8+, checked call/SafeERC20, informational lint); contextual guards (onlyOwner, nonReentrant) are flagged for review, never dropped (recall 1.0)
• Calibrates severity across tools (Aderyn LOW → Medium when warranted)

Want the full 9-layer analysis with AI correlation?

miesc audit full MyContract.sol -o results.json
miesc report results.json -t premium -f pdf --llm-interpret

=== Layer 1: Static Analysis ===
OK slither: 5 findings in 1.7s
OK aderyn: 5 findings in 3.0s
OK solhint: 0 findings in 0.7s

=== Layer 2: Dynamic Testing ===
OK echidna: 0 findings in 2.0s
OK foundry: 0 findings in 9.0s

=== Layer 3: Symbolic Execution ===
OK mythril: 2 findings in 298.0s

=== Layer 5: AI Analysis ===
OK smartllm: 4 findings in 198.9s
OK gptscan: 4 findings in 49.7s

 Full Audit Summary
+----------+-------+
| Severity | Count |
+----------+-------+
| CRITICAL |     1 |
| HIGH     |    11 |
| MEDIUM   |     1 |
| LOW      |     9 |
| TOTAL    |    22 |
+----------+-------+

Tools executed: 12/50
Report saved to results.json

Why MIESC

The problem: Professional smart contract audits cost $50K-$200K and take weeks. Meanwhile, $1.5B+ is lost to exploits every year. Most projects ship without any audit at all. Running Slither alone catches ~70% of vulnerabilities with 15-20% false positives. Every tool has blind spots. Auditors manually run 5-10 tools, normalize outputs, and cross-reference findings. This takes hours.

MIESC makes that workflow accessible to everyone. One command orchestrates multiple security tools across 9 complementary analysis techniques, deduplicates findings, and generates professional reports. Free, open-source, runs locally — your code never leaves your machine.

Benchmark Results

SmartBugs-curated (143 contracts, 207 ground-truth vulnerabilities):

A controlled, LLM-free ablation shows where the recall comes from — each layer adds detected contracts without losing any (all figures recomputed by benchmarks/verify_paper_claims.py):

Precision on this legacy corpus is 22.2% (36.0% F1) — the expected trade-off for a recall-first pre-audit triage tool.

To re-run this profile on your own machine and compare it with the paper artifact, follow REPRODUCE.md (about 15 minutes, no LLM or API key needed).

The full-corpus SmartBugs result is the reproducible Paper 1 profile. A local Ollama follow-up on the remaining misses is reported in Paper 1 as 140/143 (97.9%) and should be treated as a secondary follow-up claim until its own machine-readable lift artifact is published. The 9-layer run is reported separately as an end-to-end integration smoke run, not as a corpus-wide claim.

Real-world exploits (11 confirmed DeFi exploits, $1.59B in combined losses):

81.8% recall on real-world exploits — MIESC would have flagged 9 of 11 multi-million dollar exploits before deployment. Paper 1 reproducibility | Exploit evaluation

Why recall matters more than precision for pre-audit triage: High recall means fewer missed vulnerabilities. False positives are filtered in the triage step — missed vulnerabilities become exploits in production.

Cost efficiency (EVMBench, 40 audits): detection does not require frontier prices. An open-weight model (DeepSeek-R1, MIT weights) reaches the best precision (88.5%) and F1 (78.7%) in the comparison at an estimated ~$0.08/audit — 15–69× cheaper than frontier APIs — while a fully-local 32B model reaches 59.2% recall at $0. Paying frontier prices buys higher single-run recall, not better precision/F1. See Paper 1 for the run-count-matched detail.

Research Papers and Reproducible Claims

MIESC has two linked research tracks. Paper 1 evaluates detection and multi-layer security assessment. Paper 2 extends that evidence into automatic remediation artifacts and independent verification steps. Paper 2 does not replace or invalidate Paper 1; it starts from the same detection pipeline and measures what happens after a finding is converted into a patch candidate.

For research citation and review, the canonical current claims are the two paper PDFs, their reproducibility notes, and the benchmarks/results/paper*_claims_matrix.json files. The platform alignment plan maps these paper results into CLI, API, MCP, RAG, and remediation workflow requirements: Paper learnings and platform alignment. RAG source selection and weighting are governed by the RAG source policy. Older release notes, thesis drafts, and roadmap documents are kept for project history and may contain previous benchmark runs or version-specific metrics.

Current technical-debt cleanup and remaining platform work are tracked in the technical debt remediation plan.

The 9 Defense Layers

Layer 1  Static Analysis            Slither, Aderyn, Solhint, Semgrep
Layer 2  Dynamic Testing            Echidna, Foundry, Medusa
Layer 3  Symbolic Execution         Mythril, Halmos, Manticore
Layer 4  Formal Verification        SMTChecker, Scribble, Certora*
Layer 5  AI Analysis                SmartLLM, GPTScan, LLMSmartAudit, GPTLens (Ollama)
Layer 6  ML Detection               DA-GNN, SmartBugs-ML, SmartGuard, Peculiar
Layer 7  Specialized Analysis       Threat Model, Gas Analyzer, MEV Detector, Clone Detector, DeFi
Layer 8  Cross-Chain & ZK Security  Cross-Chain, ZK Circuit, Bridge Monitor, L2 Validator, Circom
Layer 9  Advanced AI Ensemble       LLMBugScanner, Audit Consensus, Exploit Synthesizer, Vuln Verifier

Layers 8–9 include experimental multi-chain/ZK and ensemble-consensus modules; the EVM analysis path (Layers 1–7) is the production-ready core (multi-chain is on the roadmap). The canonical layer definition lives in miesc/cli/constants.py.

*Certora requires API key. All other tools are fully open-source.

What MIESC integrates

vs. SmartBugs 2.0 (closest competitor)

GitHub Action

Add smart contract security to any CI/CD pipeline in 30 seconds:

# .github/workflows/security.yml
name: Security
on: [push, pull_request]

permissions:
  security-events: write
  pull-requests: write

jobs:
  miesc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: fboiero/MIESC@v6.0.0
        with:
          path: contracts/
          mode: scan
          fail-on: high
          upload-sarif: true
          comment-on-pr: true

Results appear in GitHub's Security tab and as a PR comment. See example workflow for advanced configurations.

Available Modes

Installation

# Minimal CLI
pip install miesc

# With PDF reports
pip install miesc[pdf]

# Everything for local analysis (PDF, LLM, RAG, APIs)
pip install miesc[full]

# Development
git clone https://github.com/fboiero/MIESC.git
cd MIESC && pip install -e .[dev]

Requirements: Python 3.12+. Slither installs automatically. Other tools are optional — MIESC uses whatever is available.

Slither needs a solc that matches each contract's pragma. Install the versions you analyze once; MIESC picks the installed one that satisfies the pragma:

pip install solc-select
solc-select install 0.4.26 0.5.17 0.6.12 0.7.6 0.8.20

To reproduce the paper numbers (Slither + Aderyn + Solhint + the built-in detectors), follow REPRODUCE.md.

For a full researcher workstation with isolated Mythril, Manticore, Certora CLI, Wake, Semgrep, and formal-verification tooling:

git clone https://github.com/fboiero/MIESC.git
cd MIESC
./scripts/bootstrap_researcher_tools.sh
make researcher-smoke

See Researcher Packaging Guide for the recommended PyPI + Docker + local bootstrap distribution model.

Multi-Chain Support

miesc analyze Token.sol           # EVM (Solidity/Vyper) — production
# Non-EVM (Cairo/Solana/Move/NEAR/Stellar/Algorand/Cardano) is on the ROADMAP:
# experimental adapter code exists but is not production-validated yet.

77 vulnerability types across 4 ecosystems, informed by real 2024-2026 exploits (zkLend $9.6M, Braavos, Wormhole $320M, Ronin $624M).

Bridge vulnerability detection:

miesc scan Bridge.sol             # Detects 7 bridge exploit patterns

All Commands

Docker

The latest published PyPI / GHCR release is 6.2.0, matching the code on main (see CHANGELOG). Release status, published artifact links, GHCR digest, and smoke-test commands from the most recent detailed release-status report (v5.4.2) are recorded in MIESC 5.4.2 Release Status.

# Standard image (~3GB, multi-arch including Apple Silicon)
docker pull ghcr.io/fboiero/miesc:latest
docker run --rm -v $(pwd):/contracts ghcr.io/fboiero/miesc:latest scan /contracts/MyContract.sol

# Full image (~8GB, all 50 tools, amd64)
docker pull ghcr.io/fboiero/miesc:full
docker run --rm -v $(pwd):/contracts ghcr.io/fboiero/miesc:full audit full /contracts/MyContract.sol

# Check what tools are available
docker run --rm ghcr.io/fboiero/miesc:latest doctor

# 1. Install and start Ollama on your HOST (not inside Docker)
# Download from https://ollama.com
ollama serve &
ollama pull qwen2.5-coder:14b   # Recommended: fast, ~9 GB (use :32b for higher audit quality)
ollama pull deepseek-coder:6.7b  # Lighter alternative

# 2. Scan with host Ollama (macOS)
docker run --rm \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -v $(pwd)/contracts:/contracts \
  ghcr.io/fboiero/miesc:latest \
  scan /contracts/MyContract.sol -o /contracts/results.json

# 3. Scan with host Ollama (Linux)
docker run --rm --network=host \
  -e OLLAMA_HOST=http://localhost:11434 \
  -v $(pwd)/contracts:/contracts \
  ghcr.io/fboiero/miesc:latest \
  scan /contracts/MyContract.sol

# 4. Generate AI-powered premium PDF report
docker run --rm \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -v $(pwd):/work \
  ghcr.io/fboiero/miesc:full \
  report /work/results.json -t premium -f pdf \
    --llm-interpret -o /work/audit_report.pdf

# Start MIESC + Ollama + model initialization
docker compose -f docker/docker-compose.yml --profile llm up -d

# Run analysis
docker compose -f docker/docker-compose.yml exec miesc miesc scan /app/contracts/MyContract.sol

# Stop
docker compose -f docker/docker-compose.yml down

./scripts/build-images.sh full

./scripts/bootstrap_researcher_tools.sh

MIESC_BUILD_MYTHRIL=true ./scripts/build-images.sh full
MIESC_BUILD_MANTICORE=true ./scripts/build-images.sh full
MIESC_BUILD_HALMOS=true ./scripts/build-images.sh full
MIESC_BUILD_SEMGREP=true ./scripts/build-images.sh full

CLI Reference

miesc scan contract.sol              # Quick scan (Slither + Aderyn + Solhint)
miesc scan contract.sol --ci         # CI mode: exit 1 on critical/high
miesc audit quick contract.sol       # 3-tool audit
miesc audit full contract.sol        # Full 9-layer audit
miesc audit layer 3 contract.sol     # Specific layer (e.g., symbolic execution)
miesc audit profile defi contract.sol  # Named profile (defi, token, security, etc.)
miesc report results.json -t premium -f pdf --llm-interpret  # AI-powered PDF report
miesc export results.json -f sarif   # Export as SARIF
miesc doctor                         # Check tool availability
miesc watch ./contracts              # Auto-scan on file changes
miesc benchmark ./contracts --save   # Track security posture over time

Analysis Profiles

Extend MIESC

Custom Detectors

from miesc.detectors import BaseDetector, Finding, Severity

class DangerousDelegatecall(BaseDetector):
    name = "dangerous-delegatecall"
    description = "Detects unprotected delegatecall patterns"

    def analyze(self, source_code, file_path=None):
        findings = []
        # Your detection logic here
        return findings

Register via pyproject.toml:

[project.entry-points."miesc.detectors"]
dangerous-delegatecall = "my_package:DangerousDelegatecall"

Plugin System

miesc plugins install miesc-defi-detectors   # Install from PyPI
miesc plugins create my-detector             # Scaffold a new plugin
miesc plugins list                           # List installed plugins
miesc detectors list                         # List all available detectors

Integrations

# Pre-commit hook (.pre-commit-config.yaml)
repos:
  - repo: https://github.com/fboiero/MIESC
    rev: v6.2.0
    hooks:
      - id: miesc-quick
        args: ['--ci']

# Foundry (foundry.toml)
[profile.default]
post_build_hook = "miesc audit quick ./src --ci"

// Hardhat (hardhat.config.js)
require("hardhat-miesc");
module.exports = {
  miesc: { enabled: true, runOnCompile: true, failOn: "high" }
};

MCP Server (Claude Desktop / Cursor / Claude Code)

MIESC exposes its 9-layer security analysis as MCP tools via Model Context Protocol:

pip install 'miesc[mcp]'   # Install with MCP support
miesc-mcp                   # Start stdio MCP server

Add to your Claude Desktop config.json:

{
  "mcpServers": {
    "miesc": {
      "command": "miesc-mcp",
      "env": {"OLLAMA_HOST": "http://localhost:11434"}
    }
  }
}

Available MCP tools (22): miesc_quick_scan, miesc_deep_scan, miesc_deep_audit, miesc_profile_scan, miesc_run_tool, miesc_run_layer, miesc_analyze_defi, miesc_correlate, miesc_filter_fp, miesc_detect_exploit_chains, miesc_verify_finding, miesc_generate_report, miesc_map_compliance, miesc_remediate, miesc_apply_fix, miesc_validate_remediation, miesc_remediation_evidence_bundle, miesc_get_metrics, miesc_get_status, miesc_list_tools, miesc_get_tool_info, miesc_read_contract.

The server targets the MCP Python SDK 1.x; pip install 'miesc[mcp]' pins it. If miesc-mcp reports an incompatible SDK, run pip install 'mcp[cli]<2'.

REST API Remediation

The API exposes the same remediation evidence schema as the CLI:

Examples: Remediation API and MCP guide.

Python API

from miesc.api import run_tool, run_full_audit

results = run_tool("slither", "contract.sol")
report = run_full_audit("contract.sol")

Local APIs And Reports

pip install "miesc[django]"
python -m miesc.api.rest --host 127.0.0.1 --port 8000
python -m miesc.utils.web_dashboard --results ./results --output ./dashboard

The open core exposes local REST/MCP automation and static report generation. The hosted product UI, team dashboards, licensing workflow, and IDE product clients now live in the platform layer.

Multi-Chain Support

EVM analysis (50 tools, 9 layers) is production-ready. Non-EVM chains are on the roadmap: early adapter code exists but is experimental and not yet production-validated.

Compliance Mapping

MIESC maps every finding to international security standards:

ISO/IEC 27001:2022 | NIST CSF | OWASP Smart Contract Top 10 | CWE | SWC Registry | MITRE ATT&CK | PCI-DSS | SOC 2

Architecture

Contract.sol
    |
    v
 CLI / API / MCP / GitHub Action
    |
    v
 Orchestrator --> 9 Layers --> Configured Adapter Stack
    |
    v
 Finding Aggregator --> ML Pipeline --> RAG Context --> FP Filter
    |
    v
 Report Generator --> JSON / SARIF / PDF / HTML / Markdown

All code lives in the single miesc/ package (pip-installable): CLI, adapters for the 50 tools, ML pipeline, RAG, remediation and report generation. Run miesc doctor to see which tools are usable on your machine.

See ARCHITECTURE.md for the full technical design with Mermaid diagrams.

Academic Validation

MIESC's research claims are consolidated in two companion papers for the IV Simposio Internacional de Blockchain y Ciberseguridad (RIBCi–CYTED 2026) and their reproducibility artifacts. MIESC began as a Master's thesis in Cyberdefense at UNDEF-IUA (Argentina), which remains a secondary reference. The figures below are the camera-ready paper's evidence (MIESC v5.4.1, tag 09ef10f); each is recomputed from a repository JSON by benchmarks/verify_paper_claims.py.

• 143 contracts, 10 vulnerability categories (SmartBugs-curated).
• 95.8% recall (137/143) on the reproducible, LLM-free SmartBugs profile; 22.2% precision, 36.0% F1. A controlled LLM-free ablation attributes the recall to MIESC's own layers: static 82.5% (118/143) → +own detectors 93.0% (133/143) → +intelligence engine 97.9% (140/143), each step gaining contracts without losing any.
• Business-logic (EVMBench): the score depends on the matching protocol, so both are reported. In one Claude run scored under every protocol, a lenient keyword matcher credits 88.3% (106/120) while EVMBench's official GPT-5 judge confirms 27.4% (32/117); a contract-agnostic null control credits 50% (60/120), so custom-matcher numbers need a control to be interpretable. The union of four provider runs reaches 92.5% (111/120) under the lenient matcher.
• Real-world exploits: 9/11 (81.8%, 95% Wilson CI [52%, 95%]) on DeFiHackLabs attack reproductions (a case study on attack code, not victims).
• Remediation (Paper 2): 123/143 fixes applied, 123/123 patched contracts compile standalone, 88/123 report fewer HIGH findings on re-scan, 121/123 pass bounded no-regression, and 70/123 are clean-HIGH under external Slither.
• Canonical sources: Paper 1 (camera-ready), Paper 2 (camera-ready), Paper 1 reproducibility, Paper 2 reproducibility, Paper 1 claims matrix, Paper 2 claims matrix. Re-check everything with python benchmarks/verify_paper_claims.py.

If you use MIESC in research, please cite the two RIBCi–CYTED 2026 papers (the thesis is a secondary reference):

@inproceedings{boiero2026miesc,
  title={{MIESC}: A Multi-layer Framework for Automated Smart Contract Security Evaluation},
  author={Boiero, Fernando and Mussetta, Sebastian Norberto and Cena, Norberto Gaspar},
  booktitle={IV Simposio Internacional de Blockchain y Ciberseguridad (RIBCi--CYTED 2026)},
  series={Livros de Atas},
  publisher={Edi{\c{c}}{\~o}es CEOS.PP, ISCAP},
  address={Porto, Portugal},
  year={2026}
}

@inproceedings{boiero2026remediation,
  title={From Findings to Verifiable Remediation Artifacts: A Smart Contract Security Pipeline},
  author={Boiero, Fernando and Mussetta, Sebastian Norberto and Cena, Norberto Gaspar},
  booktitle={IV Simposio Internacional de Blockchain y Ciberseguridad (RIBCi--CYTED 2026)},
  series={Livros de Atas},
  publisher={Edi{\c{c}}{\~o}es CEOS.PP, ISCAP},
  address={Porto, Portugal},
  year={2026}
}

@mastersthesis{boiero2025miesc,
  title={Integrated Security Assessment Framework for Smart Contracts:
         A Defense-in-Depth Approach to Cyberdefense},
  author={Boiero, Fernando},
  year={2025},
  school={Universidad de la Defensa Nacional (UNDEF) - IUA C{\'o}rdoba},
  type={Master's Thesis in Cyberdefense}
}

Digital Public Good

MIESC is a candidate for Digital Public Goods Alliance certification (Application ID: GID0092948), aligned with the UN Sustainable Development Goals:

• SDG 9 (Industry & Infrastructure): Strengthening blockchain infrastructure security
• SDG 16 (Peace & Strong Institutions): Protecting digital assets, reducing fraud
• SDG 17 (Partnerships): Open-source collaboration for global security standards

The project self-assesses as meeting all 9 DPGA indicators — open license (AGPL-3.0-only), clear ownership, platform independence, comprehensive documentation, data portability (SARIF/CSV/JSON), privacy-preserving (local-first), standards-based (12 international standards), and responsible use policies — and its DPGA application is under review.

Documentation

Troubleshooting

python3 -m miesc.cli.main --help

pip install miesc[full]              # All Python-based tools
brew install mythril                 # System install
docker run ghcr.io/fboiero/miesc:full  # Or use the full Docker image

ollama pull qwen2.5-coder:14b   # ~9 GB, recommended
ollama pull qwen2.5-coder:32b   # ~20 GB, more accurate (needs 24+GB RAM)

docker run -e OLLAMA_HOST=http://host.docker.internal:11434 ...

pip install solc-select
solc-select install 0.4.26 0.5.17 0.8.20

pip install 'mcp[cli]>=1.2.0,<2'

brew install pango cairo gdk-pixbuf libffi   # macOS
sudo apt install libpango-1.0-0 libpangoft2-1.0-0  # Linux

Contributing

git clone https://github.com/fboiero/MIESC.git
cd MIESC && pip install -e .[dev]
pytest tests/ --no-cov              # Fast local run
pytest tests/ --cov=miesc --cov-report=term-missing  # Coverage run

See CONTRIBUTING.md for guidelines. CONTRIBUTING_ES.md disponible en espanol.

License

AGPL-3.0 - Free for any use. Security should not be a privilege reserved for well-funded projects. If you build a service on top of MIESC, contribute your changes back.

Author

Fernando Boiero - Master's Thesis in Cyberdefense, UNDEF-IUA Argentina

Built on the shoulders of: Slither, Mythril, Echidna, Foundry, Aderyn, Halmos, and the Ethereum security community.