Next-generation firmware analysis toolkit
Firmalyzer combines the performance of Rust with the flexibility of Python to deliver deep binary analysis, vulnerability detection, and comprehensive reporting.
| Feature | Description |
|---|---|
| 🔍 45+ Signature Detection | Identify filesystems, bootloaders, compression, crypto, and more |
| 📊 Entropy Analysis | Shannon entropy with colorized sparkline visualization |
| 📦 Recursive Extraction | Automatic decompression of gzip, LZMA, and nested archives |
| 🔑 Credential Detection | Find hardcoded passwords, API keys, and secrets |
| 🔐 Crypto Key Detection | Locate RSA/AES keys, certificates, and crypto patterns |
| 🛡️ CVE Matching | Real-time NVD API integration with local caching |
| 📈 Risk Scoring | Weighted 0-100 score with severity classification |
| 📄 Multi-format Reports | JSON, XML, and interactive HTML dashboards |
| 🌐 Web GUI | Browser-based interface for visual analysis |
| 🔌 Plugin System | Extend functionality with custom Python plugins |
- Python 3.8+
- Rust 1.70+ (for building from source)
- pip or pipx
It is highly recommended to use a virtual environment.
# Clone the repository
git clone https://github.com/ismailtsdln/firmalyzer.git
cd firmalyzer
# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install build dependencies
pip install maturin
# Build and install (Use ABI3 flag for Python 3.12+)
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
cd python && maturin develop --release
# Verify installation
firmalyzer --version# Analyze a firmware file
firmalyzer analyze firmware.bin
# With entropy visualization
firmalyzer analyze firmware.bin --ec
# Generate HTML report
firmalyzer analyze firmware.bin --html report.html
# JSON output for automation
firmalyzer analyze firmware.bin --json > results.json
# Launch web GUI
firmalyzer guiUsage: firmalyzer [OPTIONS] COMMAND [ARGS]...
Options:
-V, --version Show version and exit
-v, --verbose Enable verbose/debug output
-q, --quiet Suppress all output except errors
--help Show this message and exit
Commands:
analyze Analyze a firmware file
gui Launch the web-based GUI dashboard
Usage: firmalyzer analyze [OPTIONS] PATH
Options:
-e, --extract Perform recursive extraction
--entropy-chunks, --ec Show chunked entropy visualization
--chunk-size INTEGER Chunk size for entropy (default: 1024)
--json Output in JSON format
--xml Output in XML format
--html PATH Generate HTML report to specified path
╔═══════════════════════════════════════════════════════════════╗
║ 🔬 FIRMALYZER Analysis Report ║
╚═══════════════════════════════════════════════════════════════╝
╭──── 📦 Size ────╮ ╭── 📊 Entropy ───╮ ╭─ 🔍 Signatures ─╮
│ 4,521,984 │ │ 6.8724 │ │ 12 │
│ bytes │ │ bits/byte │ │ found │
╰─────────────────╯ ╰─────────────────╯ ╰─────────────────╯
📈 Entropy Distribution
╭───────────────────────────────────────────────────────────────╮
│ ▁▂▂▃▄▅▆▇▇▇▇▆▆▅▄▃▂▁▁▂▃▄▅▆▇▇▇▆▅▄▃▂▁ │
╰───────────────────────────────────────────────────────────────╯
🔍 Identified Signatures (Root)
╭──────────────┬────────────┬─────────────┬──────────────────────╮
│ Offset │ Name │ Type │ Description │
├──────────────┼────────────┼─────────────┼──────────────────────┤
│ 0x00000000 │ uImage │ BOOTLOADER │ U-Boot boot image │
│ 0x00010000 │ SquashFS │ FILESYSTEM │ SquashFS filesystem │
│ 0x003F0000 │ gzip │ COMPRESSION │ gzip compressed data │
╰──────────────┴────────────┴─────────────┴──────────────────────╯
🔌 Plugin Insights
• Crypto Detector: total_keys: 2 | total_certs: 1
• String Analyzer: total_ascii: 1,247 | passwords: 3
Risk Assessment:
Score: 🟠 65/100 (HIGH)
• Private key found at 0x1A2B3C
• Potential passwords: 3
firmalyzer/
├── core/ # 🦀 Rust performance engine
│ ├── src/lib.rs # Entropy, signatures, extraction
│ └── Cargo.toml # Rust dependencies
│
├── python/ # 🐍 Python CLI & plugins
│ └── firmalyzer/
│ ├── main.py # CLI entrypoint
│ ├── config.py # Configuration system
│ ├── logger.py # Logging system
│ ├── security.py # Input validation
│ ├── scoring.py # Risk scoring
│ ├── plugins/ # Plugin modules
│ │ ├── manager.py
│ │ ├── string_analyzer.py
│ │ ├── crypto_detector.py
│ │ └── nvd_cve.py
│ ├── reporters/ # Report generators
│ └── gui/ # Web dashboard
│
├── ext/
│ └── signatures.json # 45+ signature patterns
│
├── tests/ # 🧪 Test suite
├── Makefile # Development commands
├── Dockerfile # Container deployment
└── README.md
Create custom analysis plugins in python/firmalyzer/plugins/:
from . import BasePlugin
class MyPlugin(BasePlugin):
@property
def name(self) -> str:
return "my_plugin"
@property
def description(self) -> str:
return "Custom analysis plugin"
def analyze(self, data: bytes, results: dict) -> dict:
# Your analysis logic here
findings = {"custom_field": "value"}
return findingsPlugins are automatically loaded and executed during analysis.
Create ~/.firmalyzer/config.yaml:
general:
max_file_size_mb: 500
max_extraction_depth: 5
chunk_size: 1024
plugins:
enabled: true
auto_load: true
nvd_api:
enabled: true
cache_days: 7
api_key: YOUR_NVD_API_KEY # Optional
logging:
level: INFO
file_logging: falseEnvironment variable overrides:
export FIRMALYZER_MAX_FILE_SIZE=1000
export FIRMALYZER_LOG_LEVEL=DEBUG
export FIRMALYZER_NVD_API_KEY=your-key# Build image
docker build -t firmalyzer:latest .
# Run analysis
docker run -v $(pwd):/data firmalyzer:latest analyze /data/firmware.bin
# Generate report
docker run -v $(pwd):/data firmalyzer:latest analyze /data/firmware.bin --html /data/report.html# Install development dependencies
cd python && pip install -e ".[dev]"
# Build with modern Python support (3.12+)
export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1
make dev
# Run tests
make test
# Format and Lint
make format
make lint
# Build production wheel
make buildContributions are welcome! See CONTRIBUTING.md for guidelines.
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests and lints
- Submit a pull request
This project is licensed under the MIT License - see LICENSE for details.
- PyO3 - Rust/Python bindings
- Rich - Beautiful terminal output
- Click - CLI framework
- NVD - Vulnerability database
Built with ❤️ by Ismail Tasdelen