codevet-cli 1.1.0 → 1.1.1

package/.claude/skills/codevet/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: codevet
+description: Vet a project for security issues (leaked secrets, vulnerable dependencies, missing middleware, personal data flow) before committing, deploying, or trusting a cloned repo.
+---
+
+See [`AGENTS.md`](../../../AGENTS.md) at the repo root for full instructions —
+this file exists only so Claude Code discovers the skill; the canonical
+content lives in one place to avoid drift between CLI-specific copies.

package/.cursor/skills/codevet/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: codevet
+description: Vet a project for security issues (leaked secrets, vulnerable dependencies, missing middleware, personal data flow) before committing, deploying, or trusting a cloned repo.
+---
+
+See [`AGENTS.md`](../../../AGENTS.md) at the repo root for full instructions —
+this file exists only so Claude Code discovers the skill; the canonical
+content lives in one place to avoid drift between CLI-specific copies.

package/.opencode/skills/codevet/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: codevet
+description: Vet a project for security issues (leaked secrets, vulnerable dependencies, missing middleware, personal data flow) before committing, deploying, or trusting a cloned repo.
+---
+
+See [`AGENTS.md`](../../../AGENTS.md) at the repo root for full instructions —
+this file exists only so Claude Code discovers the skill; the canonical
+content lives in one place to avoid drift between CLI-specific copies.

package/AGENTS.md

@@ -0,0 +1,70 @@
+# CodeVet — Agent Skill
+
+This file is the canonical instructions for using CodeVet from inside an
+AI coding CLI (Claude Code, Cursor, OpenCode, Codex, etc.). Every CLI-specific
+skill file in this repo (`.claude/skills/codevet/SKILL.md`,
+`.cursor/skills/codevet/SKILL.md`, etc.) just points back here — this is
+the one place the actual instructions live.
+
+## What this skill does
+
+Lets you ask the agent to vet a project's security directly in
+conversation — "scan this repo with CodeVet," "check this project for
+leaked secrets," "is this safe to deploy" — without leaving the coding CLI
+to run a separate tool.
+
+## When to use it
+
+- Before committing, pushing, or opening a PR
+- Before deploying to production
+- Before cloning and trusting a third-party repo
+- When asked to "check for security issues" or "vet this code"
+
+## How to run it
+
+```bash
+npx codevet scan                          # scan the current project
+npx codevet scan <path>                   # scan a specific folder
+npx codevet scan <git-url>                # review a repo before keeping a clone
+npx codevet scan --json report.json       # machine-readable output
+npx codevet scan --fail-on-high-risk      # non-zero exit if anything critical/high is found
+```
+
+If `codevet` isn't installed yet, `npx codevet` fetches and runs it
+without a global install.
+
+## Interpreting results
+
+CodeVet reports four categories, each with a severity:
+
+- **CRITICAL** — fix before anyone else touches this code (e.g. a
+  Supabase table with no Row Level Security)
+- **HIGH** — fix before launch (e.g. missing rate limiting on auth routes,
+  a leaked secret, a known-vulnerable dependency)
+- **MODERATE** — real, but rarely the sole cause of an incident on its own
+  (e.g. missing security headers)
+- **LOW** — worth doing, not urgent
+
+Every finding includes a `Suggested fix` with real, working code — apply
+it directly rather than researching the fix from scratch. When a finding
+has a `Verify:` note, treat that as a genuine caveat: some checks are
+heuristic and can be wrong for unusual setups (e.g. the "no validation
+library" check can't see hand-written validation).
+
+## What NOT to do with this skill
+
+- Don't silently "fix" every finding without explaining it to the user
+  first — some are false positives, and blindly applying every suggested
+  fix (especially `codevet remove-dependency`) can break a working app
+- Don't treat a clean scan as a guarantee — CodeVet checks known,
+  disclosed issues in specific categories, not a full security audit
+- Don't run `codevet fix --force` or `codevet remove-dependency` without
+  explicit user confirmation — these modify the project's dependencies
+
+## Related commands
+
+- `codevet fix` — safely upgrade flagged dependencies within existing semver ranges
+- `codevet fix --force` — allow major-version upgrades (may need code changes after)
+- `codevet remove-dependency <name>` — explicitly uninstall a flagged package (not the same as fixing it)
+- `codevet clean <path>` — remove a repo CodeVet previously cloned and kept
+- `codevet config disable <secrets|dependencies|hygiene|data-flow|all>` — turn off a specific check for this project

package/CLAUDE.md

@@ -0,0 +1,2 @@
+See [AGENTS.md](./AGENTS.md) — canonical instructions for this repo,
+shared across every AI coding CLI rather than duplicated per-tool.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## The short version
+
+Be respectful. Assume good faith. Disagree about code, not about people.
+
+## Expected behavior
+
+- Give constructive feedback focused on the work, not the person
+- Accept that reasonable people disagree about implementation choices
+- Respect that maintainers are often volunteers with limited time
+
+## Unacceptable behavior
+
+- Harassment, insults, or personal attacks, in issues, PRs, discussions, or
+  anywhere else connected to this project
+- Publishing others' private information without consent
+- Sustained disruption of discussions or reviews
+
+## Enforcement
+
+Maintainers may remove comments, close discussions, or block contributors
+who violate this code of conduct. Report concerns the same way you'd
+report anything else sensitive — privately, per the contact details in
+`README.md`, not in a public thread.
+
+## Scope
+
+This applies within all project spaces (issues, pull requests,
+discussions) and in any other setting when someone is representing the
+project publicly.

package/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to CodeVet
+
+## Before you start
+
+- Check existing issues/PRs first — avoid duplicate work
+- For anything beyond a small fix, open an issue to discuss the approach
+  before writing code
+
+## Code quality — not allowed in this codebase
+
+- `console.log` left in production code (use structured output through the
+  existing report/CLI layers instead)
+- TODOs, placeholder implementations, or fake/mocked scan results outside
+  of `tests/`
+- Commented-out code, dead code, unused imports
+- `@ts-ignore` or `as any` used to silence a real type problem instead of
+  fixing it
+- A "fix" that only handles the reproduction case shown in an issue —
+  trace the actual root cause (see the EXDEV cross-drive bug and the
+  Windows `unzip` bug in git history for what root-cause fixes look like
+  here, versus a narrow patch)
+
+## Engineering standards (please actually follow these)
+
+This project deliberately avoids "vibe coding" — generating code until it
+looks like it works. Concretely, that means:
+
+- **Understand the change before writing it.** What does it need to do,
+  where does it belong, what existing code should it reuse?
+- **Minimum code that correctly solves the problem.** Don't add
+  abstraction, config options, or generality a second real use case
+  hasn't actually asked for yet.
+- **Every dependency must justify itself.** Before adding a package: can
+  Node's standard library do this? Is it maintained? Run `npm audit`
+  before proposing it — a vulnerability in a *security tool's* own
+  dependency tree undermines the whole project (this has already caught
+  one proposed dependency during development — see git history).
+- **No mock data, no fake functionality.** Every finding shown to a user
+  must come from a real scanner run against real test data, not a
+  hardcoded example.
+- **Type-safe.** Strict TypeScript, no `any`, no unexplained `@ts-ignore`.
+- **Test against a real, reproduced scenario**, not just "it compiles."
+  If you're fixing a bug, reproduce it first, then verify the fix against
+  that reproduction — a regression test, not just a description.
+
+## If you're using an AI coding tool to contribute
+
+CodeVet's own audience uses AI coding tools daily, so this comes up a lot
+— the same discipline applies to AI-assisted PRs as to any other:
+
+- Generate only the files the change actually requires — an AI tool
+  "helpfully" refactoring unrelated files, renaming things, or reorganizing
+  folders outside the scope of the change will be asked to be reverted
+- Don't let the AI invent architecture or add a dependency the issue
+  didn't call for — if it suggests one, evaluate it against the
+  Dependencies rule above before including it in the PR
+  A locked pattern in this codebase (e.g. scanners always wrap a real
+  external tool, never reimplement detection) should not get silently
+  "improved" away because a different approach seemed cleaner
+- Ask for the complete implementation, not `// rest of the code...` or
+  `// TODO: implement error handling` — incomplete generated code should
+  never reach a PR
+- Run the real verification steps below yourself before opening the PR —
+  "the AI said it works" is not the same as it actually working against
+  real test data, and this project's whole history (see git log) is full
+  of cases where something that looked correct had a real bug underneath
+
+## Definition of done
+
+A change is not complete until it is:
+
+- Production-ready (no placeholder or "good enough for now" behavior)
+- Type-safe (strict TypeScript, `npx tsc --noEmit` clean)
+- Tested against a real, reproduced scenario (not just "it compiles")
+- Free of dead code, TODOs, and stray `console.log`
+- Passing `npm test` and showing `0 vulnerabilities` from `npm audit`
+- Verified with `node dist/index.js scan .` (CodeVet against its own code)
+
+Anything less is incomplete, regardless of how small the change looks.
+
+## Setting up locally
+
+```
+git clone https://github.com/i-akb25/codevet.git
+cd codevet
+npm install
+npm run build
+node dist/index.js scan .   # should complete cleanly against this repo itself
+```
+
+## Before opening a PR
+
+```
+npm run build          # must compile with zero TypeScript errors
+npm audit               # must show 0 vulnerabilities before you add a dependency
+node dist/index.js scan .   # sanity-check CodeVet against its own code
+```
+
+## Adding a new scanner
+
+Each scanner lives in `src/scanners/`, wraps a real, trusted external tool
+(never reimplements detection logic from scratch), and exports a function
+returning normalized findings — follow the shape of
+`src/scanners/gitleaksScanner.ts` or `npmAuditScanner.ts` as a template.
+
+## A known, accepted noise source in CodeVet's own self-scan
+
+When CodeVet scans its own repo, Bearer's data-flow check flags roughly
+70 LOW-severity "logger leak" findings across `src/index.ts` and
+`src/report.ts`. This is expected, not a bug: those files' entire job is
+printing scan results to the terminal — that's the CLI's actual output,
+not a leak. This is specific to a CLI tool scanning itself; it does not
+affect Bearer's real value for a typical backend app, where
+`console.log`-ing a password or SSN genuinely is a problem worth catching.
+
+**A real false positive was found and fixed here, worth knowing about
+directly:** `src/fixLibrary/templates.ts` is a library of example code
+shown to users (including a variable named `SECRET` correctly read from
+`process.env` — the safe pattern we specifically teach). Bearer's static
+analysis flagged that as a CRITICAL hardcoded secret before we added
+`--skip-path` for fix-library/template directories in
+`src/scanners/bearerScanner.ts`. Any new template file added to that
+scanner needs to stay covered by that skip-path — verify with
+`node dist/index.js scan . --no-secrets --no-dependencies --no-hygiene`
+before merging.
+
+## Questions
+
+Open a discussion or issue — this file will grow as real contribution
+patterns emerge, rather than trying to anticipate everything upfront.

package/INFO.md

@@ -0,0 +1,143 @@
+# INFO.md — What every file and folder in this repo is for
+
+This is the complete map of the repository: what each piece does, who
+actually needs to touch it, and how to use it. If you're new to this repo,
+read this before poking around.
+
+---
+
+## The short version — what you actually need, by role
+
+**Just want to use CodeVet?** You need none of this repo directly —
+`npm install -g codevet-cli`. Read [`README.md`](./README.md) and
+[`docs/HELP.md`](./docs/HELP.md).
+
+**Want to contribute code?** You need `src/`, `tests/`, and
+[`CONTRIBUTING.md`](./CONTRIBUTING.md). Everything under `dist/` and
+`templates/` is *generated* — never hand-edit it.
+
+**Want to understand a specific check's logic?** Go straight to
+`src/scanners/<name>.ts` — each one is self-contained and documented.
+
+**Want to package/deploy CodeVet somewhere new?** You need `package.json`,
+`scripts/postinstall.mjs`, and `action.yml`.
+
+---
+
+## Root-level files
+
+| File | What it is | Who touches it |
+|---|---|---|
+| `README.md` | The landing page — install, usage, what it checks | Anyone updating the public-facing pitch |
+| `INFO.md` | This file — the full repo map | Anyone adding/removing/renaming a file (keep this in sync) |
+| `AGENTS.md` | Canonical instructions for using CodeVet from inside an AI coding CLI (Claude Code, Cursor, etc.) — the single source of truth all `.claude/`, `.cursor/`, `.opencode/` skill files point back to | Anyone changing how the CLI should be used conversationally |
+| `CLAUDE.md` | One-line pointer to `AGENTS.md`, so Claude Code picks up the instructions automatically | Rarely — only if the pointer pattern itself changes |
+| `LICENSE` | MIT license text | Legal only |
+| `PRIVACY.md` | Exactly what data each check touches and where it goes (no telemetry, no CodeVet server) | Update if a new scanner talks to a new external service |
+| `TERMS.md` | What a scan result does and doesn't mean — no-warranty language | Update if the product's scope/guarantees change |
+| `SECURITY.md` | How to report a vulnerability *in CodeVet itself* (private disclosure) | Rarely |
+| `CODE_OF_CONDUCT.md` | Standard OSS contributor conduct policy | Rarely |
+| `CONTRIBUTING.md` | Engineering standards, code-quality bans, Definition of Done, AI-assisted-contribution guidance | Update when the engineering bar or contribution process changes |
+| `action.yml` | The composite GitHub Action definition — what `uses: codevet/codevet@v1` actually runs in someone else's CI | Update when the scan command's flags or the PR-comment flow changes |
+| `package.json` | Dependencies, `bin` entry (makes `codevet` a real command), build/test/publish scripts | Anyone adding a dependency or changing how the package is built/published |
+| `tsconfig.json` | TypeScript compiler config — strict mode on | Rarely |
+| `package-lock.json` | Locked dependency versions | Auto-managed by npm, don't hand-edit |
+
+---
+
+## `src/` — the actual source code (edit this, not `dist/`)
+
+| Path | What it is |
+|---|---|
+| `src/index.ts` | The CLI entry point — wires every scanner together, defines all commands (`scan`, `fix`, `remove-dependency`, `clean`, `config`), handles the existence check, error handling, and the pre-clone confirmation flow |
+| `src/report.ts` | Formats every scanner's output into the human-readable report — severity labels (CRITICAL/HIGH/MODERATE/LOW), the `hasFindings`/`hasHighRiskFindings` logic that CI gating depends on |
+| `src/config.ts` | Reads/writes `.codevet/config.json` (per-project enable/disable toggles) — **only trusted for a project the user owns locally**, never for an untrusted clone (see the security note in the file itself) |
+| `src/resolveTarget.ts` | Turns CLI args into an actual scan target — handles unquoted multi-word paths, git/GitHub URL cloning, persisting or discarding a clone, the provenance marker `codevet clean` relies on |
+| `src/promptConfirm.ts` | The y/N confirmation prompt (built on Node's own `readline`, no extra dependency) |
+| `src/detectors/detectStack.ts` | Looks for `package.json`/`requirements.txt`/`build.gradle`/`Podfile` to identify which stack(s) are present |
+| `src/fixLibrary/templates.ts` | **Single source of truth** for every suggested-fix code snippet (helmet, CORS, rate limiter, account backoff, error handler, password hashing, JWT, validation, file upload, `.env.example`, RLS-enable SQL, the CI workflow template, the pre-commit hook template) |
+| `src/scanners/gitleaksScanner.ts` | Wraps the vendored `gitleaks` binary — secret detection |
+| `src/scanners/npmAuditScanner.ts` | Wraps `npm audit` — Node dependency vulnerabilities |
+| `src/scanners/pipAuditScanner.ts` | Wraps `pip-audit` — Python dependency vulnerabilities (supports both `requirements.txt` and `pyproject.toml`) |
+| `src/scanners/bearerScanner.ts` | Wraps the vendored `bearer` binary — personal data flow (PII logging, etc.); no native Windows build, handled gracefully |
+| `src/scanners/hygieneScanner.ts` | CodeVet's own heuristic scanner — missing middleware, error leaks, Supabase RLS gaps — maps every finding to a real fix template |
+| `src/scanners/npmFixActions.ts` | Backs the `fix` and `remove-dependency` commands |
+
+**Every scanner file follows the same shape:** wraps a real, trusted
+external tool (never reimplements detection logic), exports a function
+returning normalized findings, and throws a specific error class when the
+tool genuinely fails — never silently returns an empty result on failure.
+Follow this pattern for any new scanner (see `CONTRIBUTING.md`).
+
+---
+
+## `dist/` — compiled output (generated, never hand-edit)
+
+Produced by `npm run build` (`tsc`). This is what actually ships when
+someone installs the package — `src/` is only needed by contributors
+editing the tool. If you edit anything in `dist/` directly, it'll be
+silently overwritten on the next build.
+
+---
+
+## `templates/` — human-browsable fix-library files (generated)
+
+A plain, readable copy of every fix template from `src/fixLibrary/templates.ts`,
+regenerated via `npm run generate-templates`. This exists so someone can
+browse the actual fix code on GitHub without reading TypeScript string
+literals. **Never hand-edit files under here** — edit `templates.ts` and
+regenerate. `scripts/generateTemplates.mjs` is what performs the generation.
+
+---
+
+## `scripts/` — standalone Node scripts (not part of the compiled CLI)
+
+| File | What it does |
+|---|---|
+| `scripts/postinstall.mjs` | Runs automatically after `npm install` — downloads the correct `gitleaks`/`bearer` binary for the installing machine's OS/architecture. Skips `bearer` cleanly on Windows (no native build exists) |
+| `scripts/generateTemplates.mjs` | Regenerates `templates/` from `src/fixLibrary/templates.ts` |
+| `scripts/postPrComment.mjs` | Used by `action.yml` — formats a JSON scan report as Markdown and posts it as a PR comment via the GitHub REST API |
+
+---
+
+## `tests/` — the automated test suite
+
+Run with `npm test`. Uses Node's built-in test runner (`node:test`), no
+external test framework — one less dependency to justify. Each scanner
+that can be tested without a real network call has real, reproduced test
+cases (a vulnerable fixture, a clean fixture) — not mocked data.
+
+| File | Covers |
+|---|---|
+| `tests/config.test.ts` | `.codevet/config.json` load/save, `.gitignore` auto-append |
+| `tests/detectStack.test.ts` | Stack detection across Node/Python/multi-stack/unrecognized projects |
+| `tests/hygieneScanner.test.ts` | Every hygiene check — helmet, error leaks, CORS, Supabase RLS (both Express and non-Express projects) |
+| `tests/fixtures/` | Present but currently empty — tests build fixtures inline (temp directories created and torn down per-test) rather than static files here. Kept as the conventional place to add static fixtures if a future test needs one |
+
+---
+
+## `docs/` — reference documentation
+
+| File | What it is |
+|---|---|
+| `docs/HELP.md` | The complete command reference — every flag, every subcommand, kept in sync with actual `--help` output |
+| `docs/ABOUT.md` | Project philosophy, why it exists, explicit scope boundaries |
+| `docs/SECURITY-CHECKLIST.md` | The full severity-annotated security checklist CodeVet's automated checks are built around, including what stays a human judgment call |
+
+---
+
+## `.claude/`, `.cursor/`, `.opencode/` — Agent Skill packaging
+
+Each contains a thin `skills/codevet/SKILL.md` that just points back to
+the canonical `AGENTS.md` at the repo root — so there's exactly one place
+the actual instructions live, no risk of the copies drifting out of sync.
+This is what lets someone ask their AI coding CLI to "scan this with
+CodeVet" directly in conversation.
+
+---
+
+## `bin/vendor/` (not committed — created by `postinstall.mjs`)
+
+Where the downloaded `gitleaks`/`bearer` binaries actually live after
+install. Gitignored, platform-specific, regenerated by every fresh
+`npm install`.

package/PRIVACY.md

@@ -0,0 +1,71 @@
+# Privacy Policy
+
+CodeVet is a local command-line tool. There is no CodeVet server, no account,
+and no telemetry — this document describes exactly what data the tool
+touches and where it goes, based on what the code actually does.
+
+## What CodeVet does NOT do
+
+- It does not collect, transmit, or store analytics about you or your usage
+- It does not send your source code, file contents, or scan results to any
+  CodeVet-operated server — there isn't one
+- It does not require a sign-up, account, or API key to use
+
+## What actually happens when you run a scan
+
+**Secret scanning (`gitleaks`)** — runs entirely on your machine, reading
+files from the path you point it at. Nothing leaves your machine during
+this step.
+
+**Dependency scanning (`npm audit`)** — this step sends your project's
+package names and version numbers to the public npm registry
+(`registry.npmjs.org`) so it can be checked against npm's own published
+vulnerability advisory database. This is standard `npm audit` behavior,
+identical to running it yourself directly — CodeVet does not add any
+additional data to that request, and the registry is operated by npm/GitHub,
+not by CodeVet.
+
+**Scanning a git/GitHub URL** — CodeVet runs a normal `git clone` against
+the URL you provide. This follows whatever access rules that repository
+host already has (e.g. a private GitHub repo still requires your existing
+git credentials — CodeVet doesn't bypass or store these).
+
+**Installing CodeVet itself** — the `postinstall` step downloads the
+`gitleaks` binary directly from its official GitHub releases page, matched
+to your OS/architecture. No user data is included in that request.
+
+## Local files CodeVet creates
+
+- `.codevet/config.json` — stores which scanners you've enabled/disabled
+  for a project. Stays on your machine, auto-added to `.gitignore`, never
+  transmitted anywhere.
+- Temporary clone folders (for URL scans) — created under your OS's temp
+  directory, deleted automatically unless you choose to keep the result.
+
+## Third-party services this tool talks to
+
+| Service | What for | Whose policy applies |
+|---|---|---|
+| npm registry (`registry.npmjs.org`) | Dependency vulnerability lookups | [npm's privacy policy](https://docs.npmjs.com/policies/privacy) |
+| GitHub (`github.com`, releases) | Downloading the gitleaks binary; cloning repos you point CodeVet at | [GitHub's privacy statement](https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement) |
+
+## Compliance posture (India's DPDP Act, and equivalents elsewhere)
+
+CodeVet does not collect, store, or process personal data as defined under
+India's Digital Personal Data Protection Act, 2023 (or GDPR, CCPA, etc.) —
+there is no CodeVet-operated backend for any personal data to flow into.
+Scanning happens entirely on your machine; the only external calls are the
+ones described above (npm registry, GitHub), each governed by that
+service's own policy, not CodeVet's.
+
+If CodeVet ever introduces a feature that does process personal data (for
+example, an account-based hosted dashboard), that feature will document
+its own lawful basis, retention period, and user rights under applicable
+law before it ships — not retroactively.
+
+## Changes to this policy
+
+If CodeVet ever adds a feature that changes this (for example, an optional
+hosted dashboard mentioned as a possible future addition), that feature
+will be opt-in and this document will be updated to describe it plainly
+before it ships.

package/README.md

@@ -61,7 +61,7 @@ Full command reference: [`docs/HELP.md`](./docs/HELP.md).
 
 | Check | Tool | Severity model |
 |---|---|---|
-| Leaked secrets — API keys, credentials, connection strings, Supabase service-role-key exposure | `gitleaks` (extended ruleset) | Every finding is real and confirmed |
+| Leaked secrets — API keys, credentials, connection strings, Supabase service-role-key exposure | `gitleaks` (extended ruleset) | High-confidence pattern matches — still worth a quick look, since any pattern-based scanner can flag example/fixture/documentation code that only looks like a real secret |
 | Dependency vulnerabilities (Node) | `npm audit` | CRITICAL/HIGH/MODERATE/LOW from the advisory database. Skipped (not failed) on pnpm-managed projects — a confirmed bug in npm itself, run `pnpm audit` directly for those |
 | Dependency vulnerabilities (Python) | `pip-audit` | Unranked — PyPA's database has no severity field; prioritize by whether a fix exists |
 | Missing security middleware — no helmet, no rate limiting, wide-open CORS, error responses leaking internals, missing Supabase Row Level Security | CodeVet's own heuristic scanner | CRITICAL/HIGH/MODERATE, each with a `Verify:` note on how the check could be wrong |

package/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+CodeVet is a security tool, so vulnerabilities in its own code are treated
+seriously and reviewed quickly.
+
+## Reporting a vulnerability
+
+**Please do not open a public GitHub issue for security vulnerabilities.**
+Instead, use GitHub's private vulnerability reporting (Security tab →
+"Report a vulnerability") on this repository, or email the maintainers
+directly (see `README.md` for current contact details).
+
+Please include:
+- A description of the vulnerability and its potential impact
+- Steps to reproduce it
+- Which version of CodeVet you tested against
+
+## What happens next
+
+- We'll acknowledge your report as soon as possible
+- We'll investigate and let you know if it's confirmed, and roughly how
+  long a fix will take
+- We'll credit you in the fix's changelog, unless you'd prefer to stay
+  anonymous
+- Please give us a reasonable window to ship a fix before any public
+  disclosure
+
+## Scope
+
+This policy covers CodeVet's own code (the CLI, the GitHub Action, the
+postinstall script, the bundled `.gitleaks.toml` rules). It does not cover
+vulnerabilities in the third-party tools CodeVet wraps (`gitleaks`,
+`npm`/`npm audit`) — please report those directly to their respective
+maintainers.
+
+## A note on irony
+
+Yes, a security scanner having its own vulnerabilities is exactly the kind
+of thing it's supposed to help catch elsewhere. `npm audit` runs against
+this project's own dependencies as part of CI for that reason — see
+`CONTRIBUTING.md` for how that's enforced before any change is merged.

package/TERMS.md

@@ -0,0 +1,56 @@
+# Terms of Use
+
+By downloading, installing, or using CodeVet, you agree to the following.
+
+## What CodeVet is
+
+CodeVet is a free, open-source command-line tool that runs trusted
+third-party security scanners (currently `gitleaks` for leaked secrets and
+`npm audit` for known dependency vulnerabilities) against code you point it
+at, and presents the results in plain language.
+
+## No warranty, "as is"
+
+CodeVet is provided **as is**, without warranty of any kind, under the MIT
+License (see `LICENSE`). In plain terms:
+
+- **CodeVet does not guarantee the absence of security vulnerabilities.**
+  It surfaces *known, disclosed* issues via established scanners — it
+  cannot detect novel vulnerabilities, zero-days, or issues outside the
+  categories it currently checks (leaked secrets, known-vulnerable
+  dependencies).
+- **A clean scan result is not a certification.** It means the specific
+  checks CodeVet currently runs found nothing — it is not a statement that
+  the code is secure overall.
+- **CodeVet is not a substitute for a professional security audit.**
+  Anything handling real user data, payments, or production traffic at
+  meaningful scale should still get a human security review before launch,
+  regardless of what CodeVet reports.
+
+## Your responsibility when scanning a repository
+
+The pre-clone review feature (`codevet scan <url>`) shows you findings and
+asks whether to keep a cloned repository. **CodeVet does not scan for
+malware, viruses, or intentionally obfuscated malicious code beyond what
+its underlying scanners cover** (currently: leaked secrets and known CVEs
+in dependencies). Choosing to keep a repository despite a warning, or
+running code from any repository at all, is done at your own judgment and
+risk.
+
+## Acceptable use
+
+CodeVet is free to use, modify, and redistribute under the MIT License.
+Don't use it, or represent it, in a way that implies a guarantee or
+certification CodeVet does not actually provide (see "No warranty" above).
+
+## Changes
+
+These terms may be updated as CodeVet's feature set changes. Material
+changes will be reflected here directly, in plain language, not buried in
+a changelog.
+
+## Related documents
+
+- [`PRIVACY.md`](./PRIVACY.md) — what data the tool touches and where it goes
+- [`SECURITY.md`](./SECURITY.md) — how to report a vulnerability in CodeVet itself
+- [`LICENSE`](./LICENSE) — the MIT License text

package/dist/scanners/ensureBinary.js

@@ -1,9 +1,10 @@
 import { existsSync } from "node:fs";
-import { mkdir, chmod, rm, writeFile } from "node:fs/promises";
+import { mkdir, chmod, rm, writeFile, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
+import { createHash } from "node:crypto";
 const execFileAsync = promisify(execFile);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // This file lives at dist/scanners/ensureBinary.js at runtime — two levels
@@ -12,6 +13,33 @@ const PACKAGE_ROOT = join(__dirname, "..", "..");
 const VENDOR_DIR = join(PACKAGE_ROOT, "bin", "vendor");
 const GITLEAKS_VERSION = "8.30.1";
 const BEARER_VERSION = "2.1.0";
+// Pinned SHA-256 checksums, verified by us against each project's own
+// published checksums.txt at the time this version was pinned — NOT
+// fetched dynamically alongside the binary itself. Fetching a checksum
+// from the same GitHub release as the binary it's meant to verify
+// provides no real protection (an attacker who could tamper with one
+// could tamper with both); a hash pinned in our own source, reviewed at
+// a different time, is what actually catches a compromised or corrupted
+// download. Real, verified security concern raised in external review —
+// addressed properly here rather than skipped.
+const CHECKSUMS = {
+    "gitleaks_8.30.1_darwin_arm64.tar.gz": "b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5",
+    "gitleaks_8.30.1_darwin_x64.tar.gz": "dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709",
+    "gitleaks_8.30.1_linux_arm64.tar.gz": "e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080",
+    "gitleaks_8.30.1_linux_x64.tar.gz": "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb",
+    "gitleaks_8.30.1_windows_arm64.zip": "b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f",
+    "gitleaks_8.30.1_windows_x64.zip": "d29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e",
+    "bearer_2.1.0_darwin_amd64.tar.gz": "d08f3b74724619e4dc8f4673085ce16df4d881e5e104a85b6104498431e6a777",
+    "bearer_2.1.0_darwin_arm64.tar.gz": "8ffcda3cff9ed7c74a1727e5fbd6caf056d076e61ae30bf65428eafde56e8549",
+    "bearer_2.1.0_linux_amd64.tar.gz": "0bd1129669dbfa2461ba64f2cf99b9cb1fc8c0ca35fb27fdfdf3d3f4146ec7b9",
+    "bearer_2.1.0_linux_arm64.tar.gz": "3bec731fe183881b7999193f5958b80db5e0925a6171083514c160392a2dade4",
+};
+export class ChecksumMismatchError extends Error {
+    constructor(assetName, expected, actual) {
+        super(`SECURITY: downloaded file "${assetName}" does not match its pinned checksum. Expected ${expected}, got ${actual}. The download has been deleted and will NOT be executed. This could mean a corrupted download or a compromised release — do not retry without investigating.`);
+        this.name = "ChecksumMismatchError";
+    }
+}
 function resolveGitleaksSpec() {
     const platformMap = { linux: "linux", darwin: "darwin", win32: "windows" };
     const archMap = { x64: "x64", arm64: "arm64" };
@@ -28,6 +56,7 @@ function resolveGitleaksSpec() {
         url: `https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${assetName}`,
         ext,
         binName,
+        assetName,
     };
 }
 function resolveBearerSpec() {
@@ -46,6 +75,7 @@ function resolveBearerSpec() {
         url: `https://github.com/Bearer/bearer/releases/download/v${BEARER_VERSION}/${assetName}`,
         ext: "tar.gz",
         binName: "bearer",
+        assetName,
     };
 }
 async function downloadAndExtract(spec) {
@@ -57,6 +87,22 @@ async function downloadAndExtract(spec) {
     }
     const buf = Buffer.from(await res.arrayBuffer());
     await writeFile(archivePath, buf);
+    // Verify against the pinned checksum BEFORE extracting or executing
+    // anything. If there's no pinned hash for this exact asset (e.g. a
+    // platform/version combo added later without updating CHECKSUMS), fail
+    // closed rather than silently skip verification — a security tool
+    // should never extract an unverified binary.
+    const expectedHash = CHECKSUMS[spec.assetName];
+    if (!expectedHash) {
+        await rm(archivePath).catch(() => { });
+        throw new Error(`No pinned checksum found for "${spec.assetName}" — refusing to extract an unverified binary. This is a CodeVet bug (a supported platform is missing from its own checksum table), not a download problem.`);
+    }
+    const fileBuffer = await readFile(archivePath);
+    const actualHash = createHash("sha256").update(fileBuffer).digest("hex");
+    if (actualHash !== expectedHash) {
+        await rm(archivePath).catch(() => { });
+        throw new ChecksumMismatchError(spec.assetName, expectedHash, actualHash);
+    }
     if (spec.ext === "tar.gz") {
         await execFileAsync("tar", ["-xzf", archivePath, "-C", VENDOR_DIR, spec.binName]);
     }

package/docs/ABOUT.md

@@ -0,0 +1,55 @@
+# About CodeVet
+
+## What it is
+
+CodeVet is a free, open-source security co-pilot for developers who aren't
+security experts — students, solo/indie developers, and small teams who
+can't justify (or don't yet need) an enterprise AppSec platform.
+
+Instead of building yet another scanning engine, CodeVet orchestrates
+trusted, independently-maintained tools (`gitleaks`, `npm audit`, with more
+planned) and translates their output into plain language: what's wrong, why
+it matters in practice, and — where possible — the exact fix.
+
+## Why it exists
+
+Every existing free security tool is built for teams that already have
+security expertise. Nobody was serving the developer who's never heard of
+a CVE, doesn't know what CVSS means, and just wants to know if it's safe to
+ship. That gap is what CodeVet is for.
+
+## What it currently does
+
+- Scans for leaked secrets and credentials (via `gitleaks`, with an
+  extended ruleset for cases the defaults miss, like connection-string
+  credentials)
+- Scans dependencies for known, disclosed vulnerabilities (via `npm audit`)
+- Lets you review a repository's risk *before* deciding to keep a local
+  clone of it
+- Runs entirely locally — no account, no server, no telemetry (see
+  `PRIVACY.md`)
+
+## What it doesn't do (yet, or by design)
+
+- It is not a malware/antivirus scanner
+- It does not detect novel or zero-day vulnerabilities — only known,
+  disclosed issues in its scanners' databases
+- It is not a replacement for a professional security audit on anything
+  handling real user data or payments at meaningful scale
+
+See `TERMS.md` for the full, precise scope of what a scan result does and
+doesn't mean.
+
+## Project values
+
+- **No fake security** — findings are real, sourced from trusted scanners,
+  never simulated or implied
+- **No vibe coding** — every module has a defined responsibility, is
+  type-checked in strict mode, and is tested against real, reproduced
+  scenarios before being considered done
+- **Minimum dependencies** — every third-party package is chosen
+  deliberately (and audited — see `SECURITY.md`)
+
+## License
+
+MIT — see `LICENSE`.

package/docs/HELP.md

@@ -0,0 +1,173 @@
+# Help
+
+## Installing
+
+```
+npm install -g codevet-cli          # global install, gives you the `codevet` command anywhere
+# or
+npm install --save-dev codevet-cli  # install into a specific project, run via `npx codevet`
+```
+
+## Scanning
+
+```
+codevet scan                    # scans the current directory
+codevet scan ./some/folder      # scans a specific local folder
+codevet scan https://github.com/user/repo   # clones and scans a repo before you keep it
+```
+
+If your path has spaces and you forget to quote it, CodeVet will try to
+rejoin it automatically and tell you it did so. Quoting the path yourself
+(`codevet scan "C:\My Projects\app"`) is still the reliable way.
+
+### Options
+
+```
+codevet scan --no-secrets        # skip the secret-scanning check, this run only
+codevet scan --no-dependencies   # skip the dependency-vulnerability check, this run only
+```
+
+## Scanning a repository before you trust it
+
+```
+codevet scan https://github.com/someone/some-repo
+```
+
+- If nothing is found, the repo is automatically kept in your current
+  directory.
+- If something is found, you'll see exactly what and be asked whether you
+  still want to keep it. Answering no discards it completely — nothing is
+  left behind.
+
+## Turning scanners on/off for a project
+
+```
+codevet config status                  # see what's currently enabled
+codevet config disable dependencies    # turn off dependency scanning for this project
+codevet config enable secrets          # turn a scanner back on
+codevet config disable all             # turn everything off
+```
+
+This is stored in `.codevet/config.json` inside the project and only
+applies to a project you're scanning locally — it has no effect when
+reviewing a freshly-cloned, not-yet-trusted repository (see `TERMS.md` for
+why: a malicious repo can't ship a config that disables its own scan).
+
+## Removing a repository CodeVet cloned and kept
+
+```
+codevet clean ./some-repo-you-kept
+codevet clean ./some-repo-you-kept --yes   # skip the confirmation prompt
+```
+
+Checks for a marker CodeVet writes when it persists a clone, so you get a
+clear warning if you point it at a folder it didn't actually create.
+Refuses outright on anything that resolves to a root or home directory.
+
+## Fixing flagged dependencies
+
+```
+codevet fix                    # safe upgrade — only within your existing semver ranges
+codevet fix --force            # allow major-version upgrades (may include breaking changes)
+```
+
+This runs the real `npm audit fix` under the hood. If a package is pinned
+to an exact version with no `^`/`~`, the safe mode often can't touch it —
+`--force` is what breaks out of that, at the cost of possibly needing code
+changes afterward.
+
+## Removing a specific flagged dependency entirely
+
+```
+codevet remove-dependency axios
+codevet remove-dependency axios --yes   # skip the confirmation prompt
+```
+
+**This is different from `fix`.** It uninstalls the package outright — use
+this only when you're sure the flagged package isn't actually used
+anywhere in your code, not as a shortcut around fixing something you
+depend on.
+
+## Getting more detail on any command
+
+```
+codevet --help
+codevet scan --help
+codevet config --help
+```
+
+## Running automatically on every PR (GitHub Action)
+
+Add this to `.github/workflows/codevet.yml` in your repo:
+
+```yaml
+name: CodeVet
+on: [pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codevet/codevet@v1
+```
+
+This runs all four checks (secrets, dependencies, hygiene, personal data
+flow) on every PR and posts the results as a comment directly on the PR —
+no separate dashboard, no account. By default the check fails if any
+secret or high/critical dependency/data-flow finding is present; set
+`fail-on-high-risk: "false"` in the action's `with:` block if you want it
+advisory-only instead.
+
+## Personal data flow scanning (via bearer)
+
+```
+codevet scan --no-data-flow    # skip this check for this run only
+codevet config disable data-flow
+```
+
+Catches things pattern-based scanning can't — like logging a password or
+SSN, or sending PII to a third-party endpoint — by tracing where sensitive
+values actually flow through your code, not just matching text patterns.
+
+**Platform note:** bearer has no native Windows build. On Windows,
+CodeVet's other three checks (secrets, dependencies, hygiene) work
+normally, but this specific check is unavailable — you'll see a clear
+message explaining why rather than a silent gap. WSL is a workaround if
+you need this check on Windows.
+
+## A known limitation: pnpm-managed projects
+
+Dependency scanning is skipped (not failed) on projects using pnpm
+(detected via `pnpm-lock.yaml` or `node_modules/.pnpm`). This isn't a
+CodeVet limitation — it's a real, confirmed bug in npm itself: npm's own
+dependency resolver crashes with an internal error when it encounters
+pnpm's symlink structure in `node_modules`. Run `pnpm audit` directly for
+these projects; secrets, hygiene, and data-flow checks are unaffected.
+
+## Machine-readable output (for CI/tooling)
+
+```
+codevet scan --json report.json         # also writes a JSON report alongside the normal output
+codevet scan --fail-on-high-risk         # exits with a non-zero code if anything serious is found
+```
+
+## Installing into a pnpm or Yarn workspace
+
+Don't run `npm install codevet-cli` (or `npm i codevet-cli`) inside a pnpm-
+or Yarn-managed monorepo — npm's own dependency resolver can crash trying
+to interpret pnpm's symlinked `node_modules` structure (a real, confirmed
+npm bug, not something CodeVet causes). Use `npx` instead, which doesn't
+touch the workspace's dependency tree at all:
+
+```
+npx codevet-cli scan .
+```
+
+If you want CodeVet available as an actual dev dependency in a pnpm
+workspace, use pnpm itself to install it: `pnpm add -D codevet-cli`.
+
+## Something not working?
+
+Check `TROUBLESHOOTING.md` if it exists in this repo, or open an issue —
+unless it's a security vulnerability, in which case see `SECURITY.md`
+instead of a public issue.

package/docs/SECURITY-CHECKLIST.md

@@ -0,0 +1,94 @@
+# SECURITY-CHECKLIST.md — Severity-annotated
+
+**CRITICAL** = fix before anyone else touches this code. **HIGH** = fix before
+launch. **MODERATE** = real, but rarely the sole cause of an incident —
+schedule it, don't panic. **LOW** = worth doing, not urgent.
+
+Items marked **[CodeVet]** are checked automatically by `codevet scan`.
+Everything else stays a human judgment call — no scanner replaces review
+for business logic, authorization correctness, or the legal/business
+items at the bottom.
+
+---
+
+## Security (highest priority)
+
+| Item | Severity | Automated? |
+|---|---|---|
+| No hardcoded API keys/secrets/credentials — use env vars | **CRITICAL** | **[CodeVet]** gitleaks |
+| `.env` not gitignored (real values could reach git history) | **CRITICAL** | **[CodeVet]** |
+| Supabase: Row Level Security enabled on every table | **CRITICAL** | **[CodeVet]** (static check — verify in dashboard too) |
+| Supabase: service role key never in client-side code | **CRITICAL** | **[CodeVet]** gitleaks |
+| Exposed `.env` files, `.git` folders, or admin routes in production | HIGH | Manual — deployment config |
+| SQL injection / XSS / CSRF protection in place | HIGH | Manual — needs code review |
+| No rate limiting on auth routes (login/signup/reset) | HIGH | **[CodeVet]** |
+| CORS wide open (`*`) | HIGH | **[CodeVet]** (pattern match — confirm runtime config) |
+| Error responses leak stack traces / internal details | HIGH | **[CodeVet]** |
+| Passwords hashed (bcrypt/argon2), never plaintext | HIGH | Manual — CodeVet can't verify runtime behavior |
+| Auth flows tested: session expiry, token refresh, RBAC | HIGH | Manual |
+| Dependencies scanned for known vulnerabilities | HIGH | **[CodeVet]** npm audit |
+| No security headers configured (helmet) | MODERATE | **[CodeVet]** |
+| No schema validation library detected | MODERATE | **[CodeVet]** (false-positive-prone — hand-written validation is invisible to this check) |
+
+## Code & architecture
+
+| Item | Severity | Automated? |
+|---|---|---|
+| Every API route checks who's calling (auth check present) | HIGH | Manual — AI-generated routes often skip this |
+| Test accounts / seed data / debug pages removed before launch | HIGH | Manual |
+| Error handling doesn't leak internals to users | HIGH | **[CodeVet]** (same check as above) |
+| No leftover `console.log`s, debug routes, or test data | LOW | Manual |
+| Environment configs separated (dev/staging/prod) | MODERATE | Manual |
+| Remove unused code, commented-out blocks, dead dependencies | LOW | Manual |
+
+## Data & backend
+
+| Item | Severity | Automated? |
+|---|---|---|
+| Input validation on the server (never trust the client) | HIGH | Manual + **[CodeVet]** validation-library check |
+| Rate limiting on anything that costs money (AI calls, email, login) | HIGH | Partial — **[CodeVet]** checks auth routes; other cost-bearing endpoints need manual review |
+| Database backups configured and tested (can you actually restore?) | HIGH | Manual |
+| Migrations are clean and reversible | MODERATE | Manual |
+
+## Deployment & ops
+
+| Item | Severity | Automated? |
+|---|---|---|
+| Plan for key rotation if one leaks | HIGH | Manual — have the runbook ready before you need it |
+| SSL/HTTPS enforced everywhere | HIGH | Manual — deployment/infra config |
+| CI/CD or a documented, repeatable deploy process | MODERATE | Manual |
+| Monitoring/error tracking set up (Sentry, etc.) | MODERATE | Manual |
+
+## Legal & business
+
+**Not automatable — CodeVet has no visibility into contracts or business
+terms.** Still worth having a checklist for, since these cause real pain
+when skipped:
+
+| Item | Severity |
+|---|---|
+| Written contract: scope, deliverables, payment, revision limits | HIGH |
+| IP ownership clause — who owns the code once paid? | HIGH |
+| Privacy policy / terms of service if collecting user data | HIGH |
+| DPDP Act / GDPR / CCPA compliance if applicable to your user base | HIGH |
+| Clear statement of what's *not* included (maintenance, hosting, fees) | MODERATE |
+| Handover docs: run locally, deploy, env vars, admin access | MODERATE |
+
+## Handover checklist
+
+| Item | Severity |
+|---|---|
+| All credentials transferred securely, never over Slack/email plaintext | HIGH |
+| README with setup instructions | MODERATE |
+| You retain no unnecessary access after the project ends | HIGH |
+
+---
+
+## The honest read
+
+If you only have time for the CRITICAL and HIGH rows: that's a legitimate
+launch bar for a small project. MODERATE items are real but rarely the
+single cause of an incident — schedule them, don't block launch on them.
+The two things people skip most and regret most: **security hardening**
+(the CRITICAL/HIGH rows above) and **the contract** (Legal & business
+section) — if you only fix two categories, make it those.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codevet-cli",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Vet your code before it ships \u2014 a free, open-source security co-pilot that checks for leaked secrets, vulnerable dependencies, missing security middleware, and personal data flow, with real working fixes shown inline.",
   "scripts": {
     "build": "tsc",
@@ -40,7 +40,19 @@
   "files": [
     "dist",
     ".gitleaks.toml",
-    "scripts"
+    "scripts",
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".claude",
+    ".cursor",
+    ".opencode",
+    "docs",
+    "PRIVACY.md",
+    "TERMS.md",
+    "SECURITY.md",
+    "INFO.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md"
   ],
   "repository": {
     "type": "git",