Mitig8it

Mitig8it is a GitHub-native security reviewer for pull requests. It receives GitHub App webhooks, analyzes changed PR files with a three-tier detection pipeline, stores results in PostgreSQL, and posts review feedback back to GitHub.

The repository is still named codesentry and some environment variables, package names, metrics, and Cloud Run resources still use the CodeSentry name. Treat Mitig8it as the product name and CodeSentry as the current infrastructure/code namespace.

Runtime Components

• frontend/ - React 18 + Vite dashboard served locally on port 5173.
• services/api-service/ - Node.js/Express control plane on port 3000; handles auth, webhooks, repository/PR/finding APIs, orchestration, and migrations.
• services/github-service/ - Node.js/Express GitHub adapter on port 3002; fetches PR files and posts comments/check runs through the GitHub App.
• services/analysis-service/ - FastAPI analysis engine on port 8001; runs regex rules, dependency checks, OpenGrep rules, and optional LLM triage.
• postgres - PostgreSQL 15 system of record.
• prometheus - Local metrics scrape target on port 9090.

Primary local wiring lives in docker-compose.yml. Production deployment wiring lives in .github/workflows/.

How PR Analysis Flows

1. GitHub sends pull_request, installation, or installation_repositories events to POST /webhooks/github on the API service.
2. The API verifies the webhook signature with GITHUB_WEBHOOK_SECRET and deduplicates deliveries by webhook_deliveries.delivery_id.
3. For PR events, the API persists repository/PR state, creates an analysis_runs row, and starts orchestration.
4. The API calls the GitHub service with GITHUB_SERVICE_INTERNAL_SECRET to fetch changed files and publish GitHub feedback.
5. The API calls the analysis service with an internal secret to analyze changed files.
6. Findings are normalized, clustered, fingerprinted, stored in PostgreSQL, filtered by suppressions/baseline state, and surfaced in the dashboard.
7. High-confidence findings can be posted inline; summaries/check runs are posted through the GitHub service.

Detection Pipeline

• Tier 1: deterministic regex and dependency-risk checks in services/analysis-service/src/security_rules.py.
• Tier 2: OpenGrep AST rules in services/analysis-service/src/opengrep_rules/.
• Tier 3: optional LLM triage through GEMINI_API_KEY; failures are non-blocking.

The combined production path is POST /analyze/pr. Tier-specific endpoints also exist for focused testing: /analyze/pr/tier1, /analyze/pr/tier2, and /analyze/pr/tier3.

Quick Start

./scripts/setup-local-dev.sh
./scripts/install-git-hooks.sh

Then fill in real GitHub values in .env:

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_APP_ID
• GITHUB_APP_PRIVATE_KEY
• GITHUB_WEBHOOK_SECRET if you do not want the generated local value

Validate and start:

./scripts/validate-env.sh
docker-compose up --build

Local URLs:

• Frontend: http://localhost:5173
• API: http://localhost:3000
• GitHub service: internal Docker service on github-service:3002; expose manually for standalone development
• Analysis: internal Docker service on analysis-service:8001; expose manually for direct local calls
• Prometheus: http://localhost:9090

Standalone Development

# API
cd services/api-service
npm install
npm run dev

# GitHub service
cd services/github-service
npm install
npm run dev

# Analysis service
cd services/analysis-service
pip install -r src/requirements.txt
uvicorn src.main:app --reload --port 8001

# Frontend
cd frontend
npm install
npm run dev

The Node services load the root .env automatically as a fallback. For standalone Python runs, export the needed values from the root .env before starting Uvicorn.

Test and Verification

# Frontend lint, tests, and build
cd frontend
npm run lint
npm test
npm run build

# API tests
cd services/api-service
npm test

# GitHub service tests
cd services/github-service
npm test

# Analysis tests
cd services/analysis-service/src
pytest tests -q

# Environment validation
./scripts/validate-env.sh

CI also runs Gitleaks, dependency review on PRs, npm audits, Python pip-audit, Bandit, and Docker image builds for the backend services.

Deployment

Deployments are performed by GitHub Actions after the CI workflow succeeds on main, or manually via workflow_dispatch.

• Frontend deploys to Firebase Hosting.
• API, GitHub service, and analysis service deploy to Cloud Run.
• Images are pushed to Google Artifact Registry.
• API migrations run from the release image before the API Cloud Run revision is deployed.
• Secrets are read from GCP Secret Manager and GitHub Actions secrets/variables.

See cloud-run-firebase.md.

Documentation

All project documentation lives under docs/, organized by workflow:

docs/
  getting-started/   local setup, environment variables, GitHub App setup
  architecture/      system overview, guardrails, known limitations
  deployment/        CI/CD, Cloud Run/Firebase deployment, rollout notes
  services/          frontend, API, GitHub service, analysis service
  operations/        scripts, benchmarks, observability
  contributors/      contributor guidelines

Start with the Documentation Index. Common entry points:

• Local Development
• Environment Setup
• Architecture Overview
• CI/CD Pipeline
• Cloud Run and Firebase Deployment