🛡️ DevShield

AI-Powered Continuous Security for GitHub

DevShield is a full-stack security workspace for GitHub repositories. It combines source-code security scanning, dependency analysis, AI-assisted vulnerability explanation, safe patch generation, patch validation, Patch-to-PR automation, and continuous Pull Request security.

Protect every commit. 🔐

DevShield is built as a college/portfolio-ready security engineering project, but its architecture is intentionally close to a production workflow: GitHub App → signed webhook → PostgreSQL job queue → scanner → AI analyst → safety gates → GitHub PR.

---

✨ Features

Feature	What it does
🔍 Repository Scanner	Scans source files for common security-risk patterns.
📦 Dependency Scanner	Reads GitHub Dependabot alerts and summarizes dependency risk.
🤖 AI Security Analyst	Explains vulnerabilities, reasons about severity, and recommends remediation.
🛠️ AI Patch Engine	Generates focused patch operations and applies safety validation before GitHub changes.
🧪 Patch Validation	Rejects unsafe paths/content and supports test/CI verification gates.
🔀 Patch-to-PR	Creates a branch, commits the patch, pushes it, and opens a GitHub Pull Request.
⚡ Automatic PR Security	GitHub PR webhooks queue security scans automatically.
🪝 Signed Webhooks	Verifies X-Hub-Signature-256 before accepting GitHub events.
👷 Background Worker	Processes queued PR security jobs through /api/jobs/worker.
⚙️ Security Settings	Controls AI review, automatic patching, PR scanning, and validation policy.
📊 Security Dashboard	Shows score, findings, dependencies, PRs, history, and reports.
🐳 Docker Support	Runs the Next.js app, PostgreSQL, and worker with Docker Compose.

---

🧠 Architecture

                         ┌──────────────────────┐
                         │     GitHub App       │
                         │ Installation + Auth  │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │ Signed GitHub Webhook│
                         │ /api/webhooks/github │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │ PostgreSQL Job Queue  │
                         │       Prisma         │
                         └──────────┬───────────┘
                                    │
                                    ▼
                         ┌──────────────────────┐
                         │   DevShield Worker   │
                         └──────────┬───────────┘
                                    │
                         ┌──────────┴───────────┐
                         ▼                      ▼
                ┌─────────────────┐    ┌─────────────────┐
                │ Source Scanner  │    │ Dependency Scan │
                └────────┬────────┘    └────────┬────────┘
                         └──────────┬───────────┘
                                    ▼
                         ┌──────────────────────┐
                         │ AI Security Analyst  │
                         │ Explain • Severity   │
                         │ Remediation • Context│
                         └──────────┬───────────┘
                                    ▼
                         ┌──────────────────────┐
                         │    AI Patch Engine   │
                         │ Generate • Validate  │
                         │ Test • Safety Gate   │
                         └──────────┬───────────┘
                                    ▼
                         ┌──────────────────────┐
                         │     Patch-to-PR      │
                         │ Branch • Commit • PR │
                         └──────────────────────┘

---

🚀 Phase 2 → Phase 5

🤖 Phase 2 — AI Security Analyst

• Vulnerability explanation
• Severity reasoning
• Remediation suggestions
• Repository/file context

🛠️ Phase 3 — AI Patch Engine

• Generate patch
• Validate patch
• Test/CI safety gate
• Reject unsafe patch operations

🔀 Phase 4 — Patch-to-PR

• Create Git branch
• Commit changes
• Push branch
• Create GitHub Pull Request
• Add a DevShield security report to the PR

⚡ Phase 5 — Automatic PR Security

• Receive GitHub pull_request webhooks
• Verify webhook signatures
• Queue PR scan jobs in PostgreSQL
• Worker processes queued jobs
• Scan source/dependencies
• Review the PR with DevShield

---

🖥️ Screenshots

🏠 Security Dashboard

The dashboard is the central workspace for repository scans, security score, findings, AI remediation, dependencies, and Pull Requests.

🤖 AI Security Finding

Open a finding to inspect severity, impact, recommended remediation, and AI actions such as explanation and patch generation.

⚙️ Security Settings

Configure AI analysis, automatic patch generation, PR scanning, and patch-validation policy.

---

🧰 Tech Stack

Frontend

• ⚛️ React 19
• ▲ Next.js 16 App Router
• 🟦 TypeScript
• 🎨 Tailwind CSS
• ✨ Framer Motion
• 🎯 Lucide React

Backend

• 🟢 Next.js Route Handlers
• 🐘 PostgreSQL
• 🔷 Prisma ORM
• 🪝 GitHub Webhooks
• 🔐 GitHub App authentication
• 🍪 HTTP-only encrypted sessions with iron-session

AI

• 🤖 OpenRouter by default
• 🔌 OpenAI-compatible providers
• 🧠 Configurable model/base URL
• 🛡️ AI explanation and remediation
• 🛠️ AI patch generation

Infrastructure

• 🐳 Docker + Docker Compose
• 👷 PostgreSQL-backed worker queue
• 🌐 ngrok for local webhook development
• ✅ Vitest + GitHub Actions CI

---

📋 Requirements

You can run DevShield locally with Node.js + PostgreSQL, or use Docker Compose for the database and application stack.

1. Node.js

Use Node.js 20 LTS or newer.

• Official download: https://nodejs.org/
• Check installation:

node --version
npm --version

2. Git

• Official download: https://git-scm.com/downloads

git --version

3. Docker Desktop

Recommended for the easiest full-stack setup.

• Official download: https://www.docker.com/products/docker-desktop/

docker --version
docker compose version

4. GitHub

You need a GitHub account and a repository for testing.

• GitHub: https://github.com/
• GitHub Apps: https://github.com/settings/apps
• GitHub App documentation: https://docs.github.com/en/apps

5. ngrok

Required only when GitHub needs to reach a development server running on your computer.

• Official download: https://ngrok.com/download
• Documentation: https://ngrok.com/docs

---

📥 Installation

Step 1 — Clone the repository

Use your actual GitHub repository URL:

git clone <YOUR_GITHUB_REPOSITORY_URL>
cd DevShield

If your repository folder has a different name, use that folder name in cd.

Step 2 — Install dependencies

For a clean, reproducible install:

npm ci

Use npm install only when you intentionally want npm to update the lockfile.

Step 3 — Create .env

Copy-Item .env.example .env
notepad .env

Never commit .env. The repository contains .env.example only.

---

🔐 Environment Variables

The example file is intentionally safe to publish:

# Database
DATABASE_URL="postgresql://devshield:devshield_local@localhost:5432/devshield"

# Session security
SESSION_SECRET=""

# GitHub App
GITHUB_APP_ID=""
GITHUB_APP_SLUG=""
GITHUB_APP_PRIVATE_KEY=""
GITHUB_WEBHOOK_SECRET=""

# Optional GitHub OAuth
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

# AI provider
AI_PROVIDER="openrouter"
AI_API_KEY=""
AI_BASE_URL="https://openrouter.ai/api/v1"
AI_MODEL="openai/gpt-4o-mini"
AI_HTTP_REFERER="http://localhost:3000"
AI_APP_NAME="DevShield"

# Background worker
WORKER_SECRET=""

# Development-only personal token fallback
ALLOW_DEV_GITHUB_TOKEN="false"

🔑 Generate safe local secrets

Run:

npm run setup:secrets

This generates values for:

• SESSION_SECRET
• WORKER_SECRET
• GITHUB_WEBHOOK_SECRET

Paste the generated values into your local .env file.

🚨 Never commit these values

Never publish:

• AI_API_KEY
• GITHUB_APP_PRIVATE_KEY
• GITHUB_CLIENT_SECRET
• GITHUB_WEBHOOK_SECRET
• SESSION_SECRET
• WORKER_SECRET
• GitHub personal access tokens
• .pem/private-key files
• production database credentials

---

🐘 Database Setup

Option A — Docker Compose

Start PostgreSQL:

docker compose up -d db

Check it:

docker compose ps

Option B — Local PostgreSQL

Install PostgreSQL from:

https://www.postgresql.org/download/

Create a database named devshield, then set:

DATABASE_URL="postgresql://USERNAME:PASSWORD@localhost:5432/devshield"

---

🗄️ Prisma Setup

Generate Prisma Client:

npx prisma generate

Apply the development migration:

npx prisma migrate dev --name init

For an existing production database with committed migrations:

npx prisma migrate deploy

If Prisma reports Environment variable not found: DATABASE_URL, make sure .env exists in the project root and contains a valid DATABASE_URL.

• Prisma docs: https://www.prisma.io/docs

---

🐙 GitHub App Setup

DevShield's production workflow uses a GitHub App. This is preferable to putting a personal access token into the application because GitHub App installation tokens are short-lived and scoped to the installation.

Step 1 — Create the App

Open:

https://github.com/settings/apps/new

Suggested name:

DevShield Security

For local development, use the ngrok HTTPS URL after starting the application.

Step 2 — Configure the App

Homepage URL

https://YOUR-NGROK-DOMAIN.ngrok-free.app

Callback URL

https://YOUR-NGROK-DOMAIN.ngrok-free.app/api/github/app/callback

Webhook URL

https://YOUR-NGROK-DOMAIN.ngrok-free.app/api/webhooks/github

Webhook content type

application/json

Webhook secret

Use the exact value from:

GITHUB_WEBHOOK_SECRET="..."

Step 3 — Repository permissions

For the complete DevShield workflow, use the minimum permissions required by your enabled features. A typical setup is:

Permission	Access
Contents	Read & write
Metadata	Read-only
Pull requests	Read & write
Checks	Read-only
Dependabot alerts	Read-only

GitHub permissions reference: https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps

Step 4 — Subscribe to events

Enable:

• Pull request
• Installation (recommended)

Step 5 — Generate the private key

After creating the App, generate a private key from the GitHub App settings.

Set:

GITHUB_APP_ID="YOUR_APP_ID"
GITHUB_APP_SLUG="YOUR_APP_SLUG"
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_KEY\n-----END PRIVATE KEY-----"

Do not paste the real private key into this README or into GitHub.

Step 6 — Install the App

Install DevShield on the test repository/repositories you want it to protect.

• GitHub App installation docs: https://docs.github.com/en/apps/using-github-apps/installing-a-github-app

---

🌐 Local Webhook Development with ngrok

GitHub cannot send a webhook directly to localhost. Use ngrok to expose port 3000 through HTTPS.

Install ngrok

Official instructions: https://ngrok.com/download

After installing ngrok on Windows, close PowerShell and open a new PowerShell window so the updated PATH is loaded.

Check:

ngrok version

Then:

ngrok http 3000

If Windows still says ngrok is not recognized, open a fresh terminal. The installer may have updated PATH only for new shells.

Copy the HTTPS forwarding URL, for example:

https://example.ngrok-free.app

Then use:

https://example.ngrok-free.app/api/webhooks/github

as the GitHub App webhook URL.

⚠️ The ngrok URL can change between sessions on some plans. Update the GitHub App webhook URL whenever your public URL changes.

---

🤖 AI Provider Setup

OpenRouter is the recommended default.

OpenRouter

1. Create an account: https://openrouter.ai/
2. Create an API key: https://openrouter.ai/keys
3. Put the key only in .env:

AI_PROVIDER="openrouter"
AI_API_KEY="YOUR_OPENROUTER_KEY"
AI_BASE_URL="https://openrouter.ai/api/v1"
AI_MODEL="openai/gpt-4o-mini"
AI_HTTP_REFERER="http://localhost:3000"
AI_APP_NAME="DevShield"

4. Restart DevShield.
5. Open http://localhost:3000/setup.
6. Click Test AI connection.

OpenRouter documentation: https://openrouter.ai/docs

Model availability and pricing can change. If a model becomes unavailable, select a currently supported model and update AI_MODEL.

---

▶️ Run DevShield Locally

Start the database first:

docker compose up -d db

Generate Prisma Client and apply migrations:

npx prisma generate
npx prisma migrate dev --name init

Start Next.js:

npm run dev

Open:

• Dashboard: http://localhost:3000
• Setup: http://localhost:3000/setup
• Settings: http://localhost:3000/settings
• Health: http://localhost:3000/api/health

---

🐳 Run the Full Stack with Docker

This is the recommended way to reproduce the complete local stack.

docker compose up -d --build

The Compose stack contains:

• 🐘 db — PostgreSQL
• 🌐 app — DevShield Next.js application
• 👷 worker — background job runner

Check status:

docker compose ps

View all logs:

docker compose logs -f

View application logs:

docker compose logs -f app

View worker logs:

docker compose logs -f worker

Stop:

docker compose down

Stop and delete the PostgreSQL volume:

docker compose down -v

⚠️ docker compose down -v deletes the local PostgreSQL volume and its data.

---

👷 Background Worker

The worker endpoint is:

POST /api/jobs/worker

Protect it with:

WORKER_SECRET="YOUR_RANDOM_WORKER_SECRET"

Manual PowerShell test:

$headers = @{ Authorization = "Bearer $env:WORKER_SECRET" }
Invoke-WebRequest -Method POST http://localhost:3000/api/jobs/worker -Headers $headers

For production, call the endpoint from a trusted scheduler such as GitHub Actions, cron, or your container platform.

Never expose the endpoint without WORKER_SECRET in production.

---

🧪 Testing

Run the test suite:

npm test

Watch mode:

npm run test:watch

Production build:

npx prisma generate
npm run build

Start the production build:

npm start

CI is defined in:

.github/workflows/ci.yml

The CI workflow runs:

1. npm ci
2. npx prisma generate
3. npm test
4. npm run build

---

🧪 End-to-End Test Plan

Use a disposable test repository when testing patch creation and automatic PR security.

Test 1 — Repository scan

1. Start DevShield.
2. Open http://localhost:3000.
3. Enter a public GitHub repository.
4. Click Scan repository.
5. Confirm the scan completes.
6. Check the score and findings.

Test 2 — AI explanation

1. Open a finding.
2. Click Explain with AI.
3. Confirm the AI response contains an explanation and remediation guidance.

Test 3 — AI patch

1. Open a suitable finding.
2. Click Generate patch.
3. Confirm the patch is returned.
4. Confirm unsafe patch operations are rejected.
5. Review the proposed changes before creating a PR.

Test 4 — Patch-to-PR

1. Connect the GitHub App.
2. Install it on a disposable test repository.
3. Generate a safe patch.
4. Click Patch → PR.
5. Confirm a devshield/... branch is created.
6. Confirm the commit is pushed.
7. Confirm a GitHub Pull Request is opened.
8. Confirm the DevShield security report appears in the PR.

Test 5 — Automatic PR security

1. Create a test branch.
2. Make a harmless security-test change.
3. Push the branch.
4. Open a Pull Request.
5. Confirm GitHub sends the webhook.
6. Confirm a PR_SCAN job appears in PostgreSQL.
7. Run the worker.
8. Confirm the PR scan completes.
9. Confirm the security review/report is produced.

---

🔍 Useful Commands

# Install dependencies
npm ci

# Generate Prisma Client
npx prisma generate

# Validate Prisma schema
npx prisma validate

# Create/apply a development migration
npx prisma migrate dev --name init

# Run tests
npm test

# Run the application in development
npm run dev

# Build production
npm run build

# Start production
npm start

# Generate local secrets
npm run setup:secrets

# Docker
Docker compose up -d --build
docker compose ps
docker compose logs -f
docker compose down

PowerShell command names are case-insensitive, but docker compose is the standard spelling used throughout this README.

---

🔐 Security Checklist Before Publishing

Before pushing DevShield to GitHub:

• .env is ignored.
• .env.example contains placeholders only.
• GitHub App private key is not included.
• AI API keys are not included.
• GitHub OAuth client secret is not included.
• Worker/session/webhook secrets are not included.
• Private-key file patterns are ignored.
• node_modules is ignored.
• .next is ignored.
• Docker build context excludes local dependencies/build output.
• Prisma migrations are committed.
• GitHub Actions uses repository secrets for the worker URL/secret.
• Webhook signatures are verified server-side.
• Production sessions require a strong SESSION_SECRET.

If a secret was ever committed to Git, deleting the file is not enough. Revoke/rotate the secret and remove it from Git history before publishing.

---

📁 Project Structure

DevShield/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── worker.yml
├── app/
│   ├── api/
│   │   ├── ai/
│   │   ├── auth/
│   │   ├── github/
│   │   ├── jobs/
│   │   ├── patch-to-pr/
│   │   ├── patch/
│   │   ├── prs/
│   │   ├── scan/
│   │   └── webhooks/
│   ├── settings/
│   ├── setup/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   └── DevShield.tsx
├── docs/
│   └── screenshots/
├── lib/
│   ├── ai.ts
│   ├── db.ts
│   ├── dependency-scanner.ts
│   ├── github-api.ts
│   ├── github-app.ts
│   ├── patch-engine.ts
│   ├── pr-review.ts
│   ├── queue.ts
│   ├── scanner.ts
│   ├── security-scanner.ts
│   ├── session.ts
│   └── webhook.ts
├── prisma/
│   ├── migrations/
│   └── schema.prisma
├── scripts/
│   └── generate-secrets.mjs
├── tests/
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── .env.example
├── .gitignore
└── README.md

---

📚 Documentation

• GitHub + AI setup
• Security hardening
• Project phases
• Dependency scanner
• Prisma documentation
• Next.js documentation
• GitHub Apps documentation
• GitHub Webhooks documentation
• OpenRouter documentation
• Docker Compose documentation
• ngrok documentation

---

🚀 Publishing to GitHub

1. Create the repository

On GitHub, create a new repository named DevShield (or your preferred name).

GitHub repository creation: https://github.com/new

Do not upload .env or any real credentials.

2. Initialize Git locally

From the DevShield project folder:

git init
git branch -M main
git add .
git status

Review git status carefully. You should not see:

.env
node_modules/
.next/
*.pem
*.key

Then commit:

git commit -m "feat: publish DevShield v8.1"

3. Connect the GitHub repository

git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPOSITORY.git
git remote -v

4. Push

git push -u origin main

5. Verify the published repository

Open the repository in your browser and confirm:

• README screenshots render.
• .env is absent.
• No private key is present.
• No API key is present.
• GitHub Actions starts successfully.
• The repository contains prisma/migrations/.

---

⚠️ If a Secret Was Accidentally Committed

Immediately revoke/rotate the credential.

Examples:

• OpenRouter: https://openrouter.ai/keys
• GitHub Apps: https://github.com/settings/apps

Then remove the secret from Git history using a tool such as git filter-repo or BFG Repo-Cleaner, force-push the cleaned history, and verify the old credential no longer works.

For GitHub-specific secret scanning and remediation: https://docs.github.com/en/code-security/secret-scanning

---

📄 License

DevShield is released under the MIT License.

---

⭐ DevShield

Detect. Explain. Patch. Validate. Protect. 🛡️

Built with Next.js, TypeScript, PostgreSQL, Prisma, GitHub Apps, Docker, and AI.