🛡️ SecureFlow

AI-Powered GitHub Pull Request Security Scanner

Automatically detect vulnerabilities, hardcoded secrets, and code flaws before they reach production.

---

📋 Table of Contents

Click to expand

- [🌟 Features](#-features) - [🧠 How It Works](#-how-it-works) - [🛠️ Tech Stack](#️-tech-stack) - [📁 Project Structure](#-project-structure) - [🚀 Getting Started](#-getting-started) - [Prerequisites](#prerequisites) - [1. Fork & Clone](#1-fork--clone) - [2. Environment Variables](#2-environment-variables) - [3. GitHub App Setup](#3-github-app-setup) - [4. Database Setup](#4-database-setup) - [5. Run the App](#5-run-the-app) - [Docker Setup](#-docker-setup)

• 🔑 Environment Variables Reference
• 📝 Available Scripts
• 🔒 Security Policies
• 📊 Architecture
• 🤝 Contributing
• ❓ FAQ
• 📄 License

---

SecureFlow integrates directly with GitHub via a GitHub App and webhooks. Every time a Pull Request is opened or updated, it extracts the code diff, runs it through Groq's LLM (Llama 3.1), and generates actionable security findings with AI-written explanations and remediation steps — all visible on a centralized dashboard.

🤖 AI-Powered Detection

Uses Groq's Llama 3.1 to detect hardcoded secrets, vulnerabilities, and misconfigurations in your code.

⚡ Real-time Scanning

Automatically scans every opened or updated Pull Request as soon as it's created.

🛡️ Smart Remediation

Generates precise explanations and concrete code fixes for each security finding.

📊 Centralized Dashboard

View all your repositories, PRs, findings, and audit logs in one unified interface.

💬 GitHub PR Comments

Posts detailed security reports directly on your PRs with collapsible remediation blocks.

✅ GitHub Check Runs

Sets Pass/Review Required/Blocked status on PR commits for clear CI/CD integration.

🎯 Custom Policies

Create, toggle, and manage security policies per user or organization.

🚫 Smart Exclusions

Intelligently ignores non-executable files and mock placeholders to reduce noise.

---

🧠 How It Works

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 → AI generates explanation + remediation steps
              ↓
Findings saved to PostgreSQL via Prisma
              ↓
Results posted as a GitHub PR comment + commit check status
              ↓
Everything visible on the SecureFlow Dashboard

What Gets Detected

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

---

🛠️ Tech Stack

Layer	Technology
Framework	Next.js 15 - App Router + Turbopack
Database	PostgreSQL + Prisma ORM
Authentication	NextAuth.js v5 with GitHub OAuth
AI / LLM	Groq SDK (llama-3.1-8b-instant) + Genkit
GitHub Integration	Octokit
UI	Tailwind CSS + Radix UI + Recharts

---

📁 Project Structure

secureflow/
├── 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  # Genkit AI flow
│   │
│   ├── app/
│   │   ├── api/
│   │   │   ├── auth/            # NextAuth route handler
│   │   │   └── webhooks/
│   │   │       └── github/
│   │   │           └── route.ts # Main webhook handler (PR scanning logic)
│   │   │
│   │   ├── dashboard/
│   │   │   ├── audit/           # Audit log page
│   │   │   ├── findings/        # Security findings page
│   │   │   ├── policies/        # Policy management page
│   │   │   └── page.tsx         # 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

---

🚀 Getting Started

Prerequisites

Make sure you have the following installed and ready:

• 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

---

1. Fork & Clone

# Fork the repo on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/secureflow.git
cd secureflow
npm install

---

2. Environment Variables

cp .env.example .env

⚠️ Important: Fill in your .env file. See Environment Variables Reference for details on each value.

---

3. GitHub App Setup

SecureFlow requires a GitHub App to receive webhook events and post PR comments.

1. Go to GitHub → Settings → Developer Settings → GitHub Apps → New GitHub App
2. 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_SECRET in .env
3. Set these Repository Permissions:
   • Contents: Read
   • Pull Requests: Read & Write
   • Checks: Read & Write
4. Subscribe to these Webhook Events:
   • Pull request
   • Installation
   • Installation repositories
5. After creating the app:
   • Copy the App ID → GITHUB_APP_ID
   • Generate a Private Key → download the .pem file, copy its contents → GITHUB_PRIVATE_KEY
   • Create a Client ID & Secret under OAuth → GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET

---

4. Database Setup

Option A — Local PostgreSQL:

-- In psql or pgAdmin:
CREATE DATABASE secureflow;

Then set DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/secureflow" in .env

Option B — Free Cloud DB (easier):

• Sign up at neon.tech or supabase.com
• Create a new project and copy the connection string directly into DATABASE_URL

Then run:

# Generate Prisma Client
npm run db:gen

# Apply migrations (creates all tables)
npm run db:migrate

# Seed default security policy templates
npm run db:seed

---

5. Run the App

npm run dev

Open 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

Optional — Genkit AI dev environment (for working on AI explanation flows):

npm run genkit:dev

---

🐳 Docker Setup

1. Copy .env.example to .env and fill in values (note: DATABASE_URL is auto-set by compose)
2. docker compose up --build
3. App runs at http://localhost:9002

---

🔑 Environment Variables Reference

Variable	Required	Description
DATABASE_URL	✅	PostgreSQL connection string
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

---

📝 Available Scripts

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

---

🔒 Security Policies

SecureFlow ships with pre-built policy templates that are seeded into the database. Users can toggle them on/off from the dashboard.

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

---

📊 Architecture

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 dashboard
• Backend: API routes handle authentication, webhooks, and business logic
• AI Layer: Groq SDK processes code diffs through Llama 3.1 model
• Database: PostgreSQL with Prisma ORM for data persistence
• GitHub Integration: Octokit manages webhooks, PR comments, and checks

---

🤝 Contributing

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    # documentation

Use 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"

---

❓ FAQ

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.

---

Built with ❤️ to make every Pull Request safer.

⭐ Star us on GitHub — it helps!

Report Bug · Request Feature · View Demo