VibeHat

White-hat security for vibe-coded apps.

VibeHat is a local-first CLI tool for people building apps with AI coding tools like Codex, Claude Code, Cursor, Lovable, Bolt, v0, Replit Agent, and similar tools.

The goal is simple:

Help non-security people find obvious vulnerabilities before they deploy AI-built apps.

VibeHat should not try to replace professional security review. It should give builders a fast, understandable, one-command safety check using proven open-source tools and beginner-friendly explanations.

Project direction

VibeHat is a local-first defensive CLI for AI-built and vibe-coded apps. It focuses first on free and open-source security checks that can run on a developer's own machine or in CI without requiring cloud login, paid APIs, or source-code upload to AI services.

The near-term roadmap is to keep improving practical local checks, reports, CI gates, optional tool integrations, and beginner-friendly fix guidance before adding heavier enterprise workflows. See docs/ROADMAP.md, docs/SECURITY_MODEL.md, and docs/TOOLING_MATRIX.md for the current product direction and safety boundaries.

Research background lives at docs/research/deep-research-report.md.

License

MIT. See LICENSE.

Current MVP CLI

This starter now includes a runnable Node.js/TypeScript CLI foundation.

Website

The branded VibeHat website lives in website/.

cd website
npm install
npm run dev

The website uses the real VibeHat logo, a logo-based blue/navy palette, and includes third-party optional-tool attribution. Build and lint it with:

npm run lint
npm run build

MVP status

VibeHat v0.1.4 is ready for release. It supports local scans, quick scans, JSON and Markdown reports, AI-safe fix prompts, project-specific fix-loop prompts, accepted-risk reporting, AI-agent workflow guides, CI thresholds, optional external tool detection, GitHub Actions/pre-commit setup, and explicit passive ZAP scans for URLs the user owns or has permission to test.

Human-readable CLI commands show a branded VibeHat banner or compact header. Machine-readable --json output stays clean and does not include banner/header text.

Release notes and the release checklist live in docs/RELEASE_NOTES.md and docs/RELEASE_CHECKLIST.md.

Recommended user workflow

npm install -g vibehat
vibehat setup
vibehat scan
vibehat fix-loop

vibehat setup defaults to the standard profile. Basic scans work without optional tools; setup checks what is available and helps with optional local scanner setup.

Then paste VIBEHAT_FIX_LOOP_PROMPT.md into Codex, Claude Code, Cursor, or another coding agent.

vibehat setup --profile basic
vibehat setup --profile standard
vibehat setup --profile full
vibehat setup --profile standard --dry-run
vibehat setup --profile standard --yes
vibehat setup --profile full --yes

Setup profiles:

| Profile | Behavior | |---|---| | basic | Confirms VibeHat works and does not install optional external tools. | | standard | Recommended default. Checks Gitleaks, Semgrep, and OSV-Scanner. On Windows, --yes can install missing tools with known safe commands. | | full | Checks standard tools plus Trivy, and shows Docker/ZAP readiness guidance for runtime scans. On Windows, --yes can install missing scanner tools, but never installs Docker or runs ZAP. |

--dry-run previews installed tools, missing tools, and the exact install commands that would run. It does not install anything.

For a full scan against a running app:

vibehat scan --preset full --url http://localhost:3000

Install dependencies

npm install

Build locally

npm run build

Run locally

After building, run commands with Node:

node dist/cli.js setup
node dist/cli.js setup --profile basic
node dist/cli.js setup --profile standard
node dist/cli.js setup --profile full
node dist/cli.js setup --dry-run
node dist/cli.js setup --yes
node dist/cli.js setup --json
node dist/cli.js scan
node dist/cli.js scan --preset basic
node dist/cli.js scan --preset standard
node dist/cli.js scan --preset full
node dist/cli.js scan --json
node dist/cli.js scan --ci
node dist/cli.js scan --fail-on high
node dist/cli.js scan --tools
node dist/cli.js scan --no-gitleaks
node dist/cli.js scan --no-semgrep
node dist/cli.js scan --no-osv
node dist/cli.js scan --no-trivy
node dist/cli.js scan --url http://localhost:3000
node dist/cli.js scan --preset full --url http://localhost:3000
node dist/cli.js scan --url http://localhost:3000 --no-zap
node dist/cli.js scan --url http://localhost:3000 --verbose
node dist/cli.js quick
node dist/cli.js quick --json
node dist/cli.js quick --ci
node dist/cli.js quick --fail-on medium
node dist/cli.js fix-prompt
node dist/cli.js fix-loop
node dist/cli.js report
node dist/cli.js tools
node dist/cli.js tools --json
node dist/cli.js tools install gitleaks --dry-run
node dist/cli.js tools install semgrep --dry-run
node dist/cli.js tools install osv-scanner --dry-run
node dist/cli.js tools install trivy --dry-run
node dist/cli.js init --github-actions
node dist/cli.js init --pre-commit
node dist/cli.js init --pre-commit --strict
node dist/cli.js init --cursor
node dist/cli.js init --claude
node dist/cli.js init --codex
node dist/cli.js init --agent

Or link the package locally:

npm link
vibehat scan
vibehat quick
vibehat fix-prompt
vibehat fix-loop

Generated files

VIBEHAT_SECURITY_REPORT.md
VIBEHAT_REPORT.json
VIBEHAT_FIX_PROMPT.md
VIBEHAT_AGENT_GUIDE.md
VIBEHAT_FIX_LOOP_PROMPT.md

Use report commands to read existing report files:

node dist/cli.js report --print
node dist/cli.js report --json
node dist/cli.js report --format markdown
node dist/cli.js report --format json

--json prints machine-readable JSON only, with no banner or extra text.

CI behavior

Use --ci to fail the command when critical or high findings exist:

node dist/cli.js scan --ci

Use --fail-on for explicit thresholds:

node dist/cli.js scan --fail-on critical
node dist/cli.js scan --fail-on high
node dist/cli.js scan --fail-on medium
node dist/cli.js scan --fail-on low

info findings never fail the build.

Scan presets

vibehat scan defaults to the standard preset.

| Preset | Runs | |---|---| | basic | Built-in VibeHat checks and npm audit only. Skips Gitleaks, Semgrep, OSV-Scanner, Trivy, and ZAP. | | standard | Built-in checks, npm audit, Gitleaks if installed, Semgrep if installed, and OSV-Scanner if installed. Skips Trivy and ZAP by default. | | full | Built-in checks, npm audit, Gitleaks, Semgrep, OSV-Scanner, and Trivy if installed. Runs ZAP only when --url is provided. |

Explicit skip flags override presets:

vibehat scan --preset full --no-trivy
vibehat scan --preset full --url http://localhost:3000 --no-zap

Optional external tools

VibeHat can optionally run local open-source security tools when they are installed on your machine. These tools are not bundled with VibeHat and are not required for basic scans.

VibeHat uses optional tools according to the selected scan preset. Run setup to see what is installed and install missing recommended tools only after confirmation. --json output is valid JSON only, with no banner, prompts, or interactive text.

node dist/cli.js setup
node dist/cli.js setup --profile standard --yes
node dist/cli.js setup --profile full --yes
node dist/cli.js setup --dry-run
node dist/cli.js setup --json
node dist/cli.js tools
node dist/cli.js tools --json
node dist/cli.js tools install gitleaks --dry-run
node dist/cli.js tools install semgrep --dry-run
node dist/cli.js tools install osv-scanner --dry-run
node dist/cli.js tools install trivy --dry-run
node dist/cli.js scan --tools
node dist/cli.js scan --tools --json
node dist/cli.js scan --no-gitleaks
node dist/cli.js scan --no-semgrep
node dist/cli.js scan --no-osv
node dist/cli.js scan --no-trivy

If a tool is missing, VibeHat adds an info finding and continues. quick does not run Gitleaks, Semgrep, OSV-Scanner, or Trivy. If a tool is already installed, vibehat tools install <tool> does not reinstall or upgrade it by default.

Windows setup install commands:

winget install --id Gitleaks.Gitleaks -e
pip install semgrep
winget install --id Google.OSVScanner -e
winget install --id AquaSecurity.Trivy -e

Setup checks for winget before Gitleaks, OSV-Scanner, or Trivy installs and checks for pip before Semgrep installs. macOS and Linux setup currently provide install guidance only; scans remain usable when optional tools are missing.

Docker and OWASP ZAP remain manual setup guidance in vibehat setup. Setup does not install Docker, pull the ZAP image, run ZAP, write reports, or run scans.

Optional local tool links:

• Gitleaks — MIT License — https://github.com/gitleaks/gitleaks
• Semgrep CE — LGPL 2.1 — https://github.com/semgrep/semgrep
• OSV-Scanner — Apache 2.0 — https://github.com/google/osv-scanner
• Trivy — Apache 2.0 — https://github.com/aquasecurity/trivy
• OWASP ZAP — Apache 2.0 — https://github.com/zaproxy/zaproxy

Third-party tool names and trademarks belong to their respective projects/owners. VibeHat is not sponsored by, endorsed by, or affiliated with those projects unless explicitly stated.

See docs/OPTIONAL_TOOLS.md for manual install commands.

Optional runtime web scanning

VibeHat can run an OWASP ZAP baseline/passive scan when you explicitly provide a URL:

node dist/cli.js scan --url http://localhost:3000

ZAP is never run by default, and quick does not run ZAP. Only scan applications you own or have permission to test. The default runtime scan is baseline/passive only, not an aggressive active attack scan.

Use the full preset when you want runtime scanning:

node dist/cli.js scan --preset full --url http://localhost:3000

Docker is required for ZAP scanning. On the first ZAP scan, VibeHat checks for the fixed official image ghcr.io/zaproxy/zaproxy:stable and downloads it automatically if it is missing. The first run can take a few minutes, so VibeHat shows clean progress messages every 30 seconds while hiding noisy Docker layer output by default. Use --verbose if you need raw Docker pull and ZAP output. If Docker is missing or the image download fails, VibeHat keeps running and adds an info finding explaining what happened.

Skip ZAP explicitly:

node dist/cli.js scan --url http://localhost:3000 --no-zap

When ZAP runs through Docker and your app is running on the host machine, Docker may need a host-reachable URL such as http://host.docker.internal:3000 depending on your OS and Docker setup.

The init command can also generate:

.github/workflows/vibehat-security.yml
.git/hooks/pre-commit
.cursor/rules/vibehat-security.md
CLAUDE.md
AGENTS.md
VIBEHAT_AGENT_GUIDE.md
VIBEHAT_FIX_LOOP_PROMPT.md

Using VibeHat with AI coding agents

VibeHat can generate a local-first workflow guide and copy-paste fix loop prompt for Codex, Claude Code, Cursor, and similar coding agents.

vibehat scan
vibehat fix-loop
vibehat fix-prompt
vibehat init --agent

vibehat fix-loop reads the latest VIBEHAT_REPORT.json and creates a project-specific VIBEHAT_FIX_LOOP_PROMPT.md. Paste that file into Codex, Claude Code, Cursor, or another coding agent. The prompt includes the current score/status, severity summary, grouped findings, top critical/high items, detected npm test/build commands, safe fix order, rescan instructions, and careful commit guidance.

vibehat init --agent creates reusable agent guidance files. The workflow tells agents to read the VibeHat reports, fix only the listed issues, avoid exposing secrets, run tests, run VibeHat again, and stop when user approval is required.

Accepted risk and false positives

VibeHat supports documented accepted risk in a repo-local .vibehat.json file. This is for known false positives or intentionally accepted risks after review. Accepted risk does not delete findings, disable scanners, or hide issues silently. Accepted findings still appear in reports under an Accepted Risk section.

Example .vibehat.json:

{
  "acceptedFindings": [
    {
      "id": "accepted-stateless-proxy-csrf",
      "findingId": "VH-SEMGREP-001",
      "ruleId": "javascript.express.security.audit.express-csrf-disabled",
      "category": "code",
      "tool": "semgrep",
      "file": "proxy-server/server.js",
      "reason": "GET-only stateless API, no cookies, sessions, auth, or state-changing operations.",
      "acceptedAt": "2026-05-24",
      "expires": "2026-08-01"
    }
  ]
}

Each accepted finding needs a specific reason of at least 20 characters and at least two exact match fields from findingId, ruleId, category, tool, file, title, and packageName. VibeHat does not support wildcard matching for accepted risk.

For a likely CSRF false positive on a stateless GET-only proxy, match the exact Semgrep rule and file and explain why the endpoint has no cookies, sessions, auth, or state-changing operations.

For a public-by-design SPA client ID in an ignored local env file, be careful. Only document accepted risk when the value is genuinely public by design, the file is local/ignored, and there is no client secret, private key, refresh token, or credential. Secret-related accepted risks require file plus findingId, ruleId, or title, and reports show a manual-review warning.

Expired accepted-risk entries count as open findings again and appear under Expired Accepted Risk.

Implemented in this first MVP step

• Basic CLI entrypoint
• Commands: scan, quick, fix-prompt, fix-loop, report, init
• Project type detection for Node.js, Next.js, React, Express, Python, Docker, and GitHub Actions
• Basic local pattern checks for env files, missing .gitignore, possible secrets, unsafe HTML rendering, token localStorage usage, dynamic code execution, wildcard CORS, and raw error patterns
• Real npm audit --json integration when package-lock.json exists
• Clear dependency findings normalized into the VibeHat report format
• Stable JSON report generation in VIBEHAT_REPORT.json
• JSON CLI output for scan, quick, and report
• CI exit behavior with --ci and --fail-on
• GitHub Actions workflow generation for VibeHat CI scans
• Pre-commit hook generation with quick and strict modes
• Optional Gitleaks integration when gitleaks is installed locally
• Optional Semgrep integration when semgrep is installed locally
• Optional OSV-Scanner integration when osv-scanner is installed locally
• Optional Trivy integration when trivy is installed locally
• Optional OWASP ZAP baseline/passive runtime scanning with explicit --url
• Clean branded terminal output
• Markdown security report generation
• AI-safe fix prompt generation

Still planned

• Stronger GitHub Actions templates
• Dependabot and SECURITY.md generation
• Threat model / PRD helper
• Checkov integration if Trivy does not cover enough IaC needs
• Broader tests and fixtures

Why this exists

AI-assisted coding is fast, but AI often optimizes for code that works, not code that protects.

Common AI-generated mistakes include:

• Hardcoded API keys and secrets
• .env files committed to the repo
• Missing authentication on API routes
• Frontend-only authorization
• Weak CORS settings
• Missing security headers
• Missing input validation
• Unsafe HTML rendering / XSS risk
• Missing rate limits on login/chat/API endpoints
• Vulnerable dependencies
• Insecure cloud/IaC configuration
• Prompt injection issues in chatbot apps
• Debug routes, stack traces, or test endpoints exposed in production

VibeHat should turn security best practice into a simple workflow:

npx vibehat scan
npx vibehat fix-prompt

Product positioning

VibeHat is not "another enterprise SAST platform."

It is a security guardrail for vibe coders and AI-assisted builders.

Target user

Someone who says:

"I built this app with AI. It works. But is it safe to deploy?"

Tagline ideas

• White-hat security for vibe-coded apps.
• Security checks before your AI-built app goes live.
• Find the obvious holes before attackers do.
• A friendly security guardrail for AI-assisted development.

MVP

The first version should be a CLI that runs locally.

Main commands

npx vibehat scan

Runs a normal security scan of the current project.

npx vibehat quick

Runs a faster scan for secrets, dependencies, and obvious risky patterns.

npx vibehat scan --url http://localhost:3000

Runs local code checks and a passive web scan against a running local app.

npx vibehat fix-prompt

Generates a safe, focused prompt the user can paste into Codex, Claude Code, Cursor, etc.

npx vibehat fix-loop

Generates a project-specific repair loop prompt from the latest VIBEHAT_REPORT.json.

npx vibehat init --github-actions

Creates a GitHub Actions workflow for running VibeHat in CI.

npx vibehat init --pre-commit

Creates a Git pre-commit hook that runs vibehat quick --fail-on high before commits.

npx vibehat init --pre-commit --strict

Creates a stricter pre-commit hook that runs vibehat scan --fail-on high.

npx vibehat init --codex

Creates a project instruction file for Codex with secure-coding rules.

npx vibehat init --claude

Creates Claude Code instructions/hooks where possible.

npx vibehat init --cursor

Creates Cursor project rules where possible.

npx vibehat init --agent

Creates a safe AI-agent workflow guide and fix loop prompt for Codex, Claude Code, Cursor, and similar coding agents.

Suggested toolchain

VibeHat should orchestrate existing free/open-source tools where possible.

| Area | Tool | Purpose | |---|---|---| | SAST / code security | Semgrep Community Edition | Find insecure code patterns | | Secrets | Gitleaks | Detect API keys, tokens, passwords, private keys | | Dependency vulnerabilities | OSV-Scanner | Check dependency vulnerabilities against OSV | | Node dependency check | npm audit / pnpm audit | Native JS dependency vulnerability checks | | Python dependency check | pip-audit | Python dependency vulnerability checks | | IaC / config | Checkov | Scan Terraform, Kubernetes, Dockerfile, GitHub Actions, etc. | | Runtime web scan | OWASP ZAP baseline | Passive scan of a running app | | Custom checks | VibeHat rules | AI/vibe-coding-specific checks |

VibeHat should normalize all findings into one common report format.

Example output

VibeHat Security Report

Score: 64/100
Status: Not ready to deploy

Critical
- Exposed Supabase service role key found in .env.example
- API route /api/admin/users appears to have no server-side auth check

High
- CORS allows all origins
- Login route appears to have no rate limiting

Medium
- Missing Content-Security-Policy header
- 3 vulnerable npm packages found

Next step
Run: npx vibehat fix-prompt

Report format

Internally, VibeHat should normalize findings to this shape:

{
  "id": "VH-SECRETS-001",
  "severity": "critical",
  "category": "secret",
  "tool": "gitleaks",
  "title": "Possible API key exposed",
  "file": ".env.example",
  "line": 4,
  "description": "A value that looks like an API key was found in a committed file.",
  "why_it_matters": "Anyone with this key may be able to use your paid account or access private data.",
  "fix": "Remove the key, rotate it in the provider dashboard, and store the new value in environment variables only.",
  "ai_fix_prompt": "Remove all hardcoded secrets from this project. Use environment variables instead. Do not create fake real-looking secrets. Update documentation with safe setup steps."
}

Custom VibeHat checks

VibeHat should include checks aimed at common AI-generated web app mistakes.

Secrets

• Detect .env files committed to the repo
• Detect hardcoded API keys/tokens/passwords
• Detect fake-looking secrets in docs/examples
• Warn if .gitignore does not include .env, .env.local, .env.*.local

Authentication and authorization

• Detect API routes with no visible auth/session check
• Detect admin routes without role checks
• Detect frontend-only authorization patterns
• Detect tokens stored in localStorage
• Detect weak cookie settings

Input/output safety

• Detect missing input validation in API handlers
• Detect unsafe HTML rendering
• Detect missing sanitization for AI/chatbot output
• Detect dangerous functions like eval, new Function, unsafe shell execution

Web security config

• Detect broad CORS settings like *
• Detect missing CSP/HSTS/security headers where relevant
• Detect stack traces or raw error messages returned to users
• Detect exposed debug/test endpoints

AI/chatbot-specific

• Detect system prompts exposed in frontend bundles
• Detect chatbot APIs with no input length limit
• Detect lack of output sanitization
• Detect no rate limiting on chat endpoints
• Detect direct tool/function calling without allowlists

Dependencies and supply chain

• Run dependency vulnerability scans
• Warn about suspicious dependency names or newly-added packages
• Warn if lockfiles are missing
• Warn if install scripts are allowed without review

Project workflow

Suggested development plan for Codex:

1. Build a Node/TypeScript CLI skeleton.
2. Add project detection: Node, Python, Next.js, React, Express, Docker, GitHub Actions.
3. Add scanner runner abstraction.
4. Add Gitleaks integration.
5. Add OSV-Scanner integration.
6. Add Semgrep integration.
7. Add npm/pnpm audit integration.
8. Add custom VibeHat rules.
9. Add report normalization.
10. Add terminal report output.
11. Add Markdown/JSON report export.
12. Add fix-prompt generation.
13. Add init --github-actions.
14. Add init --codex, init --claude, and init --cursor.
15. Add scan --url with OWASP ZAP baseline as an optional advanced feature.

Recommended repo structure

vibehat/
|-- src/
|   |-- cli.ts
|   |-- commands/
|   |   |-- scan.ts
|   |   |-- quick.ts
|   |   |-- fixPrompt.ts
|   |   `-- init.ts
|   |-- scanners/
|   |   |-- semgrep.ts
|   |   |-- gitleaks.ts
|   |   |-- npmAudit.ts
|   |   |-- osvScanner.ts
|   |   |-- trivy.ts
|   |   `-- zap.ts
|   |-- report/
|   |-- prompts/
|   `-- utils/
|-- docs/
|-- assets/
|-- README.md
`-- package.json

Safety boundaries

VibeHat is a defensive tool.

It should:

• Scan only the current project or URLs explicitly provided by the user
• Default to passive checks for runtime scanning
• Avoid exploit automation by default
• Explain findings without teaching harmful exploitation
• Generate fix prompts, not attack prompts
• Warn users before running active scans
• Never upload source code to a third-party service without clear opt-in

Reference material

The included PDF presentation explains the methodology behind this product idea:

reference/Hvordan-vibecode-sikkert.pdf

Use it as background for the security workflow, not as code implementation.