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

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