@uniqweb/vibe-it-securely 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 <YOUR NAME>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# vibe-it-securely
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A security baseline for JavaScript, TypeScript and Python projects, set up with one command.
+
+Built for people who build fast with AI coding tools and are not sure whether the result is safe.
+
+> **Honest scope:** this sets up a *baseline* and finds *common, obvious* problems. It reduces risk. It does not make a project secure, and a clean report is not a security audit.
+
+## Quick start
+
+```bash
+npx vibe-it-securely init     # generate the baseline files
+npx vibe-it-securely check    # find problems, explained in plain language
+```
+
+Requires Node 18+. No dependencies.
+
+## `init`: set up the safeguards
+
+Detects your stack (JS, TS, Python, or a mix; npm, pnpm or yarn) and generates:
+
+| File | Purpose |
+|---|---|
+| `.pre-commit-config.yaml` | Fast local checks: secret scanning and private-key detection before every commit |
+| `.github/workflows/security.yml` | The same checks in CI, plus dependency audit and static analysis. CI is the real enforcement, because local hooks can be skipped with `--no-verify` |
+| `Dockerfile`, `.dockerignore` | Multi-stage build, non-root user, no secrets copied in (skip with `--no-docker`) |
+| `AGENTS.md` | Security rules for AI coding assistants (copy to `CLAUDE.md` or `.cursorrules` if your tool needs that name) |
+| `.env.example`, `.gitignore`, `.gitleaksignore` | Created only if missing |
+
+**It never overwrites your files.** If one already exists, the new version is saved as `<name>.suggested` for you to review and merge.
+
+Options: `--dir <path>`, `--dry-run`, `--no-docker`.
+
+After `init`: `pip install pre-commit && pre-commit install`.
+
+### Secret scan flagged something fake?
+
+The CI secret scan (gitleaks) also looks at your git history, so a fake key in a test file can fail the build. If the value is fake or an example, copy the `Fingerprint:` line from the CI log into `.gitleaksignore` (one per line; `#` starts a comment). Better still, build fake values at runtime in tests so no scanner sees a literal. If the value is real, revoke it and replace it instead.
+
+### What blocks and what only warns
+
+To avoid false alarms that make people turn the tool off, only high-confidence problems block CI: committed secrets, private keys, and critical dependency vulnerabilities. Everything else is reported as a warning.
+
+## `check`: find problems
+
+```bash
+vibe-it-securely check [--dir <path>] [--fail-on high|medium|none] [--json] [--online]
+```
+
+Looks for:
+
+- **Leaked secrets:** private keys; AWS, GitHub, Slack and AI-provider keys; hardcoded passwords and tokens
+- **`.env` mistakes:** committed to git, or not covered by `.gitignore`
+- **Risky code:** `eval`, SQL built by joining text, raw HTML insertion, wide-open CORS, turned-off HTTPS checks, `shell=True`, `yaml.load`, `pickle`, debug mode left on
+- **Docker problems:** running as root, unpinned images, secrets in `ENV`/`ARG`, `.env` copied into the image
+- **Missing safeguards:** pre-commit hooks, CI, lockfile, AI-assistant rules
+- **Common AI-app mistakes:**
+  - Routes that change data (Express-style, Next.js `app/` and `pages/api`) with no sign of a login check. This is a heuristic, so public routes need the ignore comment.
+  - Supabase `service_role` keys in code (including inside JWTs), and secrets exposed to the browser through public env variables such as `NEXT_PUBLIC_*`
+  - Supabase tables created without row level security, or with it switched off
+- **Invented dependencies** (with `--online`): checks that every package in `package.json` and `requirements.txt` really exists on npm / PyPI. AI tools sometimes make up names, and an attacker can register them. This contacts the public registries, so it is opt-in. Private-registry scopes and network failures are reported as "could not verify", never as findings.
+
+Every finding says **where** it is, **why** it matters and **how** to fix it. Secret values are never printed.
+
+The exit code is `1` if anything at or above `--fail-on` (default `high`) is found, so it works as a CI gate.
+
+### Silencing false alarms
+
+- On one line: add the comment `vibe-it-securely-ignore`
+- For whole files or folders: list them in `.vibe-it-securely-ignore` (one path per line, `#` for comments)
+
+```
+# .vibe-it-securely-ignore
+test/fixtures/
+```
+
+## Limitations
+
+- `check` uses pattern matching, not deep code analysis. It misses things and sometimes flags harmless code. The generated CI workflow adds Semgrep and gitleaks for deeper coverage.
+- The route-auth check looks for auth keywords near the route, so it can miss real gaps and flag public routes.
+- It does not check your dependency versions itself. That is done by `npm audit` / `pip-audit` in the generated CI workflow.
+- Generated Dockerfiles guess your start command. Review the `TODO` comments in them.
+- Review generated files before relying on them. Pin third-party GitHub Actions to commit SHAs for stronger supply-chain safety.
+
+## Development
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { init } from "../src/init.js";
+import { check } from "../src/check.js";
+import { checkDependencies } from "../src/deps.js";
+import { formatReport, countBySeverity } from "../src/report.js";
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (name) => args.includes(name);
+const value = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+const dir = path.resolve(value("--dir") || process.cwd());
+
+const HELP = `vibe-it-securely - a security baseline for your project
+
+Usage:
+  vibe-it-securely init  [--dir <path>] [--dry-run] [--no-docker]
+  vibe-it-securely check [--dir <path>] [--fail-on high|medium|none] [--json] [--online]
+
+init   Generates pre-commit hooks, CI checks, hardened Docker files and AI-assistant
+       rules. Existing files are never overwritten; new versions are saved as
+       <name>.suggested for you to review. Use --no-docker for libraries, CLIs
+       and scripts that do not ship as a container.
+check  Looks for leaked secrets, risky code patterns, Docker problems and missing
+       safeguards, and explains each finding in plain language.
+       --online also verifies that every dependency name really exists on npm/PyPI
+       (AI tools sometimes invent package names). It contacts the public registries.
+       Exit code 1 if anything at or above --fail-on is found (default: high).`;
+
+if (!cmd || cmd === "--help" || cmd === "-h") {
+  console.log(HELP);
+  process.exit(0);
+}
+
+if (cmd === "init") {
+  const dryRun = flag("--dry-run");
+  const { stack, results, notes, error } = init({ dir, dryRun, docker: !flag("--no-docker") });
+  if (error) {
+    console.error(error);
+    process.exit(1);
+  }
+  const langs = [stack.typescript ? "TypeScript" : stack.node ? "JavaScript" : null, stack.python ? "Python" : null].filter(Boolean);
+  console.log("Detected: " + langs.join(" + ") + (dryRun ? "  (dry run, nothing written)" : ""));
+  console.log("");
+  const label = {
+    created: "created   ",
+    suggested: "suggested ",
+    "skipped-exists": "kept as-is",
+    "would-be-created": "would create ",
+    "would-be-suggested": "would suggest ",
+  };
+  for (const r of results) console.log("  " + (label[r.status] || r.status) + "  " + r.path);
+  if (results.some((r) => r.status === "suggested" || r.status === "would-be-suggested")) {
+    console.log("\nFiles marked suggested already existed. Yours were left untouched; review the .suggested copies and merge what you want.");
+  }
+  if (notes.length) {
+    console.log("\nHeads up:");
+    for (const n of notes) console.log("  - " + n);
+  }
+  console.log("\nNext: pip install pre-commit && pre-commit install, then run: vibe-it-securely check");
+  console.log("Note: this sets up a security baseline. It reduces common risks; it does not make your project secure on its own.");
+} else if (cmd === "check") {
+  const failOn = value("--fail-on") || "high";
+  if (!["high", "medium", "none"].includes(failOn)) {
+    console.error("--fail-on must be high, medium or none");
+    process.exit(1);
+  }
+  const result = check(dir);
+  result.notes = [];
+  if (flag("--online")) {
+    const dep = await checkDependencies(dir);
+    result.findings.push(...dep.findings);
+    result.notes.push(`Checked ${dep.checked} dependency names against npm/PyPI.` + (dep.unverified ? ` ${dep.unverified} could not be verified (network problem or private registry).` : ""));
+  }
+  if (flag("--json")) console.log(JSON.stringify({ findings: result.findings, filesScanned: result.filesScanned, notes: result.notes }, null, 2));
+  else console.log(formatReport(result));
+  const c = countBySeverity(result.findings);
+  const fail = failOn === "high" ? c.high > 0 : failOn === "medium" ? c.high + c.medium > 0 : false;
+  process.exit(fail ? 1 : 0);
+} else {
+  console.log(HELP);
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@uniqweb/vibe-it-securely",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A security baseline for JavaScript, TypeScript and Python projects: pre-commit hooks, CI checks, hardened Docker config and AI-assistant rules, plus a plain-language security check.",
+  "type": "module",
+  "bin": {
+    "vibe-it-securely": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniqueweb1/vibe-it-securely.git"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "security",
+    "pre-commit",
+    "docker",
+    "vibe-coding",
+    "ai-generated-code",
+    "secrets",
+    "devsecops",
+    "cli"
+  ]
+}