Code Review Workflow

An automated code review system that analyzes projects for security vulnerabilities, safety issues, and scalability problems. Works with Python, JavaScript/TypeScript, and Go projects.

---

Table of Contents

• Introduction
• Features
• Tools Included
• Installation
• How It Works
• Usage
  • Command Line
  • CI/CD Integration
  • Web Dashboard
• Configuration
• Troubleshooting
• Contributing
• License
• Acknowledgments

---

Introduction

Code Review Workflow is an open-source automation tool that reviews your code for common problems before they reach production. It combines multiple security scanners, pattern-based analysis, and generates easy-to-read reports.

Who Is This For?

• Developers who want automated code quality checks
• Teams who need consistent security review processes
• CI/CD pipelines that require automated quality gates
• Anyone learning about secure coding practices

What Problems Does It Solve?

Problem	How We Help
Hardcoded passwords/API keys	Detects secrets in code
SQL injection vulnerabilities	Finds unsafe database queries
Missing error handling	Identifies unhandled exceptions
Slow database patterns	Catches N+1 queries and unbounded fetches
Cross-site scripting (XSS)	Detects unsafe HTML rendering

---

Features

Core Features

• Multi-Language Support - Python, JavaScript/TypeScript, Go
• Security Scanning - OWASP Top 10 vulnerability detection
• Scalability Analysis - Performance anti-pattern detection
• Safety Checks - Error handling and input validation review
• Confidence Filtering - Only shows high-confidence issues (≥80%)

Output Formats

• Markdown Reports - Human-readable summaries
• JSON Reports - Machine-parseable for automation
• Inline Annotations - Comments in your code files
• GitHub/GitLab Integration - PR comments and CI status checks

Advanced Features

• Web Dashboard - Visual review history and trends
• Auto-Fix Suggestions - Automated remediation for common issues
• RAG-Enhanced Guidance - Context-aware security recommendations
• AST Analysis - Deep code structure analysis

---

Tools Included

Security Scanners

Tool	Purpose	Languages
security_scanner.py	Orchestrates security analysis	All
Bandit	Python security linter	Python
Semgrep	Pattern-based vulnerability detection	All
npm audit	Dependency vulnerability scanning	JavaScript

Analysis Tools

Tool	Purpose
scalability_checker.py	Detects performance anti-patterns
generate_report.py	Creates formatted reports
fix_engine.py	Generates auto-fix suggestions

Infrastructure

Component	Purpose
dashboard/	Web UI for review history
ci-integration/	GitHub Actions & GitLab CI configs
rag-system/	Security guidance retrieval
mcp-servers/	Advanced code analysis server

---

Installation

Prerequisites

• Python 3.9 or higher
• pip (Python package manager)
• Git

Step 1: Clone the Repository

git clone https://github.com/augmentedivan/code-review-workflow.git
cd code-review-workflow

Step 2: Create Virtual Environment (Recommended)

# Create virtual environment
python -m venv .venv

# Activate it
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Verify Installation

python tools/security_scanner.py --help
python tools/scalability_checker.py --help

---

How It Works

Simple Explanation

Your Code → Scanners → Filter Results → Report

Detailed Step-by-Step

Step 1: Language Detection

The system analyzes your project to determine what languages are used:

Project contains:
├── Python files (.py)     → Will use Bandit + Semgrep
├── JavaScript files (.js) → Will use npm audit + Semgrep
└── Go files (.go)         → Will use Semgrep

Step 2: Security Scanning

Multiple security tools run in parallel:

┌─────────────────┐
│  Your Project   │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│Bandit │ │Semgrep│  ← Security scanners
└───┬───┘ └───┬───┘
    │         │
    └────┬────┘
         ▼
┌─────────────────┐
│ Raw Findings    │  ← All potential issues
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Filter ≥80%     │  ← Remove low-confidence
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Final Report   │  ← Only real issues
└─────────────────┘

Step 3: Scalability Analysis

Pattern matching finds performance problems:

Pattern	Problem	Example
Query in loop	N+1 database queries	for user in users: db.get(user.id)
fetchall()	Unbounded data loading	Loading 1M rows into memory
Missing pagination	Memory exhaustion	API returning all records
Blocking I/O in async	Thread starvation	time.sleep() in async function

Step 4: Confidence Filtering

Not all warnings are real problems. We filter by confidence:

Raw findings: 47 issues
After filtering (≥80% confidence): 12 issues

Removed:
- False positives
- Stylistic preferences
- Already-handled edge cases

Step 5: Report Generation

Final output in your chosen format:

=== Code Review Report ===

Summary:
- Critical: 2 issues
- High: 3 issues
- Medium: 5 issues
- Low: 2 issues

Top Issues:

1. [CRITICAL] Hardcoded API key
   File: src/config.py, Line: 23
   → Move to environment variable

2. [CRITICAL] SQL Injection
   File: src/database.py, Line: 45
   → Use parameterized queries

---

Usage

Command Line

Basic Scan

# Scan current directory
python tools/security_scanner.py .

# Scan specific project
python tools/security_scanner.py /path/to/project

# Save results to file
python tools/security_scanner.py . --output results.json

Full Review (Security + Scalability)

# Using the CI runner for complete analysis
python tools/ci-integration/review_runner.py \
    --path /path/to/project \
    --output ./reports

Generate Reports

# Generate all report formats
python tools/generate_report.py \
    --findings-dir ./reports \
    --project-name "My Project" \
    --output-dir ./reports \
    --format all

CI/CD Integration

GitHub Actions

Add to .github/workflows/code-review.yml:

name: Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: pip install bandit semgrep

      - name: Run code review
        run: |
          python tools/ci-integration/review_runner.py \
            --path . \
            --output .tmp \
            --github-annotations \
            --fail-on-critical

GitLab CI

Add to .gitlab-ci.yml:

code-review:
  stage: test
  image: python:3.11
  script:
    - pip install bandit semgrep
    - python tools/ci-integration/review_runner.py --path . --output .tmp
  artifacts:
    paths:
      - .tmp/review_report.md

Web Dashboard

Start the dashboard to view review history:

# Start the dashboard
python tools/dashboard/app.py

# Open in browser
# http://localhost:5000

Dashboard features:

• View all past reviews
• Track issues over time
• See severity trends
• Export reports

---

Configuration

Quick Setup with Presets

We provide configuration presets for different deployment scenarios. Choose the one that matches your use case:

# For personal/development use (no auth, no rate limiting)
cp config/local.env.example .env

# For shared team dashboards (API key auth, moderate rate limiting)
cp config/team.env.example .env

# For production deployments (full security, strict rate limiting)
cp config/production.env.example .env

Then edit .env to customize values for your environment.

When to Enable Each Feature

Feature	Local	Team	Production	Why?
API Key Auth	❌	✅	✅	Prevents unauthorized access
Rate Limiting	❌	✅	✅	Prevents abuse
CSRF Protection	✅	✅	✅	Always on (built-in)
Semgrep	Optional	✅	✅	Multi-language scanning
Dashboard	Optional	✅	✅	Visual reports & history

See config/README.md for detailed configuration documentation.

Environment Variables

Variable	Description	Default
DASHBOARD_API_KEY	API key for dashboard auth (empty = disabled)	None
RATE_LIMIT_REQUESTS	Max requests per time window (0 = disabled)	100
RATE_LIMIT_WINDOW	Rate limit window in seconds	60
FLASK_SECRET_KEY	Secret key for sessions/CSRF	Auto-generated
VIBE_TOOLS_PATH	Path to tools directory	Auto-detected
GITHUB_TOKEN	GitHub API token (for PR comments)	None
GITHUB_REPOSITORY	Repository name (owner/repo)	None

Confidence Threshold

Edit tools/ci-integration/review_runner.py to adjust:

# Line 228: Change minimum confidence
all_findings = [f for f in all_findings if f.get("confidence", 0) >= 80]

Ignored Patterns

Create .code-review-ignore in your project:

# Ignore test files
**/test_*.py
**/*_test.go

# Ignore vendor directories
vendor/
node_modules/

# Ignore specific files
legacy/old_code.py

---

Troubleshooting

Common Issues

"bandit: command not found"

Problem: Bandit security scanner is not installed.

Solution:

pip install bandit

"semgrep: command not found"

Problem: Semgrep is not installed.

Solution:

pip install semgrep

Unicode/Encoding Errors on Windows

Problem: UnicodeDecodeError when running scanners.

Solution: This is fixed in the current version. If you see this error, make sure you have the latest code that includes encoding="utf-8" in subprocess calls.

"No findings in report"

Problem: Report shows 0 issues but you expected some.

Possible causes:

1. All findings were below 80% confidence threshold
2. No security issues detected (good news!)
3. Wrong project path specified

Debug:

# Run with verbose output
python tools/security_scanner.py . --output debug.json
cat debug.json

Dashboard Won't Start

Problem: ModuleNotFoundError: No module named 'flask'

Solution:

pip install flask

GitHub Action Failing

Problem: CI pipeline fails with permission errors.

Solution: Ensure your workflow has correct permissions:

permissions:
  contents: read
  pull-requests: write

Getting Help

1. Check the Issues page
2. Search existing issues for your problem
3. Create a new issue with:
   • Your operating system
   • Python version (python --version)
   • Full error message
   • Steps to reproduce

---

Contributing

We welcome contributions! Here's how to help:

Reporting Bugs

1. Check if the bug is already reported
2. Create a new issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs actual behavior
   • Your environment details

Suggesting Features

1. Open an issue with the "enhancement" label
2. Describe the feature and why it's useful
3. Include examples if possible

Submitting Code

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature-name

3. Make your changes
4. Run tests:

   python -m pytest tests/

5. Commit with clear messages:

   git commit -m "Add feature: description of change"

6. Push and create a Pull Request

Code Style

• Follow PEP 8 for Python code
• Use meaningful variable names
• Add comments for complex logic
• Include docstrings for functions

Adding New Scanners

To add support for a new language or tool:

1. Create adapter in tools/security_scanner.py
2. Add language detection logic
3. Parse tool output to standard format
4. Add tests
5. Update documentation

---

License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2024 Code Review Workflow Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Acknowledgments

• Bandit - Python security linter
• Semgrep - Pattern-based code analysis
• OWASP - Security guidelines and standards
• All contributors who help improve this project

---

Made with care for secure, safe, and scalable code.