"In this heist, we're not stealing — we're protecting." SecureFlow automatically detects vulnerabilities, hardcoded secrets, and code flaws before they reach production.
Featured in Nexus Spring of Code
Click to expand
- 🌟 The Crew's Abilities (Features)
- 🧠 The Blueprint (How It Works)
- 🛠️ Tech Stack
- 📁 Project Structure
- 🚀 Joining the Resistance (Getting Started)
- 🐳 Docker Setup
- 🔑 Environment Variables Reference
- 📝 Available Scripts
- 🔒 Defense Strategy (Security Policies)
- 📊 Architecture
- 📖 Technical Documentation
- 🤝 Contributing
- ❓ FAQ
- 📄 License
SecureFlow integrates directly with GitHub via a GitHub App and webhooks. Every time a Pull Request is opened or updated, The Professor — SecureFlow's AI mastermind — extracts the code diff, runs it through Groq's LLM (GPT-OSS-20B), and returns actionable security findings with AI-written explanations and remediation steps, all visible on a centralized Mission Control dashboard.
Think of every Pull Request as a member of the crew trying to get into The Vault (your codebase). The Professor checks their credentials at the door — no leaked keys, no sloppy code, no breaches on his watch.
Uses Groq's GPT-OSS-20B to detect hardcoded secrets, vulnerabilities, and misconfigurations in your code.
Automatically scans every opened or updated Pull Request as soon as it's created — The Professor never sleeps.
Generates precise explanations and concrete code fixes for each security finding.
View all your repositories, PRs, findings, and audit logs in one unified command center. Includes a keyboard-accessible Command Palette (Ctrl+K or ⌘K) for rapid navigation and quick actions across sections.
Posts detailed security reports directly on your PRs with collapsible remediation blocks.
Sets Pass/Review Required/Blocked status on PR commits for clear CI/CD integration.
Create, toggle, and manage security policies per user or organization — write your own rules for the plan.
Intelligently ignores non-executable files and mock placeholders to reduce noise.
Maintainers can dismiss findings directly from the dashboard:
- Status & Reason: Triage findings as
DISMISSEDwith a mandatory reason category (False positive,Accepted risk, orWon't fix) and a required explanation note. - Stable Fingerprints: Findings generate deterministic SHA-256 fingerprints (
repositoryId + fileLocation + type + codeSnippet) so dismissals reliably persist across commits and subsequent scans. - Scan-time Suppression: Dismissed findings are automatically suppressed during PR scans—they do not block pull requests or inflate open finding tallies, and are reported as previously dismissed in PR scan summaries.
- Audit Trail & Reversal: Every dismissal and reopening action is logged in the Vault Audit Log with actor identity, timestamp, and notes. Reopening restores findings to
OPENstatus instantly.
Developer opens or updates a Pull Request
↓
GitHub sends a webhook event to SecureFlow
↓
Octokit extracts the code diff (added/modified lines only)
↓
ArmorIQScanner sends the diff to Groq LLM with active policy context
↓
LLM returns structured findings (type, severity, file, snippet)
↓
For each finding → The Professor generates explanation + remediation steps
↓
Findings saved to PostgreSQL via Prisma — the Vault Logs
↓
Results posted as a GitHub PR comment + commit check status
↓
Everything visible on the SecureFlow Mission Control Dashboard
| Category | Examples |
|---|---|
| 🔑 Hardcoded Secrets | API keys, passwords, tokens committed in code |
| 📤 Contextual Leaks | console.log(process.env), logging sensitive objects |
| ⚙️ Misconfigurations | Wildcard CORS, disabled auth, insecure headers |
| 🧱 Code Vulnerabilities | SQL injection patterns, unsafe deserialization |
| ☁️ IaC Issues | Public S3 buckets, root container execution |
Before a PR diff is sent to the LLM, SecureFlow runs a rule-based secret scan
(src/lib/armor/secret-detector.ts) over the added lines only.
- Detects: AWS access key IDs, GitHub tokens, Slack tokens, PEM private key
headers, and high-entropy values assigned to secret-named variables
(
password,secret,token,apiKey). - Severity: every deterministic secret finding is
CRITICAL. - No false alarms on samples: values labelled
EXAMPLE/changeme, env lookups, and low-entropy values are not flagged. - Masked everywhere: stored findings, PR comments and dashboards only show a masked form of the value. The raw secret is never persisted or posted, and it is not part of the request sent to Groq.
- Merge and de-duplicate: if the LLM reports the same file and line as a deterministic finding, only one finding is shown (the deterministic one wins).
- Graceful degradation: if the LLM call fails or times out, the deterministic findings are still saved and reported.
Run its tests:
npx vitest run src/lib/armor/secret-detector.test.ts src/lib/armor/secret-detector.prescreen.test.ts src/lib/armor/secret-detector.llm-payload.test.ts
| Layer | Technology |
|---|---|
| Framework | Next.js 16 - App Router + Turbopack |
| Database | PostgreSQL + Prisma ORM |
| Authentication | NextAuth.js v5 with GitHub OAuth |
| AI / LLM | Groq SDK (openai/gpt-oss-20b) + Genkit |
| GitHub Integration | Octokit |
| UI | Tailwind CSS + Radix UI + Recharts |
secureflow/
├── docs/
│ ├── api.md # API route endpoints and specifications
│ ├── blueprint.md # Brand, style guidelines, and terminology dictionary
│ ├── runbook.md # Operations runbook for diagnosing failed scans and outages
│ └── security/
│ └── prompt-injection.md # Security controls and defenses for LLM prompt injections
│
├── prisma/
│ ├── migrations/ # Database migration history
│ ├── schema.prisma # Database schema (User, Repo, PR, Finding, etc.)
│ └── seed.ts # Seeds default security policy templates
│
├── src/
│ ├── ai/
│ │ └── flows/
│ │ └── developer-receives-ai-security-explanations.ts # The Professor's Genkit AI flow
│ │
│ ├── app/
│ │ ├── api/
│ │ │ ├── auth/ # NextAuth route handler
│ │ │ └── webhooks/
│ │ │ └── github/
│ │ │ └── route.ts # Main webhook handler (PR scanning logic)
│ │ │
│ │ ├── dashboard/
│ │ │ ├── audit/ # Vault Logs (audit log page)
│ │ │ ├── findings/ # Breach Attempts (security findings page)
│ │ │ ├── policies/ # Defense Strategy (policy management page)
│ │ │ └── page.tsx # Mission Control (main dashboard overview)
│ │ │
│ │ ├── login/ # Login page
│ │ └── setup/ # GitHub App installation setup page
│ │
│ ├── components/
│ │ ├── ui/ # Radix UI + shadcn components
│ │ └── dashboard-nav.tsx # Sidebar navigation
│ │
│ └── lib/
│ ├── armor/
│ │ ├── scanner.ts # ArmorIQScanner — core LLM scanning engine
│ │ └── iq.ts # ArmorIQ policy engine + evaluation logic
│ └── prisma.ts # Prisma client singleton
Make sure you have the following installed and ready before the heist begins:
- Node.js v20+
- PostgreSQL (local) or a free cloud DB (Neon / Supabase)
- A Groq API Key (free tier available)
- A GitHub Account to create a GitHub App
- Fork the repo on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/secureflow.gitcd secureflownpm installcp .env.example .env
⚠️ Important: Fill in your.envfile. See Environment Variables Reference for details on each value.
SecureFlow requires a GitHub App to receive webhook events and post PR comments.
- Go to GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App
- Fill in the following:
- Homepage URL:
http://localhost:9002 - Webhook URL: Your public URL +
/api/webhooks/github(use ngrok for local dev:ngrok http 9002) - Webhook Secret: Any random string — copy it to
GITHUB_WEBHOOK_SECRETin.env
- Homepage URL:
- Set these Repository Permissions:
- Contents:
Read - Pull Requests:
Read & Write - Checks:
Read & Write
- Contents:
- Subscribe to these Webhook Events:
Pull requestInstallationInstallation repositories
- After creating the app:
- Copy the App ID →
GITHUB_APP_ID - Generate a Private Key → download the
.pemfile, copy its contents →GITHUB_PRIVATE_KEY - Create a Client ID & Secret under OAuth →
GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET
- Copy the App ID →
Option A — Local PostgreSQL (Development):
-- In psql or pgAdmin:
CREATE DATABASE secureflow;Set your local connection string in .env:
DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/secureflow"Option B — Production Serverless with Connection Pooling (Neon / PgBouncer):
In serverless environments (Next.js API routes on Vercel/AWS Lambda), multiple concurrent function instances spin up rapidly under heavy traffic. Without connection pooling, this can quickly exhaust PostgreSQL connection limits.
SecureFlow supports connection poolers (e.g. Neon Pooler or PgBouncer) paired with Prisma's native pg driver pool adapter (@prisma/adapter-pg).
Configure your production .env / environment settings with database connection strings:
# Standard / Direct Database connection string (Used by Prisma CLI for migrations & fallback)
DATABASE_URL="postgresql://neondb_owner:pass@ep-direct.c-9.us-east-1.aws.neon.tech/neondb?sslmode=verify-full"
# Application Runtime Query Pooler URL (Optional: PgBouncer / Neon connection pooler)
DATABASE_POOL_URL="postgresql://neondb_owner:pass@ep-pooler.c-9.us-east-1.aws.neon.tech/neondb?sslmode=verify-full"
# Optional: Max connections per serverless function instance pool (default: 10)
DB_POOL_MAX=10💡 Why database pooler? SecureFlow uses
DATABASE_POOL_URLfor application runtime queries in serverless production environments while Prisma CLI migrations automatically useDATABASE_URL(direct connection string).
Then run database setup:
- Generate Prisma Client
npm run db:gen- Apply migrations (creates all tables using
DATABASE_URL)
npm run db:migrate- Seed default security policy templates
npm run db:seednpm run devOpen http://localhost:9002 in your browser.
- Sign in with GitHub
- Install the GitHub App on your repositories via the Setup page
- Open a Pull Request on any linked repo to trigger a scan — and let The Professor take it from there
Optional — Genkit AI dev environment (for working on AI explanation flows):
npm run genkit:dev- Copy
.env.exampleto.envand fill in values (note:DATABASE_URLis auto-set by compose) docker compose up --build- App runs at http://localhost:9002
SecureFlow's Docker image uses a secure multi-stage build running as an unprivileged user:
- Non-root execution: The final runtime container creates and runs under the unprivileged
nextjsuser (UID 1001,GID 1001), ensuring processes never run asroot(id verifies non-zero UID). - Multi-stage isolation: Build tools and dev dependencies are discarded; only the Next.js standalone bundle, public assets, and production client artifacts are included.
- Built-in HEALTHCHECK: Container liveness is continuously monitored via a native
HEALTHCHECKdirective. - Database migrations: Managed cleanly via dedicated one-shot migrator or Kubernetes hooks with non-root privileges.
| Variable | Required | Description |
|---|---|---|
DATABASE_URL |
✅ | PostgreSQL connection string (Direct/Standard) |
DATABASE_POOL_URL |
⬜ | Recommended for production serverless connection pooler (PgBouncer/Neon Pooler) |
DB_POOL_MAX |
⬜ | Max connections per serverless function instance (default: 10) |
GROQ_API_KEY |
✅ | API key from console.groq.com |
GITHUB_APP_ID |
✅ | Numeric ID of your GitHub App |
GITHUB_WEBHOOK_SECRET |
✅ | Secret used to verify webhook payloads |
GITHUB_PRIVATE_KEY |
✅ | RSA private key from your GitHub App (.pem contents) |
GITHUB_APP_URL |
✅ | Public URL of your GitHub App (e.g. https://github.com/apps/your-app) |
GITHUB_CLIENT_ID |
✅ | OAuth Client ID for GitHub login |
GITHUB_CLIENT_SECRET |
✅ | OAuth Client Secret for GitHub login |
AUTH_SECRET |
✅ | Random secret for NextAuth session encryption — generate with openssl rand -base64 32 |
ARMORIQ_API_KEY |
⬜ | Optional — ArmorIQ SDK key for advanced policy features |
USER_ID |
⬜ | Optional — ArmorIQ user ID |
AGENT_ID |
⬜ | Optional — ArmorIQ agent ID |
TRUSTED_PROXY_HOP_COUNT |
⬜ | Trusted proxies in front of the app (default: 0). Set 1 behind a single proxy — see below |
TRUSTED_PROXY_IPS |
⬜ | Optional — comma-separated proxy addresses / IPv4 CIDRs, used instead of a fixed hop count |
DATA_RETENTION_DAYS |
⬜ | Optional — Auto-cleanup older findings, scans, and audit logs (default: unset / keep forever) |
SCAN_CACHE_TTL_SECONDS |
⬜ | Scan deduplication cache TTL in seconds (default: 86400 / 24 hours) |
Rate limits are bucketed per client IP, and that IP is derived from
X-Forwarded-For. Because any caller can put whatever they like at the front of
that header, the app has to know how many hops in front of it are actually
trustworthy — otherwise a caller can vary the header and land in a fresh bucket
on every request, which makes every rate limit unenforceable.
Set TRUSTED_PROXY_HOP_COUNT to the number of proxies between the internet and
the app:
| Deployment | Value |
|---|---|
| Vercel / Render / Fly / a single nginx | 1 |
| Cloudflare in front of one of the above | 2 |
| App exposed directly, no proxy | 0 (the default) |
With 0 (or when the variable is unset), the forwarding headers are ignored
entirely — nothing in front of the app is authoritative, so nothing in them is
believed. Every caller then shares one rate-limit bucket, so behind a proxy
you must set this, or one busy client throttles everyone. The app logs a
one-time warning when it sees forwarding headers with the variable unset.
If the hop count varies (multiple ingress paths), set TRUSTED_PROXY_IPS
instead — e.g. TRUSTED_PROXY_IPS=10.0.0.0/8,192.168.1.1. The chain is then
walked from the right past known proxies rather than counting a fixed number of
hops. IPv4 CIDR blocks and bare addresses are supported; IPv6 entries are matched
exactly.
Findings and audit logs accumulate over time. Self-hosters can bound storage growth by configuring DATA_RETENTION_DAYS:
# Optional: Auto-cleanup findings and audit logs older than N days (off by default)
DATA_RETENTION_DAYS=90Retention operations can be executed via the unified CLI script:
- CLI Dry Run (default):
npm run retention(reports eligible counts without modifying the database) - CLI Applied Deletion:
npm run retention -- --apply(purges eligible older records in batches) - CLI Custom Window:
npm run retention -- --days=30 --apply - CLI Custom Batch Size:
npm run retention -- --batch-size=200 --apply - CLI Target Isolation:
npm run retention -- --only=auditLog --apply
🛡️ Safety Guarantee: The retention cleanup strictly deletes older
Finding,ScanResult, andAuditLogrows in safe batches. It never deletes users, repositories, or policies.
| Script | Description |
|---|---|
npm run dev |
Start dev server on port 9002 with Turbopack |
npm run build |
Build for production |
npm run start |
Start production server |
npm run lint |
Run ESLint |
npm run typecheck |
Run TypeScript compiler checks |
npm run db:gen |
Generate Prisma Client |
npm run db:migrate |
Run Prisma migrations |
npm run db:push |
Push schema to DB without migrations |
npm run db:seed |
Seed default policy templates |
npm run genkit:dev |
Start Genkit AI development environment |
npm run retention |
Unified data retention runner (dry-run default; pass -- --apply to delete) |
SecureFlow ships with pre-built policy templates that are seeded into the database. Users can toggle them on/off from the dashboard — think of it as briefing the crew before every job.
| Policy | Severity | Default |
|---|---|---|
| Enforce Parameterized Queries | HIGH | ✅ On |
| Prevent PII Logging | CRITICAL | Off |
| Block Internal Network Requests (SSRF) | HIGH | Off |
| Enforce Strict CORS Policies | MEDIUM | Off |
| Prevent Unsafe Deserialization | CRITICAL | Off |
| Deprecate Weak Hashing Algorithms | HIGH | Off |
| Deny Public Cloud Storage | CRITICAL | Off |
| Prevent Root Execution in Containers | MEDIUM | Off |
| Enforce Smart Contract Reentrancy Guards | CRITICAL | Off |
The architecture follows a modern Next.js full-stack approach with real-time GitHub integration:
- Frontend: Next.js App Router with Tailwind CSS for the Mission Control dashboard
- Backend: API routes handle authentication, webhooks, and business logic
- AI Layer: Groq SDK processes code diffs through GPT-OSS-20B model — The Professor's brain
- Database: PostgreSQL with Prisma ORM for data persistence — the Vault Logs
- GitHub Integration: Octokit manages webhooks, PR comments, and checks
For more in-depth details about the architecture, developer API, and security practices of SecureFlow, check out:
- Local Development Setup: Step-by-step guide to acquiring every credential (Prisma/PostgreSQL, Groq, GitHub App, GitHub OAuth/NextAuth, Redis) needed to run SecureFlow locally.
- Kubernetes Deployment & Egress Hardening: Production deployment architecture, zero-trust network policies, and egress rule whitelisting for backend worker pods.
- System Blueprint: Explains the application blueprint, core capabilities, style guidelines, visual tokens, and heist-themed copywriting dictionary.
- API Reference: Provides exhaustive details on HTTP endpoints, authentication, rate limits, error formats, and system types.
- AI Security & Prompt Injection Defense: Documents the threat vector, policy isolation boundaries, pre-filtering layers, and UI indicators used to protect against LLM prompt injection attacks.
- Threat Intelligence MCP Server: Guide to connecting IDE agents (Cursor, Claude Desktop, Windsurf) to the SecureFlow CLI MCP server with ArmorIQ cryptographic intent verification.
- Local Inference & VRAM Guide: Hardware/VRAM requirements, memory management, and environment variables for air-gapped scanning with local Ollama and vLLM models.
- Operator Runbook: Operational troubleshooting guide for scan outages, webhook delivery failures, queue/Redis stalls, Groq rate limits, database pooling errors, and proxy configuration.
- Status Badge: Embed a live SVG badge in your README showing the latest scan status.
Add a live security-status badge to your repository README:
The badge reflects the latest scan: passing (green), review required (yellow), blocked (red), or unknown (grey). Enable it in your repository settings — see the Status Badge docs for details.
Every good heist needs a crew. Contributions are welcome! Please read CONTRIBUTING.md for guidelines on branching, commit messages, and the PR process.
# Create a branch following the naming convention
git checkout -b fix/your-issue-name # bug fix
git checkout -b feat/your-feature # new feature
git checkout -b docs/update-readme # documentationUse Conventional Commits for commit messages:
git commit -m "fix: description of what you fixed"
git commit -m "feat: description of new feature"
git commit -m "docs: description of documentation change"How does SecureFlow protect my secrets? SecureFlow uses AI to detect hardcoded secrets and sensitive data in your code. It's designed to catch API keys, passwords, tokens, and other credentials that might accidentally be committed to your repository.
Can I customize the scanning rules? Yes! You can create, toggle, and manage custom policies through the dashboard. This allows you to enforce organization-specific security rules.
Is my data sent to external services? Your code diffs are sent to Groq's LLM service for analysis. We do not store your code or share it with third parties. The service is compliant with data protection standards.
How much does it cost to use SecureFlow? SecureFlow is open-source and free to self-host. You'll need a Groq API key (free tier available) and your own PostgreSQL database.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ to make every Pull Request safer.
"The vault is empty. Zero traces left behind." — every clean audit, thanks to The Professor.
⭐ Star us on GitHub — it helps!
