diff --git a/README.md b/README.md index 79cf21d..f10d48e 100644 --- a/README.md +++ b/README.md @@ -1,346 +1,33 @@ # AI Code Audit CLI -A CLI tool that validates AI-generated code for common issues, anti-patterns, and security vulnerabilities. It analyzes code produced by AI assistants (like GitHub Copilot, Claude Code, etc.) and generates quality reports with improvement suggestions and confidence scores. - -![CI Status](https://7000pct.gitea.bloupla.net/api/badges/7000pctAUTO/ai-code-audit-cli/status.svg) -![Python Version](https://img.shields.io/badge/python-3.9%2B-blue) -![License](https://img.shields.io/badge/License-MIT-green) +A CLI tool for scanning code and auditing for issues using AI. ## Features -- **Security Vulnerability Detection**: Detect hardcoded secrets, SQL injection risks, command injection, and other security issues -- **Code Smell Detection**: Identify code smells like unused imports, mutable defaults, complex functions, and poor error handling -- **Multi-language Support**: Analyze Python, JavaScript, and TypeScript code -- **Confidence Scoring**: Get a 0-100 score reflecting code quality and security posture -- **Multiple Output Formats**: Terminal output with Rich formatting, JSON, and Markdown export options -- **Severity-based Filtering**: Filter issues by severity level (critical, high, medium, low, info) +- Scan Python, JavaScript, and TypeScript files +- Multiple output formats (terminal, JSON, markdown) +- Severity-based filtering +- Confidence scoring for results ## Installation -### From Source - -```bash -git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/ai-code-audit-cli.git -cd ai-code-audit-cli -pip install -e . -``` - -### Using pip - ```bash pip install ai-code-audit-cli ``` -## Quick Start - -```bash -# Audit a single file -audit scan path/to/file.py - -# Audit a directory recursively -audit scan path/to/project/ - -# Audit with JSON output -audit scan path/to/code/ --format json - -# Audit with verbose output -audit scan path/to/code/ --verbose - -# Filter by language -audit scan path/to/code/ --language python - -# Filter by severity -audit scan path/to/code/ --severity high -``` - ## Usage -### Basic Scanning - ```bash -# Scan a Python file -audit scan my_script.py - -# Scan a JavaScript file -audit scan index.js - -# Scan a TypeScript file -audit scan app.ts - -# Scan a directory -audit scan src/ -``` - -### Output Options - -```bash -# Rich terminal output (default) -audit scan path/to/code/ - -# JSON output for CI/CD -audit scan path/to/code/ --format json - -# Markdown report -audit scan path/to/code/ --format markdown - -# Quiet mode (minimal output) -audit scan path/to/code/ --quiet -``` - -### Filtering Options - -```bash -# Only scan Python files -audit scan path/to/code/ --language python - -# Only show critical and high severity issues -audit scan path/to/code/ --severity critical high - -# Skip color output -audit scan path/to/code/ --no-color - -# Verbose output with more details -audit scan path/to/code/ --verbose +audit scan [--format terminal|json|markdown] [--severity low|medium|high|critical] ``` ## Configuration -### Audit Configuration File - -Create an `audit.toml` file in your project root: - -```toml -[severity] -critical = true -high = true -medium = true -low = true -info = false - -[languages] -python = true -javascript = true -typescript = true - -[scanners] -bandit = true -ruff = true -tree_sitter = true - -[confidence] -min_score = 70 +Create a `.env` file with: ``` - -### PyProject.toml Integration - -The tool automatically reads Ruff configuration from your `pyproject.toml`: - -```toml -[tool.ruff] -line-length = 88 -select = ["E", "F", "W", "C90", "I", "N", "UP", "B", "SIM"] -ignore = ["E501"] - -[tool.ruff.per-file-ignores] -"__init__.py" = ["F401"] -``` - -## Output Formats - -### Terminal Output - -The default terminal output uses Rich formatting to display: - -``` - AI Code Audit Report - - Summary: - ┌─────────────────────────────────────────────┐ - │ Files Scanned │ 15 │ - │ Issues Found │ 23 │ - │ Confidence Score │ 78 │ - └─────────────────────────────────────────────┘ - - Issues by Severity: - ├─ Critical: 2 - ├─ High: 5 - ├─ Medium: 8 - ├─ Low: 6 - └─ Info: 2 -``` - -### JSON Output - -```json -{ - "summary": { - "files_scanned": 15, - "total_issues": 23, - "confidence_score": 78 - }, - "issues": [ - { - "id": "B001", - "severity": "high", - "category": "security", - "message": "Possible hardcoded password detected", - "file": "src/auth.py", - "line": 42 - } - ] -} -``` - -### Markdown Output - -```markdown -# AI Code Audit Report - -## Summary - -| Metric | Value | -|--------|-------| -| Files Scanned | 15 | -| Issues Found | 23 | -| Confidence Score | 78 | - -## Issues - -### Critical - -| File | Line | Issue | -|------|------|-------| -| src/auth.py | 42 | Possible hardcoded password | -``` - -## Confidence Score - -The confidence score (0-100) reflects the overall quality and security posture of the analyzed code: - -- **90-100**: Excellent - Code is well-structured and secure -- **70-89**: Good - Minor issues found, generally safe to use -- **50-69**: Moderate - Several issues, review recommended -- **30-49**: Poor - Significant issues, refactoring advised -- **0-29**: Critical - Major problems, do not deploy - -### Score Calculation - -The score is calculated based on: - -1. **Security Issues (40% weight)**: Critical issues have highest impact -2. **Code Smells (30% weight)**: Anti-patterns and poor practices -3. **Complexity (20% weight)**: Function complexity and file size -4. **Error Handling (10% weight)**: Missing exception handling - -## Supported Languages - -| Language | Security Scanning | Linting | Pattern Detection | -|----------|------------------|---------|-------------------| -| Python | ✅ Bandit | ✅ Ruff | ✅ Tree-sitter | -| JavaScript | ⚠️ Basic | ✅ Ruff | ✅ Tree-sitter | -| TypeScript | ⚠️ Basic | ✅ Ruff | ✅ Tree-sitter | - -## Scanner Details - -### Bandit Scanner - -Detects common security issues in Python code: - -- Hardcoded passwords and secrets -- SQL injection vulnerabilities -- Command injection risks -- Insecure cryptographic usage -- Path traversal issues - -### Ruff Scanner - -Fast linting for code quality: - -- PEP 8 compliance -- Import sorting -- Code complexity -- Anti-patterns -- Unused code - -### Tree-sitter Scanner - -Multi-language pattern detection: - -- API key and credential patterns -- SQL injection patterns -- Dangerous function usage -- Deprecated API calls - -## API Usage - -### Python API - -```python -from src.core.scanner import Scanner -from src.reporting.confidence import ConfidenceScorer - -# Initialize scanner -scanner = Scanner() - -# Scan a directory -results = scanner.scan_directory("path/to/code") - -# Calculate confidence score -scorer = ConfidenceScorer() -score = scorer.calculate(results) - -# Print results -scanner.print_report(results) -``` - -### Custom Configuration - -```python -from src.core.config import AuditConfig - -config = AuditConfig( - severity_filter={"critical", "high", "medium"}, - language_filter={"python"}, - scanners={"bandit", "ruff"} -) - -scanner = Scanner(config=config) -results = scanner.scan("path/to/code") -``` - -## Contributing - -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request - -### Development Setup - -```bash -git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/ai-code-audit-cli.git -cd ai-code-audit-cli -pip install -e ".[dev]" - -# Run tests -pytest tests/ -v --cov=src - -# Run linting -ruff check . - -# Type checking -mypy src/ +OPENAI_API_KEY=your_api_key ``` ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. - -## Acknowledgments - -- [Bandit](https://bandit.readthedocs.io/) for Python security scanning -- [Ruff](https://github.com/astral-sh/ruff) for fast linting -- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) for code parsing -- [Typer](https://typer.tiangolo.com/) for CLI interface -- [Rich](https://rich.readthedocs.io/) for beautiful terminal output +MIT