smom-dbis-138/docs/security/SOLIDITYSCAN_SETUP.md

# SolidityScan Setup Guide

## Overview

This guide explains how to set up and configure SolidityScan for automated contract vulnerability scanning.

## Prerequisites

- SolidityScan account (sign up at https://solidityscan.com)
- API key from SolidityScan
- Access to Blockscout configuration

## Step 1: Create SolidityScan Account

1. Visit https://solidityscan.com
2. Sign up for an account
3. Navigate to API Keys section
4. Generate a new API key
5. Copy the API key (you'll need it later)

## Step 2: Configure API Key

### Kubernetes Secret

Create a Kubernetes secret with the API key:

```bash
kubectl create secret generic solidityscan-secrets \
  --from-literal=api-key='<your-api-key>' \
  -n besu-network
```

### Update Deployment

The secret is referenced in `k8s/blockscout/solidityscan-integration.yaml`:

```yaml
env:
  - name: SOLIDITYSCAN_API_KEY
    valueFrom:
      secretKeyRef:
        name: solidityscan-secrets
        key: api-key
```

## Step 3: Deploy SolidityScan Integration

```bash
# Apply SolidityScan integration
kubectl apply -f k8s/blockscout/solidityscan-integration.yaml

# Verify deployment
kubectl get pods -n besu-network -l app=solidityscan
```

## Step 4: Configure Blockscout

### Enable SolidityScan in Blockscout

Update Blockscout configuration to enable SolidityScan:

```yaml
# In k8s/blockscout/deployment.yaml
env:
  - name: ENABLE_SOLIDITYSCAN
    value: "true"
  - name: SOLIDITYSCAN_API_KEY
    valueFrom:
      secretKeyRef:
        name: solidityscan-secrets
        key: api-key
```

## Step 5: Configure Automatic Scanning

### Enable Auto-Scan on Verification

Configure Blockscout to automatically scan contracts when verified:

```yaml
env:
  - name: SOLIDITYSCAN_AUTO_SCAN
    value: "true"
```

## Step 6: Configure Webhooks (Optional)

Set up webhook notifications for vulnerabilities:

1. In SolidityScan dashboard, configure webhook URL
2. Update Blockscout configuration with webhook URL

```yaml
env:
  - name: SOLIDITYSCAN_WEBHOOK_URL
    value: "https://your-webhook-url.com/vulnerabilities"
```

## Step 7: Verify Setup

### Test Scanning

1. Deploy a test contract
2. Verify the contract in Blockscout
3. Check SolidityScan dashboard for scan results
4. Verify security score is displayed in Blockscout

### Check Logs

```bash
# Check Blockscout logs
kubectl logs -n besu-network -l app=blockscout | grep solidityscan

# Check SolidityScan integration logs
kubectl logs -n besu-network -l app=solidityscan
```

## CI/CD Integration

### GitHub Actions

The CI/CD pipeline includes SolidityScan:

```yaml
- name: Run SolidityScan
  if: ${{ secrets.SOLIDITYSCAN_API_KEY != '' }}
  run: |
    pip install solidityscan
    solidityscan --api-key ${{ secrets.SOLIDITYSCAN_API_KEY }} --project-path .
```

### Add Secret to GitHub

1. Go to repository Settings > Secrets
2. Add `SOLIDITYSCAN_API_KEY` secret
3. CI/CD will automatically run SolidityScan on commits

## Security Score Display

Security scores are displayed in Blockscout contract pages:

- **Score 90-100**: Excellent (Green)
- **Score 70-89**: Good (Yellow)
- **Score 50-69**: Fair (Orange)
- **Score 0-49**: Poor (Red)

## Troubleshooting

### API Key Invalid

**Error**: "Invalid API key"

**Solution**:
1. Verify API key is correct
2. Check API key hasn't expired
3. Regenerate API key if needed

### Scan Not Running

**Error**: "Scan not triggered"

**Solution**:
1. Check Blockscout configuration
2. Verify auto-scan is enabled
3. Check SolidityScan integration pod logs
4. Verify API key is set correctly

### Webhook Not Working

**Error**: "Webhook not receiving notifications"

**Solution**:
1. Verify webhook URL is accessible
2. Check webhook URL format
3. Test webhook endpoint manually
4. Check firewall rules

## Best Practices

1. **Regular Scanning**: Scan all contracts before deployment
2. **Review Scores**: Review security scores before production
3. **Fix Issues**: Address high-severity issues immediately
4. **Monitor**: Set up alerts for critical vulnerabilities
5. **Documentation**: Document security decisions

## References

- [SolidityScan Documentation](https://docs.solidityscan.com)
- [SolidityScan Dashboard](https://solidityscan.com)
- [Blockscout Integration](https://docs.blockscout.com)