Leak Shield 🛡️

Leak Shield is a local, privacy-first VS Code extension that scans source code and configuration files to detect credentials, API keys, private keys, tokens, and database secrets before they are committed or leaked.

Why Leak Shield?

Accidental credential exposure is one of the most common and costly security mistakes in software development. Many existing scanning tools rely on remote cloud APIs (which paradoxically transmit your source code to external servers), require complex CI/CD configurations, or produce overwhelming false positives.

Leak Shield is built on three core principles:

1. 100% Local & Private: Operates entirely offline with zero telemetry, zero network calls, and no secret storage.
2. Low False Positives: Focuses on high-confidence patterns and uses Shannon entropy heuristics alongside strict suppression for common placeholders (your-api-key, changeme, test, dummy).
3. Seamless In-Editor Experience: Runs automatically as you code, presenting findings via native VS Code diagnostics, hovers, and quick-fixes.

How It Works: The Automatic Workflow

💡 You do NOT need to repeatedly open the Command Palette.
Leak Shield is designed to operate passively in the background without interrupting your workflow.

The primary workflow is fully automatic:

1. Open / Edit / Save a File
           │
           ▼
2. Automatic Background Scan (Debounced)
           │
           ▼
3. Native Diagnostics Appear (Squiggly Underlines & Problems Panel)
           │
           ▼
4. Hover to Inspect (Safe Redacted Preview & Remediation Advice)
           │
           ▼
5. Apply Quick Fix (Explain Finding or Add Inline Ignore Comment)

1. Automatic Scanning: Whenever you open, edit, or save a supported file, Leak Shield automatically scans the content.
2. Clear Diagnostics: Detected secrets are underlined directly in the editor and listed in the VS Code Problems tab with masked previews (e.g. AKIA...****...PLE).
3. Informative Hovers: Hovering over any flagged range displays a markdown tooltip with finding details, confidence level, entropy rating, and remediation advice.
4. Quick-Fix Code Actions: Click the lightbulb (or press Cmd+. / Ctrl+.) to:
   • Explain Finding: Open a safe dialog summarizing the finding and remediation steps.
   • Ignore Line: Insert a language-appropriate ignore comment (// leak-shield-ignore or # leak-shield-ignore).

Command Palette commands (Scan Workspace, Scan Current File, Clear Diagnostics) are available whenever you need manual or workspace-wide controls.

Supported Detections

Leak Shield includes deterministic detectors for high-risk credentials:

Supported File Types

Leak Shield is syntax-independent and scans all standard text and source files:

• Languages: JavaScript, TypeScript, Python, Go, Rust, Java, Kotlin, C, C++, C#, Ruby, PHP, Shell (Bash/Zsh/Sh)
• Configuration & Data: JSON, YAML, TOML, XML, Markdown, Plaintext, .env templates

Binary files (images, archives, compiled executables, fonts, bytecode) and files exceeding the size limit are automatically skipped.

Privacy & Security Guarantees

Leak Shield was designed from the ground up to guarantee strict privacy:

• Zero Network Access: No HTTP, WebSocket, DNS, or external API calls. Works completely offline in air-gapped environments.
• No Telemetry: No analytics, telemetry events, tracking pixels, or diagnostic phone-homes.
• No Secret Storage: Raw secrets are never saved to disk, temp directories, workspace storage, or the clipboard.
• Redaction Everywhere: Diagnostics, hovers, status bars, and inspection dialogs mask secret values (e.g. AKIA...****...PLE or postgres://user:****@host:5432/db).
• Workspace Boundary Enforcement: Directory scans strictly respect the workspace boundary and will not follow symlinks outside the project root.
• No Shell Execution: Does not execute shell commands or arbitrary external scripts.

Commands

Access manual controls via the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• Leak Shield: Scan Current File (leak-shield.scanCurrentFile) — Forces an immediate scan of the active document.
• Leak Shield: Scan Workspace (leak-shield.scanWorkspace) — Performs a full workspace scan with progress reporting and cancellation support.
• Leak Shield: Clear Diagnostics (leak-shield.clearDiagnostics) — Clears all active Leak Shield diagnostics.
• Leak Shield: Explain Finding (leak-shield.explainFinding) — Opens safe finding details for the secret at cursor position or active file.

Configuration

Customize behavior in VS Code Settings (leakShield.*):

Example: Custom Pattern Configuration

{
  "leakShield.customPatterns": [
    {
      "id": "corp-api-key",
      "name": "Acme Internal Token",
      "regex": "acme_token_[0-9a-zA-Z]{32}",
      "confidence": "high",
      "description": "Internal Acme microservice authentication key."
    }
  ]
}

Ignoring Findings

Line-Level Ignore

Append // leak-shield-ignore or # leak-shield-ignore to any line:

const testKey = "AKIA...DEMO_KEY"; // leak-shield-ignore

File-Level Ignore

Add // leak-shield-ignore-file or # leak-shield-ignore-file at the top of a file to bypass scanning for that entire file:

// leak-shield-ignore-file

Examples (Using Synthetic Credentials)

Note: All examples below use illustrative synthetic placeholders.

AWS Access Key ID

// Flagged: Possible AWS Access Key ID detected [HIGH confidence]
const awsKey = "AKIA" + "...[16-char ID]";

Database URL with Password

// Flagged: Database connection string containing embedded credentials [HIGH confidence]
const dbUrl = "postgres://appuser:[REDACTED]@db.internal:5432/production";

Suppressed Placeholders (Low False-Positive Philosophy)

// NOT flagged: Known non-secret placeholders are automatically suppressed
const key1 = "your-api-key";
const key2 = "changeme";
const key3 = "placeholder";
const key4 = "YOUR_API_KEY";

Installation

From VS Code Marketplace

Search for Leak Shield in the Extensions view (Ctrl+Shift+X / Cmd+Shift+X) and click Install.

From VSIX

1. Download leak-shield-1.0.0.vsix from the Releases page.
2. In VS Code, run Extensions: Install from VSIX... from the Command Palette and select the downloaded file.

Development & Testing

# Clone the repository
git clone https://github.com/AJ-Kaarthick/leak-shield.git
cd leak-shield

# Install dependencies
npm install

# Run unit and integration tests
npm test

# Type-check TypeScript
npm run typecheck

# Build production bundle with esbuild
npm run build

# Package extension into VSIX
npm run package

Limitations & Disclaimer

• Heuristic Nature: Leak Shield uses deterministic regex patterns, Shannon entropy heuristics, and syntactic checks. It does not guarantee that all secrets will be caught, nor does it verify if a detected secret is active on external services.
• Defense in Depth: Leak Shield serves as an in-editor developer safety net. It should be used alongside pre-commit hooks, secret rotation policies, and CI/CD secret scanning.

Issues & Feedback

Found a bug or have a suggestion? Please open an issue on GitHub:
👉 https://github.com/AJ-Kaarthick/leak-shield/issues

License

MIT © ajkaarthick