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/29
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):

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.

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/LLM Analysis        SmartLLM, GPTScan, LLMSmartAudit (Ollama)
Layer 6  Pattern Detection      Gas Analyzer, Clone Detector, Threat Model
Layer 7  DeFi Security          MEV Detector, Flash Loan Analyzer, Oracle Checker
Layer 8  Exploit Validation     PoC Synthesizer (Foundry), Vulnerability Verifier
Layer 9  Consensus & Reporting  Bayesian Consensus, RAG Enrichment, PDF Reports

*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@v5
        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.

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 $326M, Ronin $624M).

Bridge vulnerability detection:

miesc scan Bridge.sol             # Detects 7 bridge exploit patterns

All Commands

Docker

The current release is v5.4.3 (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   # Best model for code analysis
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: v5.4.3
    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: miesc_quick_scan, miesc_deep_scan, miesc_deep_audit, miesc_run_tool, miesc_run_layer, miesc_analyze_defi, miesc_apply_fix, miesc_validate_remediation, miesc_remediation_evidence_bundle, miesc_list_tools, miesc_doctor

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 src.utils.web_dashboard --results analysis/results --output analysis/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

MIESC uses a dual-package architecture:

• miesc/ - Public API (stable, pip-installable)
• src/ - Internal implementation (35 analysis modules, ML pipeline, RAG, report generation)

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

Academic Validation

MIESC was developed as a Master's thesis in Cyberdefense at UNDEF-IUA (Argentina). The current research claims are consolidated in Paper 1, Paper 2, and their reproducibility artifacts:

• 143 contracts, 207 ground-truth vulnerabilities, 10 categories
• 95.8% recall on the latest full-corpus reproducible local SmartBugs profile; Slither alone baseline: 43.2%
• Paper 1 reports a local Ollama follow-up on the residual SmartBugs misses at 140/143 (97.9%); the reproducible corpus artifact remains the 95.8% JSON profile.
• Paper 1 now treats EVMBench as the primary business-logic benchmark: static-only reaches 22/120 (18.3%), while the reproducible four-provider ensemble reaches 111/120 (92.5%)
• Paper 2 evaluates remediation artifacts: 123/143 fixes applied, 123/123 patched contracts compile standalone, 88/123 eliminate the original finding by re-scan, 121/123 pass bounded no-regression, and 70/123 are clean-HIGH under external Slither
• Reproducible SmartBugs profile runs in 737.0s total (~5.15 sec/contract)
• Canonical results: Paper 1 reproducibility, Paper 2 reproducibility, Paper 1 claims matrix, Paper 2 claims matrix

If you use MIESC in research, please cite:

@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 is fully compliant with all 9 DPGA indicators: open license (AGPL-3.0), clear ownership, platform independence, comprehensive documentation, data portability (SARIF/CSV/JSON), privacy-preserving (local-first), standards-based (12 international standards), and responsible use policies.

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

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