codeaugur-cli 0.1.0

CodeAugur AppSec Platform — CLI for scanning repos and enforcing security policies in CI/CD

CodeAugur AppSec Platform

AI-powered application security scanning SaaS platform. Multi-tenant (orgs → projects → scans). Runs a 9-scanner open-source fleet against any Git repository, triages findings with Claude Haiku or Gemini 2.5 Flash, and presents results in a React dashboard with attack paths, SCA/SBOM inventory, executive reporting, CI/CD policy gates, and notification integrations.

What it does

• 9-scanner fleet: Semgrep, Bandit, gosec (SAST) · Trivy, Grype, Syft (SCA/SBOM) · Gitleaks (secrets) · Checkov + Hadolint (IaC)
• DAST: 25-check passive scanner (always runs, no external binary) · OWASP ZAP baseline · Nuclei templates — OWASP Top 10 grid in the UI. Covers: headers, CSP, CORS, cookies, TLS, JWT, sensitive paths, MIME, body disclosure, hidden content, CDN trackers, JS library CVEs (jQuery/Bootstrap/Lodash), CMS fingerprinting, login forms, HSTS depth, DOM XSS sinks, DNS (SPF/DMARC/DNSSEC/CAA), port exposure, sitemap analysis
• AI triage: Anthropic (Haiku 4.5, tool_use) or Google Gemini 2.5 Flash — verdict, risk score (0–100), plain-English reasoning per finding. Provider resolved per-user at runtime.
• Per-user AI keys: Each user can store their own Anthropic or Gemini API key (AES-256-GCM encrypted at rest) via Settings → Integrations → My AI Key. Resolution hierarchy: personal → org → system env.
• Dual-provider AI: Anthropic and Gemini both supported across triage, attack paths, analytics deep analysis, and patch generation.
• Attack Paths: AI-constructed exploit chains showing how findings chain into real attacks
• SCA/SBOM tab: Full package inventory with per-CVE details, deduped across tools
• Analytics tab: Per-scan FP/TP triage engine — rule-based classification, Sonnet/Gemini deep analysis with executive summary and per-group exploitability + remediation plan
• Management Dashboard: Compliance exposure (PCI/SOC2/GDPR/ISO 27001), Fix Today queue, trend sparklines
• CI/CD policy gates (Phase 1 complete): codeaugur-cli package + GitHub/GitLab/Jenkins/CircleCI/Bitbucket/Azure DevOps workflow templates — fail builds on policy violations
• Notification integrations (Phase 2 complete): Slack, Teams, Jira, PagerDuty, GitHub Issues, generic webhook — per-finding alerts dispatched post-scan
• SLA tracking: Deadlines stamped at finding creation (critical=24h, high=7d, medium=30d, low=90d); overdue count at /api/integrations/sla/overdue
• Settings GUI: Manage org-level AI API keys (Anthropic + Gemini), personal AI key, and git provider PATs from the UI — no server restart needed
• Zip upload: Scan without git access — upload a .zip or .tar.gz directly from the New Scan modal (max 200 MB)
• PR auto-open: After AI generates a patch, a draft GitHub PR is automatically opened when github_token is configured
• Org API Keys: Generate CODEAUGUR_API_KEY tokens for CLI/CI pipelines — SHA-256 hashed in DB, revocable, full key shown once
• License tier enforcement: Enabled scanner list per tier enforced at scan start
• Admin console (per-tenant): Users (search/role filter), Audit Log (module/result filters, live refresh, CSV export), AI Usage (top users, by-module, cost, per-call log + CSV export), Permissions (per-tenant role × module/action matrix), License tabs
• Platform dashboard: Global stats, tenant tile grid, tenant management, impersonation, cross-tenant AI Usage panel (ranked by cost, drillable per tenant), Activity log with module/result filters + tenant picker + CSV export
• Session termination: deactivating a user or resetting a password (tenant- or platform-admin-issued) immediately revokes that user's active sessions
• Personal AI key: provider cards with cost hints, key reveal toggle, AES-256-GCM privacy notice, and a "My AI Usage" stats section under Settings → Integrations

Stack

Layer	Tech
Backend	FastAPI + SQLAlchemy 2 async + Postgres 16 + Alembic
AI triage	Haiku 4.5 (Anthropic) · Gemini 2.5 Flash (Google) — resolved per-user
Frontend	React 18 + Vite + TypeScript + Tailwind CSS
Scanners	Semgrep, Trivy, Grype, Syft, Gitleaks, Checkov, Hadolint, Bandit, gosec (static) + dast-passive, ZAP, Nuclei (DAST)
Queue	FastAPI BackgroundTasks (→ Arq + Redis in Phase 3)
CLI	codeaugur-cli (PyPI) — policy-gated CI/CD scanning

CLI Quick Start

pip install codeaugur-cli

# Set credentials (from Integrations → API Keys in the UI)
export CODEAUGUR_API_URL=https://your-instance.example.com
export CODEAUGUR_API_KEY=ca_...

# Run a scan and apply policy
codeaugur scan --repo-url https://github.com/org/repo --policy strict

Exit codes: 0 = passed, 1 = policy violation (fail CI), 2 = scan/API error.

Setup

Prerequisites

• Python 3.13 (/usr/local/bin/python3.13) — asyncpg doesn't support 3.14
• Node 18+
• Docker (for Postgres + Redis)

Static scanners (install once via Homebrew):

brew install trivy syft grype gitleaks gosec hadolint
pip install bandit checkov semgrep

DAST scanners (optional — passive scanner runs without these):

docker pull ghcr.io/zaproxy/zaproxy:stable
brew install nuclei && nuclei -update-templates

ZAP and Nuclei are skipped gracefully if not available — the passive header scanner always runs and produces OWASP Top 10 coverage on its own.

1. Start services

docker compose up -d postgres redis

2. Backend

cd backend
/usr/local/bin/python3.13 -m venv .venv
.venv/bin/pip install -r requirements.txt

Create backend/.env:

DATABASE_URL=postgresql+asyncpg://appsecsvc:changeme@localhost:5432/appsec
SECRET_KEY=replace-with-64-char-random-hex-string       # openssl rand -hex 32
AI_KEY_ENCRYPTION_SECRET=replace-with-64-char-hex       # openssl rand -hex 32 — encrypts user AI keys at rest
GEMINI_API_KEY=AIza...          # system-level Gemini key (org/personal keys take priority)
ANTHROPIC_API_KEY=sk-ant-...    # system-level Anthropic key
GEMINI_MODEL=gemini-2.5-flash
ENVIRONMENT=development

Security note (2026-06-30): integration secrets in app_settings are org-scoped. After upgrading across migration a5b6c7d8e9f0, re-save each tenant's git-provider PAT and AI keys in Settings. In ENVIRONMENT=production, the backend refuses to start with a default SECRET_KEY.

Run migrations and start:

DATABASE_URL="postgresql+asyncpg://appsecsvc:changeme@localhost:5432/appsec" \
  .venv/bin/alembic upgrade head

DATABASE_URL="postgresql+asyncpg://appsecsvc:changeme@localhost:5432/appsec" \
SECRET_KEY="<your-key>" \
.venv/bin/uvicorn app.main:app --port 8000 --reload --log-level info

3. Bootstrap accounts (first run only)

cd backend

# Create platform admin
python scripts/bootstrap.py admin --email [e-mail] --password "SecurePass!"

# Create first tenant (enterprise tier)
python scripts/bootstrap.py tenant \
  --slug acmecorp --name "Acme Corp" --tier enterprise \
  --admin-email [e-mail] --admin-password "SecurePass!"

4. Frontend

cd frontend && npm install && npm run dev

Login URLs

Role	URL	Credentials
Platform admin	http://localhost:5173/platform/login	email + password (no org slug)
Tenant admin/user	http://localhost:5173/login	org slug + email + password
Admin console	http://localhost:5173/admin	tenant admin or auditor only

Usage

Trigger a scan

1. Open http://localhost:5173/login and log in as a tenant user
2. Click + New Scan, enter any Git repo URL
3. Watch queued → running → completed
4. Click Open to enter the scan detail view

Scan detail tabs

Tab	Contents
Dashboard	Posture summary, compliance, Fix Today queue, trend sparklines
Attack Paths	AI-generated exploit chains in business language
Surface	Findings grouped by entry-point category
SCA / SBOM	Package inventory with expandable CVE details
DAST	OWASP Top 10 grid, passive + ZAP + Nuclei findings
All Findings	Paginated, filterable by severity / verdict / tool
Analytics	FP/TP classification + Sonnet/Gemini deep analysis

Integrations page tabs

Tab	Contents
CI/CD	Copy-pasteable full workflow files for 6 CI providers
Notifications	Configure Slack, Teams, Jira, PagerDuty, GitHub Issues, webhook
Webhooks	Inbound push-event webhooks (GitHub/GitLab/Bitbucket)
API Keys	Manage org-scoped CODEAUGUR_API_KEY tokens

Set up CI/CD policy gate

1. Go to Integrations → CI/CD and copy the full workflow file for your CI provider
2. Add repository secrets: CODEAUGUR_API_URL and CODEAUGUR_API_KEY
3. Paste the file into your repo (e.g. .github/workflows/security.yml)
4. The workflow installs codeaugur-cli from PyPI and fails the build on policy violations
5. To auto-block a deploy on a failed scan, make the deploy job/stage depend on the scan job's success (needs: in GitHub Actions/GitLab, sequential stages in Jenkins/Bitbucket, requires: in CircleCI, dependsOn:/condition: in Azure DevOps) — see the worked examples in ci-templates/* for each provider.

Note for maintainers: frontend/src/pages/IntegrationsPage.tsx's CI_PROVIDERS snippets are a separate, hand-maintained copy of ci-templates/* (not generated from it) — this is what step 1 above actually copies. Keep the two in sync manually when either changes.

Set up notification integrations

1. Go to Integrations → Notifications
2. Select a provider (Slack, Teams, Jira, PagerDuty, GitHub Issues, or Webhook)
3. Enter the required config (webhook URL, API key, project key, etc.)
4. Click Test to verify connectivity, then toggle Enable

Post-scan, the notifier fans out to all enabled configs for the org. Jira creates an issue per confirmed/likely finding; PagerDuty only fires for risk_score ≥ 90.

Admin console (per-tenant)

Go to http://localhost:5173/admin — Users · Audit Log · AI Usage · License tabs.

Platform dashboard

Go to http://localhost:5173/platform — global stats, tenant tiles, create/manage/impersonate.

Via API

# Login
TOKEN=$(curl -s -c cookies.txt -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"org_slug":"acmecorp","email":"[e-mail]","password":"SecurePass!"}' \
  | jq -r .access_token)

# Trigger scan
curl -X POST http://localhost:8000/api/scans/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/WebGoat/WebGoat", "scan_type": "full"}'

# Get SLA overdue count
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/integrations/sla/overdue

# List integration configs
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/integrations/

API docs: http://localhost:8000/docs

Product Roadmap

See product-roadmap/ for the full roadmap.

Shipped:

• Phase 0 — Foundation (auth, multi-tenant, scanner fleet, AI triage)
• Phase 1 — CI/CD Gate (codeaugur-cli, OPA policy engine, webhook ingest, PR auto-decoration, GitHub/GitLab/Jenkins/CircleCI/Bitbucket/Azure DevOps templates)
• Phase 2 — Ticketing + Notifications (Slack, Teams, Jira, PagerDuty, GitHub Issues, webhook, SLA tracking)

Next: Phase 3 — CSPM (Prowler for AWS/GCP/Azure, kube-bench, Falco, tfsec/terrascan, drift detection)

Scan types

scan_type	Scanners	Notes
sast	Semgrep, Bandit, gosec
sca	Trivy, Syft, Grype
secrets	Gitleaks
iac	Checkov, Hadolint
full	All static scanners
sbom	Syft only
image	Trivy image mode	Pass image tag as repo_url
dast	Passive headers + ZAP + Nuclei	Pass target URL as dast_target_url
supply_chain	OSSF Scorecard + license scan

DAST via API

curl -X POST http://localhost:8000/api/scans/ \
  -H "Content-Type: application/json" \
  -d '{"scan_type": "dast", "dast_target_url": "https://app.example.com"}'

Production / internal-server deployment

The platform deploys as two separated tiers so it scales to a commercial SaaS without a code rewrite — the app tier reaches the database ONLY via DATABASE_URL/REDIS_URL, so the data tier can later become a managed service (RDS/Cloud SQL) with no code change.

• App tier — docker-compose.prod.yml (backend + Arq worker + nginx frontend)
• Data tier — docker-compose.data.yml (Postgres + Redis)

Scan execution & isolation (all default-off; enable per environment, see DEPLOYMENT.md §9):

• SCAN_EXECUTION_MODE — inline (in-process, dev) or queue (Arq worker, prod)
• SCAN_SANDBOX_MODE — subprocess (host), docker (ephemeral network-none container), or k8s (ephemeral Job in the tenant namespace; manifests in k8s/)
• SCAN_TENANT_ISOLATION — per-tenant network (docker) / namespace (k8s) per org

Quickstart on the server:

docker network create appsec_net
cp .env.prod.example .env.prod            # fill in secrets; CORS_ORIGINS is a JSON array
docker compose --env-file .env.prod -f docker-compose.data.yml up -d
docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm backend alembic upgrade head
docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build

Migrate an existing instance (app + data) from your dev machine:

./scripts/migrate-to-server.sh --server user@host --path /opt/codeaugur --push-env

Full guide — architecture, ops/backups, and the commercial scale-out path (managed DB, Arq workers, replicas, TLS, object storage) — in DEPLOYMENT.md.