🔓 Open Source

BlastShield is fully open source. You are free to clone, modify, and self-host the extension and its backend.

Note: The extension requires a running BlastShield backend to function. If you're setting up from this repo, you'll need to deploy your own backend instance. See Backend Setup below.

💥 The Problem

Every engineering team has experienced it:

Code passes all linters. Tests are green. PR is approved. You deploy.
Then production breaks.

Race conditions. Unsafe file operations. Missing boundary checks. Incorrect async flows. These failures are invisible during development — they only surface under real load.

BlastShield eliminates this guesswork.

🚀 What BlastShield Does

BlastShield is a deterministic-first security & reliability engine that lives inside your IDE. It combines AST-based static analysis with optional AI reasoning to detect deployment-grade risks that traditional tools miss.

🆕 What's New in v0.1.0 (Backend v2.0.0)

🛠️ Architecture

┌──────────────────────────────────────────────────────────┐
│                    VS Code Extension (v0.1.0)             │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │ Scan     │  │ Blast Report │  │ Fix Engine         │  │
│  │ Command  │  │ Panel (UI)   │  │ (Single + Bulk)    │  │
│  │ + Poll   │  │ + Evidence   │  │                    │  │
│  └────┬─────┘  └──────────────┘  └────────────────────┘  │
│       │              ▲                     ▲              │
└───────┼──────────────┼─────────────────────┼──────────────┘
        │              │                     │
        ▼              │                     │
┌───────────────────────────────────────────────────────────┐
│              Backend Server (v2.0.0 — FastAPI)            │
│                                                           │
│  ┌─────────────────────────────────────────────────────┐  │
│  │           Layer 1: Deterministic Core               │  │
│  │  AST Parser → Call Graph → Data Flow → Rule Engine  │  │
│  │  → Risk Scoring → Test Harness                      │  │
│  └────────────────────────┬────────────────────────────┘  │
│                           ▼                               │
│  ┌─────────────────────────────────────────────────────┐  │
│  │           Layer 2: AI-Assisted (Optional)           │  │
│  │  LLM Explanations → Patch Generation → Validation   │  │
│  └────────────────────────┬────────────────────────────┘  │
│                           ▼                               │
│  ┌─────────────────────────────────────────────────────┐  │
│  │           Layer 3: API & Infrastructure             │  │
│  │  FastAPI → Background Workers → Caching → PR Scan   │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘
        ▲
        │
┌───────┴───────────────────────────────────────────────────┐
│                  GitHub Actions CI/CD                      │
│  ┌─────────────────────┐  ┌────────────────────────────┐  │
│  │ PR Scan             │  │ Main Branch Scan           │  │
│  │ → Comment on PR     │  │ → Create Issue if Critical │  │
│  └─────────────────────┘  └────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

📦 Installation

VS Code Extension

# Install from .vsix file
code --install-extension blastshield-0.1.0.vsix

Or search "BlastShield" in the VS Code Marketplace.

Configuration

The extension reads the backend URL from a .env file located inside the extension's installation directory:

# Find your extension directory and add a .env file
# Typical path: ~/.vscode/extensions/blastshield.blastshield-0.1.0/
BLASTSHIELD_API_URL=https://your-backend-url.com

Tip: Copy the included .env.example for reference.

🔧 Backend Setup

The backend (v2.0.0) is a FastAPI server with a deterministic-first architecture. It uses AST parsing and rule evaluation as the primary analysis layer, with optional LLM for explanations and patch suggestions.

git clone https://github.com/Deepesh1024/blastshield-backend.git
cd blastshield-backend

pip install -r requirements.txt

# Set your API key (optional — LLM is only used for explanations/patches)
export GROQ_API_KEY="your-groq-api-key"

uvicorn main:app --host 0.0.0.0 --port 80 --workers 2

Note: Even without a Groq API key, the deterministic core (AST analysis, rule engine, risk scoring) works fully. The LLM layer only enhances explanations and patch suggestions.

📡 API Reference

GET /health

Health check endpoint.

Response:

{ "status": "ok" }

POST /scan

Full project scan. Sends all project files for analysis.

Request:

{
  "files": [
    { "path": "src/server.ts", "content": "...file contents..." },
    { "path": "src/utils.py", "content": "...file contents..." }
  ]
}

Response (scan_complete):

{
  "message": "scan_complete",
  "scan_id": "sc_a1b2c3d4",
  "report": {
    "riskScore": 72,
    "summary": "3 critical issues found: unsafe eval usage, blocking I/O in async handler, SQL injection risk.",
    "deterministic_only": true,
    "issues": [
      {
        "id": "issue-1",
        "issue": "Dangerous eval() Usage",
        "file": "src/server.ts",
        "line": 15,
        "severity": "critical",
        "rule_id": "dangerous_eval",
        "evidence": [
          "eval() called at line 15 with non-literal argument",
          "User input flows from req.body.code → eval() without sanitization"
        ],
        "explanation": "User-controlled input is passed directly to eval()...",
        "risk": "Attackers can execute arbitrary code on the server.",
        "patches": [
          {
            "file": "src/server.ts",
            "start_line": 15,
            "end_line": 20,
            "new_code": "...safe replacement code..."
          }
        ],
        "testImpact": ["tests/test_eval.py::test_safe_eval"]
      }
    ],
    "risk_breakdown": {
      "total_score": 72,
      "formula": "sum(severity_weight × blast_radius_factor) / max_possible × 100",
      "violation_contributions": [
        {
          "rule_id": "dangerous_eval",
          "severity": "critical",
          "weighted_score": 40.0,
          "blast_radius_factor": 2.0
        }
      ]
    },
    "audit": {
      "scan_id": "sc_a1b2c3d4",
      "files_scanned": 12,
      "violations_found": 3,
      "duration_ms": 1250,
      "llm_tokens_used": 0
    }
  }
}

Response (scan_queued — large projects >10 files):

{
  "message": "scan_queued",
  "scan_id": "sc_a1b2c3d4"
}

The extension will automatically poll GET /scan/{scan_id}/status until the scan completes.

POST /pr-scan

PR-scoped scan. Same format as /scan, optimized for PR diffs. Used by GitHub Actions.

⚙️ Usage

In VS Code

1. Open any project in VS Code
2. Add a .env file with your BLASTSHIELD_API_URL (see Configuration)
3. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
4. Run BlastShield: Scan Project
5. View all issues in the BlastShield sidebar panel
6. Expand Evidence and Risk Breakdown sections for full transparency
7. Click Fix This Issue or Fix All Issues

GitHub Actions (Automatic PR Scanning)

Add BLASTSHIELD_API_URL to your repo secrets, and every PR gets scanned automatically:

🎯 Why BlastShield?

🏗️ Tech Stack

🏆 Built For

AWS Nationwide Hackathon — AI for Learning & Developer Productivity

Instead of teaching concepts, BlastShield teaches real-world failure modes — the most important skill in software engineering — inside the IDE where developers actually learn.