| --- |
| title: SecBrief |
| emoji: 🛡️ |
| colorFrom: yellow |
| colorTo: green |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| license: mit |
| --- |
| |
| # SecBrief |
|
|
| **Explain the risk. Enforce the fix.** |
|
|
| Security copilot for the **ArmorIQ Hackathon (Track 2)**: turn CVE/SARIF noise and vulnerable code into plain-English **security briefings** with **OWASP / CWE / SOC 2 / INR** mapping, then **cryptographically verified** remediation plans via ArmorIQ. |
|
|
| **Live demo:** use this Space URL. Set `ARMORIQ_API_KEY` and `MISTRAL_API_KEY` in **Settings → Variables**. |
|
|
| --- |
|
|
| ## One-liner |
|
|
| *ChatGPT explains the CVE. SecBrief enforces the fix.* |
|
|
| --- |
|
|
| ## How it works |
|
|
| ``` |
| Input (SARIF / alert / repo / code) → Brief (Mistral + compliance) → Plan → Enforce (ArmorIQ) → Export |
| ``` |
|
|
| | Layer | Role | |
| |-------|------| |
| | **Mistral** | Plain-English explanations, risk scores, OWASP/CWE/SOC2/INR fields, remediation steps | |
| | **ArmorIQ SDK** | Signs the intent plan (CSRG), enforces allow / block / hold per step, audit on [platform.armoriq.ai](https://platform.armoriq.ai) | |
| | **FastAPI + SQLite** | API, SARIF/npm parsing, GitHub deep scan, session history | |
| | **Next.js** | Demo UI — scan, audit code, explain, verify, export | |
|
|
| **Why both?** Mistral is the *brain* (language + planning). ArmorIQ is the *bouncer* (cryptographic proof that only declared steps run). |
|
|
| --- |
|
|
| ## Features |
|
|
| - **Inputs:** GitHub deep scan · code snippet audit · paste alert · upload SARIF / npm audit JSON · curated demo repos |
| - **Briefings:** Severity, risk score 1–10, OWASP/CWE/SOC2/INR chips on every analysis |
| - **Enforcement:** Per-step allow / block / hold + intent receipt (plan hash) |
| - **Demos:** Attack-the-agent (`delete_all` blocked) · delegation (scoped sub-agent) |
| - **Export:** Monday-morning Markdown incident brief |
| - **Sessions:** SQLite audit log per user email |
|
|
| --- |
|
|
| ## Quick start (local) |
|
|
| ### Prerequisites |
|
|
| - Python 3.11+ |
| - Node.js 18+ |
| - [ArmorIQ API key](https://platform.armoriq.ai) |
| - [Mistral API key](https://console.mistral.ai) |
|
|
| ### Environment |
|
|
| Copy `.env.example` → `.env` at repo root: |
|
|
| ```env |
| ARMORIQ_API_KEY=ak_live_... |
| MISTRAL_API_KEY=... |
| MISTRAL_MODEL=mistral-small-latest |
| NEXT_PUBLIC_API_URL=http://localhost:8000 |
| ``` |
|
|
| ### Run locally |
|
|
| ```powershell |
| cd backend |
| .\.venv\Scripts\activate |
| python -m uvicorn main:app --reload --port 8000 |
| |
| cd frontend |
| npm install |
| npm run dev |
| ``` |
|
|
| Or Docker (same as HF): `docker build -t secbrief .` then `docker run -p 7860:7860 --env-file .env secbrief` |
|
|
| --- |
|
|
| ## Demo script (~2 min) |
|
|
| | Step | Action | |
| |------|--------| |
| | 1 | **Code** tab → SQLi sample → **Audit code** | |
| | 2 | **Attack-the-agent** → **Generate verified fix plan** | |
| | 3 | Show **BLOCK** on `delete_all` + intent receipt | |
|
|
| Full talking points: [PITCH.md](./PITCH.md) |
|
|
| --- |
|
|
| ## API |
|
|
| | Method | Path | Description | |
| |--------|------|-------------| |
| | GET | `/health` | Service status | |
| | GET | `/api/why-secbrief` | Comparison JSON | |
| | POST | `/api/github/scan` | Deep repo scan | |
| | POST | `/api/audit-code` | Code snippet audit | |
| | POST | `/api/plan-fix` | Verified plan + intent receipt | |
| | POST | `/api/export-brief` | Markdown incident brief | |
|
|
| --- |
|
|
| ## Project structure |
|
|
| ``` |
| backend/ # FastAPI + ArmorIQ + Mistral |
| frontend/ # Next.js UI (static export in Docker) |
| Dockerfile # HF Space build |
| ``` |
|
|
| Deploy guide: [HF_DEPLOY.md](./HF_DEPLOY.md) |
|
|
