# Security Scanning Guide

**Last Updated**: 2025-01-27  
**Status**: Active

This guide explains how to use the security scanning tools integrated into this project.

## Table of Contents

- [Overview](#overview)
- [Security Tools](#security-tools)
- [Running Scans](#running-scans)
- [Interpreting Results](#interpreting-results)
- [Remediation](#remediation)
- [CI/CD Integration](#cicd-integration)

## Overview

The project integrates 5 security scanning tools to ensure code quality and security:

1. **SolidityScan** - Solidity-specific security scanner
2. **Slither** - Static analysis framework for Solidity
3. **Mythril** - Security analysis tool for Ethereum smart contracts
4. **Snyk** - Dependency vulnerability scanner
5. **Trivy** - Container image vulnerability scanner

## Security Tools

### 1. SolidityScan

**Purpose**: Solidity-specific security vulnerabilities

**Usage**:
```bash
# Run SolidityScan
npm run security:solidityscan

# Or directly
npx @solidityscan/cli scan contracts/
```

**Output**: HTML report with vulnerabilities and recommendations

### 2. Slither

**Purpose**: Static analysis for Solidity contracts

**Usage**:
```bash
# Run Slither
slither contracts/

# With specific detectors
slither contracts/ --detect all
```

**Output**: Console output and JSON report

### 3. Mythril

**Purpose**: Security analysis using symbolic execution

**Usage**:
```bash
# Run Mythril
myth analyze contracts/ContractName.sol

# With options
myth analyze contracts/ContractName.sol --execution-timeout 300
```

**Output**: Security issues and recommendations

### 4. Snyk

**Purpose**: Dependency vulnerability scanning

**Usage**:
```bash
# Test dependencies
snyk test

# Monitor dependencies
snyk monitor

# Test container images
snyk container test <image>
```

**Output**: Vulnerability report with severity levels

### 5. Trivy

**Purpose**: Container image vulnerability scanning

**Usage**:
```bash
# Scan container image
trivy image <image-name>

# Scan filesystem
trivy fs .

# Scan repository
trivy repo <repo-url>
```

**Output**: Vulnerability report with CVSS scores

## Running Scans

### Complete Security Scan

```bash
# Run all security scans
make security-scan

# Or individually
make security:solidityscan
make security:slither
make security:mythril
make security:snyk
make security:trivy
```

### Contract-Specific Scans

```bash
# Scan specific contract
slither contracts/OracleAggregator.sol
myth analyze contracts/OracleAggregator.sol
```

### CI/CD Integration

Scans can be integrated into CI/CD pipelines:

```yaml
# Example GitHub Actions
- name: Run Security Scans
  run: |
    make security-scan
```

## Interpreting Results

### Severity Levels

- **Critical**: Immediate action required
- **High**: Should be addressed soon
- **Medium**: Should be addressed when possible
- **Low**: Consider addressing
- **Info**: Informational only

### Common Issues

#### Reentrancy
- **Tool**: Slither, Mythril
- **Severity**: High/Critical
- **Description**: Contract vulnerable to reentrancy attacks

#### Unchecked External Calls
- **Tool**: Slither
- **Severity**: Medium/High
- **Description**: External calls without proper checks

#### Integer Overflow/Underflow
- **Tool**: Slither, Mythril
- **Severity**: Medium
- **Description**: Potential integer overflow/underflow

#### Access Control Issues
- **Tool**: Slither
- **Severity**: High
- **Description**: Missing or incorrect access controls

## Remediation

### Fixing Issues

1. **Review the issue**: Understand the vulnerability
2. **Assess impact**: Determine severity and impact
3. **Fix the code**: Implement the fix
4. **Re-scan**: Verify the fix resolved the issue
5. **Test**: Run tests to ensure functionality

### Example Fixes

#### Reentrancy Protection

```solidity
// Before (vulnerable)
function withdraw() external {
    uint amount = balances[msg.sender];
    (bool success, ) = msg.sender.call{value: amount}("");
    balances[msg.sender] = 0;
}

// After (protected)
function withdraw() external {
    uint amount = balances[msg.sender];
    balances[msg.sender] = 0; // Update state first
    (bool success, ) = msg.sender.call{value: amount}("");
}
```

## CI/CD Integration

### GitHub Actions Example

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Slither
        run: slither contracts/
      - name: Run Snyk
        run: snyk test
```

## Best Practices

1. **Run scans regularly**: Before commits and in CI/CD
2. **Fix critical issues immediately**: Don't deploy with critical vulnerabilities
3. **Review all findings**: Not all findings are actual vulnerabilities
4. **Keep tools updated**: Use latest versions for best detection
5. **Document exceptions**: If a finding is a false positive, document why

## Related Documentation

- [Security Documentation](SECURITY.md)
- [Master Documentation Index](../MASTER_DOCUMENTATION_INDEX.md)

---

**Last Updated**: 2025-01-27