Metadata-Version: 2.4
Name: codeaugur-cli
Version: 0.1.0
Summary: CodeAugur AppSec Platform — CLI for scanning repos and enforcing security policies in CI/CD
License: MIT
Project-URL: Homepage, https://github.com/sridharan1808/app-sec
Project-URL: Documentation, https://github.com/sridharan1808/app-sec/blob/main/docs/ci-integration.md
Project-URL: Bug Tracker, https://github.com/sridharan1808/app-sec/issues
Keywords: security,appsec,sast,sca,devsecops,codeaugur,shiftleft
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0

# 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

```bash
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):
```bash
brew install trivy syft grype gitleaks gosec hadolint
pip install bandit checkov semgrep
```

**DAST scanners** (optional — passive scanner runs without these):
```bash
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
```bash
docker compose up -d postgres redis
```

### 2. Backend
```bash
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:
```bash
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)
```bash
cd backend

# Create platform admin
python scripts/bootstrap.py admin --email admin@yourcompany.com --password "SecurePass!"

# Create first tenant (enterprise tier)
python scripts/bootstrap.py tenant \
  --slug acmecorp --name "Acme Corp" --tier enterprise \
  --admin-email alice@acmecorp.com --admin-password "SecurePass!"
```

### 4. Frontend
```bash
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
```bash
# 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":"alice@acmecorp.com","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/`](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
```bash
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:

```bash
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:

```bash
./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](DEPLOYMENT.md)**.
