Initial upload of ai-code-audit-cli project
This commit is contained in:
347
README.md
347
README.md
@@ -1,3 +1,346 @@
|
||||
# ai-code-audit-cli
|
||||
# AI Code Audit CLI
|
||||
|
||||
A CLI tool that validates AI-generated code for common issues, anti-patterns, and security vulnerabilities
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## 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)
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### 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/
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
Reference in New Issue
Block a user