Metadata-Version: 2.4
Name: codesentin3l
Version: 3.2.0
Summary: AI Code Review & Security Assistant — Powered by loopy-agent
Author-email: Dream Pixels Forge <patrick@dreampixelsforge.com>
License: MIT
Project-URL: Homepage, https://github.com/Dream-Pixels-Forge/codesentin3l
Project-URL: Documentation, https://github.com/Dream-Pixels-Forge/codesentin3l#readme
Project-URL: Repository, https://github.com/Dream-Pixels-Forge/codesentin3l
Project-URL: Issues, https://github.com/Dream-Pixels-Forge/codesentin3l/issues
Project-URL: Changelog, https://github.com/Dream-Pixels-Forge/codesentin3l/blob/main/CHANGELOG.md
Keywords: security,code-review,ai,llm,prompt-injection,vulnerability-scanner
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: loopy-agent>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: tui
Requires-Dist: textual>=0.40; extra == "tui"
Requires-Dist: rich>=13.0; extra == "tui"

# 🛡️ CodeSentinel

**AI Code Review & Security Assistant** — Powered by [loopy-agent](https://github.com/Dream-Pixels-Forge/loopy-agent)

![Python](https://img.shields.io/badge/Python-3.10+-blue)
![License](https://img.shields.io/badge/License-MIT-green)

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🔒 **Security Scanner** | Pattern-based detection for 12+ vulnerability types |
| 🤖 **AI Code Review** | Maker/checker verification for accurate reviews |
| 📊 **Risk Scoring** | Prioritized findings by severity |
| 📁 **Repo Scanning** | Batch scan entire repositories |
| 🔗 **GitHub Integration** | Auto-review PRs and post comments |
| 🌐 **MCP Server** | Expose as tool for AI assistants |
| 📄 **Report Export** | HTML, JSON, Markdown, SARIF formats |
| 💾 **Caching** | Reduces API costs on repeated reviews |

---

## 🚀 Quick Start

```bash
# Install
pip install codesentin3l

# Or clone and install
git clone https://github.com/Dream-Pixels-Forge/codesentin3l
cd codesentinel
pip install -e .
```

---

## 📖 Usage

### CLI Commands

```bash
# Security scan (no API key needed)
codesentin3l scan myfile.py

# AI-powered review
export OPENAI_API_KEY="sk-..."
codesentin3l review myfile.py

# Full scan + review
codesentin3l full myfile.py

# Scan entire repository
codesentin3l repo ./my-project

# Review a git diff
codesentin3l pr changes.diff

# Start MCP server
codesentin3l mcp

# Run demo
codesentin3l demo
```

### CLI Options

```bash
--provider openai|anthropic    # LLM provider (default: openai)
--model gpt-4|claude-3-opus   # Model (default: gpt-4)
--output <dir>                 # Output directory for reports
--format html|markdown|json    # Report format
```

---

## 🐍 Python API

### Quick Review

```python
import asyncio
from src import CodeReviewer

async def main():
    reviewer = CodeReviewer(provider="openai", model="gpt-4")
    result = await reviewer.review_file("my_code.py")
    reviewer.print_report(result)
    await reviewer.close()

asyncio.run(main())
```

### Security Scan

```python
from src import SecurityScanner

scanner = SecurityScanner()
findings = scanner.scan_file("my_code.py")
scanner.print_findings(findings)

risk_score = scanner.get_risk_score(findings)
```

### Repo Scanning

```python
from src import RepoScanner

scanner = RepoScanner()
summary = scanner.scan_repo("./my-project")
scanner.print_summary(summary)
```

### Report Generation

```python
from src import ReportGenerator, ReportConfig, ReportFormat

config = ReportConfig(
    format=ReportFormat.HTML,
    output_dir="./reports",
)
generator = ReportGenerator(config)
content = generator.generate(review=result, security_findings=findings)
path = generator.save(content, "my-review")
```

---

## 🌐 MCP Server

Start the MCP server to expose CodeSentinel as tools:

```bash
codesentin3l mcp
```

### Available Tools

| Tool | Description |
|------|-------------|
| `codesentinel_scan` | Scan code for security issues |
| `codesentinel_review` | AI-powered code review |
| `codesentinel_full` | Full scan + review combined |
| `codesentinel_scan_file` | Scan a file from disk |

### Using with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "codesentin3l": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/codesentinel"
    }
  }
}
```

---

## 🔗 GitHub Integration

### Review a PR

```python
from src import GitHubIntegration

async def main():
    gh = GitHubIntegration(token="ghp_...")
    review = await gh.review_pr("owner", "repo", pr_number=123)
    print(review.summary)
    print(f"Approved: {review.approved}")

asyncio.run(main())
```

### Post Review Comment

```python
review = await gh.review_pr("owner", "repo", 123, post_comment=True)
```

---

## 🔒 Security Patterns Detected

| Pattern | Severity | Description |
|---------|----------|-------------|
| SQL Injection | 🔴 Critical | String formatting in queries |
| Command Injection | 🔴 Critical | os.system, eval, exec |
| Hardcoded Secrets | 🔴 Critical | API keys, passwords in code |
| Private Keys | 🔴 Critical | Embedded private keys |
| Weak Hashing | 🟠 High | MD5, SHA1 for passwords |
| XSS Risk | 🟠 High | innerHTML, dangerouslySetInnerHTML |
| Path Traversal | 🟠 High | Unsanitized file paths |
| Insecure Random | 🟡 Medium | random module for security |
| Debug Enabled | 🟡 Medium | DEBUG=True in production |
| CORS Wildcard | 🟡 Medium | Access-Control-Allow-Origin: * |
| Weak Crypto | 🟠 High | ECB mode, DES, RC4 |

---

## 📊 Report Formats

| Format | Use Case |
|--------|----------|
| **HTML** | Visual reports, CI dashboards |
| **JSON** | Machine parsing, integrations |
| **Markdown** | GitHub, documentation |
| **SARIF** | GitHub Code Scanning |

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    CodeSentinel                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐ │
│  │   Security  │    │     AI      │    │   GitHub    │ │
│  │   Scanner   │    │   Reviewer  │    │ Integration │ │
│  │  (patterns) │    │  (loopy)    │    │   (PRs)     │ │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘ │
│         │                  │                  │         │
│         └──────────────────┼──────────────────┘         │
│                            │                            │
│                    ┌───────▼───────┐                    │
│                    │    Reporter   │                    │
│                    │ HTML/JSON/MD  │                    │
│                    └───────────────┘                    │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                   loopy-agent                           │
│  ┌──────────┬──────────┬──────────┬──────────┐         │
│  │   loop   │ gateway  │ verification│  cache  │         │
│  └──────────┴──────────┴──────────┴──────────┘         │
└─────────────────────────────────────────────────────────┘
```

---

## 🧪 Examples

See the `examples/` directory:
- `vulnerable_app.py` — Code with intentional security issues
- `clean_app.py` — Secure coding best practices

---

## 📝 License

MIT

---

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

---

*Built with ❤️ using [loopy-agent](https://github.com/Dream-Pixels-Forge/loopy-agent)*
