# AI-Powered Smart Contract Audit Assistant
An interactive SpoonOS-powered tool that provides real-time vulnerability checks, natural-language explanations, and hands-on learning for your Solidity contracts—before you deploy.
## Features
- **Real-time Security Analysis**: Instant vulnerability detection using static analysis tools (Slither, Mythril, Solhint)
- **AI-Powered Explanations**: Natural language explanations of vulnerabilities with reasoning and suggested fixes powered by SpoonOS Agent Framework
- **Interactive Learning**: Step-by-step tutorials and remediation guidance
- **Multiple Interfaces**: CLI tool, VS Code extension, and web dashboard
- **Professional Reports**: Export detailed audit reports in HTML, JSON, Markdown, and PDF formats
- **CI/CD Integration**: GitHub Actions and Git hooks for automated security checks
- **Watch Mode**: Continuous monitoring of contract changes during development
## Installation
### Prerequisites
- Python 3.10+
- Node.js 16+ (for VS Code extension and web dashboard)
- Git
### Install from PyPI
```bash
pip install spoon-audit
```
### Install from Source
```bash
git clone https://github.com/CodeKage25/smart-audit-assistant.git
cd smart-audit-assistant
pip install -e .
```
### Optional Dependencies
For PDF export functionality:
```bash
pip install weasyprint
```
## Quick Start
### 1. Configuration
First, configure your API keys and preferences:
```bash
# View current configuration
spoon-audit config --show
# Set OpenAI API key (required for AI explanations)
spoon-audit config --set api_keys.openai "your-api-key-here"
# Set LLM provider (default: openai)
spoon-audit config --set llm_provider "openai"
# Set model preference
spoon-audit config --set model_name "gpt-4"
```
### 2. Scan a Contract
```bash
# Scan a single Solidity file
spoon-audit scan ./contracts/MyContract.sol
# Scan with detailed AI explanations
spoon-audit scan --detailed ./contracts/MyContract.sol
# Scan entire project directory
spoon-audit scan ./contracts/
# Enable debug mode for detailed output
spoon-audit scan --debug ./contracts/MyContract.sol
```
### 3. View Reports
```bash
# Show the last scan report
spoon-audit report
# Show detailed report with AI reasoning and suggested fixes
spoon-audit report --detailed
# Filter by severity level
spoon-audit report --severity high
# Show only AI findings
spoon-audit report --ai-only
```
### 4. Export Professional Reports
```bash
# Export as HTML (modern, interactive report)
spoon-audit export --format html
# Export and open in browser
spoon-audit export --format html --open-browser
# Export as PDF (requires weasyprint)
spoon-audit export --format pdf
# Export as JSON for CI/CD integration
spoon-audit export --format json > audit-report.json
# Export as Markdown
spoon-audit export --format markdown
```
### 5. Watch Mode
Monitor your contracts during development:
```bash
# Watch a file and re-scan on changes
spoon-audit watch ./contracts/MyContract.sol
# Watch entire directory with detailed output
spoon-audit watch ./contracts/ --detailed
# Watch with custom interval
spoon-audit watch ./contracts/ --interval 5
```
## CLI Commands Reference
### `spoon-audit scan`
Analyze Solidity files or directories for vulnerabilities.
**Options:**
- `--detailed`: Show comprehensive AI analysis with reasoning and suggested fixes
- `--output-format`: Report format (console, json, markdown)
- `--severity`: Minimum severity level (info, low, medium, high, critical)
- `--exclude`: Patterns to exclude from scanning
- `--include-dependencies`: Include node_modules and dependencies
- `--debug`: Enable debug mode with verbose output
**Examples:**
```bash
# Comprehensive scan with detailed AI analysis
spoon-audit scan ./contracts/ --detailed
# High-severity issues only in JSON format
spoon-audit scan ./contracts/ --output-format json --severity high
# Exclude test files
spoon-audit scan ./src/ --exclude "**/test/**" --include-dependencies
```
### `spoon-audit report`
Display the last scan report with various filtering options.
**Options:**
- `--detailed`: Show comprehensive analysis with AI reasoning
- `--severity`: Filter by severity level (info, low, medium, high, critical)
- `--ai-only`: Show only AI-detected vulnerabilities
- `--static-only`: Show only static analysis findings
- `--format`: Output format (console, json, markdown)
**Examples:**
```bash
# Detailed report with all AI explanations
spoon-audit report --detailed
# Only critical and high severity issues
spoon-audit report --severity high --detailed
# AI findings only with reasoning
spoon-audit report --ai-only --detailed
```
### `spoon-audit export`
Export professional audit reports in various formats.
**Options:**
- `--format`: Export format (html, pdf, json, markdown)
- `--output, -o`: Output file path
- `--open-browser`: Open HTML report in browser automatically
- `--detailed`: Include comprehensive AI analysis in export
**Examples:**
```bash
# Professional HTML report with auto-open
spoon-audit export --format html --open-browser --detailed
# PDF audit report
spoon-audit export --format pdf -o security_audit.pdf
# JSON for CI/CD integration
spoon-audit export --format json -o results.json
```
### `spoon-audit watch`
Continuously monitor files for changes and re-scan automatically.
**Options:**
- `--detailed`: Show detailed AI analysis on each scan
- `--interval`: Check interval in seconds (default: 2)
- `--clear`: Clear screen between scans
**Examples:**
```bash
# Watch with detailed analysis
spoon-audit watch ./contracts/Token.sol --detailed
# Custom interval with screen clearing
spoon-audit watch ./src/ --interval 5 --clear
```
### `spoon-audit config`
Manage runtime configuration and API keys.
**Options:**
- `--show`: Display current configuration
- `--set key value`: Set configuration value
- `--reset`: Reset to default configuration
**Examples:**
```bash
spoon-audit config --show
spoon-audit config --set model_name "gpt-4"
spoon-audit config --set base_url "https://api.openai.com/v1"
spoon-audit config --set scan_settings.severity_threshold "high"
```
## Configuration
The tool uses a `config.json` file stored in your home directory (`~/.spoon-audit/config.json`). You can also set environment variables:
```bash
export SPOON_AUDIT_OPENAI_API_KEY="your-api-key"
export SPOON_AUDIT_LLM_PROVIDER="openai"
export SPOON_AUDIT_MODEL_NAME="gpt-4"
```
### Configuration Schema
```json
{
"api_keys": {
"openai": "your-openai-api-key",
"anthropic": "your-anthropic-api-key"
},
"base_url": "https://api.openai.com/v1",
"default_agent": "default",
"llm_provider": "openai",
"model_name": "gpt-4",
"scan_settings": {
"include_dependencies": false,
"severity_threshold": "medium",
"output_format": "console",
"detailed_by_default": false
}
}
```
## Report Formats
### Console Output
- Color-coded severity levels
- Detailed AI explanations with `--detailed` flag
- Clean, readable formatting for terminal use
### HTML Export
- **Modern Design**: Professional gradient styling and responsive layout
- **Interactive Features**: Table of contents, print button, smooth scrolling
- **Comprehensive**: Includes all findings with AI reasoning and suggestions
- **Mobile-Friendly**: Responsive design for all devices
### PDF Export
- **Professional Layout**: Print-ready audit reports
- **Complete Analysis**: All vulnerabilities with detailed explanations
- **Requires**: `weasyprint` package (`pip install weasyprint`)
### JSON Export
- **Structured Data**: Perfect for CI/CD integration and automated processing
- **Complete Information**: All findings with metadata and confidence scores
- **API Integration**: Easy to parse and integrate with other tools
## Project Structure
```
smart-audit-assistant/
├── README.md
├── pyproject.toml
├── .env.example
├── cli/
│ ├── __init__.py
│ └── main.py # CLI entry point with enhanced reporting
├── analysis/
│ ├── __init__.py
│ ├── parser.py # Solidity AST parsing
│ ├── static_scanner.py # Static analysis integration
│ └── ai_analyzer.py # SpoonOS AI analysis with reasoning
├── reports/
│ ├── __init__.py
│ ├── exporters.py # HTML, PDF, JSON, Markdown exporters
│ └── templates/ # Professional report templates
├── extension/ # VS Code extension
│ ├── package.json
│ ├── src/
│ │ └── extension.ts
│ └── README.md
├── web-dashboard/ # Next.js web interface
│ ├── package.json
│ ├── src/
│ │ ├── app/
│ │ └── components/
│ └── README.md
├── tests/
│ ├── test_parser.py
│ ├── test_static_scanner.py
│ ├── test_ai_analyzer.py
│ └── test_exporters.py
└── docs/
└── architecture.md
```
## Architecture
The tool follows a modular architecture with enhanced AI analysis and professional reporting:
```mermaid
flowchart TD
subgraph INGESTION
A[Solidity Code] --> B[Parser]
B --> C[AST]
C --> D[Static Scanner]
D --> D1[Slither]
D --> D2[Mythril]
D --> D3[Solhint]
end
subgraph AI_ANALYSIS
D --> E[SpoonOS Agent]
E --> F[Vector DB]
E --> G[OpenAI/Anthropic]
F & G --> H[Detailed Explanations]
H --> H1[Reasoning]
H --> H2[Suggested Fixes]
H --> H3[Confidence Scores]
end
subgraph REPORTING
H --> I[Report Engine]
I --> I1[Console Output]
I --> I2[HTML Export]
I --> I3[PDF Export]
I --> I4[JSON Export]
I --> I5[Markdown Export]
end
subgraph INTEGRATIONS
I --> J[CLI Interface]
I --> K[VS Code Extension]
I --> L[Web Dashboard]
I --> M[CI/CD Pipeline]
end
```
## AI Analysis Features
The SpoonOS-powered AI analysis provides:
- **Detailed Reasoning**: Explains why each vulnerability is problematic
- **Suggested Fixes**: Specific code changes to resolve issues
- **Confidence Scores**: AI certainty levels for each finding
- **Context Awareness**: Understands contract patterns and business logic
- **Natural Language**: Clear explanations for developers of all levels
## VS Code Extension
Install the VS Code extension for inline diagnostics and quick fixes:
1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Spoon Audit"
4. Install and reload
Features:
- Real-time vulnerability highlighting
- Hover tooltips with AI explanations
- Quick-fix suggestions with reasoning
- Integrated with CLI backend
## Web Dashboard
Launch the web dashboard for project management and interactive tutorials:
```bash
cd web-dashboard
npm install
npm run dev
```
Visit `http://localhost:3000` to access:
- Project scan history with detailed reports
- Interactive vulnerability tutorials
- Team collaboration features
- Professional report generation
- Detailed analytics and trends
## CI/CD Integration
### GitHub Actions
Add to `.github/workflows/audit.yml`:
```yaml
name: Smart Contract Audit
on: [push, pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: '3.10'
- name: Install spoon-audit
run: pip install spoon-audit
- name: Run comprehensive audit
run: |
spoon-audit scan ./contracts/ --detailed
spoon-audit export --format json -o audit-results.json
env:
SPOON_AUDIT_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
- name: Upload audit results
uses: actions/upload-artifact@v3
with:
name: audit-results
path: audit-results.json
```
### Git Hooks
Set up pre-commit hooks:
```bash
# Install pre-commit
pip install pre-commit
# Add to .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: spoon-audit
name: Smart Contract Audit
entry: spoon-audit scan
language: system
files: \.sol$
args: [--severity, high, --detailed]
```
## Supported Vulnerabilities
The tool detects and provides AI-powered explanations for:
### Critical Issues
- **Reentrancy attacks** - Complete analysis with attack vectors and fixes
- **Access control bypasses** - Detailed explanation of privilege escalation risks
- **Integer overflow/underflow** - Context-aware detection with SafeMath recommendations
### High-Risk Issues
- **Unchecked external calls** - Analysis of failure handling and return value checks
- **Timestamp dependence** - Explanation of miner manipulation risks
- **Front-running vulnerabilities** - MEV risks and mitigation strategies
### Medium-Risk Issues
- **Gas optimization opportunities** - Detailed gas usage analysis
- **Logic errors** - Business logic vulnerabilities and edge cases
- **State inconsistencies** - Contract state management issues
### Low-Risk Issues
- **Code quality improvements** - Best practices and maintainability suggestions
- **Documentation gaps** - Missing NatSpec and comment recommendations
## Development
### Setting up Development Environment
```bash
# Clone the repository
git clone https://github.com/CodeKage25/smart-audit-assistant.git
cd smart-audit-assistant
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install development dependencies
pip install -e ".[dev]"
# Install optional PDF support
pip install weasyprint
# Run tests
pytest tests/
# Run with debug mode
spoon-audit scan --debug --detailed ./examples/vulnerable-contract.sol
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=analysis --cov=cli --cov=reports
# Run specific test categories
pytest tests/test_static_scanner.py
pytest tests/test_exporters.py
pytest tests/test_ai_analyzer.py
```
## Usage Examples
### Basic Workflow
```bash
# 1. Scan your contracts
spoon-audit scan ./contracts/ --detailed
# 2. Review findings in detail
spoon-audit report --detailed --severity medium
# 3. Export professional report
spoon-audit export --format html --open-browser
# 4. Fix issues and re-scan
spoon-audit watch ./contracts/ --detailed
```
### Advanced Usage
```bash
# Comprehensive security audit with PDF export
spoon-audit scan ./contracts/ --detailed --severity low
spoon-audit export --format pdf -o comprehensive_audit.pdf
# CI/CD integration
spoon-audit scan ./src/ --detailed --output-format json > results.json
spoon-audit export --format markdown -o SECURITY_REPORT.md
# Development workflow with continuous monitoring
spoon-audit watch ./contracts/ --detailed --clear --interval 3
```
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/enhanced-analysis`)
3. Commit your changes (`git commit -m 'Add enhanced AI analysis'`)
4. Push to the branch (`git push origin feature/enhanced-analysis`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [docs.spoon-audit.com](https://docs.spoon-audit.com)
- **Issues**: [GitHub Issues](https://github.com/CodeKage25/smart-audit-assistant/issues)
- **Discord**: [SpoonOS Community](https://discord.gg/spoonos)
- **Email**: team@secureaudit.xyz
## Changelog
### Latest Updates
- ✅ **Enhanced AI Analysis**: Complete reasoning and suggested fixes now display properly
- ✅ **Professional Reports**: Beautiful HTML and PDF export with modern design
- ✅ **Interactive Features**: Auto-open browser, table of contents, mobile-responsive design
- ✅ **Comprehensive CLI**: Detailed reporting options with filtering and export capabilities
- ✅ **Improved Configuration**: Better API key management and settings
## Acknowledgments
- Built with [SpoonOS Agent Framework](https://spoonai.io/)
- Powered by [OpenAI GPT-4](https://openai.com) and [Anthropic Claude](https://anthropic.com)
- Static analysis by [Slither](https://github.com/crytic/slither), [Mythril](https://github.com/ConsenSys/mythril), and [Solhint](https://github.com/protofire/solhint)
- PDF generation by [WeasyPrint](https://weasyprint.org)
- Special thanks to the Web3 security community
Raw data
{
"_id": null,
"home_page": null,
"name": "spoon-audit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "solidity, smart-contracts, audit, security, blockchain",
"author": null,
"author_email": "SecureAudit Collective <team@secureaudit.xyz>",
"download_url": "https://files.pythonhosted.org/packages/66/54/d4ab02395319b48768a9316de34d4cbd85e5e66c8a3dad5513b9194bb230/spoon_audit-0.1.0.tar.gz",
"platform": null,
"description": "# AI-Powered Smart Contract Audit Assistant\n\nAn interactive SpoonOS-powered tool that provides real-time vulnerability checks, natural-language explanations, and hands-on learning for your Solidity contracts\u2014before you deploy.\n\n## Features\n\n- **Real-time Security Analysis**: Instant vulnerability detection using static analysis tools (Slither, Mythril, Solhint)\n- **AI-Powered Explanations**: Natural language explanations of vulnerabilities with reasoning and suggested fixes powered by SpoonOS Agent Framework\n- **Interactive Learning**: Step-by-step tutorials and remediation guidance\n- **Multiple Interfaces**: CLI tool, VS Code extension, and web dashboard\n- **Professional Reports**: Export detailed audit reports in HTML, JSON, Markdown, and PDF formats\n- **CI/CD Integration**: GitHub Actions and Git hooks for automated security checks\n- **Watch Mode**: Continuous monitoring of contract changes during development\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10+\n- Node.js 16+ (for VS Code extension and web dashboard)\n- Git\n\n### Install from PyPI\n\n```bash\npip install spoon-audit\n```\n\n### Install from Source\n\n```bash\ngit clone https://github.com/CodeKage25/smart-audit-assistant.git\ncd smart-audit-assistant\npip install -e .\n```\n\n### Optional Dependencies\n\nFor PDF export functionality:\n```bash\npip install weasyprint\n```\n\n## Quick Start\n\n### 1. Configuration\n\nFirst, configure your API keys and preferences:\n\n```bash\n# View current configuration\nspoon-audit config --show\n\n# Set OpenAI API key (required for AI explanations)\nspoon-audit config --set api_keys.openai \"your-api-key-here\"\n\n# Set LLM provider (default: openai)\nspoon-audit config --set llm_provider \"openai\"\n\n# Set model preference\nspoon-audit config --set model_name \"gpt-4\"\n```\n\n### 2. Scan a Contract\n\n```bash\n# Scan a single Solidity file\nspoon-audit scan ./contracts/MyContract.sol\n\n# Scan with detailed AI explanations\nspoon-audit scan --detailed ./contracts/MyContract.sol\n\n# Scan entire project directory\nspoon-audit scan ./contracts/\n\n# Enable debug mode for detailed output\nspoon-audit scan --debug ./contracts/MyContract.sol\n```\n\n### 3. View Reports\n\n```bash\n# Show the last scan report\nspoon-audit report\n\n# Show detailed report with AI reasoning and suggested fixes\nspoon-audit report --detailed\n\n# Filter by severity level\nspoon-audit report --severity high\n\n# Show only AI findings\nspoon-audit report --ai-only\n```\n\n### 4. Export Professional Reports\n\n```bash\n# Export as HTML (modern, interactive report)\nspoon-audit export --format html\n\n# Export and open in browser\nspoon-audit export --format html --open-browser\n\n# Export as PDF (requires weasyprint)\nspoon-audit export --format pdf\n\n# Export as JSON for CI/CD integration\nspoon-audit export --format json > audit-report.json\n\n# Export as Markdown\nspoon-audit export --format markdown\n```\n\n### 5. Watch Mode\n\nMonitor your contracts during development:\n\n```bash\n# Watch a file and re-scan on changes\nspoon-audit watch ./contracts/MyContract.sol\n\n# Watch entire directory with detailed output\nspoon-audit watch ./contracts/ --detailed\n\n# Watch with custom interval\nspoon-audit watch ./contracts/ --interval 5\n```\n\n## CLI Commands Reference\n\n### `spoon-audit scan`\n\nAnalyze Solidity files or directories for vulnerabilities.\n\n**Options:**\n- `--detailed`: Show comprehensive AI analysis with reasoning and suggested fixes\n- `--output-format`: Report format (console, json, markdown)\n- `--severity`: Minimum severity level (info, low, medium, high, critical)\n- `--exclude`: Patterns to exclude from scanning\n- `--include-dependencies`: Include node_modules and dependencies\n- `--debug`: Enable debug mode with verbose output\n\n**Examples:**\n```bash\n# Comprehensive scan with detailed AI analysis\nspoon-audit scan ./contracts/ --detailed\n\n# High-severity issues only in JSON format\nspoon-audit scan ./contracts/ --output-format json --severity high\n\n# Exclude test files\nspoon-audit scan ./src/ --exclude \"**/test/**\" --include-dependencies\n```\n\n### `spoon-audit report`\n\nDisplay the last scan report with various filtering options.\n\n**Options:**\n- `--detailed`: Show comprehensive analysis with AI reasoning\n- `--severity`: Filter by severity level (info, low, medium, high, critical)\n- `--ai-only`: Show only AI-detected vulnerabilities\n- `--static-only`: Show only static analysis findings\n- `--format`: Output format (console, json, markdown)\n\n**Examples:**\n```bash\n# Detailed report with all AI explanations\nspoon-audit report --detailed\n\n# Only critical and high severity issues\nspoon-audit report --severity high --detailed\n\n# AI findings only with reasoning\nspoon-audit report --ai-only --detailed\n```\n\n### `spoon-audit export`\n\nExport professional audit reports in various formats.\n\n**Options:**\n- `--format`: Export format (html, pdf, json, markdown)\n- `--output, -o`: Output file path\n- `--open-browser`: Open HTML report in browser automatically\n- `--detailed`: Include comprehensive AI analysis in export\n\n**Examples:**\n```bash\n# Professional HTML report with auto-open\nspoon-audit export --format html --open-browser --detailed\n\n# PDF audit report\nspoon-audit export --format pdf -o security_audit.pdf\n\n# JSON for CI/CD integration\nspoon-audit export --format json -o results.json\n```\n\n### `spoon-audit watch`\n\nContinuously monitor files for changes and re-scan automatically.\n\n**Options:**\n- `--detailed`: Show detailed AI analysis on each scan\n- `--interval`: Check interval in seconds (default: 2)\n- `--clear`: Clear screen between scans\n\n**Examples:**\n```bash\n# Watch with detailed analysis\nspoon-audit watch ./contracts/Token.sol --detailed\n\n# Custom interval with screen clearing\nspoon-audit watch ./src/ --interval 5 --clear\n```\n\n### `spoon-audit config`\n\nManage runtime configuration and API keys.\n\n**Options:**\n- `--show`: Display current configuration\n- `--set key value`: Set configuration value\n- `--reset`: Reset to default configuration\n\n**Examples:**\n```bash\nspoon-audit config --show\nspoon-audit config --set model_name \"gpt-4\"\nspoon-audit config --set base_url \"https://api.openai.com/v1\"\nspoon-audit config --set scan_settings.severity_threshold \"high\"\n```\n\n## Configuration\n\nThe tool uses a `config.json` file stored in your home directory (`~/.spoon-audit/config.json`). You can also set environment variables:\n\n```bash\nexport SPOON_AUDIT_OPENAI_API_KEY=\"your-api-key\"\nexport SPOON_AUDIT_LLM_PROVIDER=\"openai\"\nexport SPOON_AUDIT_MODEL_NAME=\"gpt-4\"\n```\n\n### Configuration Schema\n\n```json\n{\n \"api_keys\": {\n \"openai\": \"your-openai-api-key\",\n \"anthropic\": \"your-anthropic-api-key\"\n },\n \"base_url\": \"https://api.openai.com/v1\",\n \"default_agent\": \"default\",\n \"llm_provider\": \"openai\",\n \"model_name\": \"gpt-4\",\n \"scan_settings\": {\n \"include_dependencies\": false,\n \"severity_threshold\": \"medium\",\n \"output_format\": \"console\",\n \"detailed_by_default\": false\n }\n}\n```\n\n## Report Formats\n\n### Console Output\n- Color-coded severity levels\n- Detailed AI explanations with `--detailed` flag\n- Clean, readable formatting for terminal use\n\n### HTML Export\n- **Modern Design**: Professional gradient styling and responsive layout\n- **Interactive Features**: Table of contents, print button, smooth scrolling\n- **Comprehensive**: Includes all findings with AI reasoning and suggestions\n- **Mobile-Friendly**: Responsive design for all devices\n\n### PDF Export\n- **Professional Layout**: Print-ready audit reports\n- **Complete Analysis**: All vulnerabilities with detailed explanations\n- **Requires**: `weasyprint` package (`pip install weasyprint`)\n\n### JSON Export\n- **Structured Data**: Perfect for CI/CD integration and automated processing\n- **Complete Information**: All findings with metadata and confidence scores\n- **API Integration**: Easy to parse and integrate with other tools\n\n## Project Structure\n\n```\nsmart-audit-assistant/\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 .env.example\n\u251c\u2500\u2500 cli/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 main.py # CLI entry point with enhanced reporting\n\u251c\u2500\u2500 analysis/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 parser.py # Solidity AST parsing\n\u2502 \u251c\u2500\u2500 static_scanner.py # Static analysis integration\n\u2502 \u2514\u2500\u2500 ai_analyzer.py # SpoonOS AI analysis with reasoning\n\u251c\u2500\u2500 reports/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 exporters.py # HTML, PDF, JSON, Markdown exporters\n\u2502 \u2514\u2500\u2500 templates/ # Professional report templates\n\u251c\u2500\u2500 extension/ # VS Code extension\n\u2502 \u251c\u2500\u2500 package.json\n\u2502 \u251c\u2500\u2500 src/\n\u2502 \u2502 \u2514\u2500\u2500 extension.ts\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 web-dashboard/ # Next.js web interface\n\u2502 \u251c\u2500\u2500 package.json\n\u2502 \u251c\u2500\u2500 src/\n\u2502 \u2502 \u251c\u2500\u2500 app/\n\u2502 \u2502 \u2514\u2500\u2500 components/\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_parser.py\n\u2502 \u251c\u2500\u2500 test_static_scanner.py\n\u2502 \u251c\u2500\u2500 test_ai_analyzer.py\n\u2502 \u2514\u2500\u2500 test_exporters.py\n\u2514\u2500\u2500 docs/\n \u2514\u2500\u2500 architecture.md\n```\n\n## Architecture\n\nThe tool follows a modular architecture with enhanced AI analysis and professional reporting:\n\n```mermaid\nflowchart TD\n subgraph INGESTION\n A[Solidity Code] --> B[Parser]\n B --> C[AST]\n C --> D[Static Scanner]\n D --> D1[Slither]\n D --> D2[Mythril]\n D --> D3[Solhint]\n end\n\n subgraph AI_ANALYSIS\n D --> E[SpoonOS Agent]\n E --> F[Vector DB]\n E --> G[OpenAI/Anthropic]\n F & G --> H[Detailed Explanations]\n H --> H1[Reasoning]\n H --> H2[Suggested Fixes]\n H --> H3[Confidence Scores]\n end\n\n subgraph REPORTING\n H --> I[Report Engine]\n I --> I1[Console Output]\n I --> I2[HTML Export]\n I --> I3[PDF Export]\n I --> I4[JSON Export]\n I --> I5[Markdown Export]\n end\n\n subgraph INTEGRATIONS\n I --> J[CLI Interface]\n I --> K[VS Code Extension]\n I --> L[Web Dashboard]\n I --> M[CI/CD Pipeline]\n end\n```\n\n## AI Analysis Features\n\nThe SpoonOS-powered AI analysis provides:\n\n- **Detailed Reasoning**: Explains why each vulnerability is problematic\n- **Suggested Fixes**: Specific code changes to resolve issues\n- **Confidence Scores**: AI certainty levels for each finding\n- **Context Awareness**: Understands contract patterns and business logic\n- **Natural Language**: Clear explanations for developers of all levels\n\n## VS Code Extension\n\nInstall the VS Code extension for inline diagnostics and quick fixes:\n\n1. Open VS Code\n2. Go to Extensions (Ctrl+Shift+X)\n3. Search for \"Spoon Audit\"\n4. Install and reload\n\nFeatures:\n- Real-time vulnerability highlighting\n- Hover tooltips with AI explanations\n- Quick-fix suggestions with reasoning\n- Integrated with CLI backend\n\n## Web Dashboard\n\nLaunch the web dashboard for project management and interactive tutorials:\n\n```bash\ncd web-dashboard\nnpm install\nnpm run dev\n```\n\nVisit `http://localhost:3000` to access:\n- Project scan history with detailed reports\n- Interactive vulnerability tutorials\n- Team collaboration features\n- Professional report generation\n- Detailed analytics and trends\n\n## CI/CD Integration\n\n### GitHub Actions\n\nAdd to `.github/workflows/audit.yml`:\n\n```yaml\nname: Smart Contract Audit\non: [push, pull_request]\n\njobs:\n audit:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - uses: actions/setup-python@v4\n with:\n python-version: '3.10'\n - name: Install spoon-audit\n run: pip install spoon-audit\n - name: Run comprehensive audit\n run: |\n spoon-audit scan ./contracts/ --detailed\n spoon-audit export --format json -o audit-results.json\n env:\n SPOON_AUDIT_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}\n - name: Upload audit results\n uses: actions/upload-artifact@v3\n with:\n name: audit-results\n path: audit-results.json\n```\n\n### Git Hooks\n\nSet up pre-commit hooks:\n\n```bash\n# Install pre-commit\npip install pre-commit\n\n# Add to .pre-commit-config.yaml\nrepos:\n - repo: local\n hooks:\n - id: spoon-audit\n name: Smart Contract Audit\n entry: spoon-audit scan\n language: system\n files: \\.sol$\n args: [--severity, high, --detailed]\n```\n\n## Supported Vulnerabilities\n\nThe tool detects and provides AI-powered explanations for:\n\n### Critical Issues\n- **Reentrancy attacks** - Complete analysis with attack vectors and fixes\n- **Access control bypasses** - Detailed explanation of privilege escalation risks\n- **Integer overflow/underflow** - Context-aware detection with SafeMath recommendations\n\n### High-Risk Issues\n- **Unchecked external calls** - Analysis of failure handling and return value checks\n- **Timestamp dependence** - Explanation of miner manipulation risks\n- **Front-running vulnerabilities** - MEV risks and mitigation strategies\n\n### Medium-Risk Issues\n- **Gas optimization opportunities** - Detailed gas usage analysis\n- **Logic errors** - Business logic vulnerabilities and edge cases\n- **State inconsistencies** - Contract state management issues\n\n### Low-Risk Issues\n- **Code quality improvements** - Best practices and maintainability suggestions\n- **Documentation gaps** - Missing NatSpec and comment recommendations\n\n## Development\n\n### Setting up Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/CodeKage25/smart-audit-assistant.git\ncd smart-audit-assistant\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Install optional PDF support\npip install weasyprint\n\n# Run tests\npytest tests/\n\n# Run with debug mode\nspoon-audit scan --debug --detailed ./examples/vulnerable-contract.sol\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=analysis --cov=cli --cov=reports\n\n# Run specific test categories\npytest tests/test_static_scanner.py\npytest tests/test_exporters.py\npytest tests/test_ai_analyzer.py\n```\n\n## Usage Examples\n\n### Basic Workflow\n```bash\n# 1. Scan your contracts\nspoon-audit scan ./contracts/ --detailed\n\n# 2. Review findings in detail\nspoon-audit report --detailed --severity medium\n\n# 3. Export professional report\nspoon-audit export --format html --open-browser\n\n# 4. Fix issues and re-scan\nspoon-audit watch ./contracts/ --detailed\n```\n\n### Advanced Usage\n```bash\n# Comprehensive security audit with PDF export\nspoon-audit scan ./contracts/ --detailed --severity low\nspoon-audit export --format pdf -o comprehensive_audit.pdf\n\n# CI/CD integration\nspoon-audit scan ./src/ --detailed --output-format json > results.json\nspoon-audit export --format markdown -o SECURITY_REPORT.md\n\n# Development workflow with continuous monitoring\nspoon-audit watch ./contracts/ --detailed --clear --interval 3\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/enhanced-analysis`)\n3. Commit your changes (`git commit -m 'Add enhanced AI analysis'`)\n4. Push to the branch (`git push origin feature/enhanced-analysis`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [docs.spoon-audit.com](https://docs.spoon-audit.com)\n- **Issues**: [GitHub Issues](https://github.com/CodeKage25/smart-audit-assistant/issues)\n- **Discord**: [SpoonOS Community](https://discord.gg/spoonos)\n- **Email**: team@secureaudit.xyz\n\n## Changelog\n\n### Latest Updates\n- \u2705 **Enhanced AI Analysis**: Complete reasoning and suggested fixes now display properly\n- \u2705 **Professional Reports**: Beautiful HTML and PDF export with modern design\n- \u2705 **Interactive Features**: Auto-open browser, table of contents, mobile-responsive design\n- \u2705 **Comprehensive CLI**: Detailed reporting options with filtering and export capabilities\n- \u2705 **Improved Configuration**: Better API key management and settings\n\n## Acknowledgments\n\n- Built with [SpoonOS Agent Framework](https://spoonai.io/)\n- Powered by [OpenAI GPT-4](https://openai.com) and [Anthropic Claude](https://anthropic.com)\n- Static analysis by [Slither](https://github.com/crytic/slither), [Mythril](https://github.com/ConsenSys/mythril), and [Solhint](https://github.com/protofire/solhint)\n- PDF generation by [WeasyPrint](https://weasyprint.org)\n- Special thanks to the Web3 security community\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI-powered smart contract audit assistant with SpoonOS integration",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/CodeKage25/spoon-audit/issues",
"Homepage": "https://github.com/CodeKage25/spoon-audit",
"Source": "https://github.com/CodeKage25/spoon-audit"
},
"split_keywords": [
"solidity",
" smart-contracts",
" audit",
" security",
" blockchain"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb26e6e4bca41edfc893fac74cfc4585d317d72142bb51e70f3a3ba317a3f1ed",
"md5": "3df770edc96c1492886f5effe1308393",
"sha256": "28c41e432f114440bd1808f0cecdc7f80967a13c452e0947911e4821ab7813b2"
},
"downloads": -1,
"filename": "spoon_audit-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3df770edc96c1492886f5effe1308393",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 46127,
"upload_time": "2025-08-06T16:34:52",
"upload_time_iso_8601": "2025-08-06T16:34:52.661416Z",
"url": "https://files.pythonhosted.org/packages/eb/26/e6e4bca41edfc893fac74cfc4585d317d72142bb51e70f3a3ba317a3f1ed/spoon_audit-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6654d4ab02395319b48768a9316de34d4cbd85e5e66c8a3dad5513b9194bb230",
"md5": "569db1d9362ff28a8abdfef1f3b59083",
"sha256": "e5498dedaee3de03ff8d6a89758172eae7d58df2d1cba615dbed4fdaf8d34c90"
},
"downloads": -1,
"filename": "spoon_audit-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "569db1d9362ff28a8abdfef1f3b59083",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50506,
"upload_time": "2025-08-06T16:34:54",
"upload_time_iso_8601": "2025-08-06T16:34:54.104480Z",
"url": "https://files.pythonhosted.org/packages/66/54/d4ab02395319b48768a9316de34d4cbd85e5e66c8a3dad5513b9194bb230/spoon_audit-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 16:34:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CodeKage25",
"github_project": "spoon-audit",
"github_not_found": true,
"lcname": "spoon-audit"
}
JSON
