Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/goklab/guardvibe

Security MCP for vibe coding. 429 rules, 36 tools, CLI + doctor. Host security, auth coverage mapping, LLM-powered deep scan (IDOR/business logic), taint analysis, and CVE/supply-chain IOC detection for Next.js, Supabase, Clerk, Stripe, Prisma, Drizzle, Hono, GraphQL, AI SDK, MCP, and the AI-native stack.
https://github.com/goklab/guardvibe

ai-security claude clerk cursor cve drizzle hono mcp mcp-server nextjs owasp prisma prompt-injection sast security stripe supabase typescript vercel vibe-coding

Last synced: 10 days ago
JSON representation

Security MCP for vibe coding. 429 rules, 36 tools, CLI + doctor. Host security, auth coverage mapping, LLM-powered deep scan (IDOR/business logic), taint analysis, and CVE/supply-chain IOC detection for Next.js, Supabase, Clerk, Stripe, Prisma, Drizzle, Hono, GraphQL, AI SDK, MCP, and the AI-native stack.

Awesome Lists containing this project

README 

          
# GuardVibe



[![npm version](https://img.shields.io/npm/v/guardvibe)](https://www.npmjs.com/package/guardvibe)

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[![Node.js CI](https://github.com/goklab/guardvibe/actions/workflows/ci.yml/badge.svg)](https://github.com/goklab/guardvibe/actions/workflows/ci.yml)

[![npm provenance](https://img.shields.io/badge/provenance-verified-brightgreen)](https://www.npmjs.com/package/guardvibe)

[![codecov](https://codecov.io/gh/goklab/guardvibe/graph/badge.svg)](https://codecov.io/gh/goklab/guardvibe)



**The security MCP built for vibe coding.** 433 security rules, 36 tools covering the entire AI-generated code journey — from first line to production deployment.



Works with **Claude Code, Cursor, Gemini CLI, Codex, VS Code (Copilot), Windsurf**, and any MCP-compatible coding agent.



## Why GuardVibe



Most security tools are built for enterprise security teams. GuardVibe is built for **you** — the developer using AI to build and ship web apps fast.



- **433 security rules, 36 tools** purpose-built for the stacks AI agents generate

- **Zero setup friction** — `npx guardvibe` and you're scanning

- **No account required** — runs 100% locally, no API keys, no cloud

- **Understands your stack** — not generic SAST, but rules that know Next.js, Supabase, Stripe, Clerk, and the tools you actually use

- **CVE version intelligence** — detects 67 known vulnerable package versions in package.json, refreshed every day from GHSA / OSV.dev / CISA KEV

- **AI agent & MCP security** — detects MCP server vulnerabilities, tool-description prompt injection (OWASP MCP Top 10), model-controlled sandbox-disable flags, excessive AI permissions, indirect prompt injection

- **Auto-fix suggestions** — `fix_code` tool returns concrete patches and structured edits the AI agent can apply mechanically. Coverage: hardcoded credentials → env-var migration; public-prefix LLM keys (`NEXT_PUBLIC_/VITE_/EXPO_PUBLIC_/REACT_APP_`) → prefix removal; CORS wildcards → env allowlist; `dangerouslyAllowBrowser` flags → drop; sandbox bypass flags (`unsafe`/`noSandbox`/`allowEval`) → drop; agent loops → add `maxSteps`; raw-HTML React props → ``; missing auth checks → insert auth guard; SQL injection → parameterized queries; missing rate limiters / CSRF / security headers → snippet templates.

- **Pre-commit hook** — block insecure code before it reaches your repo

- **CI/CD ready** — GitHub Actions workflow with SARIF upload to Security tab

- **Agent-friendly output** — JSON format for AI agents, Markdown for humans, SARIF for CI/CD

- **Plugin system** — extend with community or premium rule packs



## New in v3.1.x



- **Daily threat-intel pipeline** — rule set tracks GHSA / OSV.dev / CISA KEV every day. Latest shipments (v3.1.24 → v3.1.26) added `VG1069` node-ipc protestware detection, `VG1070` CI `npm` provenance / `--ignore-scripts` hardening, `VG1071` axios proxy-auth redirect credential leak, `VG1072` hono `setCookie` attribute injection, `VG1073` drizzle `sql.raw` interpolation, `VG1074` Miasma `@redhat-cloud-services` namespace compromise IOC (RHSB-2026-006), and `VG1075` Session messenger exfil endpoint IOC (`filev2.getsession.org`). The hono override floor is pinned to `^4.12.21`. Earlier in the v3.1.2x line: Next.js May 2026 13-advisory cluster, Drizzle ORM SQL identifier injection (CVE-2026-39356), Clerk `clerkFrontendApiProxy` SSRF (CVE-2026-34076), tRPC `experimental_nextAppDirCaller` prototype pollution (CVE-2025-68130), MikroORM SQL injection, angular-expressions filter RCE, `@tanstack/*` Mini Shai-Hulud supply-chain attack, Kysely JSON-path traversal, `@nyariv/sandboxjs` sandbox escape, OpenClaude `dangerouslyDisableSandbox` model-controlled flag, Strapi content-type builder SQL injection, LangSmith untrusted prompt-manifest deserialization, and more

- **OWASP MCP Top 10 alignment** — `VG1068` flags MCP / AI tool definitions whose `description`, `instructions`, or `systemPrompt` fields carry prompt-injection markers (`ignore previous instructions`, `you are now`, `jailbreak mode`, `system prompt:`, `override safety`, …); pair with `VG1063` which catches `dangerouslyDisableSandbox: true` in agent runtimes

- **Inline suppress** — `// guardvibe-ignore VG001` silences individual findings per-line

- **CLI-first approach** — `npx guardvibe audit`, `npx guardvibe scan`, `npx guardvibe doctor` all work standalone without MCP

- **Embedded remediation plan** — `remediation_plan` generates a section-by-section fix checklist after every audit

- **Score reflects all sections** — security score now factors code, dependencies, config, secrets, auth coverage, and taint analysis

- **Gitignored secrets excluded** — files matched by `.gitignore` are automatically skipped during secret scanning

- **Taint sanitizer recognition** — dataflow analysis recognizes common sanitizers (DOMPurify, escape functions, parameterized queries) and stops propagation



## How GuardVibe Compares



GuardVibe is purpose-built for the AI coding workflow. Traditional tools are excellent for enterprise CI/CD pipelines — GuardVibe fills a different gap.



| Capability | GuardVibe | Traditional SAST | Dependency Scanners |

|-----------|-----------|-----------------|-------------------|

| Runs inside AI agents (MCP) | Native | Not supported | Not supported |

| Zero config setup | `npx guardvibe` | Account + config required | Built-in (limited) |

| Vibecoding stack rules (Next.js, Supabase, Clerk, tRPC, Hono) | 100+ dedicated | Generic patterns | Not applicable |

| AI/LLM security (prompt injection, MCP, tool abuse) | 68 rules | Experimental/None | None |

| AI host security (CVE-2025-59536, CVE-2026-21852) | `guardvibe doctor` | Not supported | Not supported |

| Auto-fix suggestions for AI agents | `fix_code` tool | CLI autofix | Not supported |

| CVE version detection | 67 packages, refreshed daily | Extensive | Extensive |

| Compliance mapping (SOC2, PCI-DSS, HIPAA) | Built-in | Paid tier | None |

| SARIF CI/CD export | Yes | Yes | Limited |

| Rule count | 433 (focused, 68 AI-native) | 5000+ (broad) | N/A |



**When to use GuardVibe:** You're building with AI agents and want security scanning integrated into your coding workflow — no dashboard, no account, no CI setup.



**When to use traditional tools:** You need deep AST analysis, enterprise dashboards, org-wide policy enforcement, or coverage across hundreds of languages.



## Quick Start



### Claude Code



```bash

npx guardvibe init claude

```



Creates `.mcp.json` MCP config (pinned to current version), `.claude/settings.json` auto-scan hooks, and `CLAUDE.md` security rules. Restart Claude Code after setup.



### Cursor



```bash

npx guardvibe init cursor

```



Creates `.cursor/mcp.json` and `.cursorrules` with security rules. Restart Cursor after setup.



### Gemini CLI



```bash

npx guardvibe init gemini

```



Creates `~/.gemini/settings.json` MCP config and `GEMINI.md` security rules.



### Codex (OpenAI)



```bash

codex mcp add guardvibe -- npx -y guardvibe

```



### VS Code (GitHub Copilot)



Create `.vscode/mcp.json` in your project:



```json

{

  "servers": {

    "guardvibe": {

      "command": "npx",

      "args": ["-y", "guardvibe"]

    }

  }

}

```



> **Note:** VS Code uses `"servers"`, not `"mcpServers"`.



### Windsurf



Add to `~/.codeium/windsurf/mcp_config.json`:



```json

{

  "mcpServers": {

    "guardvibe": {

      "command": "npx",

      "args": ["-y", "guardvibe"]

    }

  }

}

```



### All platforms at once



```bash

npx guardvibe init all       # Claude + Cursor + Gemini

```



### Pre-commit hook



```bash

npx guardvibe hook install   # Blocks commits with critical/high findings

npx guardvibe hook uninstall # Remove hook

```



### CI/CD (GitHub Actions)



```bash

npx guardvibe ci github      # Generates .github/workflows/guardvibe.yml

```



## What GuardVibe Scans



### Application Code

Next.js App Router, Server Actions, Server Components, React, Express, Hono, tRPC, GraphQL, FastAPI, Go



### Authentication & Authorization

Clerk, Auth.js (NextAuth), Supabase Auth, OAuth/OIDC (state parameter, PKCE) — middleware checks, secret exposure, session handling, SSR cookie auth, admin method protection



### Database & ORM

Supabase (RLS, anon vs service role), Prisma (raw query injection, CVEs), Drizzle (SQL injection — including CVE-2026-39356 identifier-injection), MikroORM (CVE-2026-44680 runtime-identifier injection), Kysely (CVE-2026-44635 JSON-path traversal), Turso/LibSQL (client exposure, SQL injection), Convex (auth bypass, internal function exposure)



### Payments

Stripe (webhook signatures, replay protection, secret keys), Polar.sh, LemonSqueezy



### Third-Party Services

Resend (email HTML injection), Upstash Redis, Pinecone, PostHog, Google Analytics (PII tracking), Uploadthing (auth, file type/size)



### AI / LLM Security

Prompt injection detection, LLM output sinks, system prompt leaks, MCP server SSRF/path traversal/command injection, **MCP tool description prompt-injection markers (OWASP MCP Top 10 alignment, VG1068)**, **model-controlled sandbox-disable flags (`dangerouslyDisableSandbox`, VG1063)**, AI agent unrestricted shell/database access, `dangerouslyAllowBrowser`, missing `maxTokens`, agent loop without `maxSteps`, AI API key client exposure, indirect prompt injection via external data, RAG/vector poisoning, public-prefix LLM key leaks (`NEXT_PUBLIC_*`, `VITE_*`, `EXPO_PUBLIC_*`)



### AI Host Security

`guardvibe doctor` — unified host hardening scanner detecting CVE-2025-59536 (hook injection via `.claude/settings.json`), CVE-2026-21852 (API key exfiltration via `ANTHROPIC_BASE_URL` override), MCP config audit, environment scanner, permission analysis. Supports Claude, Cursor, VS Code, Gemini, Windsurf. Host-specific remediation with platform-tailored fix steps.



### OWASP API Security

BOLA/IDOR (Broken Object Level Authorization), mass assignment (spread request body, Object.assign), missing pagination, rate limiting, admin endpoint authorization, verbose error leaks



### Modern Stack

Zod `.passthrough()` mass assignment, `z.any()` bypass, file upload validation, `server-only` import guard, webhook replay protection, CSP headers, `unsafe-inline`/`unsafe-eval` detection, cron endpoint auth



### Mobile

React Native, Expo — AsyncStorage secrets, deep link token exposure, hardcoded API URLs, ATS configuration



### Firebase

Firestore security rules, Firebase Admin SDK exposure, storage rules, custom token validation



### CVE Version Intelligence (67 CVEs, refreshed daily)

**Frameworks:** Next.js (CVE-2024-34351, CVE-2024-46982, CVE-2025-29927, CVE-2026-23869, CVE-2026-44573 / 44574 / 44575 / 44578 / 44579 / 45109 May 2026 cluster), React + react-server-dom-* (CVE-2025-55182, CVE-2026-23870), Express, Hono pre-4.12.18 cluster, @vitejs/plugin-rsc, Strapi content-type-builder (CVE-2026-22599)

**Auth:** Clerk middleware bypass (GHSA-vqx2), Clerk `has()` org/billing/reverification bypass (GHSA-w24r), Clerk `clerkFrontendApiProxy` SSRF (CVE-2026-34076), NextAuth.js (2 CVEs), jsonwebtoken

**ORMs / SQL:** Drizzle SQL identifier injection (CVE-2026-39356) + Drizzle `sql.raw` interpolation (VG1073), MikroORM SQL injection (CVE-2026-44680), Prisma raw-query call-form, Kysely JSON-path traversal (CVE-2026-44635)

**AI ecosystem:** @anthropic-ai/sdk (CVE-2026-34451 + memory tool path escape), Vercel AI SDK file-type bypass (CVE-2025-48985), LangSmith untrusted prompt manifest (CVE-2026-45134), OpenClaude sandbox bypass (CVE-2026-42074), @nyariv/sandboxjs Function.caller escape (CVE-2026-43898)

**HTTP / parsing:** Axios pre-1.15.2 cluster (SSRF + prototype-pollution + DoS + CRLF) + axios proxy-auth redirect leak (VG1071), Hono `setCookie` attribute injection (VG1072, override pinned `^4.12.21`), fast-uri path traversal + host confusion (CVE-2026-6321 / 6322), fast-xml-parser CDATA injection, xmldom CDATA, protobuf.js multi-CVE cluster, undici (2 CVEs), ws

**Tools / supply chain:** node-ipc protestware (VG1069), Miasma `@redhat-cloud-services` namespace compromise IOC (VG1074), Session messenger exfil endpoint IOC (VG1075), @tanstack/* Mini Shai-Hulud (84 malicious versions, May 2026), @wdio/browserstack-service command injection (CVE-2026-25244), @babel/plugin-transform-modules-systemjs arbitrary code (CVE-2026-44728), @opentelemetry exporter-prometheus DoS (CVE-2026-44902), systeminformation Linux cmd injection (CVE-2026-44724), velocityjs prototype pollution, defu, sharp, lodash, node-fetch, tar, xml2js, crypto-js, angular-expressions RCE, i18next-http-backend, vm2 sandbox breakouts



### Deployment & Config

Vercel (vercel.json, cron secrets, headers), Next.js config, Docker, Docker Compose, Fly.io, Render, Netlify, Cloudflare



### Infrastructure

Dockerfile security, GitHub Actions CI/CD, Terraform (S3, IAM, RDS, security groups)



### Secrets & Environment

API keys (AWS, GitHub, Stripe, OpenAI, Resend, Turso), .env management, .gitignore coverage, high-entropy detection, NEXT_PUBLIC exposure



### Compliance Control Mapping

Maps security findings to SOC2, PCI-DSS, HIPAA, GDPR, ISO27001, and EU AI Act (EUAIACT) controls. Identifies which code-level vulnerabilities are relevant to specific compliance requirements. **Not a substitute for professional compliance audits.**



### Supply Chain

Malicious postinstall scripts, unpinned GitHub Actions, CI `npm` provenance / `--ignore-scripts` hardening (VG1070), typosquat detection, `node-ipc` protestware versions (VG1069), Miasma `@redhat-cloud-services` namespace compromise IOC (VG1074, RHSB-2026-006), Session messenger exfil endpoint IOC (VG1075, `filev2.getsession.org`), `@tanstack/*` Mini Shai-Hulud mass-malware versions (May 2026), `@wdio/browserstack-service` command injection via git branch names (CVE-2026-25244), lockfile poisoning patterns



## Tools (36 MCP tools)



| Tool | What it does |

|------|-------------|

| `check_code` | Analyze a code snippet for security issues |

| `check_project` | Scan multiple files with security scoring (A-F) |

| `scan_directory` | Scan a project directory from disk |

| `scan_staged` | Pre-commit scan of git-staged files |

| `scan_dependencies` | Check all dependencies for known CVEs (OSV) |

| `scan_secrets` | Detect leaked secrets, API keys, tokens |

| `check_dependencies` | Check individual packages against OSV |

| `check_package_health` | Typosquat detection, maintenance status, adoption metrics |

| `compliance_report` | Map security findings to compliance controls (SOC2, PCI-DSS, HIPAA, GDPR, ISO27001, EU AI Act) |

| `export_sarif` | SARIF v2.1.0 export for CI/CD integration |

| `get_security_docs` | Security best practices and guides |

| `fix_code` | **Auto-fix suggestions** with concrete patches for AI agents |

| `audit_config` | Audit project configuration files for cross-file security misconfigurations |

| `generate_policy` | Detect project stack and generate tailored security policies (CSP, CORS, RLS) |

| `review_pr` | Review PR diff for security issues with severity gating |

| `scan_secrets_history` | Scan git history for leaked secrets (active and removed) |

| `policy_check` | Check project against compliance policies defined in .guardviberc |

| `analyze_dataflow` | Track tainted data flows from user input to dangerous sinks |

| `analyze_cross_file_dataflow` | **Cross-file taint analysis** — track tainted data across module boundaries |

| `check_command` | Analyze shell commands for security risks before execution |

| `scan_config_change` | Compare config file versions to detect security downgrades |

| `repo_security_posture` | Assess overall repository security posture and map sensitive areas |

| `explain_remediation` | Get detailed remediation guidance with exploit scenarios and fix strategies |

| `scan_file` | Real-time single-file scan — designed for post-edit hooks |

| `scan_changed_files` | Scan only git-changed files — for PRs and incremental CI |

| `security_stats` | Cumulative security dashboard — scans, fixes, grade trend over time |

| `guardvibe_doctor` | **Host security audit** — CVE-2025-59536, CVE-2026-21852, MCP config, env scanner |

| `audit_mcp_config` | Audit MCP server configurations for hook injection, file:// abuse, sensitive paths |

| `scan_host_config` | Scan shell profiles, .env files for base URL hijack and credential sniffing |

| `verify_fix` | Verify a security fix was applied correctly — returns fixed/still_vulnerable/new_issues |

| `security_workflow` | Get recommended tool workflow for your current task (writing, pre-commit, PR review, etc.) |

| `auth_coverage` | **Auth coverage map** — enumerate routes, parse middleware matchers, detect auth guards, report coverage % |

| `deep_scan` | **LLM-powered deep analysis** — IDOR, business logic, race conditions, auth bypass. Defaults to Claude Haiku 4.5 (~cents/scan). Pass `model: 'sonnet'` for deeper analysis. CLI: `npx guardvibe deep-scan  --focus idor` |

| `full_audit` | **Single source of truth** — runs ALL checks in one call, returns PASS/FAIL/WARN verdict + score + coverage % + deterministic result hash |

| `remediation_plan` | **Remediation plan** — generates section-by-section fix checklist after audit |

| `verify_remediation` | **Remediation verification** — compares before/after audit, flags skipped sections |



All scanning tools support `format: "json"` for machine-readable output.



## Security Rules (433 rules across 25 modules)



| Category | Rules | Coverage |

|----------|-------|----------|

| Core OWASP | 38 | SQL injection, XSS, CSRF, command injection, CORS, SSRF, hardcoded secrets |

| Next.js App Router | 17 | Server Actions, secret exposure, auth bypass, CSP, redirects |

| Auth (Clerk / Auth.js / Supabase Auth) | 16 | Middleware, secret keys, session storage, role checks, SSR cookies |

| Database (Supabase / Prisma / Drizzle) | 12 | Raw queries, client exposure, service role leaks, NoSQL injection, Drizzle identifier injection (CVE-2026-39356) |

| OWASP API Security | 10 | BOLA/IDOR, mass assignment, pagination, rate limiting, error leaks |

| Modern Stack | 40 | Zod, tRPC, Hono, GraphQL, Uploadthing, Turso, Convex, OAuth, CSP, webhooks, AI SDK, React Server Action validation (React2Shell) |

| Deployment Config | 21 | Vercel, Next.js config, Docker Compose, Fly, Render, Netlify, Cloudflare, K8s secrets |

| Payments (Stripe / Polar / Lemon) | 9 | Webhook signatures, key exposure, price manipulation |

| Services (Resend / Upstash / Pinecone / PostHog) | 11 | API key leaks, PII tracking, email injection |

| Web Security | 15 | Webhooks, CSP, .env safety, AI key exposure, cookie handling |

| React Native / Expo | 10 | AsyncStorage secrets, deep links, ATS, hardcoded URLs |

| Firebase | 7 | Firestore rules, admin SDK, storage, custom tokens |

| AI / LLM Security | 16 | Prompt injection, MCP SSRF, excessive agency, indirect injection |

| **AI Host Security** | **10** | **CVE-2025-59536 hook injection, CVE-2026-21852 base URL hijack, MCP config audit** |

| **AI Tool Runtime** | **4** | **MCP tool output sanitization, obfuscated descriptions, safety bypass** |

| CVE Version Intelligence | 27 | Known vulnerable versions in package.json — incl. Axios supply-chain backdoor, Clerk middleware bypass (GHSA-vqx2), Next.js RSC DoS (CVE-2026-23869), Hono CRLF (CVE-2026-29086) |

| Shell / Bash | 5 | Pipe to bash, chmod 777, rm -rf, sudo password |

| SQL | 4 | DROP/DELETE without WHERE, stacked queries, GRANT ALL |

| Supply Chain | 16 | Malicious install scripts, lockfile integrity, dependency confusion, typosquat detection |

| Go | 6 | SQL injection, command injection, template escaping |

| Dockerfile | 7 | Root user, secrets in ENV, untagged images, non-root user |

| CI/CD (GitHub Actions) | 7 | Secrets interpolation, unpinned actions, write-all permissions |

| Terraform | 6 | Public S3, open security groups, IAM wildcards |

| Advanced Security | 21 | ReDoS, CRLF injection, race conditions, XXE, brute force, audit logging |

| Other Services | 5 | AWS, GCP, MongoDB, Convex, Sentry, Twilio |



## CLI Commands



```bash

# Scanning

npx guardvibe scan [path]            # Scan a directory for security issues

npx guardvibe scan . --format json   # JSON output for automation

npx guardvibe check            # Scan a single file

npx guardvibe diff [base]            # Scan only changed files since git ref



# Full security audit

npx guardvibe audit [path]           # Full audit with PASS/FAIL verdict + hash

npx guardvibe audit . --format json  # JSON output for CI pipelines

npx guardvibe audit --skip-deps      # Skip dependency CVE check

npx guardvibe audit --full           # Disable MCP-output truncation (full finding set)



# Host security audit

npx guardvibe doctor                 # Host hardening audit (project scope)

npx guardvibe doctor --scope host    # + shell profiles, global MCP configs

npx guardvibe doctor --scope full    # + home dir configs

npx guardvibe doctor --format json   # JSON output



# LLM-powered deep scan (IDOR, business logic, race conditions, auth bypass)

npx guardvibe deep-scan                   # Default: Haiku 4.5, all focus areas

npx guardvibe deep-scan  --focus idor     # Narrow to IDOR

npx guardvibe deep-scan  --model sonnet   # Deeper analysis (more expensive)

npx guardvibe deep-scan  --max-bytes 5000 # Truncate input for cost control

# Requires ANTHROPIC_API_KEY or OPENAI_API_KEY env var



# Setup

npx guardvibe init        # Setup MCP server (claude, cursor, gemini, all)

npx guardvibe hook install           # Install pre-commit hook

npx guardvibe hook uninstall         # Remove pre-commit hook

npx guardvibe ci github              # Generate GitHub Actions workflow



# Pre-commit / CI

npx guardvibe-scan                   # Scan staged files (for pre-commit)

npx guardvibe-scan --format sarif --output results.sarif  # CI mode



# Options (all scan commands)

#   --format markdown|json|sarif|buddy

#   --output      Write results to file

#   --fail-on    Exit 1 on findings: critical|high|medium|low|none

#   --full              Bypass response-size caps (50 JSON / 30 markdown / 200-file taint)

```



## Plugin System



Extend GuardVibe with custom or community rule packs.



```bash

npm install guardvibe-rules-awesome

```



Plugins matching `guardvibe-rules-*`, `@guardvibe/rules-*`, or `@guardvibe-pro/rules-*` are discovered automatically.



### Writing a Plugin



A plugin is an npm package that exports a `GuardVibePlugin` object:



```typescript

// index.ts

import type { GuardVibePlugin } from "guardvibe/plugins";



const plugin: GuardVibePlugin = {

  name: "my-rules",

  version: "1.0.0",

  description: "My custom security rules",

  rules: [

    {

      id: "CUSTOM001",

      name: "My Custom Rule",

      severity: "high",       // "critical" | "high" | "medium" | "low" | "info"

      owasp: "A01:2025 Broken Access Control",

      description: "What this rule detects and why it's dangerous",

      pattern: /vulnerable_pattern_here/g,   // RegExp with global flag

      languages: ["javascript", "typescript"], // which file types to scan

      fix: "How to fix the vulnerability",

      fixCode: "// Copy-paste secure code example",

      compliance: ["SOC2:CC6.1"],  // optional compliance mapping

    },

  ],

};



export default plugin;

```



### Plugin Rule Schema



| Field | Type | Required | Description |

|-------|------|----------|-------------|

| `id` | string | Yes | Unique rule ID (e.g., "CUSTOM001") |

| `name` | string | Yes | Human-readable rule name |

| `severity` | string | Yes | `critical`, `high`, `medium`, `low`, or `info` |

| `owasp` | string | Yes | OWASP category mapping |

| `description` | string | Yes | What the rule detects |

| `pattern` | RegExp | Yes | Regex pattern to match vulnerable code (use `/g` flag) |

| `languages` | string[] | Yes | File types to scan |

| `fix` | string | Yes | How to fix the issue |

| `fixCode` | string | No | Copy-paste secure code example |

| `compliance` | string[] | No | SOC2/PCI-DSS/HIPAA control IDs |



### Loading Plugins



Plugins are loaded from three sources:



1. **Auto-discovery:** Any installed npm package matching `guardvibe-rules-*` or `@guardvibe/rules-*`

2. **Config-specified:** Packages listed in `.guardviberc` `plugins` array

3. **Local paths:** Relative paths in `.guardviberc` `plugins` array



```json

// .guardviberc

{

  "plugins": [

    "guardvibe-rules-awesome",

    "./my-local-rules"

  ]

}

```



## Configuration



Create a `.guardviberc` file in your project root:



```json

{

  "rules": {

    "disable": ["VG030"],

    "severity": {

      "VG002": "medium"

    }

  },

  "scan": {

    "exclude": ["fixtures/", "coverage/"],

    "maxFileSize": 1048576

  },

  "plugins": ["guardvibe-rules-awesome"]

}

```



## Inline Suppression



```javascript

const key = process.env.API_KEY; // guardvibe-ignore VG001



// guardvibe-ignore-next-line VG002

app.get("/api/health", (req, res) => res.json({ ok: true }));

```



Supports `//`, `#`, and `` comment styles.



## GuardVibe Scans Itself



We run GuardVibe on its own codebase as a pre-commit hook. Every commit is scanned before it reaches the repository — the same workflow GuardVibe enables for your projects.



## How It Works



```

You write code with AI

    |

AI agent calls GuardVibe MCP tools

    |

GuardVibe scans locally (no cloud, no API)

    |

Returns findings with severity, OWASP mapping, and fix suggestions

    |

AI agent fixes issues before they reach production

```



## Performance



Tested on real AI-built projects (837 files, Next.js + Supabase + Clerk):



- Scan time: **~1.2s** (837 files)

- False positive rate: **near zero** — context-aware detection (React Native, Supabase client/server, static innerHTML, git-aware secrets)

- Detection rate: **100%** on known vulnerability patterns

- Security score: **A (99/100)** on production projects



## Troubleshooting



### MCP connection issues



If your AI agent cannot connect to GuardVibe:



1. **Restart your IDE/agent.** MCP servers are started by the host application. After running `npx guardvibe init`, restart Claude Code, Cursor, or Gemini CLI for the config to take effect.

2. **Check the config path.** Run `npx guardvibe init claude` again and verify the output shows the correct config file location (`.mcp.json` in your project root for Claude Code, `.cursor/mcp.json` for Cursor).

3. **Re-run `init` to upgrade.** When upgrading GuardVibe, re-run `npx guardvibe init claude` — `.mcp.json` is pinned to a specific version (e.g. `guardvibe@3.1.33`) at init time for fast deterministic startup. As of v3.1.2 the re-run also rewrites stale pins automatically (`Upgraded GuardVibe pin (3.1.27 → 3.1.28)`); since v3.1.27 the PostToolUse hook command is pinned to the same version (was `@latest`) and re-run upgrades a stale hook too. The same applies to `npx guardvibe hook install` and `npx guardvibe ci github` (since v3.1.3) — both are version-pinned at install/generate time and re-run to upgrade.

4. **Pre-3.1.1 users won't see the auto-update banner.** GuardVibe started writing a once-per-day "newer version available" notice to stderr in v3.1.1. If your install predates that, you'll never see it — run `npx -y guardvibe@latest init ` once to bake in the latest pin and start receiving banners on subsequent sessions.

5. **Verify Node.js version.** GuardVibe requires Node.js >= 18.0.0. Check with `node --version`.

6. **Check npx cache.** If you upgraded GuardVibe and the old version is cached, run `npx -y guardvibe@latest` to force the latest version.



### Node.js version requirements



GuardVibe requires **Node.js >= 18.0.0**. Earlier versions will fail with syntax errors or missing APIs. Node.js 22 LTS is recommended.



### False positives



If a rule triggers on safe code:



- **Inline suppression:** Add `// guardvibe-ignore VG001` on the same line, or `// guardvibe-ignore-next-line VG001` on the line above. Supports `//`, `#`, and `` comment styles.

- **Config exclusion:** Add the rule ID to `rules.disable` in `.guardviberc`:

  ```json

  { "rules": { "disable": ["VG030"] } }

  ```

- **Path exclusion:** Add directories to `scan.exclude` in `.guardviberc`:

  ```json

  { "scan": { "exclude": ["fixtures/", "test-data/"] } }

  ```



### Pre-commit hook issues



- **Hook not running:** Verify the hook file exists at `.git/hooks/pre-commit` and is executable (`chmod +x .git/hooks/pre-commit`).

- **Hook blocking valid commits:** Use `git commit --no-verify` to skip the hook temporarily, then investigate the findings.

- **Removing the hook:** Run `npx guardvibe hook uninstall`.



## Security Model



GuardVibe is designed for use on sensitive and proprietary codebases:



- **100% local execution.** All scanning happens on your machine. No code, findings, or metadata are sent to any server.

- **No accounts, no API keys, no telemetry.** There is no signup, no cloud dashboard, and no usage tracking of any kind.

- **One optional network call.** The `scan_dependencies` and `check_dependencies` tools query the [OSV API](https://osv.dev/) to check for known CVEs. This is opt-in -- you only call it when you explicitly use those tools. No other tool makes network requests.

- **Safe for air-gapped environments.** All code analysis rules run entirely offline. Only dependency vulnerability checks require network access.



## Configuration (.guardviberc)



Create a `.guardviberc` JSON file in your project root to customize GuardVibe behavior.



### Full example



```json

{

  "rules": {

    "disable": ["VG030", "VG045"],

    "severity": {

      "VG002": "medium",

      "VG010": "low"

    }

  },

  "scan": {

    "exclude": ["fixtures/", "coverage/", "dist/", "vendor/"],

    "maxFileSize": 1048576

  },

  "plugins": [

    "guardvibe-rules-awesome",

    "./my-local-rules"

  ],

  "compliance": {

    "frameworks": ["SOC2", "HIPAA"],

    "failOn": "high",

    "exceptions": [

      {

        "ruleId": "VG030",

        "reason": "Accepted risk per security review 2026-03",

        "approvedBy": "security-team",

        "expiresAt": "2026-12-31",

        "files": ["src/legacy/**"]

      }

    ],

    "requiredControls": ["SOC2:CC6.1"]

  },

  "scoring": {

    "densityModel": "exponential"

  }

}

```



### Configuration fields



| Field | Type | Default | Description |

|-------|------|---------|-------------|

| `rules.disable` | `string[]` | `[]` | Rule IDs to skip during scanning |

| `rules.severity` | `Record` | `{}` | Override severity for specific rules |

| `scan.exclude` | `string[]` | `[]` | Glob patterns for directories/files to skip |

| `scan.maxFileSize` | `number` | `512000` | Maximum file size in bytes (files larger than this are skipped) |

| `plugins` | `string[]` | `[]` | npm package names or local paths to load as plugins |

| `compliance.frameworks` | `string[]` | -- | Compliance frameworks to map against (`SOC2`, `PCI-DSS`, `HIPAA`, `GDPR`, `ISO27001`) |

| `compliance.failOn` | `string` | `"high"` | Minimum severity that causes compliance failure |

| `compliance.exceptions` | `PolicyException[]` | `[]` | Approved exceptions with expiration dates |

| `compliance.requiredControls` | `string[]` | -- | Controls that must pass regardless of exceptions |

| `scoring.densityModel` | `"linear" \| "exponential"` | `"linear"` | Score decay curve. `linear` matches pre-v3.0.50 (cliff at density 5). `exponential` keeps resolution past density 5 — smoother decay for large repos. Severity caps (1+ critical → max C/60, 1+ high → max B/75) apply under both. |



## Security



GuardVibe takes supply chain security seriously:



- **npm provenance** — every published version is cryptographically signed via Sigstore, linking the package to this exact GitHub repo and commit. Verify with `npm audit signatures`

- **2FA enabled** — npm account protected with two-factor authentication

- **Branch protection** — force push disabled on main, admin enforcement enabled

- **Tag protection** — version tags (`v*`) cannot be deleted or force-pushed

- **Minimal CI permissions** — GitHub Actions workflows use `permissions: contents: read` only

- **Zero runtime dependencies** — only MCP SDK and Zod (both widely audited)



To report a vulnerability, please email info@goklab.com or open a GitHub issue.



## License



Apache 2.0 — open source, patent-safe, enterprise-ready. Built by [GokLab](https://github.com/goklab).