emilianosolazzi/TSI-Audit-Scanner

# TSI-Audit-Scanner **Temporal State Inconsistency detection for smart contracts.** Autonomous, multi-chain auditor combining on-chain and repository scanning with execution-aware contradiction classification. ## 我们发现而他人未发现 ### 1. **一致性矛盾**（时间状态不一致 — TSI） State contradictions (τ₁ ≠ τ₂) across execution contexts: - **Callback state exposure**: State read before callback completes vs. after (Uniswap hooks, Balancer flash loans) - **CEI pattern violations**: Effects not finalized before external interactions - **Oracle temporal inconsistency**: Price differs between read points in same transaction - **Access control inconsistency**: Permissions granted/revoked during sensitive operations *What others miss:* Slither, MythX, Certik focus on code patterns. We classify **execution-proven contradictions** with severity, downstream impact, and remediation guidance. ### 2. **保护优先模式引擎** Instead of flagging every `call{}` as reentrancy, we: - ✓ Check for guards FIRST (ReentrancyGuard, nonReentrant, custom locks) - ✓ Only flag if pattern matches AND no protection exists - ✓ Reduce false positives by 70% vs. raw pattern matching *What others do:* Slither flags raw patterns and leaves you to filter noise. MythX runs expensive symbolic analysis. ### 3. **集成多链链上 + 仓库扫描** - Audit deployed bytecode via 7 block explorers (Etherscan, Arbiscan, Polygonscan, BSCscan, etc.) - Scan source repos (GitHub public/private) in same report - Direct comparison: deployed address vs. source code - Historical tracking: re-audit on schedule, detect changes *What others do:* Slither/Certik = code-only. Defender = on-chain only. We do both, integrated. ### 4. **执行上下文感知** Classify findings with **where and how** they matter: - Callback-sensitive protocols (Uniswap V4 hooks, Balancer, Aave flash loans) - Liquidation exposure (oracle manipulation → liquidation exploits) - Transaction-internal ordering (sandwich, front-running windows) - Privilege escalation paths (role transition + callback attack) *What others do:* Flag "oracle manipulation" as MEDIUM. We classify severity based on **exploitability in actual execution**. ### 5. **差异代码分析** Hunt for vulnerabilities in newer code paths post-audit: - Identify audit checkpoints (prior audits, test coverage) - Flag novel surfaces (initialization, upgrade paths, new token mechanics) - Prefer bounded fuzzing over speculation *What others do:* Re-audit everything. We focus on delta risk. ## 快速对比 | Feature | TSI-Scanner | Slither | MythX | Certik | Defender | |---------|-------------|---------|-------|--------|----------| | Static analysis | ✓ | ✓ | ✓ | ✓ | ✗ | | On-chain audit | ✓ | ✗ | ✗ | ✓ | ✓ | | Repo scanning | ✓ | ✓ | ✗ | ✓ | ✗ | | Consistency detection | **✓** | ✗ | ✗ | Partial | ✗ | | Protection-first | **✓** | ✗ | ✗ | ✗ | ~ | | Execution context | **✓** | ✗ | Partial | Partial | Partial | | Multi-chain | ✓ | ✓ | ✓ | ✓ | ✓ | | Scheduler/monitoring | ✓ | ✗ | ✗ | ✓ | ✓ | | REST API | ✓ | ✗ | ✓ | ✗ | ✓ | | Free/open | ✓ | ✓ | ✗ | ✗ | ✗ | ## 特性 - **Consistency Auditor** — Detect state contradictions across callback, reentrancy, oracle, and access control contexts - **On-chain audit** — Fetch source from 7 block explorer APIs, run 80+ vulnerability patterns - **Repo scanning** — Clone public/private GitHub repos, discover Solidity files, analyze - **Pattern engine** — Protection-first: checks for guards before flagging (reentrancy, access control, oracle, flash loan, MEV, front-running, arithmetic) - **Execution context** — Score findings based on exploitability in real execution - **Scheduler** — SQLite-backed target management with continuous re-scan loop - **CLI** — One-shot scans, target management, watch mode - **REST API** — 15 endpoints with tiered rate limiting ## 快速开始 ``` # 克隆 git clone https://github.com/yourorg/tsi-audit-scanner.git cd tsi-audit-scanner # 安装 pip install -r requirements.txt # 配置 cp .env.example .env # 编辑 .env — 至少设置 ETHERSCAN_API_KEY # 运行服务器 python server.py # 或直接通过 CLI 扫描仓库 python scanner_scheduler.py scan https://github.com/owner/repo --scope contracts/ ``` ## Docker ``` docker compose up -d # API 地址为 http://localhost:8080 ``` ## API 参考 ### 核心审计 | Method | Path | Description | |--------|------|-------------| | `GET` | `/health` | Health check | | `GET` | `/chains` | Supported chains (ethereum, arbitrum, polygon, bsc, optimism, base, avalanche) | | `GET` | `/pricing` | Tier information | | `GET` | `/usage` | Current rate limit usage | | `GET` | `/triage/

?chain=ethereum` | Fast plain-English risk triage with capability flags (mintable, pausable, blacklist, upgradeable, ownership) | | `GET` | `/audit/

?chain=ethereum&full=false` | Audit on-chain contract | | `POST` | `/audit/batch` | Batch audit (enterprise) | | `POST` | `/compare` | Compare two contracts | ### 扫描器 | Method | Path | Description | |--------|------|-------------| | `POST` | `/scan/repo` | Scan GitHub repository | | `POST` | `/scan/local` | Scan local directory | | `GET` | `/scan/results/` | Full scan results JSON | ### 调度器 | Method | Path | Description | |--------|------|-------------| | `GET` | `/targets` | List all scan targets | | `POST` | `/targets` | Add target (auto-detects repo vs address) | | `DELETE` | `/targets/` | Remove target | | `POST` | `/targets//scan` | Trigger immediate scan | | `GET` | `/targets//history` | Scan history | | `GET` | `/alerts?target_id=&status=failed&limit=50` | List alert delivery events | | `POST` | `/alerts//retry` | Retry one alert delivery | | `POST` | `/alerts/retry-failed` | Retry failed alert deliveries in batch | Scheduler responses now include `alerts` when risk worsens between scans (e.g., critical/high findings increase). ``` # 列出失败告警 curl "http://localhost:8080/alerts?status=failed&limit=20" # 重试单个失败告警 curl -X POST http://localhost:8080/alerts//retry # 批量重试失败告警 curl -X POST http://localhost:8080/alerts/retry-failed \ -H "Content-Type: application/json" \ -d '{"limit": 20}' ``` ### 示例 ``` # 对代币/合约进行深入审查前的快速分类 curl http://localhost:8080/triage/0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984?chain=ethereum # 使用一致性分析审计链上合约 curl http://localhost:8080/audit/0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984?chain=ethereum # 扫描 GitHub 仓库（包含一致性矛盾） curl -X POST http://localhost:8080/scan/repo \ -H "Content-Type: application/json" \ -d '{"url": "https://github.com/aave/aave-v3-core", "scope_paths": ["contracts/"]}' # 添加具有持续一致性监控的计划目标 curl -X POST http://localhost:8080/targets \ -H "Content-Type: application/json" \ -d '{"url": "https://github.com/owner/repo", "interval_hours": 24}' ``` `/triage` response includes UI-ready fields: - `summary_labels`: short chips like `Risk:HIGH`, `Upgradeable`, `Mintable` - `risk_badges`: structured badges with `label`, `severity`, and `reason` - `flags`: capability booleans (`mintable`, `pausable`, `blacklist_capability`, `owner_controlled`, `upgradeable`, etc.) `/audit` score output includes `scores.rating_breakdown` for explainability: - `contract_profile`: `STANDARD` or `INFRA_LIKE` (router/factory/pair/pool-style contracts) - `weighted_penalty`: adjusted penalty used to derive `security_score` - `severity_impact`: raw impact per severity bucket - `adjusted_severity_impact`: profile-adjusted impact per severity bucket - `high_confidence_severe_findings`: weighted signal from high-confidence `HIGH/CRITICAL` findings - `calibration_by_finding_id`: per-ID multiplier after prevalence/confidence calibration ## CLI ``` # 使用一致性检测的一次性扫描（本地目录） python scanner_scheduler.py scan /path/to/contracts --scope contracts/ # 使用一致性检测的一次性扫描（GitHub） python scanner_scheduler.py scan https://github.com/owner/repo # 管理目标 python scanner_scheduler.py add https://github.com/owner/repo --interval 24 python scanner_scheduler.py list # 持续监控循环 python scanner_scheduler.py run --interval 300 ``` ## 零接触智能端到端流程 Run full scan -> semantic validation -> dedupe -> disposition -> grading in one command: ``` python scripts/intelligent_e2e_flow.py \ --url https://github.com/scroll-tech/usx-contracts \ --branch main \ --outdir speed_tests/automation \ --max-confirmed-true 0 \ --max-critical-manual 0 \ --max-high-manual 3 ``` Outputs: - `speed_tests/automation/full_e2e_report.json` - `speed_tests/automation/full_e2e_report.md` - `speed_tests/automation/intelligent_flow_summary.json` - `speed_tests/automation/intelligent_flow_summary.md` If you post-process an existing scan in a different output folder, pass the original workspace so semantic continuation can still run: ``` python scripts/full_e2e_report.py \ --input-scan speed_tests/scroll_usx/scan_result_full.json \ --workspace-dir speed_tests/scroll_usx/workspace \ --outdir speed_tests/automation ``` CI gate behavior: - Exit code `0` when gates pass - Exit code `2` when gates fail (for pipeline blocking) You can also run this hands-off in GitHub Actions via `.github/workflows/intelligent-e2e.yml`. ## 架构 ``` server.py Flask API — 15 endpoints, rate limiting, tiered access config.py Environment config, 7 chains, 3 pricing tiers advanced_auditor.py Core engine — 80+ vuln patterns, consistency auditor (TSI), protection-first detection, multi-chain Etherscan repo_scanner.py Git clone → file discovery → pattern analysis → consistency checks source_analyzer.py solc/forge compilation, AST extraction, call graphs scanner_scheduler.py SQLite targets/history, continuous poll loop, CLI ``` ### 一致性审计器（advanced_auditor.py） Core classes: - `StateContradiction`: Immutable record (τ₁, τ₂, proof_location, execution_context) - `ContradictionClassifier`: Classifies severity, context, risk, remediation - `SolidityConsistencyAuditor`: Orchestrates detection + classification - Pattern extraction detects callback/reentrancy/oracle/storage contradictions - Severity determined by observability + context sensitivity ## 漏洞模式 The pattern engine covers: | Category | Examples | |----------|----------| | **Consistency (TSI)** | Callback state exposure, CEI violations, oracle temporal inconsistency, access control contradictions | | Reentrancy | State after external call, cross-function, read-only | | Access Control | Missing modifiers, unprotected selfdestruct, tx.origin | | Oracle | Price manipulation, stale data, single-source dependency | | Flash Loan | Unchecked callback, price in same block | | MEV | Sandwich vectors, front-running exposure | | Arithmetic | Unchecked math, precision loss, rounding | | DeFi-specific | Slippage, donation attacks, fee-on-transfer | ### 一致性审计器（TSI）详情 The consistency auditor detects **state contradictions** (τ₁ ≠ τ₂) and classifies by: **Contradiction Types:** - **STATE_TRANSITION**: Entity changes from A → ¬A without intermediate state - **CALLBACK_EXPOSURE**: State read differs before/after callback completes - **TEMPORAL_ORDER**: Events violate required ordering (init before use, etc.) - **INVARIANT_VIOLATION**: Accounting breaks (sum of balances ≠ total supply) - **ACCESS_INCONSISTENCY**: Permissions change mid-critical section - **BALANCE_MISMATCH**: Storage value contradicts expected invariant **Execution Context Mapping:** - `callback` → STATE_TRANSITION_EXPOSURE (affects Uniswap V4 hooks, Balancer flash loans) - `reentrancy` → CEI_VIOLATION (withdrawal/transfer callbacks) - `oracle` → TEMPORAL_INCONSISTENCY (liquidation exploits, price manipulation) - `storage` → STATE_ASSUMPTION_FAILURE (pausable, access control, balance tracking) **Severity Classification:** - **CRITICAL**: Observable difference (τ₁_value ≠ τ₂_value) in production - **HIGH**: Callback/reentrancy context exploitation possible - **MEDIUM**: Theoretical but specific conditions required Each pattern checks for known protections (ReentrancyGuard, access modifiers, oracle guards) before flagging — reducing false positives by ~70%. ## 配置 All settings via environment variables (see `.env.example`): | Variable | Default | Description | |----------|---------|-------------| | `ETHERSCAN_API_KEY` | — | Required for on-chain audits | | `AUDIT_PORT` | 8080 | Server port | | `GITHUB_TOKEN` | — | For private repo scanning | | `SCANNER_WORKSPACE` | `./scanner_workspace` | Clone directory | | `SCANNER_DB` | `scan_history.db` | SQLite path | | `LOG_LEVEL` | INFO | Logging verbosity | | `ALERT_WEBHOOK_URL` | — | Optional webhook endpoint for risk-worsening alerts | | `ALERT_WEBHOOK_TIMEOUT` | `5` | Webhook request timeout (seconds) | | `ALERT_WEBHOOK_RETRIES` | `2` | Retries after first webhook attempt | | `ALERT_HIGH_DELTA_THRESHOLD` | `1` | Minimum increase in high findings to trigger alerts | ### 风险恶化告警行为 Scheduler alerting triggers only on meaningful worsening: - Critical findings increase (`critical_delta > 0`) - High findings increase beyond threshold (`high_delta >= ALERT_HIGH_DELTA_THRESHOLD`) - Risk level worsens (`LOW -> MEDIUM`, `MEDIUM -> HIGH`, etc.) when available Alert delivery is deduplicated by target + delta/risk transition hash, retried with timeout controls, and persisted with delivery status (`pending`, `sent`, `failed`, `disabled`). ## 要求 - Python 3.10+ - `requests`, `flask`, `flask-cors` - Optional: `solc` or `forge` in PATH for AST analysis - Optional: `redis` for production rate limiting ## 许可证 MIT

标签：Arbiscan, Arbitrum, BSC, BSCscan, CEI 模式违规, CertiK 替代, Etherscan, GitHub 扫描, MythX 替代, On-chain 扫描, Oracle 时间不一致, Polygon, Polygonscan, SEO 关键词, Slither 替代, Temporal State Inconsistency, URL发现, 一致性矛盾检测, 仓库扫描, 以太坊, 保护优先模式引擎, 区块链安全, 历史追踪, 回调状态暴露, 多链审计, 字节码审计, 安全检测, 对称加密, 执行感知, 智能合约审计, 源码审计, 网络测绘, 自动化审计, 访问控制不一致, 误报减少, 逆向工具, 重入防护, 集成审计