mev-beta/docs/CI_CD_AUDIT_INTEGRATION.md

# CI/CD and Audit Integration Guide

**Date**: October 28, 2025
**Status**: Production Ready

## Overview

This document describes the integrated CI/CD and auditing system for the MEV Bot project, combining:

- **Go Application CI/CD** (`harness/local-ci-pipeline.sh`) - Tests, linting, security scanning for Go code
- **Solidity Contract Auditing** (`harness/solidity-audit-pipeline.sh`) - Smart contract security analysis
- **Comprehensive Documentation** (`docs/solidity_audit_bundle.md`) - 100-point audit specifications

## Quick Start

### Run Complete CI/CD Pipeline

```bash
# Full pipeline (Go + Solidity)
./harness/local-ci-pipeline.sh

# Go tests only (fast)
HARNESS_SKIP_DOCKER=true HARNESS_SKIP_MATH_AUDIT=true ./harness/local-ci-pipeline.sh

# Solidity audit only
./harness/solidity-audit-pipeline.sh
```

### Environment Variables

```bash
# Go CI/CD Pipeline
export HARNESS_SKIP_DOCKER=true          # Skip Docker build
export HARNESS_SKIP_MATH_AUDIT=true      # Skip math precision tests
export HARNESS_SKIP_SECURITY=true        # Skip security scans
export HARNESS_PARALLEL_JOBS=4           # Parallel test jobs

# Solidity Audit Pipeline
export HARNESS_SKIP_FOUNDRY=true         # Skip Foundry tests
export HARNESS_SKIP_SLITHER=true         # Skip Slither analysis
export HARNESS_SKIP_MYTHRIL=true         # Skip Mythril symbolic execution
export HARNESS_VERBOSE=true              # Verbose output
```

## Architecture

### 1. Go Application CI/CD (`harness/local-ci-pipeline.sh`)

**Purpose**: Continuous integration for Go codebase

**Steps**:
1. **Requirements Check** - Verify Go, git, container runtime
2. **Go Build** - Build binary with CGO support
3. **Unit Tests** - Run all Go tests with race detector
4. **Integration Tests** - Test contract interactions
5. **Linting** - golangci-lint, gofmt checks
6. **Security Scanning** - gosec, govulncheck
7. **Math Auditing** - Precision verification for arbitrage calculations
8. **Docker Build** - Container image creation
9. **Report Generation** - Consolidated pipeline results

**Usage**:
```bash
# Run complete pipeline
./harness/local-ci-pipeline.sh

# Quick CI (skip slow steps)
HARNESS_SKIP_DOCKER=true \\
HARNESS_SKIP_MATH_AUDIT=true \\
HARNESS_SKIP_SECURITY=true \\
./harness/local-ci-pipeline.sh
```

**Output**:
- Logs: `harness/logs/*.log`
- Reports: `harness/reports/pipeline-report.md`
- Test Coverage: `harness/reports/coverage/coverage.html`

### 2. Solidity Contract Auditing (`harness/solidity-audit-pipeline.sh`)

**Purpose**: Security analysis of smart contracts

**Tools Used**:
- **Foundry (forge)** - Gas analysis and testing
- **Slither** - Static analysis (Trail of Bits)
- **Mythril** - Symbolic execution security scanner

**Contracts Audited**:
- `contracts/ProductionArbitrageExecutor.sol` - Main arbitrage executor
- `contracts/balancer/FlashLoanReceiver.sol` - Flash loan integration
- `tests/contracts/ArbitrageTest.sol` - Test contracts

**Usage**:
```bash
# Run complete audit
./harness/solidity-audit-pipeline.sh

# Run specific tools
HARNESS_SKIP_SLITHER=true \\
HARNESS_SKIP_MYTHRIL=true \\
./harness/solidity-audit-pipeline.sh  # Foundry only
```

**Output**:
- Logs: `harness/logs/solidity/*.log`
- Reports: `harness/reports/solidity/`
  - `audit-summary.md` - Consolidated audit report
  - `forge-gas.json` - Gas analysis
  - `slither.json` - Static analysis results
  - `mythril-*.json` - Symbolic execution results

### 3. 100-Point Audit System (`docs/solidity_audit_bundle.md`)

**Purpose**: Comprehensive scoring rubric for production readiness

**Categories** (100 points total):
- A. Architecture & Design (10 pts)
- B. Security Vulnerability Analysis (25 pts)
- C. Gas & Performance Optimization (20 pts)
- D. Testing & Coverage (15 pts)
- E. Tool-Based Analysis (20 pts)
- F. Documentation & Clarity (5 pts)
- G. CI/CD & Automation (5 pts)
- H. Foundry + Hardhat Parity (5 pts)
- I. Code Quality & Readability (5 pts)
- J. Protocol-Specific Checks (10 pts)
- K. Deployment & Production Readiness (10 pts)

**Scoring**:
```bash
# Generate audit score
python3 scripts/score_audit.py \\
  --input harness/reports/solidity/merged.json \\
  --out audit-score.md \\
  --json audit-score.json
```

## Integration with GitHub Actions

The CI/CD system integrates with GitHub Actions via `.github/workflows/ci.yml`:

```yaml
name: CI Pipeline

on: [push, pull_request]

jobs:
  go-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.25'
      - name: Run Go CI Pipeline
        run: |
          HARNESS_SKIP_DOCKER=true \\
          HARNESS_SKIP_MATH_AUDIT=true \\
          ./harness/local-ci-pipeline.sh

  solidity-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1
      - name: Run Solidity Audit
        run: ./harness/solidity-audit-pipeline.sh
```

## Docker-Based Execution

Both pipelines support Docker/Podman for reproducible builds:

```bash
# Using Docker
export HARNESS_RUNTIME=docker
./harness/local-ci-pipeline.sh

# Using Podman
export HARNESS_RUNTIME=podman
./harness/solidity-audit-pipeline.sh
```

## Local Development Workflow

### Pre-Commit Checks

```bash
# Fast pre-commit (< 30 seconds)
./scripts/ci-quick.sh

# Full pre-commit with security
./scripts/ci-precommit.sh
```

### Continuous Development

```bash
# Watch mode for continuous testing
./scripts/ci-watch.sh

# Development server with auto-rebuild
./scripts/ci-dev.sh
```

### Pre-Production Checklist

```bash
# 1. Run complete Go CI/CD
./harness/local-ci-pipeline.sh

# 2. Run Solidity audit
./harness/solidity-audit-pipeline.sh

# 3. Check math precision
./bin/math-audit validate
./bin/math-audit audit

# 4. Review audit reports
cat harness/reports/pipeline-report.md
cat harness/reports/solidity/audit-summary.md

# 5. Generate deployment artifacts
make build-production
docker build -t mev-bot:latest .
```

## Monitoring and Reporting

### Log Analysis

```bash
# View pipeline logs
tail -f harness/logs/*.log

# Check for errors
grep -r "ERROR\\|FAIL" harness/logs/

# Solidity audit logs
tail -f harness/logs/solidity/*.log
```

### Report Generation

```bash
# Generate consolidated report
cat harness/reports/pipeline-report.md

# View test coverage
open harness/reports/coverage/coverage.html

# Solidity audit summary
cat harness/reports/solidity/audit-summary.md
```

### Metrics Tracking

```bash
# Test pass rate
grep "PASS\\|FAIL" harness/logs/go-test.log | awk '{print $1}' | sort | uniq -c

# Security issues found
jq '.results | length' harness/reports/solidity/slither.json

# Gas consumption
jq '.tests | map(.gas) | add' harness/reports/solidity/forge-gas.json
```

## Troubleshooting

### Common Issues

**1. Docker/Podman not found**
```bash
# Install Docker
curl -fsSL https://get.docker.com | sh

# Or use Podman
sudo apt install podman
```

**2. Go version mismatch**
```bash
# Check version
go version

# Upgrade to 1.25+
sudo rm -rf /usr/local/go
wget https://go.dev/dl/go1.25.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.25.0.linux-amd64.tar.gz
```

**3. Foundry not installed**
```bash
# Install Foundry
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

**4. Slither/Mythril failures**
```bash
# Use Docker images instead of local installation
export HARNESS_RUNTIME=docker
./harness/solidity-audit-pipeline.sh
```

### Performance Optimization

**Parallel Execution**
```bash
# Increase parallel test jobs
export HARNESS_PARALLEL_JOBS=8
./harness/local-ci-pipeline.sh
```

**Caching**
```bash
# Use Go build cache
export GOCACHE=/tmp/go-cache
export GOMODCACHE=/tmp/go-mod-cache
```

**Skip Slow Steps**
```bash
# Development mode (fast)
HARNESS_SKIP_DOCKER=true \\
HARNESS_SKIP_SECURITY=true \\
HARNESS_SKIP_MATH_AUDIT=true \\
./harness/local-ci-pipeline.sh
```

## Production Deployment

### Final Checklist

- [ ] All Go tests passing (`./harness/local-ci-pipeline.sh`)
- [ ] No critical security issues (`gosec`, `govulncheck`)
- [ ] Solidity contracts audited (`./harness/solidity-audit-pipeline.sh`)
- [ ] No high/critical Slither findings
- [ ] Math precision verified (`./bin/math-audit audit`)
- [ ] Docker image builds successfully
- [ ] Documentation updated
- [ ] Audit score ≥ 80/100

### Deployment Commands

```bash
# 1. Tag release
git tag -a v1.0.0 -m "Production release"
git push origin v1.0.0

# 2. Build production binary
make build-production

# 3. Build Docker image
docker build -t mev-bot:v1.0.0 .
docker tag mev-bot:v1.0.0 mev-bot:latest

# 4. Push to registry
docker push mev-bot:v1.0.0
docker push mev-bot:latest

# 5. Deploy to production
kubectl apply -f k8s/production/
```

## References

- [Go CI/CD Pipeline](../harness/local-ci-pipeline.sh)
- [Solidity Audit Pipeline](../harness/solidity-audit-pipeline.sh)
- [Audit Bundle Specifications](../docs/solidity_audit_bundle.md)
- [GitHub Actions Workflows](../.github/workflows/)
- [Foundry Documentation](https://book.getfoundry.sh/)
- [Slither Security Scanner](https://github.com/crytic/slither)
- [Mythril Symbolic Execution](https://github.com/ConsenSys/mythril)

## Support

For issues or questions:
- Create an issue in the repository
- Review logs in `harness/logs/`
- Check reports in `harness/reports/`
- Consult the audit bundle documentation

---

**Last Updated**: October 28, 2025
**Version**: 1.0.0
**Status**: Production Ready ✅