depsentinel 0.1.2

package/docs/security-best-practices.md

@@ -0,0 +1,202 @@
+# depsentinel Security Best Practices Guide
+
+This document turns npm/pnpm supply-chain best practices into practical actions with `depsentinel`.
+
+Goal: help any JS/TS project adopt secure defaults with low friction.
+
+## What depsentinel already enforces
+
+- `scan`: detects package manager (`npm`, `pnpm`, `yarn`, `bun`), lockfile, workspace hint, and framework hint.
+- `scan`: returns `risk_score`, `proposed_diff`, and `remediation_commands`.
+- `init`: writes secure baseline files (`depsentinel.*`, `.npmrc`, `.npmignore`, CI workflow) and PM-specific configs automatically based on detection.
+- `ci`: fails (non-zero exit code) when critical policy findings exist.
+- `install <package>`: preflight safety check with `allow|warn|block` decision, optional tool adapters (`npq`, `sfw`, `lockfile-lint`), graceful degradation diagnostics, and `--force` for override.
+- `doctor`: diagnoses project against 26 best practices across 4 categories with PASS/FAIL/SKIP.
+- `fix`: applies known remediations (`.npmrc`, `.npmignore`, `lint:lockfile`, `sbom` scripts, PM configs) with dry-run by default.
+- `override add|remove|list`: manage policy exceptions with reason and expiration date.
+- Unknown framework: no hard-fail; falls back to universal JS/TS baseline checks.
+
+## Secure defaults generated by `init`
+
+### `.npmrc`
+
+Generated baseline:
+
+```ini
+ignore-scripts=true
+allow-git=none
+min-release-age=3
+```
+
+Why it matters:
+
+- `ignore-scripts=true`: blocks lifecycle script execution by default.
+- `allow-git=none`: blocks git-based dependency resolution.
+- `min-release-age=3`: introduces a cooldown before fresh releases are installable.
+
+### `pnpm-workspace.yaml` (when pnpm detected or no PM yet)
+
+Generated baseline (universal, any JS/TS project):
+
+```yaml
+packages:
+  - "."
+
+minimumReleaseAge: 43200
+trustPolicy: no-downgrade
+blockExoticSubdeps: true
+strictDepBuilds: true
+allowBuilds:
+  esbuild: true
+  rolldown: true
+  unrs-resolver: true
+```
+
+Why it matters:
+
+- `minimumReleaseAge`: cooldown window to reduce fresh-compromise risk.
+- `trustPolicy: no-downgrade`: blocks trust-regression package versions.
+- `blockExoticSubdeps`: blocks transitive git/tarball exotic sources.
+- `strictDepBuilds` + `allowBuilds`: converts unreviewed build scripts into hard failures.
+
+### PM-specific configs (auto-detected)
+
+| Lockfile detected | Extra config generated |
+|---|---|
+| `pnpm-lock.yaml` or none | `pnpm-workspace.yaml` |
+| `bun.lockb` | `bunfig.toml` with `minimumReleaseAge` |
+| `yarn.lock` | `.yarnrc.yml` with `npmMinimalAgeGate` |
+
+All projects get `.npmrc`, `.npmignore`, and CI workflow regardless of PM.
+
+## Quick start
+
+```bash
+# 1) Diagnose
+npx depsentinel scan
+
+# 2) Generate secure baseline files (dry-run by default)
+npx depsentinel init
+
+# 3) Apply generated files
+npx depsentinel init --write
+
+# 4) Check a package before installing
+npx depsentinel install express
+
+# 5) Force-install after acknowledging risks
+npx depsentinel install some-package --force
+
+# 6) Enforce in CI
+npx depsentinel ci --json
+```
+
+## Full Coverage Matrix: both source documents mapped to depsentinel
+
+This matrix combines OWASP/Snyk npm best practices and Liran Tal's Awesome npm Security Best Practices into a single view.
+
+### Automated by depsentinel
+
+| # | Best Practice | How depsentinel helps |
+|---|---|---|
+| 1 | Disable post-install scripts | `init` writes `.npmrc` with `ignore-scripts=true`; pnpm projects get `strictDepBuilds` + `allowBuilds` |
+| 2 | Block git-based dependencies | `init` writes `.npmrc` with `allow-git=none`; `scan` detects disallowed protocols (`git+`, `http:`, `file:`) |
+| 3 | Cooldown (minimumReleaseAge) | `init` writes `.npmrc` `min-release-age=3`; pnpm projects get `pnpm-workspace.yaml` `minimumReleaseAge: 43200` |
+| 4 | Enforce lockfile | `scan` blocks if missing lockfile (`lockfile.required` policy); `ci` returns non-zero exit code |
+| 5 | Deterministic CI installs | `scan` suggests PM-specific frozen-lockfile command; CI workflow generated by `init` uses `--frozen-lockfile` for each PM |
+| 6 | Audit vulnerabilities | `scan`/`ci` check critical advisory matches; `install` evaluates package safety pre-install |
+| 7 | Hardening tools (npq / sfw / lockfile-lint) | `install` detects and uses optional adapters with `executed|skipped|failed` reporting |
+| 8 | Typosquatting / slopsquatting detection | `install` delegates to `npq`/`sfw` adapters (when available) which detect typosquatting patterns |
+| 9 | Package health assessment | `scan` returns `risk_score`; `install` evaluates health signals via integrated adapters |
+| 10 | pnpm trust policy | `init` writes `trustPolicy: no-downgrade` in `pnpm-workspace.yaml` for pnpm projects |
+| 11 | pnpm exotic subdeps blocking | `init` writes `blockExoticSubdeps: true` in `pnpm-workspace.yaml` for pnpm projects |
+
+### Guided in documentation (manual implementation)
+
+| # | Best Practice | User action required |
+|---|---|---|
+| 12 | Avoid publishing secrets to registry | Use `files` allowlist in `package.json`; add `.npmignore`; review tarball with `npm pack --dry-run` |
+| 13 | npx hardening (offline + workspace) | Create dedicated workspace, install packages with lockfile, run `npx --offline` (see snippets below) |
+| 14 | Lockfile injection prevention beyond baseline | Add `lockfile-lint` as pre-install gate in `package.json` scripts |
+| 15 | Secrets hygiene (.env plaintext) | Replace plaintext secrets with 1Password/Infisical references; never commit `.env` files |
+| 16 | Dev Containers | Create `.devcontainer/devcontainer.json`; use VS Code remote containers |
+| 17 | Maintainer 2FA | `npm profile enable-2fa auth-and-writes` |
+| 18 | Publishing with provenance / OIDC | Configure trusted publisher on npmjs.com; use `id-token: write` in CI |
+| 19 | SBOM generation and artifact signing | Integrate `@cyclonedx/cyclonedx-npm` for SBOM; use `sigstore` for artifact signatures |
+| 20 | Dependency confusion protection | Use scoped package names (`@yourorg/pkg`); configure `.npmrc` scope routing; claim names on public registry |
+| 21 | Manage npm author tokens securely | Rotate tokens, restrict with CIDR and `--read-only`, revoke unused tokens |
+| 22 | Use a local npm proxy (Verdaccio) | Install private registry; configure proxy cache; route internal dependencies |
+
+### Not covered (out of tool scope)
+
+| # | Best Practice | Reason |
+|---|---|---|
+| 23 | Responsible vulnerability disclosure | Process requiring human coordination and judgement |
+| 24 | Verify documentation examples before copying | Requires manual code review |
+| 25 | Avoid blind npm package upgrades | Manual review needed; `fix` sets up safe foundation |
+| 26 | Reduce package dependency tree | Architectural design decision, not a tooling concern |
+
+## Current boundaries
+
+These are not fully implemented yet:
+
+- Live advisory feed ingestion (uses deterministic fixture-backed provider for reliable tests).
+- Advanced governance checks (SBOM/provenance/signature verification pipelines).
+
+## Recommended adoption policy
+
+1. Run `scan` on every PR.
+2. Use `install` before adding any new dependency.
+3. Keep `ci` as required status check.
+4. Start with strict defaults and use explicit overrides only with reason and expiration.
+5. Review `proposed_diff` and `remediation_commands` before applying changes.
+
+## Guided snippets for controls not yet automated
+
+### Harden `npx` usage for tooling
+
+```bash
+mkdir -p "$HOME/mcp" && cd "$HOME/mcp"
+npm init -y
+npm install @modelcontextprotocol/server-filesystem
+npx --include-workspace-root --workspace "$HOME/mcp" --no --offline @modelcontextprotocol/server-filesystem /path/to/allowed/directory
+```
+
+### Add lockfile linting gate
+
+```json
+{
+  "scripts": {
+    "lint:lockfile": "lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https"
+  }
+}
+```
+
+### Deterministic install commands by package manager
+
+```bash
+npm ci
+pnpm install --frozen-lockfile
+yarn install --immutable --immutable-cache
+bun install --frozen-lockfile
+```
+
+### Private scope routing to prevent dependency confusion
+
+```ini
+@yourcompany:registry=https://npm.yourcompany.com/
+```
+
+### Generate SBOM for supply chain governance
+
+```bash
+npm install @cyclonedx/cyclonedx-npm
+npx @cyclonedx/cyclonedx-npm --validate > sbom.json
+```
+
+## Notes for any JS/TS project
+
+- `init` auto-detects your package manager and generates appropriate configs.
+- If your PM is unknown, `depsentinel` defaults to pnpm (recommended for strongest supply-chain hardening).
+- If framework detection is unknown, `depsentinel` still applies universal checks and reports diagnostics instead of breaking.
+- `install` works with any package manager and adapts to `npm/pnpm/yarn/bun` automatically.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "depsentinel",
+  "version": "0.1.2",
+  "description": "JS/TS supply-chain hardening CLI — scan, secure, and enforce dependency policies",
+  "license": "MIT",
+  "author": "depsentinel contributors",
+  "keywords": [
+    "npm",
+    "pnpm",
+    "yarn",
+    "bun",
+    "supply-chain",
+    "security",
+    "cli",
+    "hardening",
+    "lockfile",
+    "dependencies",
+    "audit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/axelvalles/depsentinel"
+  },
+  "homepage": "https://github.com/axelvalles/depsentinel#readme",
+  "type": "module",
+  "bin": {
+    "depsentinel": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs/security-best-practices.md",
+    "README.md"
+  ],
+  "dependencies": {
+    "cac": "6.7.14"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.31",
+    "lockfile-lint": "4.14.1",
+    "typescript": "5.8.3",
+    "vitest": "2.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint:lockfile": "node scripts/lint-lockfile.mjs",
+    "sbom": "npx @cyclonedx/cyclonedx-npm --validate > sbom.json"
+  }
+}