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:

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:

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

Step 3: Deploy SolidityScan Integration

# 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:

# 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:

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

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

# 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:

- 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
• SolidityScan Dashboard
• Blockscout Integration