🍔 Deburger

Deburger is a terminal-native CLI that answers one critical question:

What breaks the business first if this code fails?

It is not a SAST replacement.
It is the decision layer before SAST.

---

🎯 What Problem It Solves

Modern SAST tools:

• Generate hundreds of findings
• Treat all issues as equal
• Lack business or failure impact context

Teams know what is wrong
They do not know what to fix first

---

✨ What Deburger Does

Deburger analyzes a codebase and outputs:

• Only the top 10 issues
• Ranked by failure impact
• Explained in business consequences

It focuses on:

• Failure-prone areas
• Single-point-of-failure logic
• Risk concentration, not volume

---

🏗️ Architecture

Deburger operates as a decision layer on top of SAST:

┌───────────────────────────┐
│     Project Codebase      │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│      Semgrep Runner       │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│       Raw Findings        │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│    Findings Normalizer    │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│    Gemini AI Reasoner     │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│   Prioritization Engine   │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│  Fix Generator (optional) │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│   CLI Output / Results    │
└───────────────────────────┘

---

🚀 Installation

Prerequisites

• Node.js >= 16
• Semgrep (for scanning)
• Google Gemini API Key (for AI analysis)

Install Semgrep

macOS:

brew install semgrep

Linux/Other:

pip install semgrep

Install Deburger

npm install -g deburger

Or clone and build:

git clone <repository-url>
cd deburger
npm install
npm run build

---

📖 Usage

Initialize Identity

First, set up your identity:

deburger init

Scan and Analyze

Run a complete scan and analysis:

# Analyze current directory
deburger scan

# Analyze a specific directory
deburger scan ./path/to/project

# With project name
deburger scan --project my-project

Analyze Existing Findings

If you already have a findings.json file:

deburger analyze

# Or specify a file
deburger analyze findings.json

Project Management

# Create a project
deburger project create my-project

Integrations

Configure integrations:

# Configure Jira
deburger config jira

# Configure ClickUp
deburger config clickup

Create issues/tasks after analysis:

deburger scan --create-jira
deburger scan --create-clickup

---

🔧 Configuration

Environment Variables

Create a .env file in your project root or ~/.deburger/.env:

# Required for AI analysis
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-1.5-pro

# Optional: Database persistence (MongoDB)
DATABASE_URL=mongodb://localhost:27017/deburger
# Or use MONGODB_URI for connection string format
MONGODB_URI=mongodb://user:pass@localhost:27017/deburger?authSource=admin
MONGODB_DB_NAME=deburger

# Optional: Jira integration
JIRA_DOMAIN=company.atlassian.net
JIRA_EMAIL=your@email.com
JIRA_API_TOKEN=your_jira_token
JIRA_PROJECT_KEY=PROJ

# Optional: ClickUp integration
CLICKUP_API_TOKEN=your_clickup_token
CLICKUP_LIST_ID=12345678

Getting a Gemini API Key

1. Go to Google AI Studio
2. Create a new API key
3. Add it to your .env file

---

🎨 Features

Business Impact Analysis

Deburger analyzes findings based on:

• Payment Processing: Stripe, PayPal, checkout flows
• Authentication: Login, JWT, session management
• Admin Functions: Dashboard, management interfaces
• Public APIs: Exposed endpoints, controllers, routes
• Database Operations: Data modifications, secrets, vaults
• Production Context: Production configs, environment variables

AI-Powered Prioritization

Uses Google Gemini AI to:

• Correlate related findings
• Estimate blast radius and failure propagation
• Explain why an issue matters
• Help decide what to fix first

Interactive Fix Generation

After analysis, Deburger can:

• Generate AI-powered code fixes
• Show fix explanations
• Apply fixes with your approval
• Suggest imports and dependencies

---

🎯 Core Principles

• Failure-first, not vulnerability-first: Focus on what breaks the business
• Forced prioritization: Top 10 issues only (by default)
• Business impact over technical noise: Real-world consequences matter
• Deterministic and auditable logic: Same input = same output
• Terminal-only workflow: No web UI, pure CLI

---

🔄 How It Fits With SAST

SAST tools

• Find what is wrong

Deburger

• Decides what matters first

Recommended flow:

Deburger → Decide priorities → SAST → Fix

---

🛠️ Development

Build

npm run build

Run Locally

npm run analyze

Project Structure

deburger/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── api.ts            # Programmatic API
│   ├── parser.ts         # Semgrep parser
│   ├── context.ts        # Business signal extraction
│   ├── gemini.ts         # Gemini AI integration
│   ├── ai.ts             # AI fix generation
│   ├── ui.ts             # Terminal UI
│   ├── db.ts             # Database operations
│   ├── identity.ts       # User identity management
│   ├── fixer.ts          # Code fix application
│   └── integrations/     # Jira, ClickUp
├── bin/
│   └── deburger.js       # CLI executable
└── dist/                 # Compiled output

---

📊 Output Format

Deburger displays:

1. Top 10 Risks with:

   • Business impact explanation
   • Technical reason
   • Remediation steps
   • Code snippets
   • Location and confidence

2. Additional Findings in a summary table

3. Interactive Fix Flow for selected findings

---

⚙️ Technical Details

Analysis Pipeline

1. Semgrep scans the codebase
2. Findings are normalized into unified format
3. Context enrichment extracts business signals
4. Gemini AI analyzes and prioritizes
5. Top 10 risks are displayed
6. Optional fix generation for selected findings

Business Signal Detection

Deburger looks for:

• Payment keywords: stripe, payment, checkout, billing
• Auth keywords: auth, login, jwt, token, identity
• Admin keywords: admin, dashboard, management
• Public-facing: api/, controllers/, routes/
• Database: insert, update, delete, vault, secret, prod

---

🚨 Limitations

• Dependent on Semgrep rule quality
• Static analysis only (no runtime behavior)
• AI-generated fixes require human review
• Business intent cannot be inferred directly
• Requires Semgrep and Gemini API access

---

📝 License

MIT

---

🤝 Contributing

Contributions welcome! Please ensure:

• Code follows TypeScript best practices
• Tests pass (if applicable)
• Documentation is updated
• Changes align with "failure-first" philosophy

---

🎓 Philosophy

Deburger is built on the principle that not all vulnerabilities are equal. A SQL injection in a payment flow is more critical than a low-severity issue in a rarely-used utility function.

By focusing on business impact and failure propagation, Deburger helps teams make informed decisions about where to invest their security efforts.

---

Built with ❤️ and 🍔

// fix

// fix