https://github.com/friendlygeorge/base-scanner
Lightweight on-chain security scanner for Base chain smart contracts — 15 pattern-based checks, no API key required
https://github.com/friendlygeorge/base-scanner
audit base ethereum python scanner security smart-contracts solidity web3
Last synced: 4 days ago
JSON representation
Lightweight on-chain security scanner for Base chain smart contracts — 15 pattern-based checks, no API key required
- Host: GitHub
- URL: https://github.com/friendlygeorge/base-scanner
- Owner: friendlygeorge
- License: mit
- Created: 2026-06-06T09:01:42.000Z (12 days ago)
- Default Branch: main
- Last Pushed: 2026-06-06T10:12:29.000Z (12 days ago)
- Last Synced: 2026-06-06T12:09:48.660Z (12 days ago)
- Topics: audit, base, ethereum, python, scanner, security, smart-contracts, solidity, web3
- Language: Python
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# base-scanner
A lightweight on-chain security scanner for Base chain smart contracts. Fetches verified source code from Sourcify, runs pattern-based security analysis, and generates human-readable reports.
## Features
- **No API key required** — uses Sourcify (free) for source code verification
- **15 security checks** covering the most common vulnerability patterns
- **Clean markdown reports** with severity ratings and evidence
- **JSON output** for programmatic use
- **Multi-chain ready** — works on Base (default) and any EVM chain supported by Sourcify
## GitHub Actions
Use base-scanner as a GitHub Action to automatically scan contracts in your CI pipeline.
### Manual trigger (scan a specific contract)
```yaml
- uses: friendlygeorge/base-scanner@main
with:
contract_address: '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5'
chain: 'base'
min_severity: 'low'
output_format: 'markdown'
```
### In your workflow
```yaml
name: Security Scan
on:
workflow_dispatch:
inputs:
contract_address:
description: 'Contract to scan'
required: true
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: friendlygeorge/base-scanner@main
with:
contract_address: ${{ github.event.inputs.contract_address }}
chain: 'base'
min_severity: 'low'
- uses: actions/upload-artifact@v4
with:
name: scan-report
path: scan-report.*
```
### Available inputs
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `contract_address` | Yes | — | Contract address to scan |
| `chain` | No | `base` | Chain (base, ethereum, optimism, arbitrum, polygon) |
| `min_severity` | No | `low` | Minimum severity to report (info, low, medium, high) |
| `output_format` | No | `markdown` | Output format (markdown, json) |
## Security Checks
| Check | Severity | What it detects |
|-------|----------|-----------------|
| Reentrancy | MEDIUM | External calls followed by state changes without guards |
| Access Control | HIGH | Admin functions without access control patterns |
| Unchecked Calls | LOW | Low-level calls without return value checks |
| tx.origin | MEDIUM | Use of tx.origin for authorization |
| Selfdestruct | MEDIUM | Contract can be destroyed |
| Delegatecall | HIGH/INFO | Delegatecall usage (high if user-controlled) |
| Timestamp Dependence | LOW | Heavy block.timestamp usage |
| Integer Overflow | MEDIUM | Missing SafeMath on pre-0.8.0 compilers |
| Flash Loan | INFO | Oracles used with deposit/swap functions |
| Oracle Manipulation | INFO | Single-block price reads |
| Upgradeable | MEDIUM/INFO | Proxy patterns (medium without timelock) |
| Centralization | LOW | Single owner without multisig |
| Missing Events | INFO | State changes without event emissions |
| Gas Griefing | MEDIUM | Unbounded loops over dynamic arrays |
| First Deposit | MEDIUM | ERC-4626 vault without inflation protection |
## Installation
```bash
pip install .
```
Or install from source:
```bash
git clone https://github.com/friendlygeorge/base-scanner
cd base-scanner
pip install -e .
```
## Usage
### CLI
```bash
# Scan a contract on Base (default)
base-scanner 0xA238Dd80C259a72e81d7e4664a9801593F98d1c5
# Output as JSON
base-scanner 0xA238Dd80C259a72e81d7e4664a9801593F98d1c5 --json
# Save report to file
base-scanner 0xA238Dd80C259a72e81d7e4664a9801593F98d1c5 -o report.md
# Scan on a different chain
base-scanner 0x... --chain-id 1 # Ethereum mainnet
```
### Python
```python
from base_scanner import SecurityScanner
scanner = SecurityScanner("0xA238Dd80C259a72e81d7e4664a9801593F98d1c5")
result = scanner.scan()
print(f"Found {result['summary']['total']} findings")
print(f" High: {result['summary']['high']}")
print(f" Medium: {result['summary']['medium']}")
print(f" Low: {result['summary']['low']}")
```
## Output Format
### Markdown (default)
```markdown
# Security Scan Report
**Contract:** USDC (0xA238Dd80C259a72e81d7e4664a9801593F98d1c5)
**Compiler:** ^0.8.17
**Scan Time:** 2026-06-06T12:00:00+00:00
## Summary
| Severity | Count |
|----------|-------|
| 🔴 Critical | 0 |
| 🟠 High | 0 |
| 🟡 Medium | 1 |
| 🔵 Low | 2 |
| ⚪ Info | 3 |
| **Total** | **6** |
```
### JSON
```json
{
"address": "0xa238dd80c259a72e81d7e4664a9801593f98d1c5",
"contract_name": "USDC",
"compiler": "^0.8.17",
"chain_id": 8453,
"summary": {
"total": 6,
"critical": 0,
"high": 0,
"medium": 1,
"low": 2,
"info": 3
},
"findings": [...]
}
```
## How It Works
1. **Bytecode check** — Verifies the address has deployed code
2. **Source fetch** — Pulls verified source from Sourcify (free, no API key)
3. **Pattern analysis** — Runs 15 regex-based security checks against the source
4. **Report generation** — Outputs findings sorted by severity
## Limitations
- **Pattern-based only** — This is not a formal verification tool or a substitute for manual audit
- **Source-dependent** — Only works on verified contracts
- **No economic analysis** — Does not check for MEV, oracle manipulation economics, or complex DeFi attack vectors
- **Regex false positives** — Some findings may be false positives; always review manually
For comprehensive security analysis, use tools like [Slither](https://github.com/crytic/slither), [Mythril](https://github.com/ConsenSys/mythril), or hire a professional auditor.
## Requirements
- Python 3.9+
- `requests`
- `web3`
## License
MIT
## Contributing
Contributions welcome! Open an issue or PR at [github.com/friendlygeorge/base-scanner](https://github.com/friendlygeorge/base-scanner).