The Context-Aware Vulnerability Orchestrator based on the SecureScan Framework.
Cerberus is a production-grade vulnerability management platform designed to solve Alert Fatigue. Unlike traditional scanners that dump thousands of findings, Cerberus uses a Context Engine to correlate vulnerabilities with runtime context, environment criticality, and reachability.
The Problem: 5,000 "Critical" bugs, but only 5 matter. The Solution: Cerberus tells you which 5 matter.
- Dashboard: http://localhost:3000
- API Docs: http://localhost:8000/docs
- CLI:
securescan scan --help
Cerberus doesn't just scan code; it understands it.
- Environment Weighting: A bug in
prod> a bug indev. - Reachability Analysis: Is the vulnerable function actually called?
- Public Exposure: Is the service internet-facing?
Run the best-in-class tools under one roof.
- SAST: Semgrep
- SCA: Trivy
- DAST: OWASP ZAP
- Secrets: Gitleaks
- IaC: Checkov
- VS Code Extension: Real-time security linting
- CLI Tool:
cerberus scan --context=prod --reachability=true - Modern Dashboard: React-based vulnerability management
- API-First: RESTful APIs with OpenAPI docs
Detailed Architecture
For comprehensive diagrams including System Overview, Scan Workflows, and Authentication Flows, please see docs/ARCHITECTURE.md.
graph TD
CLI[Cerberus CLI] --> Gateway[API Gateway]
Web[Web Dashboard] --> Gateway
Gateway --> API[FastAPI Backend]
API --> Auth[Auth Service]
API --> DB[(PostgreSQL)]
subgraph "The Brain"
Engine[Context Engine]
Policy[Policy Manager]
end
API <--> Engine
API --> Queue[Redis Queue]
Queue --> Workers[Celery Workers]
Workers --> Scanners[Scanner Engines]
Scanners --> Results[(Scan Results)]
Results --> Engine
# Required
- Docker & Docker Compose
- Python 3.10+
- Node.js 18+
- Git
# Optional
- VS Code (for extension)
- Kubernetes (for production)git clone https://github.com/yourusername/securescan-framework.git
cd securescan-framework
# Start infrastructure
docker-compose up -d
# Install dependencies
make install
# Run migrations
make migrate
# Start all services
make dev# Web Dashboard
open http://localhost:3000
# API Documentation
open http://localhost:8000/docs
# CLI Tool
securescan scan --path ./examples/vulnerable-app# Using CLI
securescan scan \
--path ./examples/vulnerable-app \
--scanners semgrep,trivy \
--output sarif
# Using API
curl -X POST http://localhost:8000/api/v1/scan \
-H "Authorization: Bearer $(cat .env | grep API_KEY | cut -d= -f2)" \
-H "Content-Type: application/json" \
-d '{
"project_name": "my-app",
"repo_url": "https://github.com/user/vulnerable-app",
"scanners": ["semgrep", "trivy"]
}'securescan-framework/
├── 📁 backend/ # FastAPI Backend
│ ├── app/
│ │ ├── api/ # REST API endpoints
│ │ ├── core/ # Core services & config
│ │ ├── db/ # Database models & migrations
│ │ ├── scanners/ # Scanner integrations
│ │ └── workers/ # Celery background tasks
│ ├── tests/ # Backend tests
│ └── requirements.txt
├── 📁 frontend/ # React Dashboard
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── pages/ # Dashboard pages
│ │ ├── hooks/ # Custom React hooks
│ │ └── services/ # API clients
│ ├── tests/ # Frontend tests
│ └── package.json
├── 📁 cli/ # Python CLI Tool
│ ├── securescan/
│ │ ├── commands/ # CLI commands
│ │ ├── core/ # Core CLI logic
│ │ └── scanners/ # Scanner interfaces
│ ├── tests/ # CLI tests
│ └── setup.py
├── 📁 vscode-extension/ # VS Code Extension
│ ├── src/ # TypeScript source
│ ├── resources/ # Extension assets
│ └── package.json
├── 📁 infrastructure/ # Deployment configs
│ ├── docker/ # Docker configurations
│ ├── kubernetes/ # K8s manifests
│ └── terraform/ # Infrastructure as Code
├── 📁 docs/ # Documentation
│ ├── api/ # API documentation
│ ├── guides/ # User guides
│ └── architecture/ # Technical docs
├── 📁 examples/ # Example projects
│ ├── vulnerable-app/ # Test application
│ └── ci-cd-configs/ # CI/CD examples
├── 📁 scripts/ # Development scripts
├── docker-compose.yml # Local development
├── Makefile # Development commands
└── README.md # This file
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Run backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# Run tests
pytest tests/ -vcd frontend
npm install
npm run dev
# Run tests
npm test
npm run test:e2ecd cli
npm install
npm run build
# Link for local development
npm link
# Test CLI
securescan --help
securescan scan --path ../examples/vulnerable-appcd vscode-extension
npm install
npm run compile
# Test extension
code --extensionDevelopmentPath=$(pwd) ../examples/vulnerable-appmake test# Backend tests
cd backend && pytest tests/ -v --cov=app
# Frontend tests
cd frontend && npm test -- --coverage
# CLI tests
cd cli && python -m pytest tests/
# Integration tests
python scripts/run_integration_tests.py
# E2E tests
npm run test:e2edocker-compose up -d# Deploy to Kubernetes
kubectl apply -f infrastructure/kubernetes/
# Or use Helm
helm install securescan infrastructure/helm/# AWS EKS
terraform apply infrastructure/terraform/aws/
# GCP GKE
terraform apply infrastructure/terraform/gcp/
# Azure AKS
terraform apply infrastructure/terraform/azure/- Prometheus: http://localhost:9090
- Grafana: http://localhost:3001
- Dashboards: Pre-configured security scanning metrics
- Structured logging with JSON format
- Centralized logs with ELK stack
- Audit trails for all security operations
# API Health
curl http://localhost:8000/health
# Scanner Health
curl http://localhost:8000/api/v1/scanners/health
# Database Health
curl http://localhost:8000/api/v1/health/db- JWT tokens for API access
- API keys for CLI/CI-CD integration
- RBAC for fine-grained permissions
# Generate secure secrets
python scripts/generate_secrets.py
# Validate security config
securescan config validate
# Security audit
make security-audit- Scan Speed: 100K LOC in < 3 minutes
- Concurrent Scans: 10+ parallel scans
- API Throughput: 1000+ requests/second
- Dashboard Load: < 2 second initial load
- Async processing with Celery
- Caching with Redis
- Database indexing for fast queries
- CDN integration for static assets
- Fork the repository
- Create a feature branch
- Write tests for your changes
- Implement the feature
- Run the test suite
- Submit a pull request
- Backend (Python): Black formatting, flake8 linting
- Frontend/CLI (TypeScript): Prettier formatting, ESLint
- Git: Conventional commits
- Documentation: Keep docs updated
- Core API with 3 scanners
- CLI tool
- Basic dashboard
- Docker deployment
- VS Code extension
- 5+ additional scanners
- Advanced analytics
- Policy engine
- SSO integration
- Compliance reporting
- Multi-tenant support
- Enterprise connectors
This project is licensed under the MIT License - see the LICENSE file for details.
- Security Tools: Semgrep, Trivy, OWASP ZAP, Gitleaks, Checkov
- SARIF Standard: Microsoft Security Static Analysis Results Format
- Open Source Community: All the amazing contributors
- 🐛 Bug Reports: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📧 Email: rramesh17993@gmail.com
- 💭 Discord: Join our community
⭐ Star this repo if you find it useful!
Made with ❤️ by the SecureScan community