foundry-web3sentinel

Foundry integration for Web3Sentinel smart contract security audits.

What is Web3Sentinel?

Web3Sentinel is an AI-powered smart contract security platform that provides instant, affordable security audits. This package integrates Web3Sentinel directly into your Foundry workflow.

Installation

Global Installation (Recommended)

npm install -g foundry-web3sentinel

Project Installation

npm install --save-dev foundry-web3sentinel

Setup

Get your API key

1. Sign up at web3sentinel.org
2. Go to Dashboard → API Keys
3. Create a new API key
4. Set it as environment variable:

export WEB3SENTINEL_API_KEY=ws_your_api_key_here

Usage

Basic Usage

In your Foundry project directory:

web3sentinel-audit

This will audit all contracts in your src/ directory.

Configuration via Environment Variables

# Fail build if critical vulnerabilities found (default: true)
export FAIL_ON_CRITICAL=true

# Fail build if high severity vulnerabilities found (default: false)
export FAIL_ON_HIGH=false

# Minimum security score required (default: 70)
export MIN_SECURITY_SCORE=80

# Run audit
web3sentinel-audit

Add to Foundry Scripts

Create script/Audit.s.sol:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "forge-std/Script.sol";

contract AuditScript is Script {
    function run() external {
        // Run Web3Sentinel audit before deployment
        string[] memory inputs = new string[](1);
        inputs[0] = "web3sentinel-audit";
        
        bytes memory result = vm.ffi(inputs);
        
        // Continue with deployment if audit passes
        vm.startBroadcast();
        // Your deployment code here
        vm.stopBroadcast();
    }
}

Enable FFI in foundry.toml:

[profile.default]
ffi = true

Run with:

forge script script/Audit.s.sol

CI/CD Integration

GitHub Actions

name: Security Audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1
      
      - name: Install Web3Sentinel
        run: npm install -g foundry-web3sentinel
      
      - name: Run Audit
        run: web3sentinel-audit
        env:
          WEB3SENTINEL_API_KEY: ${{ secrets.WEB3SENTINEL_API_KEY }}

GitLab CI

audit:
  stage: test
  image: ghcr.io/foundry-rs/foundry:latest
  before_script:
    - curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
    - apt-get install -y nodejs
    - npm install -g foundry-web3sentinel
  script:
    - web3sentinel-audit
  variables:
    WEB3SENTINEL_API_KEY: $WEB3SENTINEL_API_KEY

Example Output

🔍 Web3Sentinel Smart Contract Audit (Foundry)

Found 2 contract(s) to audit

📄 Auditing: Counter.sol
   Status: completed
   ✅ Audit complete
   Security Score: 95/100
   Gas Score: 88/100
   Vulnerabilities: 0

📄 Auditing: Token.sol
   Status: completed
   ✅ Audit complete
   Security Score: 82/100
   Gas Score: 75/100
   Vulnerabilities: 1

📊 Audit Summary

🟢 Counter: 95/100 (0 issues)
🟡 Token: 82/100 (1 issues)

✅ All audits passed!

Makefile Integration

Add to your Makefile:

audit:
	@web3sentinel-audit

deploy: audit
	@forge script script/Deploy.s.sol --broadcast

test: audit
	@forge test

Then run:

make audit
make deploy  # Audits before deploying

Pre-commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash

echo "Running Web3Sentinel audit..."
web3sentinel-audit

if [ $? -ne 0 ]; then
    echo "❌ Audit failed. Commit aborted."
    exit 1
fi

echo "✅ Audit passed. Proceeding with commit."

Make it executable:

chmod +x .git/hooks/pre-commit

Features

• ✅ Automatic contract discovery in src/
• ✅ AI-powered vulnerability detection
• ✅ Gas optimization analysis
• ✅ Standards compliance checking
• ✅ Configurable failure thresholds
• ✅ CI/CD ready
• ✅ Beautiful terminal output
• ✅ Works with Foundry scripts

Comparison with Foundry's Built-in Tools

| Feature | web3sentinel-audit | forge test | slither | |---------|-------------|------------|---------| | AI-powered analysis | ✅ | ❌ | ❌ | | Gas optimization | ✅ | ✅ | ❌ | | Vulnerability detection | ✅ | ❌ | ✅ | | Cloud-based | ✅ | ❌ | ❌ | | No local setup | ✅ | ❌ | ❌ | | Continuous updates | ✅ | ❌ | ❌ |

Support

• 📧 Email: [email protected]
• 📚 Documentation: https://web3sentinel.org/docs
• 📱 Telegram: @sopdap
• 🐛 Issues: https://github.com/SopeDapo/foundry-web3sentinel/issues

License

MIT © Web3Sentinel