Hiddenden/openrabbit
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity

remove documentation that are no longer needed

Browse Source
This commit is contained in:
Latte
2026-01-16 11:15:51 +00:00
parent e8d28225e0
commit b24ae0dcda
8 changed files with 0 additions and 1517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
MILESTONE_2_STATUS.md
View File

@@ -1,287 +0,0 @@
# Milestone 2 - Documentation & Deployment Status
**Date:** 2025-12-29
**Status:** ✅ COMPLETE - Ready for Merge
---
## Executive Summary
All three Milestone 2 features have been fully implemented, tested, and documented. Documentation verification confirms 100% completion of all required items. The features are ready for merging to main branch and production deployment.
---
## Feature Implementation Status
### 1. PR Summary Generator (`@codebot summarize`)
**Branch:** `feature/pr-summary-generator` (merged to dev)
**Status:** ✅ Complete
**Implementation:**
- ✅ Prompt template: `tools/ai-review/prompts/pr_summary.md`
- ✅ PR Agent methods: `_generate_pr_summary()`, `_format_pr_summary()`
- ✅ Auto-summary on empty PRs (configurable)
- ✅ Manual trigger via `@codebot summarize` command
- ✅ Config: `agents.pr.auto_summary` settings
**Testing:**
- ✅ TestPRSummaryGeneration class - 10 tests
- ✅ Prompt formatting validation
- ✅ Command detection (case-insensitive)
- ✅ PR vs Issue distinction
- ✅ Output structure validation
**Documentation:**
- ✅ README.md - User guide with examples
- ✅ CLAUDE.md - Developer implementation guide
- ✅ Workflow routing configured
---
### 2. PR Changelog Generator (`@codebot changelog`)
**Branch:** `feature/pr-changelog-generator` (merged to dev)
**Status:** ✅ Complete
**Implementation:**
- ✅ Prompt template: `tools/ai-review/prompts/changelog.md`
- ✅ PR Agent methods: `_handle_changelog_command()`, `_format_changelog()`
- ✅ Keep a Changelog format output
- ✅ Breaking changes detection
- ✅ Manual trigger only (no auto-generation)
**Testing:**
- ✅ TestChangelogGeneration class - 9 tests
- ✅ Prompt formatting validation
- ✅ Command detection (case-insensitive)
- ✅ PR-only validation
- ✅ Empty section handling
**Documentation:**
- ✅ README.md - User guide with Keep a Changelog example
- ✅ CLAUDE.md - Developer implementation guide
- ✅ Workflow routing configured
---
### 3. Code Diff Explainer (`@codebot explain-diff`)
**Branch:** `feature/code-diff-explainer` (merged to dev)
**Status:** ✅ Complete
**Implementation:**
- ✅ Prompt template: `tools/ai-review/prompts/explain_diff.md`
- ✅ PR Agent methods: `_handle_explain_diff_command()`, `_format_diff_explanation()`
- ✅ Plain-language translation engine
- ✅ Architecture impact analysis
- ✅ Breaking changes detection
**Testing:**
- ✅ TestDiffExplanation class - 9 tests
- ✅ Prompt formatting validation
- ✅ Command detection (case-insensitive)
- ✅ PR-only validation
- ✅ Empty section handling
**Documentation:**
- ✅ README.md - User guide with plain-language examples
- ✅ CLAUDE.md - Developer implementation guide with translation rules
- ✅ Workflow routing configured
---
## Documentation Verification Results
### User Documentation (README.md)
✅ **Complete** - All features documented:
| Section | Status | Location |
|---------|--------|----------|
| Feature table | ✅ Complete | Lines 11-15 |
| Command reference | ✅ Complete | Lines 182-196 |
| PR Summary section | ✅ Complete | Lines 198-237 |
| Changelog section | ✅ Complete | Lines 238-284 |
| Diff Explainer section | ✅ Complete | Lines 285-331 |
**Features Included:**
- Features, benefits, and use cases
- Example outputs for each command
- When to use guidance
- Integration with existing commands
### Developer Documentation (CLAUDE.md)
✅ **Complete** - All implementation details documented:
| Section | Status | Location |
|---------|--------|----------|
| PR Summary Generation | ✅ Complete | Line 420 |
| PR Changelog Generation | ✅ Complete | Line 473 |
| Code Diff Explainer | ✅ Complete | Line 537 |
| Workflow Routing | ✅ Complete | Lines 79-110 |
| Prompt Templates | ✅ Complete | Lines 112-124 |
**Content Includes:**
- Architecture overview
- Implementation details
- JSON structure examples
- Prompt engineering guidelines
- Common use cases
- Workflow safety notes
### Configuration Documentation
✅ **Complete** - `config.yml` properly configured:
```yaml
interaction:
commands:
- summarize # ✅ Documented
- changelog # ✅ Documented
- explain-diff # ✅ Documented
agents:
pr:
auto_summary:
enabled: true
post_as_comment: true
```
---
## Workflow Routing Verification
### Critical Fix: Workflow Duplication Prevention
✅ **Fixed** - All workflows are mutually exclusive to prevent 10+ duplicate runs
**ai-comment-reply.yml:**
- Handles ONLY specific commands: `help`, `explain`, `suggest`, `security`, `summarize`, `changelog`, `explain-diff`, `review-again`, `setup-labels`
- ✅ Includes all three Milestone 2 commands
**ai-chat.yml:**
- Handles free-form questions (fallback)
- ✅ Excludes all specific commands including `summarize`, `changelog`, `explain-diff`
**ai-issue-triage.yml:**
- Handles ONLY `@codebot triage` command
- ✅ No conflicts with Milestone 2 features
**Result:** Each `@codebot` command triggers exactly ONE workflow (no duplicates).
---
## Testing Status
### Unit Tests
✅ **Complete** - 28 new tests added (54 total in test suite)
| Test Class | Tests | Coverage |
|------------|-------|----------|
| TestPRSummaryGeneration | 10 | ✅ Prompt, formatting, detection, output |
| TestChangelogGeneration | 9 | ✅ Prompt, formatting, detection, output |
| TestDiffExplanation | 9 | ✅ Prompt, formatting, detection, output |
**Test Coverage:**
- ✅ Prompt file existence
- ✅ Prompt formatting (double curly braces for JSON)
- ✅ Command detection (case-insensitive)
- ✅ PR vs Issue distinction
- ✅ Output structure validation
- ✅ Empty section handling
- ✅ Config validation
### Integration Testing
⚠️ **Pending** - Requires manual testing in live environment
**Recommended Tests:**
1. Create a PR and test `@codebot summarize`
2. Test `@codebot changelog` on a PR with mixed changes
3. Test `@codebot explain-diff` on a PR with technical changes
4. Verify no workflow duplication occurs
---
## Deployment Readiness
### Pre-Deployment Checklist
- ✅ All features implemented and merged to dev
- ✅ All documentation complete (README.md + CLAUDE.md)
- ✅ Configuration files updated
- ✅ Workflow routing verified (no duplicates)
- ✅ Unit tests complete (28 new tests)
- ✅ Prompt templates created and validated
- ⚠️ Manual integration testing pending
- ⚠️ Final merge to main pending
### Deployment Steps
**1. Manual testing on dev branch:**
- Test each command in a live PR
- Verify no workflow duplication
- Validate output formatting
**2. Merge to main:**
```bash
git checkout main
git merge dev
git push origin main
```
**3. Team communication:**
- Announce new features with examples
- Update team documentation
- Gather feedback
---
## Files Modified/Created
### New Prompt Templates (3)
- `tools/ai-review/prompts/pr_summary.md`
- `tools/ai-review/prompts/changelog.md`
- `tools/ai-review/prompts/explain_diff.md`
### Modified Files
- `tools/ai-review/agents/pr_agent.py` - Added 6 new methods
- `tools/ai-review/config.yml` - Added commands and auto_summary config
- `.gitea/workflows/ai-comment-reply.yml` - Added 3 commands to routing
- `.gitea/workflows/ai-chat.yml` - Excluded 3 commands from routing
- `README.md` - Added 3 feature sections with examples
- `CLAUDE.md` - Added 3 implementation guides
- `tests/test_ai_review.py` - Added 28 new tests in 3 test classes
---
## Known Issues
**None** - All features are working as designed.
---
## Recommendations
### Priority: High
1. ⚠️ **Manual integration testing** - Test in live environment before main merge
2. ⚠️ **Team announcement** - Communicate new features to team
### Priority: Medium
3. Monitor API usage after deployment (new commands will increase LLM calls)
4. Gather user feedback on plain-language explanations
5. Consider adding video demos/GIFs for each feature
### Priority: Low
6. Performance testing under load (multiple simultaneous requests)
7. Security review of prompt injection risks
8. A/B testing for prompt effectiveness
---
## Conclusion
**Milestone 2 is 100% complete and ready for deployment.**
All three features are fully implemented, thoroughly tested, and comprehensively documented. The workflow routing issue that was causing 10+ duplicate runs has been resolved. The codebase is in a production-ready state.
**Next Action:** Manual integration testing on dev branch before final production deployment to main.
---
**Verified by:** Claude Code (Automated Documentation Review)
**Verification Date:** 2025-12-29
**Status:** All features merged to dev branch and ready for production

378
SECURITY_FIXES_SUMMARY.md
View File

@@ -1,378 +0,0 @@
# Security Fixes Summary
This document summarizes the security improvements made to OpenRabbit in response to the AI code review findings.
## Date
2025-12-28
## Issues Fixed
### HIGH Severity Issues (1 Fixed)
#### 1. Full Issue and Comment JSON Data Exposed in Environment Variables
**File**: `.gitea/workflows/ai-comment-reply.yml:40`
**Problem**:
Full issue and comment JSON data were passed as environment variables (`EVENT_ISSUE_JSON`, `EVENT_COMMENT_JSON`), which could expose sensitive information (emails, private data, tokens) in logs or environment dumps.
**Fix**:
- Removed full webhook data from environment variables
- Created minimal event payload with only essential fields (issue number, comment body)
- Implemented `utils/safe_dispatch.py` for secure event processing
- Created `utils/webhook_sanitizer.py` with data sanitization utilities
**Impact**: Prevents sensitive user data from being exposed in CI/CD logs and environment variables.
---
### MEDIUM Severity Issues (4 Fixed)
#### 1. Boolean String Comparison Issues
**File**: `.gitea/workflows/ai-comment-reply.yml:44`
**Problem**:
Check for PR used string comparison on `IS_PR` environment variable which could cause unexpected behavior.
**Fix**:
- Moved boolean expression directly into shell script: `IS_PR="${{ gitea.event.issue.pull_request != null }}"`
- Added validation to ensure variable is set before use
#### 2. Complex Inline Python Script
**File**: `.gitea/workflows/ai-comment-reply.yml:47`
**Problem**:
Inline Python script embedded in shell script mixed multiple responsibilities (JSON parsing, dispatcher setup, agent registration).
**Fix**:
- Extracted to separate module: `tools/ai-review/utils/safe_dispatch.py`
- Separated concerns: validation, sanitization, and dispatch
- Added comprehensive error handling and logging
- Made code testable and reusable
#### 3. No Input Validation or Sanitization
**File**: `.gitea/workflows/ai-comment-reply.yml:47`
**Problem**:
Inline Python code didn't validate or sanitize loaded JSON data before dispatching.
**Fix**:
- Created `utils/webhook_sanitizer.py` with three key functions:
- `sanitize_webhook_data()` - Removes sensitive fields (emails, tokens, secrets)
- `validate_repository_format()` - Validates and sanitizes repo names (prevents path traversal, shell injection)
- `extract_minimal_context()` - Extracts only necessary fields from webhooks
- Added size limits (10MB max event size)
- Added JSON validation
#### 4. Repository String Split Without Validation
**File**: `.gitea/workflows/ai-comment-reply.yml:54`
**Problem**:
Repository string was split into owner and repo_name without validation.
**Fix**:
- Added regex validation: `^[a-zA-Z0-9_-]+/[a-zA-Z0-9_-]+$`
- Added path traversal detection (`..` in names)
- Added shell injection prevention (`;`, `|`, `&`, `` ` ``, etc.)
- Comprehensive error messages
---
### LOW Severity Issues (2 Fixed)
#### 1. Missing Code Comments
**File**: `.gitea/workflows/ai-comment-reply.yml:47`
**Fix**: Added comprehensive comments explaining each step in the workflow.
#### 2. No Tests for New Dispatch Logic
**File**: `.gitea/workflows/ai-comment-reply.yml:62`
**Fix**: Created comprehensive test suite (see below).
---
## New Security Infrastructure
### 1. Webhook Sanitization Utilities
**File**: `tools/ai-review/utils/webhook_sanitizer.py`
**Features**:
- **Sensitive Field Removal**: Automatically redacts emails, tokens, API keys, passwords, private keys
- **Field Truncation**: Limits large text fields (body, description) to prevent log flooding
- **Nested Sanitization**: Recursively sanitizes nested dicts and lists
- **Minimal Context Extraction**: Extracts only essential fields for each event type
- **Repository Validation**:
- Format validation (owner/repo)
- Path traversal prevention
- Shell injection prevention
- **Webhook Signature Validation**: HMAC validation for future webhook integration
**Sensitive Fields Redacted**:
```python
SENSITIVE_FIELDS = {
"email", "private_email", "email_addresses",
"token", "access_token", "refresh_token", "api_key",
"secret", "password", "private_key", "ssh_key",
"phone", "phone_number", "address", "ssn", "credit_card",
"installation_id", "node_id",
}
```
### 2. Safe Dispatch Utility
**File**: `tools/ai-review/utils/safe_dispatch.py`
**Features**:
- Input validation (repository format, JSON structure)
- Data sanitization before dispatch
- Size limits (10MB max)
- Comprehensive error handling
- Logging with sanitized data
- Exit codes for CI/CD integration
**Usage**:
```bash
python utils/safe_dispatch.py issue_comment owner/repo '{"action": "created", ...}'
```
### 3. Pre-commit Security Hooks
**File**: `.pre-commit-config.yaml`
**Hooks**:
1. **Security Scanner** (`security/pre_commit_scan.py`) - Scans Python files for vulnerabilities
2. **Workflow Validator** (`security/validate_workflows.py`) - Validates workflow files for security anti-patterns
3. **Secret Detector** (`security/check_secrets.py`) - Detects hardcoded secrets
4. **YAML Linting** - Validates YAML syntax
5. **Bandit** - Python security linter
**Anti-patterns Detected**:
- Full webhook data in environment variables (`toJSON(github.event)`)
- Unvalidated repository inputs
- Direct user input in shell without escaping
- Inline Python with environment variable JSON parsing
### 4. Security Documentation
**File**: `SECURITY.md`
**Contents**:
- Workflow security best practices
- Input validation requirements
- Secret management guidelines
- Security scanning procedures
- Vulnerability reporting process
- Security checklist for contributors
**Key Sections**:
- ✅ Good vs ❌ Bad examples for workflows
- Boolean comparison patterns
- Webhook data handling
- Pre-commit hook setup
- CI failure thresholds
---
## Test Coverage
### 1. Security Utilities Tests
**File**: `tests/test_security_utils.py`
**Test Coverage**:
- Email field redaction
- Token and secret redaction
- Large body truncation
- Nested data sanitization
- List sanitization
- Minimal context extraction for different event types
- Repository format validation
- Path traversal rejection
- Shell injection rejection
- Edge cases (empty dicts, mixed types, case-insensitive matching)
**Test Count**: 20+ test cases
### 2. Safe Dispatch Tests
**File**: `tests/test_safe_dispatch.py`
**Test Coverage**:
- Valid JSON loading
- Invalid JSON rejection
- Size limit enforcement
- Successful dispatch
- Error handling
- Repository validation
- Path traversal prevention
- Shell injection prevention
- Data sanitization verification
- Exception handling
**Test Count**: 12+ test cases
### 3. Manual Validation
All security utilities tested manually:
```bash
✓ Sanitization works: True
✓ Valid repo accepted: True
✓ Malicious repo rejected
✓ Minimal extraction works: True
```
---
## Updated Files
### Core Security Files (New)
1. `tools/ai-review/utils/webhook_sanitizer.py` - Sanitization utilities
2. `tools/ai-review/utils/safe_dispatch.py` - Safe dispatch wrapper
3. `tools/ai-review/security/pre_commit_scan.py` - Pre-commit security scanner
4. `tools/ai-review/security/validate_workflows.py` - Workflow validator
5. `tools/ai-review/security/check_secrets.py` - Secret detector
6. `tests/test_security_utils.py` - Security utility tests
7. `tests/test_safe_dispatch.py` - Safe dispatch tests
### Documentation (New/Updated)
1. `SECURITY.md` - Comprehensive security guidelines (NEW)
2. `CLAUDE.md` - Added security best practices section (UPDATED)
3. `.pre-commit-config.yaml` - Pre-commit hook configuration (NEW)
4. `SECURITY_FIXES_SUMMARY.md` - This document (NEW)
### Workflow Files (Updated)
1. `.gitea/workflows/ai-comment-reply.yml` - Secure webhook handling
---
## Security Improvements by the Numbers
- **7 vulnerabilities fixed** (1 HIGH, 4 MEDIUM, 2 LOW)
- **7 new security modules** created
- **32+ new test cases** added
- **4 pre-commit hooks** implemented
- **50+ sensitive field patterns** detected and redacted
- **17 built-in security scanner rules** (existing)
- **10MB event size limit** enforced
- **100% code coverage** for security utilities
---
## Prevention Measures for Future Development
### 1. Pre-commit Hooks
Developers will be alerted BEFORE committing:
- Hardcoded secrets
- Workflow security anti-patterns
- Security vulnerabilities in code
### 2. Documentation
Comprehensive security guidelines ensure developers:
- Know what NOT to do
- Have working examples of secure patterns
- Understand the security model
### 3. Reusable Utilities
Centralized security utilities prevent re-implementing:
- Input validation
- Data sanitization
- Repository format checking
### 4. Automated Testing
Security utility tests ensure:
- Sanitization works correctly
- Validation catches malicious inputs
- No regressions in security features
### 5. CI/CD Integration
Workflows now:
- Validate all inputs
- Use minimal data
- Log safely
- Fail fast on security issues
---
## Security Principles Applied
1. **Principle of Least Privilege**: Only pass necessary data to workflows
2. **Defense in Depth**: Multiple layers (validation, sanitization, size limits)
3. **Fail Securely**: Validation errors cause immediate failure
4. **Security by Default**: Pre-commit hooks catch issues automatically
5. **Input Validation**: All external inputs validated and sanitized
6. **Data Minimization**: Extract only essential fields from webhooks
7. **Separation of Concerns**: Security logic in dedicated, testable modules
---
## Attack Vectors Prevented
### 1. Information Disclosure
- ✅ User emails no longer exposed in logs
- ✅ Tokens and API keys redacted from event data
- ✅ Private repository URLs sanitized
### 2. Path Traversal
- ✅ Repository names validated (no `..` allowed)
- ✅ Prevents access to `/etc/passwd` and other system files
### 3. Shell Injection
- ✅ Dangerous characters blocked (`;`, `|`, `&`, `` ` ``, `$()`)
- ✅ Repository names validated before shell execution
### 4. Log Injection
- ✅ Large fields truncated to prevent log flooding
- ✅ User input properly escaped in JSON
### 5. Denial of Service
- ✅ Event size limited to 10MB
- ✅ Recursion depth limited in sanitization
### 6. Secret Exposure
- ✅ Pre-commit hooks detect hardcoded secrets
- ✅ Workflow validator prevents secret leakage
---
## Verification Steps
To verify the security fixes:
```bash
# 1. Test webhook sanitization
cd tools/ai-review
python -c "from utils.webhook_sanitizer import sanitize_webhook_data; print(sanitize_webhook_data({'user': {'email': 'test@example.com'}}))"
# Should output: {'user': {'email': '[REDACTED]'}}
# 2. Test repository validation
python -c "from utils.webhook_sanitizer import validate_repository_format; validate_repository_format('owner/repo; rm -rf /')"
# Should raise ValueError
# 3. Install and run pre-commit hooks
pip install pre-commit
pre-commit install
pre-commit run --all-files
# 4. Test workflow validation
python tools/ai-review/security/validate_workflows.py .gitea/workflows/ai-comment-reply.yml
# Should pass with no errors
```
---
## Recommendations for Ongoing Security
1. **Review SECURITY.md** before making workflow changes
2. **Run pre-commit hooks** on all commits (automatic after `pre-commit install`)
3. **Update security rules** as new vulnerability patterns emerge
4. **Rotate secrets** regularly in CI/CD settings
5. **Monitor logs** for validation errors (may indicate attack attempts)
6. **Keep dependencies updated** (especially security-related packages)
7. **Conduct security reviews** for significant changes
---
## Contact
For security concerns or questions about these fixes:
- Review: `SECURITY.md`
- Report vulnerabilities: [security contact]
- Documentation: `CLAUDE.md` (Security Best Practices section)
---
**Status**: ✅ All security issues resolved and prevention measures in place.

167
SECURITY_QUICK_REFERENCE.md
View File

@@ -1,167 +0,0 @@
# Security Quick Reference Card
Quick reference for common security tasks in OpenRabbit development.
## ❌ Common Security Mistakes
### 1. Exposing Full Webhook Data
```yaml
# ❌ NEVER DO THIS
env:
EVENT_DATA: ${{ toJSON(github.event) }} # Exposes emails, tokens!
```
### 2. Unvalidated User Input
```python
# ❌ NEVER DO THIS
owner, repo = repo_string.split('/') # No validation!
```
### 3. Hardcoded Secrets
```python
# ❌ NEVER DO THIS
api_key = "sk-1234567890abcdef" # Hardcoded secret!
```
---
## ✅ Secure Patterns
### 1. Workflow Event Handling
```yaml
# ✅ Use minimal data extraction
run: |
EVENT_DATA=$(cat <<EOF
{
"issue": {"number": ${{ github.event.issue.number }}},
"comment": {"body": $(echo '${{ github.event.comment.body }}' | jq -Rs .)}
}
EOF
)
python utils/safe_dispatch.py issue_comment "$REPO" "$EVENT_DATA"
```
### 2. Repository Validation
```python
# ✅ Always validate
from utils.webhook_sanitizer import validate_repository_format
try:
owner, repo = validate_repository_format(user_input)
except ValueError as e:
logger.error(f"Invalid repository: {e}")
return
```
### 3. Webhook Data Sanitization
```python
# ✅ Sanitize before logging
from utils.webhook_sanitizer import sanitize_webhook_data
sanitized = sanitize_webhook_data(event_data)
logger.info(f"Processing event: {sanitized}")
```
### 4. Secret Management
```python
# ✅ Use environment variables
import os
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
raise ValueError("OPENAI_API_KEY not set")
```
---
## 🔍 Pre-Commit Checks
Install once:
```bash
pip install pre-commit
pre-commit install
```
Run manually:
```bash
pre-commit run --all-files
```
Bypass (NOT recommended):
```bash
git commit --no-verify
```
---
## 🛠️ Quick Commands
### Test Security Utilities
```bash
cd tools/ai-review
# Test sanitization
python -c "from utils.webhook_sanitizer import sanitize_webhook_data; \
print(sanitize_webhook_data({'user': {'email': 'test@example.com'}}))"
# Test validation (should fail)
python -c "from utils.webhook_sanitizer import validate_repository_format; \
validate_repository_format('owner/repo; rm -rf /')"
```
### Validate Workflow Files
```bash
# Check for security issues
python tools/ai-review/security/validate_workflows.py .gitea/workflows/*.yml
# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('.gitea/workflows/ai-comment-reply.yml'))"
```
### Scan for Secrets
```bash
# Check specific file
python tools/ai-review/security/check_secrets.py path/to/file.py
# Scan all Python files
find . -name "*.py" -exec python tools/ai-review/security/check_secrets.py {} \;
```
---
## 📋 Security Checklist
Before committing:
- [ ] No hardcoded secrets in code
- [ ] All user inputs validated
- [ ] Webhook data sanitized before logging
- [ ] Repository format validated
- [ ] Pre-commit hooks pass
- [ ] No full webhook data in environment variables
Before deploying workflow changes:
- [ ] Workflow validated with `validate_workflows.py`
- [ ] YAML syntax valid
- [ ] Input validation present
- [ ] Minimal data extraction used
- [ ] SECURITY.md guidelines followed
---
## 📚 Full Documentation
- **Complete Guide**: `SECURITY.md`
- **Implementation Details**: `SECURITY_FIXES_SUMMARY.md`
- **Developer Guide**: `CLAUDE.md` (Security Best Practices section)
---
## 🚨 Security Issue Found?
1. **DO NOT** create a public issue
2. Review `SECURITY.md` for reporting process
3. Email security contact immediately
---
**Remember**: Security is everyone's responsibility!

0
CLAUDE.md → docs/CLAUDE.md
View File

0
SECURITY.md → docs/SECURITY.md
View File

440
docs/feature-ideas.md
View File

@@ -1,440 +0,0 @@
# Feature Ideas & Roadmap
This document outlines recommended feature additions for OpenRabbit, ordered by value/effort ratio.
---
## Quick Reference
| Feature | Value | Effort | Time Estimate | Status |
|---------|-------|--------|---------------|--------|
| [@codebot help Command](#1-codebot-help-command) | HIGH | LOW | 1-2 hours | ⭐ Recommended |
| [Automatic Label Creator](#2-automatic-label-creator) | HIGH | MEDIUM | 2-3 hours | Planned |
| [PR Changelog Generator](#3-pr-changelog-generator) | MEDIUM | MEDIUM | 3-4 hours | Planned |
| [Code Diff Explainer](#4-code-diff-explainer) | MEDIUM-HIGH | MEDIUM | 2-3 hours | Planned |
| [Smart Test Suggestions](#5-smart-test-suggestions) | HIGH | HIGH | 5-6 hours | Planned |
| [@codebot review-again](#6-codebot-review-again) | MEDIUM | LOW | 1-2 hours | Planned |
| [Dependency Update Advisor](#7-dependency-update-advisor) | VERY HIGH | HIGH | 6-8 hours | Planned |
---
## 1. @codebot help Command
**⭐ HIGHEST PRIORITY - Quick Win**
### Problem
Users have no way to discover what commands are available. They don't know what the bot can do without reading documentation.
### Solution
Add a `@codebot help` command that lists all available commands with descriptions and examples.
### Implementation
- Add `help` to `config.yml` commands list
- Add `_command_help()` method to IssueAgent
- Format response with all commands + descriptions
### Example Output
```markdown
@username
**Available @codebot Commands:**
**Issue Triage & Analysis:**
- `@codebot triage` - Full issue triage with auto-labeling and priority assignment
- `@codebot summarize` - Generate 2-3 sentence summary
- `@codebot explain` - Detailed explanation of the issue
- `@codebot suggest` - Solution suggestions or next steps
**Interactive Chat:**
- `@codebot [question]` - Ask questions about the codebase
**Codebase Analysis:**
- `@codebot codebase` - Trigger full codebase health analysis
**Utility:**
- `@codebot help` - Show this message
**Examples:**
- `@codebot explain` - Get detailed explanation
- `@codebot how does authentication work?` - Chat about codebase
```
### Impact
- Immediate UX improvement
- Reduces support burden
- Makes all future commands discoverable
- Foundation for growth
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/issue_agent.py`
---
## 2. Automatic Label Creator
### Problem
Major setup pain point: users must manually create 10+ labels (`priority: high`, `type: bug`, etc.). Bot silently fails to apply labels if they don't exist.
### Solution
Add `@codebot setup-labels` command that:
1. Checks which required labels are missing
2. Creates them with proper colors
3. Or provides CLI commands for manual creation
### Implementation
- Add `setup-labels` command
- Query repository labels via Gitea API
- Compare against required labels in config
- Auto-create missing labels or show creation commands
### Example Output
```markdown
@username
**Label Setup Analysis:**
**Missing Labels:**
- `priority: high` (color: #d73a4a)
- `priority: medium` (color: #fbca04)
- `type: bug` (color: #d73a4a)
**Creating labels...**
✅ Created `priority: high`
✅ Created `priority: medium`
✅ Created `type: bug`
All required labels are now set up!
```
### Impact
- Removes major setup friction
- Ensures auto-labeling works immediately
- Better onboarding experience
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/issue_agent.py`
- `/tools/ai-review/clients/gitea_client.py` (add create_label method)
---
## 3. PR Changelog Generator
### Problem
Developers spend time writing release notes and changelogs. Bot already analyzes PR content.
### Solution
Add `@codebot changelog` command that generates human-readable changelog from PR.
### Implementation
- Add `changelog` command for PRs
- Analyze PR diff + commit messages
- Generate bullet-point summary
- Format for CHANGELOG.md
### Example Output
```markdown
@username
**Changelog for PR #123:**
### Added
- User authentication system with JWT tokens
- Password reset functionality via email
### Changed
- Updated database schema for user table
- Refactored login endpoint for better error handling
### Fixed
- Session timeout bug causing premature logouts
- Security vulnerability in password validation
### Technical Details
- 15 files changed, 450 insertions, 120 deletions
- Main components: auth/, api/users/, database/
```
### Impact
- Saves time on release documentation
- Consistent changelog format
- Can copy-paste into CHANGELOG.md
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/pr_agent.py`
---
## 4. Code Diff Explainer
### Problem
Complex PRs are hard to understand, especially for:
- Non-expert reviewers
- New team members
- Documentation purposes
### Solution
Add `@codebot explain-diff` command that breaks down what changed in simple terms.
### Implementation
- Add `explain-diff` command for PRs
- Analyze PR diff section by section
- Generate plain-language explanations
- Identify architectural changes
### Example Output
```markdown
@username
**PR Explanation:**
**Overview:**
This PR adds user authentication to the application using JWT tokens.
**Key Changes:**
1. **auth/jwt.py** (new file)
- Creates JSON Web Tokens for authenticated users
- Validates tokens on protected endpoints
- Handles token expiration (24 hour lifetime)
2. **api/users.py** (modified)
- Added `/login` endpoint that accepts username/password
- Returns JWT token on successful authentication
- Added `/logout` endpoint to invalidate tokens
3. **database/schema.sql** (modified)
- Added `users` table with columns: id, username, password_hash, email
- Passwords are hashed using bcrypt (secure)
**Architecture Impact:**
- Introduces authentication layer across all API endpoints
- Adds dependency on PyJWT library
- Requires database migration to create users table
```
### Impact
- Makes code review accessible
- Great for learning/onboarding
- Documentation generation
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/pr_agent.py`
- `/tools/ai-review/prompts/` (add explain_diff.md)
---
## 5. Smart Test Suggestions
### Problem
Test coverage is critical but developers often miss edge cases or forget to update tests.
### Solution
Add `@codebot suggest-tests` command that:
1. Analyzes changed functions/classes
2. Identifies what needs testing
3. Suggests specific test cases
### Implementation
- Add `suggest-tests` command for PRs
- Parse changed code to identify functions
- Use LLM to suggest test scenarios
- Could integrate with coverage reports
### Example Output
```markdown
@username
**Test Suggestions for PR #123:**
### auth/jwt.py - `create_token()` function
**Recommended Test Cases:**
1. ✅ Valid user creates token successfully
2. ⚠️ **Missing:** Token expiration after 24 hours
3. ⚠️ **Missing:** Invalid user ID handling
4. ⚠️ **Missing:** Token creation with special characters in username
### api/users.py - `/login` endpoint
**Recommended Test Cases:**
1. ✅ Successful login with correct credentials
2. ⚠️ **Missing:** Login with wrong password
3. ⚠️ **Missing:** Login with non-existent user
4. ⚠️ **Missing:** SQL injection attempt in username field
5. ⚠️ **Missing:** Rate limiting after failed attempts
**Coverage Impact:**
- Current coverage: ~60%
- With suggested tests: ~85%
```
### Impact
- Improves test coverage
- Catches edge cases
- Reduces production bugs
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/pr_agent.py`
- `/tools/ai-review/prompts/` (add test_suggestions.md)
---
## 6. @codebot review-again
### Problem
Current workflow: developer fixes issues → pushes commit → bot auto-reviews. Sometimes developers want re-review without creating new commits (e.g., after only changing comments).
### Solution
Add `@codebot review-again` command that re-runs PR review on current state.
### Implementation
- Add `review-again` command for PRs
- Re-run PR agent on current diff
- Update existing review comment
- Compare with previous review (show what changed)
### Example Output
```markdown
@username
**Re-review Complete:**
**Previous Review:** 5 issues (2 HIGH, 3 MEDIUM)
**Current Review:** 1 issue (1 MEDIUM)
✅ Fixed: SQL injection in login endpoint
✅ Fixed: Hardcoded JWT secret
⚠️ Remaining: Missing error handling in password reset
**Status:** Changes Required → Approved (pending fix)
```
### Impact
- Smoother PR workflow
- No unnecessary commits
- Faster feedback loop
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/pr_agent.py`
---
## 7. Dependency Update Advisor
### Problem
Security vulnerabilities often exist in dependencies. Keeping dependencies up-to-date is critical but tedious.
### Solution
Add `@codebot check-deps` command that:
1. Parses requirements.txt, package.json, etc.
2. Checks for outdated packages
3. Warns about CVEs
4. Suggests upgrade commands
### Implementation
- Add `check-deps` command
- Support multiple package formats (pip, npm, cargo, go)
- Integrate with vulnerability databases (CVE, npm audit)
- Generate upgrade instructions
### Example Output
```markdown
@username
**Dependency Analysis:**
### Outdated Packages (5)
| Package | Current | Latest | Severity |
|---------|---------|--------|----------|
| requests | 2.28.0 | 2.31.0 | <20><> HIGH - CVE-2023-32681 |
| django | 3.2.0 | 4.2.8 | 🟡 MEDIUM - Multiple CVEs |
| flask | 2.0.0 | 3.0.0 | 🟢 LOW - New features |
| pyyaml | 5.4.1 | 6.0.1 | 🔴 HIGH - CVE-2022-38752 |
| sqlalchemy | 1.4.0 | 2.0.23 | 🟢 LOW - Performance improvements |
### Recommended Actions
**Immediate (Security Vulnerabilities):**
```bash
pip install --upgrade requests==2.31.0
pip install --upgrade pyyaml==6.0.1
pip install --upgrade django==4.2.8
```
**Optional (Feature Updates):**
```bash
pip install --upgrade flask==3.0.0
pip install --upgrade sqlalchemy==2.0.23
```
### Breaking Changes to Review
- **Django 4.x:** Requires Python 3.8+, check compatibility
- **Flask 3.x:** Async support added, review async patterns
- **SQLAlchemy 2.x:** ORM API changes, review queries
### Resources
- [requests CVE-2023-32681](https://nvd.nist.gov/vuln/detail/CVE-2023-32681)
- [pyyaml CVE-2022-38752](https://nvd.nist.gov/vuln/detail/CVE-2022-38752)
```
### Impact
- Critical for security
- Keeps projects up-to-date
- Prevents technical debt
- Reduces manual checking
### Files to Modify
- `/tools/ai-review/config.yml`
- `/tools/ai-review/agents/issue_agent.py`
- Add new module: `/tools/ai-review/dependency_checker.py`
### External APIs Needed
- PyPI JSON API for Python packages
- npm registry API for JavaScript
- NVD (National Vulnerability Database) for CVEs
- Or use `pip-audit`, `npm audit` CLI tools
---
## Implementation Priority
### Phase 1: Quick Wins (1-3 hours total)
1. `@codebot help` command
2. `@codebot review-again` command
### Phase 2: High Impact (5-8 hours total)
3. Automatic Label Creator
4. Code Diff Explainer
### Phase 3: Strategic Features (10-15 hours total)
5. Smart Test Suggestions
6. PR Changelog Generator
7. Dependency Update Advisor
---
## Contributing
Have an idea for a new feature? Please:
1. Check if it's already listed here
2. Consider value/effort ratio
3. Open an issue describing:
- Problem it solves
- Proposed solution
- Expected impact
- Example use case
---
## See Also
- [future_roadmap.md](future_roadmap.md) - Long-term vision (SAST, RAG, etc.)
- [configuration.md](configuration.md) - How to configure existing features
- [agents.md](agents.md) - Current agent capabilities

82
docs/future_roadmap.md
View File

@@ -1,82 +0,0 @@
# Future Features Roadmap
This document outlines the strategic plan for evolving the AI Code Review system. These features are proposed for future implementation to enhance security coverage, context awareness, and user interaction.
---
## Phase 1: Advanced Security Scanning
Expand the current 17-rule regex scanner with dedicated industry-standard tools for **Static Application Security Testing (SAST)** and **Software Composition Analysis (SCA)**.
### Proposed Integrations
| Tool | Type | Purpose | Implementation Plan |
|------|------|---------|---------------------|
| **Bandit** | SAST | Analyze Python code for common vulnerability patterns (e.g., `exec`, weak crypto). | Run `bandit -r . -f json` and parse results into the review report. |
| **Semgrep** | SAST | Polyglot scanning with custom rule support. | Integrate `semgrep --config=p/security-audit` for broader language support (JS, Go, Java). |
| **Safety** | SCA | Check installed dependencies against known vulnerability databases. | Run `safety check --json` during CI to flag vulnerable packages in `requirements.txt`. |
| **Trivy** | SCA/Container | Scan container images (Dockerfiles) and filesystem. | Add a workflow step to run Trivy for container-based projects. |
**Impact:** significantly reduces false negatives and covers dependency chain risks (Supply Chain Security).
---
## Phase 2: "Chat with Codebase" (RAG)
Move beyond single-file context by implementing **Retrieval-Augmented Generation (RAG)**. This allows the AI to answer questions like *"Where is authentication handled?"* by searching the entire codebase semantically.
### Architecture
1. **Vector Database:**
* **ChromaDB** or **Qdrant**: Lightweight, open-source choices for storing code embeddings.
2. **Embeddings Model:**
* **OpenAI `text-embedding-3-small`** or **FastEmbed**: To convert code chunks (functions/classes) into vectors.
3. **Workflow:**
* **Index:** Run a nightly job to parse the codebase -> chunk it -> embed it -> store in Vector DB.
* **Query:** When `@ai-bot` receives a question, convert the question to a vector -> search Vector DB -> inject relevant snippets into the LLM prompt.
**Impact:** Enables high-accuracy architectural advice and deep-dive explanations spanning multiple files.
---
## Phase 3: Interactive Code Repair
Transform the bot from a passive reviewer into an active collaborator.
### Features
* **`@ai-bot apply <suggestion_id>`**:
* The bot generates a secure `git patch` for a specific recommendation.
* The system commits the patch directly to the PR branch.
* **Refactoring Assistance**:
* Command: `@ai-bot refactor this function to use dependency injection`.
* Bot proposes the changed code block and offers to commit it.
**Risk Mitigation:**
* Require human approval (comment reply) before any commit is pushed.
* Run tests automatically after bot commits.
---
## Phase 4: Enterprise Dashboard
Provide a high-level view of engineering health across the organization.
### Metrics to Visualize
* **Security Health:** Trend of High/Critical issues over time.
* **Code Quality:** Technical debt accumulation vs. reduction rate.
* **Review Velocity:** Average time to AI review vs. Human review.
* **Bot Usage:** Most frequent commands and value-add interactions.
### Tech Stack
* **Prometheus** (already implemented) + **Grafana**: For time-series tracking.
* **Streamlit** / **Next.js**: For a custom management console to configure rules and view logs.
---
## Strategic Recommendations
1. **Immediate Win:** Implement **Bandit** integration. It is low-effort (Python library) and high-value (detects real vulnerabilities).
2. **High Impact:** **Safety** dependency scanning. Vulnerable dependencies are the #1 attack vector for modern apps.
3. **Long Term:** Work on **Vector DB** integration only after the core review logic is flawless, as it introduces significant infrastructure complexity.

163
docs/security.md
View File

@@ -1,163 +0,0 @@
# Security Scanning
The security scanner detects vulnerabilities aligned with OWASP Top 10.
## Supported Rules
### A01:2021 – Broken Access Control
| Rule | Severity | Description |
|------|----------|-------------|
| SEC001 | HIGH | Hardcoded credentials (passwords, API keys) |
| SEC002 | HIGH | Exposed private keys |
### A02:2021 – Cryptographic Failures
| Rule | Severity | Description |
|------|----------|-------------|
| SEC003 | MEDIUM | Weak hash algorithms (MD5, SHA1) |
| SEC004 | MEDIUM | Non-cryptographic random for security |
### A03:2021 – Injection
| Rule | Severity | Description |
|------|----------|-------------|
| SEC005 | HIGH | SQL injection via string formatting |
| SEC006 | HIGH | Command injection in subprocess |
| SEC007 | HIGH | eval() usage |
| SEC008 | MEDIUM | XSS via innerHTML |
### A04:2021 – Insecure Design
| Rule | Severity | Description |
|------|----------|-------------|
| SEC009 | MEDIUM | Debug mode enabled |
### A05:2021 – Security Misconfiguration
| Rule | Severity | Description |
|------|----------|-------------|
| SEC010 | MEDIUM | CORS wildcard (*) |
| SEC011 | HIGH | SSL verification disabled |
### A07:2021 – Authentication Failures
| Rule | Severity | Description |
|------|----------|-------------|
| SEC012 | HIGH | Hardcoded JWT secrets |
### A08:2021 – Integrity Failures
| Rule | Severity | Description |
|------|----------|-------------|
| SEC013 | MEDIUM | Pickle deserialization |
### A09:2021 – Logging Failures
| Rule | Severity | Description |
|------|----------|-------------|
| SEC014 | MEDIUM | Logging sensitive data |
### A10:2021 – Server-Side Request Forgery
| Rule | Severity | Description |
|------|----------|-------------|
| SEC015 | MEDIUM | SSRF via dynamic URLs |
### Additional Rules
| Rule | Severity | Description |
|------|----------|-------------|
| SEC016 | LOW | Hardcoded IP addresses |
| SEC017 | MEDIUM | Security-related TODO/FIXME |
## Usage
### In PR Reviews
Security scanning runs automatically during PR review:
```yaml
agents:
pr:
security_scan: true
```
### Standalone
```python
from security import SecurityScanner
scanner = SecurityScanner()
# Scan file content
for finding in scanner.scan_content(code, "file.py"):
print(f"[{finding.severity}] {finding.rule_name}")
print(f" Line {finding.line}: {finding.code_snippet}")
print(f" {finding.description}")
# Scan git diff
for finding in scanner.scan_diff(diff):
print(f"{finding.file}:{finding.line} - {finding.rule_name}")
```
### Get Summary
```python
findings = list(scanner.scan_content(code, "file.py"))
summary = scanner.get_summary(findings)
print(f"Total: {summary['total']}")
print(f"HIGH: {summary['by_severity']['HIGH']}")
print(f"Categories: {summary['by_category']}")
```
## Custom Rules
Create `security/security_rules.yml`:
```yaml
rules:
- id: "CUSTOM001"
name: "Custom Pattern"
pattern: "dangerous_function\\s*\\("
severity: "HIGH"
category: "Custom"
cwe: "CWE-xxx"
description: "Usage of dangerous function detected"
recommendation: "Use safe_function() instead"
```
Load custom rules:
```python
scanner = SecurityScanner(rules_file="security/custom_rules.yml")
```
## CI Integration
Fail CI on HIGH severity findings:
```yaml
security:
fail_on_high: true
```
Or in code:
```python
findings = list(scanner.scan_diff(diff))
high_count = sum(1 for f in findings if f.severity == "HIGH")
if high_count > 0:
sys.exit(1)
```
## CWE References
All rules include CWE (Common Weakness Enumeration) references:
- [CWE-78](https://cwe.mitre.org/data/definitions/78.html): OS Command Injection
- [CWE-79](https://cwe.mitre.org/data/definitions/79.html): XSS
- [CWE-89](https://cwe.mitre.org/data/definitions/89.html): SQL Injection
- [CWE-798](https://cwe.mitre.org/data/definitions/798.html): Hardcoded Credentials