Skill: nerua1/nerua1-vibe-safe (version 1.1.0)

--- name: vibe-safe description: Security pre-flight for AI coding agents — plan libs, audit CVEs, certify, then code. Non-blocking in autonomous mode (ex-post report). trigger: Before writing any code that installs or uses external packages/libraries version: 1.1.0 compatible: claude-code, kimi, hermes, openclaw, copilot, cursor --- # 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: ```markdown ## 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 ```bash # 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 ```bash # 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: ```bash # 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) ```bash # 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) ```bash # 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: ```bash ./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`: ```bash ./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

path: README.md
content: # VibeSafe

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm audit](https://img.shields.io/badge/npm%20audit-compatible-brightgreen)](https://docs.npmjs.com/cli/v10/commands/npm-audit)
[![pip-audit](https://img.shields.io/badge/pip--audit-compatible-blue)](https://pypi.org/project/pip-audit/)
[![Works with Claude](https://img.shields.io/badge/Claude%20Code-skill-blueviolet)](https://claude.ai)
[![Works with Kimi](https://img.shields.io/badge/Kimi-skill%20file-orange)](https://kimi.moonshot.cn)
[![Works with Hermes](https://img.shields.io/badge/Hermes%2FVox-HARNESS%20%C2%A714-red)](https://github.com/NousResearch/hermes-agent)

**Security pre-flight for AI vibe-coding agents.**

---

> Vibe coding is fast. But **73% of npm packages used in AI-generated code have known CVEs**, and **41% haven't been updated in 2+ years**. VibeSafe is a 60-second pre-flight that catches these before they become your problem.<sup>[1][2]</sup>

---

## The problem

When you ask Claude, Kimi, or any AI agent to "build me a web scraper with Puppeteer and Axios," it immediately starts writing code. It picks libraries by familiarity, not by current CVE status. By the time you realize `lodash@4.17.15` has a prototype pollution vuln or that `request` (44M weekly downloads) has been deprecated for three years — your architecture is built around them.

Changing dependencies late costs 10x more than changing them before you write line one.

## What VibeSafe does

1. Forces AI agents to **plan libraries BEFORE coding** — the plan becomes an auditable manifest
2. **Audits CVEs and maintenance health in real-time** via `npm audit`, `pip-audit`, and the OSV.dev API
3. **Issues a `stay_safe.md` certificate** (or triggers a redesign loop if blockers are found)

```mermaid
graph TD
    A[AI Agent starts coding] --> B[PLAN: list libs + threats]
    B --> C[AUDIT: npm audit + pip-audit + OSV]
    C --> D{CERTIFY?}
    D -->|PASS| E[stay_safe.md ✓]
    D -->|FAIL| F[REDESIGN]
    F --> B
    E --> G[CODE]
    G --> H[POST-SCAN report]
```

## VibeSafe Lifecycle (Detailed)

```mermaid
flowchart LR
    subgraph PLAN["1. PLAN PHASE"]
        A1[AI Agent lists<br/>intended libraries] --> A2[Generate<br/>dependency manifest]
        A2 --> A3[Identify<br/>threat surface]
    end

    subgraph AUDIT["2. AUDIT PHASE"]
        B1[npm audit / pip-audit] --> B2[OSV.dev API<br/>cross-ecosystem check]
        B2 --> B3[Parse CVEs +<br/>maintenance health]
    end

    subgraph CERTIFY["3. CERTIFY PHASE"]
        C1{Critical CVEs?} -->|No| C2[Issue stay_safe.md<br/>certificate]
        C1 -->|Yes| C3{Unmaintained<br/>>2yr?}
        C3 -->|Yes| C4[BLOCKED:<br/>replace library]
        C3 -->|No| C5[WARN:<br/>suggest alternatives]
    end

    subgraph CODE["4. CODE PHASE"]
        D1[AI Agent codes<br/>against certified deps] --> D2[On save:<br/>re-audit deps]
        D2 --> D3[Post-scan report]
    end

    PLAN --> AUDIT
    AUDIT --> CERTIFY
    CERTIFY -->|PASS| CODE
    CERTIFY -->|FAIL| PLAN
    CODE -->|New dep added| PLAN
```

## Why not just run npm audit at the end?

Because by then, the architecture is built around the vulnerable library.

- Switching from `request` to `got` mid-project means rewriting HTTP call signatures everywhere
- Switching from `jsonwebtoken@8` (has CVE) to `jose` means rethinking your auth flow
- Switching from an unmaintained geoparsing library means your AI agent has to learn a new API from scratch — and it will hallucinate because there is no training data for it

VibeSafe catches it **when changing is still free** — before a single line of integration code is written.

---

## Agent compatibility

| Agent | Integration | How |
|-------|-------------|-----|
| Claude Code | Skill | `/vibe-safe` |
| Kimi | Skill file | `cat skills/vibe-safe.md` in system prompt |
| Hermes / Vox | HARNESS §14 | auto-loaded at session start |
| OpenClaw | Webhook | `tools/audit.sh` as pre-hook |
| VS Code | Tasks | `.vscode/tasks.json` |
| GitHub CI | Actions | `ci/security-gate.yml` |

---

## Quick start

```bash
git clone https://github.com/nerua1/vibe-safe
cd vibe-safe && chmod +x tools/audit.sh
./tools/audit.sh /path/to/your/project
```

That's it. The script will:
- Detect your package ecosystem (`package.json`, `requirements.txt`, `Pipfile`, `pyproject.toml`, `go.mod`)
- Run the appropriate auditor(s)
- Pull CVE data from [OSV.dev](https://osv.google.com/) for any library not covered by native tooling
- Write `stay_safe.md` to your project root if clean
- Print a BLOCKED report if anything critical or high is found

---

## Claude Code integration

Install the skill globally:

```bash
cp skills/vibe-safe.md ~/.claude/skills/vibe-safe.md
```

Then in any project, before starting a coding session:

```
/vibe-safe
```

The skill prompts you to list your intended libraries, runs the audit, and either issues the certificate or explains what to use instead.

---

## Kimi / Hermes integration

For Kimi, prepend the skill file to your system prompt:

```bash
cat skills/vibe-safe.md >> your-system-prompt.md
```

For Hermes with a HARNESS setup, add to `HARNESS.md` §14:

```markdown
## §14 Security Pre-flight
Before any coding task that introduces new dependencies, run VibeSafe:
`bash /path/to/vibe-safe/tools/audit.sh $PROJECT_ROOT`
Block until a stay_safe.md certificate exists.
```

---

## GitHub Actions integration

Add to your repo:

```yaml
# .github/workflows/vibe-safe.yml
name: VibeSafe Security Gate
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run VibeSafe
        run: |
          bash ci/security-gate.yml
```

Full workflow in `ci/security-gate.yml`.

---

## The stay_safe.md certificate

When audit passes, VibeSafe writes a `stay_safe.md` to your project root:

```markdown
# VibeSafe Certificate
**Issued:** 2026-05-02T14:23:11Z
**Project:** my-scraper
**Audited libraries:** axios@1.6.8, cheerio@1.0.0-rc.12, puppeteer@21.7.0
**CVEs found:** 0
**Unmaintained (>2yr):** 0
**Audit tool:** npm audit (v10.5.0) + OSV.dev API
**Valid until:** 2026-06-02 (re-audit after 30 days or new dep)
```

This certificate can be committed to your repo. It tells reviewers and future AI agents: "these dependencies were vetted."

---

## Stats and context

AI agents are not security engineers. They optimize for "will this work" not "is this safe to ship."

- **49% of developers** don't regularly audit dependencies — and AI agents inherit this behavior by default.<sup>[1]</sup>
- **Top 10 most exploited vulnerabilities in 2024** all had patches available for months before exploitation. The patch existed; nobody ran the audit.<sup>[3]</sup>
- **~20% of popular npm packages** are effectively unmaintained (last commit >2 years ago, no active maintainer).<sup>[2]</sup>
- The median time between a CVE being published and a developer patching it is **>84 days**.<sup>[1]</sup>

VibeSafe does not fix the underlying ecosystem problem. It makes the audit happen at the only moment that costs nothing: before you build.

---

## Footnotes

[1] Snyk, *State of Open Source Security 2023*. https://snyk.io/reports/open-source-security/

[2] Socket.dev, *Open Source Security Research 2024*. https://socket.dev/research

[3] CISA, *Known Exploited Vulnerabilities Catalog — 2024 Annual Summary*. https://www.cisa.gov/known-exploited-vulnerabilities-catalog

---

## Installation

```bash
# Clone
git clone https://github.com/nerua1/vibe-safe
cd vibe-safe

# Make scripts executable
chmod +x tools/audit.sh tools/osv-lookup.sh

# Optional: install Python deps for pip-audit support
pip install pip-audit

# Optional: add to PATH
ln -s "$(pwd)/tools/audit.sh" /usr/local/bin/vibe-safe
```

**Requirements:**
- bash 4+
- Node.js 18+ and npm 8+ (for npm projects)
- Python 3.9+ and pip-audit (for Python projects)
- curl (for OSV.dev API calls)
- jq (for JSON parsing)

---

## Repository structure

```
vibe-safe/
├── tools/
│   ├── audit.sh          # Main entry point
│   ├── osv-lookup.sh     # OSV.dev API wrapper
│   └── report.sh         # Post-coding risk report
├── skills/
│   ├── vibe-safe.md      # Claude Code / Kimi skill
│   └── vibe-safe-short.md # Compact version for context-limited agents
├── templates/
│   ├── stay_safe.md      # Certificate template
│   └── blocked_report.md # Blocked report template
├── harness/
│   └── harness-14.md     # HARNESS §14 snippet for Hermes/Vox
├── ci/
│   └── security-gate.yml # GitHub Actions workflow
├── docs/
│   ├── how-it-works.md
│   ├── adding-ecosystems.md
│   └── false-positives.md
└── stats/
    └── sources.md        # Full citations for all stats
```

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

Short version: PRs are welcome for new ecosystem support (Rust/Cargo, Ruby/Bundler, Java/Maven), improved OSV.dev coverage, and agent skill files for new AI agents.

False positives (library flagged as unsafe but actually fine for your use case) — please open an issue with the `false-positive` template.

---

## License

MIT — see [LICENSE](LICENSE).

Built for the vibe-coding era. Use it before your AI agent doesn't.

---

*Built by [nerua1](https://github.com/nerua1)*

☕ **Support:** [PayPal.me/nerudek](https://www.paypal.me/nerudek) | [Dev.to](https://dev.to/nerua1)


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: clean (LOW)