# Scorpius Scanner v5.0

**The World's Most Powerful Smart Contract Security Scanner**

Slither-powered core with DeFi attack detection, multi-chain support, and gas optimization analysis.

[![PyPI version](https://badge.fury.io/py/scorpius-scanner.svg)](https://pypi.org/project/scorpius-scanner/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why Scorpius Scanner?

| Feature | Slither | Scorpius Scanner |
|---------|---------|------------------|
| Core Analysis | Yes | Yes (Slither-powered) |
| DeFi Attack Detection | No | **Flash Loans, Sandwich, Oracle Manipulation** |
| Gas Optimization | No | **Array caching, calldata, unchecked math** |
| Multi-Chain Support | EVM only | **Solana, Move, Cairo, CosmWasm** |
| Security Scoring | No | **A-F Grade + 0-100 Score** |
| Professional Reports | No | **HTML, PDF, Markdown, SARIF** |
| Auto-Fix Generation | No | **Patched code suggestions** |

**Benchmark Results:** Scorpius finds **53% more vulnerabilities** than Slither alone.

## Installation

```bash
pip install scorpius-scanner
```

For full Slither integration (recommended):
```bash
pip install scorpius-scanner[full]
pip install slither-analyzer solc-select
solc-select install 0.8.20
solc-select use 0.8.20
```

## Quick Start

```bash
# Scan a contract
scorpius scan MyContract.sol

# Full analysis (Slither + DeFi + Gas)
scorpius scan MyContract.sol --full

# Generate HTML report
scorpius scan MyContract.sol --format html --output report.html

# DeFi-specific analysis
scorpius defi MyContract.sol

# Multi-chain scan (Solana, Move, Cairo, CosmWasm)
scorpius multichain program.rs --chain solana
```

## Commands

| Command | Description |
|---------|-------------|
| `scorpius scan <file>` | Full security scan |
| `scorpius defi <file>` | DeFi attack analysis |
| `scorpius multichain <file>` | Multi-chain scan |
| `scorpius fix <file>` | Generate auto-fixes |
| `scorpius report <file>` | Generate detailed report |
| `scorpius benchmark` | Run accuracy benchmark |
| `scorpius setup` | Check dependencies |

## What It Detects

### Core Vulnerabilities (via Slither)
- Reentrancy attacks
- Uninitialized storage
- Access control issues
- Integer overflow/underflow
- Unchecked external calls
- 90+ detector types

### DeFi Attack Vectors (Scorpius Enhanced)
- Flash loan callback attacks
- Oracle price manipulation
- Sandwich attack vulnerabilities
- Front-running risks
- Governance manipulation
- MEV extraction risks

### Gas Optimizations
- Array length caching in loops
- Calldata vs memory usage
- Unchecked math for safe operations
- Storage vs memory optimization

### Multi-Chain Support
- **Solana/Anchor**: Missing signer checks, PDA validation, CPI guards
- **Move (Aptos/Sui)**: Capability leaks, object safety, coin handling
- **Cairo (StarkNet)**: Storage collisions, felt overflow, access control
- **CosmWasm**: Entry point validation, storage patterns, cross-contract

## Output Formats

```bash
# JSON (default)
scorpius scan contract.sol --format json

# HTML Report
scorpius scan contract.sol --format html --output report.html

# Markdown
scorpius scan contract.sol --format markdown

# SARIF (CI/CD integration)
scorpius scan contract.sol --format sarif
```

## Python API

```python
from guardescan import GuardeScanEngine

# Initialize engine
engine = GuardeScanEngine()

# Scan a contract
result = engine.scan("MyContract.sol")

# Access results
print(f"Score: {result.score}/100")
print(f"Grade: {result.grade}")
print(f"Total Issues: {len(result.all_vulnerabilities)}")

# Iterate findings
for vuln in result.all_vulnerabilities:
    print(f"[{vuln.severity}] {vuln.title}")
    print(f"  Location: {vuln.location}")
    print(f"  Recommendation: {vuln.recommendation}")
```

## Security Scoring

| Grade | Score | Meaning |
|-------|-------|---------|
| A+ | 95-100 | Excellent - Production ready |
| A | 90-94 | Very Good - Minor improvements |
| B+ | 85-89 | Good - Some issues to address |
| B | 80-84 | Acceptable - Review recommended |
| C+ | 75-79 | Fair - Improvements needed |
| C | 70-74 | Below Average - Significant issues |
| D | 60-69 | Poor - Major vulnerabilities |
| F | <60 | Critical - Do not deploy |

## CI/CD Integration

### GitHub Actions

```yaml
- name: Security Scan
  run: |
    pip install scorpius-scanner[full]
    scorpius scan contracts/ --format sarif --output results.sarif
    
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif
```

## Requirements

- Python 3.8+
- For Ethereum/Solidity: `slither-analyzer`, `solc-select`
- For Solana: Rust toolchain (optional)
- For Move: Move CLI (optional)

## License

MIT License - Free for commercial and personal use.

## Links

- [GitHub Repository](https://github.com/scorpius-security/scorpius-scanner)
- [Report Issues](https://github.com/scorpius-security/scorpius-scanner/issues)
- [PyPI Package](https://pypi.org/project/scorpius-scanner/)
