pact-audit-free/README.md

Free smart contract security scanner using Slither static analysis

# PACT Audit Free

Free smart contract security scanner using Slither static analysis by [Habify Labs](https://habifylabs.io).

[![npm version](https://badge.fury.io/js/pact-audit-free.svg)](https://badge.fury.io/js/pact-audit-free)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## About

PACT Audit Free is the community edition of PACT Audit, owned and developed by **Habify Labs**. This tool provides free smart contract security scanning to help developers identify vulnerabilities before deployment.

## Features

- 🔍 **Static Analysis** - Powered by Slither analyzer
- 🆓 **Completely Free** - No API keys or subscriptions required
- ⚡ **Fast & Lightweight** - Minimal dependencies, quick installation
- 🎯 **Easy to Use** - Simple CLI interface
- 📊 **Clean Output** - Professional vulnerability reporting
- 🔄 **CI/CD Ready** - JSON output and proper exit codes
- 🌍 **Cross-Platform** - Works on Windows, macOS, and Linux

## Installation

### Prerequisites

First, install Slither analyzer:

```bash
# Using pip
pip install slither-analyzer

# Using pip3
pip3 install slither-analyzer

# On macOS with Homebrew
brew install slither-analyzer
```

### Install PACT Audit Free

```bash
npm install -g pact-audit-free
```

## Usage

### Basic Scanning

```bash
# Scan a single Solidity file
pact-audit-free scan MyContract.sol

# Scan all Solidity files in a directory
pact-audit-free scan contracts/
```

### Output Options

```bash
# Save results to JSON file
pact-audit-free scan MyContract.sol --output results.json

# Output JSON to stdout (useful for CI/CD)
pact-audit-free scan MyContract.sol --json
```

### Example Output

```
🔍 PACT Audit Free - Slither Security Scanner
Free smart contract security analysis
══════════════════════════════════════════════

🎯 Target: /path/to/MyContract.sol
📋 Validating target path...
✅ Path validation passed
🔧 Checking Slither installation...
✅ Slither is installed and ready

🔍 Running Slither security analysis...
✅ Scan completed

📊 SCAN RESULTS
══════════════
Summary:
  HIGH: 1
  MEDIUM: 2
  LOW: 1

Details:
1. [HIGH] reentrancy-eth
   Reentrancy vulnerability in withdraw function
   📍 MyContract.sol:45

2. [MEDIUM] missing-zero-check
   Missing zero address validation in transfer
   📍 MyContract.sol:23

3. [MEDIUM] unprotected-upgrade
   Function lacks access control
   📍 MyContract.sol:67

4. [LOW] unused-return
   Return value not used
   📍 MyContract.sol:12

⚠️ HIGH SEVERITY ISSUES DETECTED - Review required before deployment!
```

## Exit Codes

- `0` - No issues or only low/informational issues
- `1` - Medium severity issues detected
- `2` - High severity issues detected

Perfect for CI/CD integration:

```bash
# This will fail the build if high/medium issues are found
pact-audit-free scan contracts/ || exit 1
```

## JSON Output Format

When using `--output` or `--json`, the tool outputs structured data:

```json
{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "target": "/path/to/contracts",
  "vulnerabilities": [
    {
      "type": "reentrancy-eth",
      "severity": "HIGH",
      "description": "Reentrancy vulnerability in withdraw function",
      "sourceMapping": {
        "filename": "MyContract.sol",
        "lines": [45]
      },
      "confidence": "high",
      "impact": "high"
    }
  ],
  "summary": {
    "total": 4,
    "high": 1,
    "medium": 2,
    "low": 1,
    "informational": 0
  }
}
```

## Supported Vulnerability Types

PACT Audit Free detects all vulnerabilities that Slither can find, including:

- Reentrancy vulnerabilities
- Access control issues
- Integer overflow/underflow
- Unprotected functions
- Missing zero address checks
- Timestamp dependencies
- Gas optimization opportunities
- Code quality issues
- And many more...

## Requirements

- **Node.js** 16.0.0 or higher
- **Slither** analyzer installed via pip
- **Python** 3.6+ (for Slither dependency)

## Troubleshooting

### Slither Not Found

If you get a "Slither not found" error:

1. Ensure Python and pip are installed
2. Install Slither: `pip install slither-analyzer`
3. Verify installation: `slither --version`
4. If using virtual environments, ensure Slither is installed in the active environment

### Permission Issues

If you encounter permission issues on macOS/Linux:

```bash
# Install with sudo if needed
sudo npm install -g pact-audit-free

# Or use npx to run without installing globally
npx pact-audit-free scan MyContract.sol
```

## Comparison

| Feature | PACT Audit Free | Raw Slither | Premium Tools |
|---------|----------------|-------------|---------------|
| Price | Free | Free | $$ |
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
| Setup time | < 1 min | ~5 min | ~15 min |
| Clean output | ✅ | ❌ | ✅ |
| JSON export | ✅ | ⚠️ | ✅ |
| CI/CD ready | ✅ | ⚠️ | ✅ |

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/habify-labs/pact-protocol-v1/blob/main/CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Related Projects

- **[pact-audit](https://www.npmjs.com/package/pact-audit)** - Enterprise version with AI analysis
- **[Slither](https://github.com/crytic/slither)** - The underlying static analysis framework
- **[PACT Protocol](https://pactprotocol.io)** - Complete DeFi security ecosystem

## Support

- 📖 [Documentation](https://docs.pactprotocol.io)
- 🐛 [Issue Tracker](https://github.com/habify-labs/pact-protocol-v1/issues)
- 💬 [Discord Community](https://discord.gg/pactprotocol)
- 🚀 [Upgrade to Premium](https://pactprotocol.io/audit)

## About Habify Labs

PACT Audit is owned and developed by **[Habify Labs](https://habifylabs.io)**, a leading blockchain security company focused on making smart contract auditing accessible to all developers.

---

Made with ❤️ by [Habify Labs](https://habifylabs.io)