Skip to content

WORKFLOWS.md

Latest commit

 

History

History
434 lines (326 loc) · 9.86 KB

WORKFLOWS.md

File metadata and controls

434 lines (326 loc) · 9.86 KB

GitHub Actions Workflows

Overview

SmartContractAudit includes several automated workflows to continuously monitor, audit, and repair smart contracts.

Workflows

1. Auditor Bot Workflow

File: .github/workflows/auditor-bot.yml

Continuously monitors contracts and flags suspicious activity.

Triggers:

  • Schedule: Every 6 hours
  • Manual trigger
  • Webhook from monitored contracts

Features:

  • Scans configured contract addresses
  • Runs all detection modules
  • Generates reports
  • Sends notifications on findings
  • Creates issues for critical vulnerabilities

Configuration:

Add to repository secrets:

  • ETHEREUM_RPC_URL
  • BSC_RPC_URL
  • NOTIFICATION_WEBHOOK

2. Auto-Repair Workflow

File: .github/workflows/auto-repair.yml

Automatically creates PRs with vulnerability fixes.

Triggers:

  • On detection of fixable vulnerabilities
  • Manual trigger
  • Issue labeled with 'auto-fix'

Features:

  • Analyzes detected vulnerabilities
  • Generates code fixes
  • Creates pull request with fixes
  • Assigns reviewers
  • Adds appropriate labels

Configuration:

Required secrets:

  • GITHUB_TOKEN (automatically provided)

Repository settings:

  • Enable PR creation from workflows
  • Configure branch protection rules

3. Continuous Audit Workflow

File: .github/workflows/continuous-audit.yml

Runs audits on all PRs and commits.

Triggers:

  • Pull request (opened, synchronized)
  • Push to main/master
  • Schedule: Daily

Features:

  • Scans changed contracts
  • Comments on PRs with findings
  • Blocks merge if critical issues found
  • Updates audit status check

4. Deep Scan Workflow

File: .github/workflows/deep-scan.yml

Comprehensive scanning for thorough analysis.

Triggers:

  • Manual trigger
  • Release creation
  • Schedule: Weekly

Features:

  • Deep wallet tracing
  • Full contract analysis
  • Historical transaction analysis
  • Generates PDF reports
  • Archives results

Workflow Examples

Example: Auditor Bot

name: Auditor Bot

on:
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:
    inputs:
      addresses:
        description: 'Contract addresses to scan (comma-separated)'
        required: false

jobs:
  audit:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run Auditor
        env:
          ETHEREUM_RPC_URL: ${{ secrets.ETHEREUM_RPC_URL }}
          BSC_RPC_URL: ${{ secrets.BSC_RPC_URL }}
          NOTIFICATION_WEBHOOK: ${{ secrets.NOTIFICATION_WEBHOOK }}
        run: |
          npm run audit:continuous
          
      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: audit-reports
          path: reports/
          
      - name: Notify on Critical Findings
        if: ${{ env.CRITICAL_FOUND == 'true' }}
        run: npm run notify -- --severity critical

Example: Auto-Repair

name: Auto-Repair

on:
  issues:
    types: [labeled]
  workflow_dispatch:
    inputs:
      issue_number:
        description: 'Issue number to fix'
        required: true

jobs:
  repair:
    runs-on: ubuntu-latest
    if: github.event.label.name == 'auto-fix'
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Generate Fix
        id: fix
        run: |
          RESULT=$(npm run generate-fix -- --issue ${{ github.event.issue.number }})
          echo "fix_generated=$?" >> $GITHUB_OUTPUT
          
      - name: Create Pull Request
        if: steps.fix.outputs.fix_generated == '0'
        # Pin to specific commit SHA for security (v6.1.0)
        # Periodically update to latest stable release
        uses: peter-evans/create-pull-request@5e914681df9dc83aa4e4098168140606ad016ba4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          branch: auto-fix-${{ github.event.issue.number }}
          title: '🔒 Fix: ${{ github.event.issue.title }}'
          body: |
            Automated fix for #${{ github.event.issue.number }}
            
            This PR was automatically generated by the Auto-Repair workflow.
            Please review carefully before merging.
          labels: security, automated-fix
          assignees: ${{ github.event.issue.assignees }}

Example: PR Audit Check

name: PR Audit Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  audit:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Get Changed Files
        id: changed
        run: |
          CHANGED_FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD | grep -E '\.(sol|js|ts)$' || true)
          echo "files=$CHANGED_FILES" >> $GITHUB_OUTPUT
          
      - name: Scan Changed Contracts
        if: steps.changed.outputs.files != ''
        env:
          ETHEREUM_RPC_URL: ${{ secrets.ETHEREUM_RPC_URL }}
        run: |
          npm run scan:changed -- ${{ steps.changed.outputs.files }}
          
      - name: Comment PR
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const report = JSON.parse(fs.readFileSync('reports/latest.json', 'utf8'));
            
            let comment = '## 🔍 Security Audit Results\n\n';
            
            if (report.issues.length === 0) {
              comment += '✅ No security issues detected!';
            } else {
              comment += `⚠️ Found ${report.issues.length} issue(s):\n\n`;
              for (const issue of report.issues) {
                comment += `- **${issue.severity}**: ${issue.description}\n`;
              }
            }
            
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: comment
            });
            
      - name: Check Status
        run: |
          CRITICAL=$(jq '.issues | map(select(.severity == "critical")) | length' reports/latest.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "❌ Critical issues found! Please fix before merging."
            exit 1
          fi

Setup Instructions

1. Enable GitHub Actions

  1. Go to repository Settings → Actions
  2. Enable "Allow all actions and reusable workflows"
  3. Save settings

2. Add Required Secrets

Go to Settings → Secrets → Actions:

ETHEREUM_RPC_URL=https://mainnet.infura.io/v3/...
BSC_RPC_URL=https://bsc-dataseed1.binance.org
POLYGON_RPC_URL=https://polygon-rpc.com
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
ETHERSCAN_API_KEY=...
BSCSCAN_API_KEY=...
SLACK_WEBHOOK=https://hooks.slack.com/services/...
NOTIFICATION_WEBHOOK=https://your-webhook-url.com

3. Configure Workflow Permissions

Settings → Actions → General → Workflow permissions:

  • Enable "Read and write permissions"
  • Enable "Allow GitHub Actions to create and approve pull requests"

4. Set Up Branch Protection

Settings → Branches → Add rule:

  • Branch name pattern: main
  • Require status checks: Enable
    • Require "PR Audit Check" to pass
  • Require pull request reviews: Enable

Manual Workflow Triggers

Trigger from GitHub UI

  1. Go to Actions tab
  2. Select workflow
  3. Click "Run workflow"
  4. Fill in inputs (if any)
  5. Click "Run workflow"

Trigger via GitHub CLI

# Trigger auditor bot
gh workflow run auditor-bot.yml

# Trigger with inputs
gh workflow run deep-scan.yml \
  -f addresses="0x123...,0x456..." \
  -f chain="ethereum"

Trigger via API

curl -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/auditor-bot.yml/dispatches \
  -d '{"ref":"main"}'

Monitoring Workflows

View Workflow Runs

  1. Go to Actions tab
  2. Select workflow
  3. View run history and logs

Set Up Notifications

Settings → Notifications → Actions:

  • Email notifications for failed workflows
  • Slack/Discord integration

Best Practices

  1. Test workflows locally using act
  2. Use caching to speed up workflow runs
  3. Set timeouts to prevent stuck jobs
  4. Use matrix builds for multi-chain testing
  5. Archive artifacts for historical analysis
  6. Monitor costs for self-hosted runners
  7. Review permissions regularly

Troubleshooting

Workflow Not Triggering

  • Check trigger conditions
  • Verify branch protection rules
  • Check workflow file syntax

Permission Denied

  • Verify repository secrets
  • Check workflow permissions
  • Update GITHUB_TOKEN scopes

Timeout Issues

  • Increase timeout value
  • Optimize scan performance
  • Use caching

Advanced Features

Matrix Builds

Scan multiple chains in parallel:

strategy:
  matrix:
    chain: [ethereum, bsc, polygon, solana]
    
steps:
  - name: Scan ${{ matrix.chain }}
    run: npm run scan -- --chain ${{ matrix.chain }}

Conditional Execution

Run steps conditionally:

- name: Critical Alert
  if: ${{ env.CRITICAL_FOUND == 'true' }}
  run: npm run alert -- --severity critical

Reusable Workflows

Create reusable workflow:

# .github/workflows/reusable-scan.yml
on:
  workflow_call:
    inputs:
      chain:
        required: true
        type: string

Use in other workflows:

jobs:
  scan:
    uses: ./.github/workflows/reusable-scan.yml
    with:
      chain: ethereum