FHE Contract Analyzer

AI-assisted FHE contract privacy audit tool for Fhenix/CoFHE smart contracts. Helps developers validate that their FHE-enabled contracts maintain privacy and follow best practices.

Features

• 🔍 Static Analysis: Detects FHE-specific privacy issues in Solidity contracts
• 🤖 AI-Assisted Self-Audit: Interactive questions guide you through privacy validation
• 🔧 Autofix Suggestions: Many issues can be automatically fixed
• 📊 Privacy Score: Get a confidence score on your contract's privacy guarantees
• 🎯 Pattern Detection: Identifies common FHE pitfalls (missing allowThis, branching on encrypted data, etc.)

Installation

npm install -g fhe-contract-analyzer

Or use with npx:

npx fhe-contract-analyzer scan <path>

Usage

Basic Scan

fhe-audit scan contracts/

JSON Output

fhe-audit scan contracts/ --json -o report.json

Skip Interactive Questions

fhe-audit scan contracts/ --no-questions

What It Detects

Critical Issues (FATAL)

• Branching on encrypted boolean values (if statements on ebool)
• On-chain decryption in public functions
• Direct plaintext leakage via events/returns

High Priority (HIGH)

• Missing FHE.allowThis() after encrypted state updates
• Missing FHE.allow() for cross-contract calls
• Missing FHE.allow() for user decryption access

Best Practices (MEDIUM/LOW)

• Unsafe decryption retrieval (use getDecryptResultSafe())
• Oversized encrypted types
• Non-reused encrypted constants

Example Output

🔐 FHE Contract Privacy Audit Report
══════════════════════════════════════════════════════════════════════

📊 Summary
──────────────────────────────────────────────────────────────────────
Total Findings: 3
Privacy Score: 85/100 ⚠️  Good
Autofixable: 2

📋 Findings by Severity
──────────────────────────────────────────────────────────────────────
HIGH    : 2
MEDIUM  : 1

🔍 Detailed Findings

HIGH (2)
  [D1] Missing FHE.allowThis() after updating encrypted state variable 'totalTips'
    → contracts/PrivateTipJar.sol:82
    💡 Autofix: Add FHE.allowThis(totalTips); after line 82

  [D3] Missing FHE.allow() before passing encrypted value to external contract
    → contracts/PrivateTipJar.sol:220
    💡 Autofix: Add FHE.allowTransient(bidAmount, auction.fherc20Token) before the call

MEDIUM (1)
  [E2] Using FHE.getDecryptResult() - prefer FHE.getDecryptResultSafe()
    → contracts/Auction.sol:289
    💡 Autofix: Replace with getDecryptResultSafe() and check decrypted flag

Privacy Specs

The analyzer uses privacy specs to understand your contract's intended privacy model. You can provide your own specs or let the tool infer from your code.

Documentation

• Usage Guide: Comprehensive usage instructions, CI/CD integration, and examples
• Deployment Guide: Steps to publish to npm
• Architecture: Technical details and extension points

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev scan contracts/

Architecture

• AST Parser: Uses solidity-parser-antlr to parse Solidity
• Pattern Matcher: AST pattern matching for rule detection
• Symbol Table: Tracks variables, functions, types
• Data Flow Analysis: Tracks encrypted value flow
• Rule Engine: Pluggable rule system for extensibility
• Question Generator: Interactive privacy validation flow

Contributing

This is an early version. Contributions welcome! Key areas for improvement:

• More rule implementations
• Better pattern matching accuracy
• Enhanced autofix capabilities
• Additional privacy specs for common patterns

Known Issues

See KNOWN_ISSUES.md for known issues and workarounds.

The tool may emit a harmless circular dependency warning from the parser library. This can be safely ignored or suppressed with node --no-warnings.

License

MIT