"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.
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.
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 |
| 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
│ └── 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
| 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 |
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.
| 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 |
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.
- 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.
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!