VibeSafe — Security Pre-Flight for AI Coding Agents

Security pre-flight for AI coding agents — plan libs, audit CVEs, certify, then code. Non-blocking in autonomous mode (ex-post report).

VibeSafe — Security Pre-Flight Protocol

Vibe coding fast is fine. Vibe coding blind is debt. Run this BEFORE committing to any library. Redesign is free before you write line 1. It's not free on line 1000.

---

WHEN TO INVOKE

Always invoke when:

• Starting a new project or feature that adds dependencies
• User says "use X library" or "install Y"
• You are about to write a package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml

Safe to skip: Pure logic code, refactoring existing code, documentation, config changes with no new deps.

Autonomous mode: Run phases 1-3 AFTER coding (ex-post), append risk-report.md to session output. Never block the user mid-flow.

Interactive mode: Run phases 1-3 BEFORE coding. User can type /skip-audit to proceed anyway (decision logged in stay_safe.md as "user-waived").

---

PHASE 1: PLAN

Before touching any code, produce this exact table in your response:

## VibeSafe Pre-Flight — Planning

### Proposed Libraries
| Library | Version (target) | Ecosystem | Purpose | Alternatives considered | Why this one |
|---------|-----------------|-----------|---------|------------------------|--------------|
| express | ^4.18           | npm       | HTTP server | fastify, hono, koa | ecosystem size |
| ...     | ...             | ...       | ...     | ...                    | ...          |

### Threat Model
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Supply chain attack via malicious package | Low | Critical | Pin exact versions, use lockfile |
| CVE in outdated dep | Medium | High | Audit before code |
| Secrets leaked to git | Medium | Critical | .env + .gitignore policy |
| Unmaintained lib breaks in 6 months | Medium | Medium | Check last commit < 12 months |

Secrets policy declaration (MANDATORY): Confirm in your plan:

• API keys go into .env file only, never in source code
• .env is always in .gitignore
• Credentials are accessed via environment variables or a secret manager
• .env.example with dummy values is committed to the repo

If any library requires embedding secrets in source code: REDESIGN, find alternative.

---

PHASE 2: AUDIT

Run these checks. Use real tools when available. Always run at least the OSV API check (no tools required).

Node.js / npm

# If package.json exists or you are about to create one:
npm audit --json 2>/dev/null | python3 -c "
import json, sys
d = json.load(sys.stdin)
vulns = d.get('vulnerabilities', {})
critical = sum(1 for v in vulns.values() if v.get('severity') == 'critical')
high = sum(1 for v in vulns.values() if v.get('severity') == 'high')
medium = sum(1 for v in vulns.values() if v.get('severity') == 'moderate')
print(f'Critical: {critical}, High: {high}, Medium: {medium}, Total: {len(vulns)}')
" 2>/dev/null || echo "npm audit not available — use OSV API check instead"

Python / pip

# Install pip-audit if missing, then run:
pip show pip-audit > /dev/null 2>&1 || pip install pip-audit --quiet
pip-audit --format=json 2>/dev/null | python3 -c "
import json, sys
d = json.load(sys.stdin)
deps = d.get('dependencies', [])
critical = [v for dep in deps for v in dep.get('vulns', []) if v.get('severity', '').lower() == 'critical']
high = [v for dep in deps for v in dep.get('vulns', []) if v.get('severity', '').lower() == 'high']
print(f'Critical: {len(critical)}, High: {len(high)}, Packages checked: {len(deps)}')
" 2>/dev/null || echo "pip-audit not available — install: pip install pip-audit"

OSV.dev API (any ecosystem, no local tools required)

For each planned library, query the open vulnerability database:

# Replace LIBRARY_NAME and ECOSYSTEM (npm, PyPI, Go, crates.io, RubyGems, Maven, NuGet)
curl -s -X POST https://api.osv.dev/v1/query \
  -H "Content-Type: application/json" \
  -d '{"package":{"name":"LIBRARY_NAME","ecosystem":"npm"}}' \
  | python3 -c "
import json, sys
d = json.load(sys.stdin)
vulns = d.get('vulns', [])
for v in vulns:
    sev = v.get('database_specific', {}).get('severity', 'unknown')
    print(f\"{v['id']}: {sev} — {v.get('summary','')[:80]}\")
if not vulns:
    print('No known vulnerabilities')
"

Maintenance check (GitHub API)

# For open-source libs, check recency of last commit:
# Replace OWNER/REPO with the package source repository
curl -s "https://api.github.com/repos/OWNER/REPO/commits?per_page=1" \
  -H "Accept: application/vnd.github.v3+json" \
  | python3 -c "
import json, sys
from datetime import datetime, timezone
d = json.load(sys.stdin)
if d and isinstance(d, list):
    date_str = d[0]['commit']['author']['date']
    last = datetime.fromisoformat(date_str.replace('Z', '+00:00'))
    age = (datetime.now(timezone.utc) - last).days
    print(f'Last commit: {date_str} ({age} days ago)')
    if age > 365:
        print('WARNING: Unmaintained (>12 months without commits)')
    if age > 730:
        print('CRITICAL: Abandoned (>24 months without commits)')
else:
    print('Could not fetch commit data')
"

deps.dev API (Google — maintenance, licensing, advisories)

# For npm packages (URL-encode as needed)
PKGNAME="express"
curl -s "https://api.deps.dev/v3alpha/packages/npm/${PKGNAME}" \
  | python3 -c "
import json, sys
d = json.load(sys.stdin)
print('Advisories:', d.get('advisoryKeys', []))
versions = d.get('versions', [])
if versions:
    latest = sorted(versions, key=lambda v: v.get('publishedAt',''), reverse=True)[0]
    print('Latest version:', latest.get('versionKey', {}).get('version'))
    print('Published:', latest.get('publishedAt'))
"

Decision thresholds

Auto-BLOCK (agent cannot proceed without redesign):

• Critical CVE with no fix available
• Package requires embedding credentials in source code
• Package has no license in a licensed project
• Package has 0 downloads and no commits in 24+ months (likely abandoned/typosquat)
• Package name matches a known typosquat pattern (e.g., reacts, lodahs)

CONDITIONAL (user decision required, proceed with acknowledgment):

• High CVE with an available fix (fix it first, then downgrade to CERTIFIED)
• Last commit 12-24 months ago
• Package has <100 weekly downloads (bus factor risk)
• Dependency chain is unusually deep (>15 levels for npm)

CERTIFIED (proceed):

• No critical or high CVEs
• Last commit within 12 months
• Active maintainer community
• License is compatible with project

---

PHASE 3: CERTIFY

After running audits, generate stay_safe.md in the project root by calling:

./tools/stay-safe-gen.sh .vibesafe/summary.json
# OR
python3 ./tools/audit.py --generate-cert

Certification rules:

Audit Result	Certificate Status	Can proceed?
No critical/high CVEs, all maintained	CERTIFIED	Yes, immediately
High CVE with available patch	CONDITIONAL	Yes, after user acknowledges
Medium CVEs or unmaintained packages	CONDITIONAL	Yes, after user acknowledges
Critical CVE with no fix	BLOCKED	No — redesign required
Abandoned package (24+ months)	BLOCKED	No — replace package

When BLOCKED: go back to PHASE 1, replace the flagged library, re-run audit. Maximum 3 redesign iterations. After 3 failures: "I cannot find a safe dependency for this purpose. Please advise."

---

PHASE 4: CODE

Only after stay_safe.md shows CERTIFIED or CONDITIONAL (with explicit user approval in interactive mode):

1. Implement the solution using ONLY audited libraries
2. Apply secrets policy: all credentials via process.env.X or os.environ["X"]
3. Create .env.example with dummy/placeholder values for all required env vars
4. Verify .gitignore covers .env, .env.*, *.key, *.pem, secrets.*, credentials.*, .vibesafe/
5. If a new dependency is discovered mid-coding that was NOT in the Phase 1 plan:
   • Stop
   • Add the package to plan
   • Run OSV API check for that package (minimum)
   • Continue only if clean

---

PHASE 5: POST-CODING REPORT (Autonomous mode)

After coding is complete, run a final scan on actually-installed packages and produce risk-report.md:

./tools/audit.sh --mode=installed > .vibesafe/post-summary.json
./tools/stay-safe-gen.sh .vibesafe/post-summary.json --template=risk-report

If post-scan finds new critical/high CVEs (introduced by transitive dependencies during install), prepend this block to the final response:

WARNING — VibeSafe Post-Coding Scan Found New Issues
=====================================================
Critical CVEs found in installed packages: N
High CVEs found in installed packages: N
These were not present in the pre-flight plan (likely transitive dependencies).
See risk-report.md for full details.
Action required before deploying to production.

---

REDESIGN LOOP

BLOCKED package detected
        |
        v
Remove from plan
        |
        v
Check "Alternatives considered" column from Phase 1
        |
        v
Evaluate alternative with Phase 2 audit
        |
   _____|_____
  |           |
CLEAN      BLOCKED
  |           |
Proceed    Attempt #2 alternative
           If no more alternatives:
           "Can this feature be implemented without any external library?"
           If no: escalate to user

---

SKIP MECHANISM

User can type /skip-audit or skip preflight at any point in interactive mode.

When skipped:

• Log in stay_safe.md: Status: USER-WAIVED — audit skipped by user at {ISO_TIMESTAMP}
• Continue coding normally
• STILL run post-coding report (Phase 5) — skip does not disable ex-post scan
• Note in final output: "Security pre-flight was skipped. Run ./tools/audit.sh before production deploy."

---

SECRETS POLICY — MANDATORY FOR ALL CODE WRITTEN

The agent MUST enforce these rules in every file it writes during Phase 4:

Rule	Implementation
No secrets in source	Never write API keys, passwords, tokens, connection strings in .js/.py/.ts/.go/.rs/.rb
Use env vars	process.env.MY_SECRET (Node) / os.environ["MY_SECRET"] (Python) / os.Getenv("MY_SECRET") (Go)
Document secrets	Always create .env.example with placeholder values
Protect .env	Always ensure .gitignore includes .env and .env.*
Recommend hooks	Suggest detect-secrets or git-secrets as pre-commit hook

---

AGENT INVOCATION REFERENCE

Agent	How to invoke
Claude Code	Skill("vibe-safe") or prefix task: "Run vibe-safe pre-flight first"
Kimi CLI / Hermes	Read this file from known path, execute phases via tool calls
OpenClaw (port 18789)	Configure webhook trigger on package install pattern
VS Code Continue/Copilot	Run "VibeSafe: Audit Project" task from .vscode/tasks.json
CI/CD	.github/workflows/security-gate.yml on push/PR

---

QUICK REFERENCE

/vibe-safe          — run full pre-flight (interactive)
/vibe-safe skip     — skip to coding, run post-scan only
/vibe-safe report   — run phase 5 post-scan on current project
/vibe-safe cert     — show current stay_safe.md status

SCOPE — WHAT VIBESAFE DOES NOT DO

• VibeSafe does not run SAST on your own code (use Semgrep, CodeQL, Bandit)
• VibeSafe does not scan container images (use Trivy, Grype)
• VibeSafe does not manage secret rotation (use Vault, AWS Secrets Manager)
• VibeSafe audits external dependencies only — not your business logic