hardhat-contractscan

Hardhat plugin for ContractScan — AI-powered smart contract vulnerability scanner.

Scan your Solidity contracts for security vulnerabilities directly from npx hardhat scan.

Installation

npm install --save-dev hardhat-contractscan

Setup

Add to your hardhat.config.ts:

import "hardhat-contractscan";

const config: HardhatUserConfig = {
  // ... your existing config
  contractscan: {
    apiKey: process.env.CONTRACTSCAN_API_KEY, // optional — free tier works without key
    failOn: "Critical",    // Critical | High | Medium | Low | None
    reportFormat: "markdown", // markdown | json | both
    autoScan: false,       // auto-scan after compile (coming soon)
  },
};

Or in hardhat.config.js:

require("hardhat-contractscan");

module.exports = {
  contractscan: {
    apiKey: process.env.CONTRACTSCAN_API_KEY,
    failOn: "High",
  },
};

Usage

Basic scan

npx hardhat scan

Compile first, then scan

npx hardhat scan --compile

Set fail threshold

npx hardhat scan --fail-on Medium

Choose report format

npx hardhat scan --report both

Reports are saved to contractscan-reports/ in your project root.

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | "" | API key for paid tiers (env: CONTRACTSCAN_API_KEY) | | apiUrl | string | https://contract-scanner.raccoonworld.xyz | API endpoint (env: CONTRACTSCAN_API_URL) | | failOn | string | "Critical" | Minimum severity to fail: Critical, High, Medium, Low, None | | reportFormat | string | "markdown" | Output format: markdown, json, both | | sources | string | hardhat.paths.sources | Directory to scan | | autoScan | boolean | false | Auto-scan after hardhat compile |

Free Tier

Works without an API key — basic scans using Slither + Semgrep engines. Paid plans add AI analysis, Mythril deep scanning, and more.

Output

Terminal output includes:

• Security score (0-100)
• Severity breakdown (Critical/High/Medium/Low/Info)
• Finding details with suggested fixes
• Report URL for sharing

Reports saved as:

• contractscan-reports/contractscan-report.md (Markdown)
• contractscan-reports/contractscan-report.json (JSON)

CI/CD Integration

Combine with the ContractScan GitHub Action for full CI/CD coverage:

# .github/workflows/security.yml
- uses: h33min/contractscan@v1
  with:
    api-key: ${{ secrets.CONTRACTSCAN_API_KEY }}
    fail-on: High

License

MIT