Scan

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

Overview

A Scan finds common vulnerability signals in the selected repository state. It is a fast first pass for triage.

Characteristic	Value
Input	Public GitHub repository for the unauthenticated endpoint
Output	Structured findings from deterministic detectors, with optional AI verification
Scope	The repository state analyzed; not deployed-contract surveillance

Quick Start

Scan a Public Repository

Use the browser form, or call the API with no account:

curl -sS https://api.firepan.com/surface/scan \
  -H "Content-Type: application/json" \
  -d '{"target": "https://github.com/your-org/your-repo"}'

The server chooses the model and AI-verification budget. Check the HTTP status and the JSON error field before reading findings.

Internal CLI

caution

The FirePan CLI below is not publicly distributed yet. It documents internal and engagement tooling. Public users should use the API above or the GitHub App.

# 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

Option	Description	Default
--format	Output format: json, html, md, csv	json
--output	Output file path	stdout
--budget	Max AI calls per repo	5
--no-llm	Skip AI verification (faster, more false positives)	false
--batch	CSV file for batch scanning	-
--max-concurrent	Concurrent scans in batch mode	10

Vulnerability Patterns

Scan detects 15+ security patterns:

Critical Severity

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

High Severity

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

Medium Severity

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

Low Severity

Pattern	Description
DEPRECATED-001	Deprecated patterns (throw, sha3, suicide)
VISIBILITY-001	Missing 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)

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

Risk Levels

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

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 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 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

• Probe - Investigate a repository baseline and compare later results
• Audit - Deeper adversarial review
• CI/CD Integration - Automate scanning in your workflow
• CLI Reference - Full command documentation