Skip to main content

Surface Scan

A lightweight, cost-effective security scanner for preliminary assessment of Solidity and Vyper smart contract repositories.

Overview​

Surface Scan is designed for rapid security assessment—quickly scanning repositories to identify potential vulnerabilities. It's fast, cheap, and scalable.

CharacteristicValue
Speed~2 seconds per repo (static analysis)
Cost~$0.05 per repo with AI verification
ScaleBatch processing for 1000+ repos

Quick Start​

Scan a Repository​

# GitHub repository
firepan scan https://github.com/your-org/your-repo

# Local directory
firepan scan /path/to/contracts

# Generate HTML report
firepan scan https://github.com/your-org/your-repo --format html --output report.html

Batch Scanning​

# Create a CSV with your repositories
cat > repos.csv << EOF
Name,GitHub URL
ProjectA,https://github.com/org/project-a
ProjectB,https://github.com/org/project-b
ProjectC,https://github.com/org/project-c
EOF

# Scan all repositories
firepan scan --batch repos.csv --output results.csv

Command Options​

OptionDescriptionDefault
--formatOutput format: json, html, md, csvjson
--outputOutput file pathstdout
--budgetMax AI calls per repo5
--no-llmSkip AI verification (faster, more false positives)false
--batchCSV file for batch scanning-
--max-concurrentConcurrent scans in batch mode10

Vulnerability Patterns​

Surface Scan detects 15+ security patterns:

Critical Severity​

PatternDescription
SELFDESTRUCT-001Unprotected selfdestruct without access control
DELEGATECALL-001Delegatecall to untrusted targets

High Severity​

PatternDescription
REENTRANCY-001External call before state update
TXORIGIN-001Using tx.origin for authorization
UNCHECKED-CALL-001.call() without return check
OVERFLOW-001Solidity < 0.8.0 without SafeMath

Medium Severity​

PatternDescription
ACCESS-001Missing access control on state-changing functions
FRONTRUN-001Frontrunning risk patterns
ORACLE-001External price feed dependencies
FLASHLOAN-001Flash loan callback patterns

Low Severity​

PatternDescription
DEPRECATED-001Deprecated patterns (throw, sha3, suicide)
VISIBILITY-001Missing explicit visibility

Risk Score Calculation​

The risk score (0-100) combines vulnerability findings and code quality:

Vulnerability Score (0-70 points)​

  • Critical findings: 25 points x confidence
  • High findings: 15 points x confidence
  • Medium findings: 8 points x confidence
  • Low findings: 3 points x confidence

Quality Deductions (0-30 points)​

FactorPoints Added
No tests+10
Solidity < 0.8.0+10
No NatSpec documentation+3
No access control patterns+5
No events+2

Risk Levels​

ScoreLevel
70-100Critical
50-69High
25-49Medium
0-24Low

Output Formats​

JSON (Default)​

{
  "repo_name": "example",
  "risk_score": 74,
  "risk_level": "critical",
  "findings": [...],
  "quality_metrics": {...},
  "summary": "Critical security issues detected..."
}

HTML Report​

Professional report suitable for sharing with:

  • Visual risk score dashboard
  • Color-coded findings by severity
  • Code snippets with line numbers
  • Quality indicators
  • Call-to-action section

CSV (Batch Mode)​

repo_url,repo_name,risk_score,risk_level,critical_count,high_count,...

Reducing False Positives​

Use AI Verification​

# Default 5 AI calls filters many false positives
firepan scan https://github.com/org/repo

# Increase verification budget for higher accuracy
firepan scan https://github.com/org/repo --budget 10

Filter by Severity​

Focus on high-confidence findings:

# Generate detailed results
firepan scan --batch repos.csv --output results.csv

# Filter only repos with critical/high findings
grep ",critical\|,high" results.csv

Best Practices​

What Surface Scan is Good For​

  • Identifying unaudited repositories with real issues
  • Initial triage and prioritization
  • Code quality signals (missing tests, old Solidity)
  • Scaling security assessment across many repos

What Surface Scan is NOT For​

  • Replacing comprehensive audits
  • Finding complex logic bugs or economic attacks
  • Auditing production code without human review
Important

Risk scores reflect both real issues AND false positives. Always verify findings before making decisions. Battle-tested protocols (OpenZeppelin, Uniswap) will show findings that are almost always false positives or intentional design decisions.

Next Steps​