ci: supply-chain security gate (OSV-Scanner + Socket) [failproofai-394]

.github/workflows/osv-scanner.yml

@@ -0,0 +1,48 @@
+# Supply-chain security gate.
+#
+# Scans the resolved dependency tree (bun.lock) against the OSV.dev database —
+# which aggregates GitHub/npm security advisories AND the OpenSSF
+# malicious-packages feed — and FAILS on any known-vulnerable or known-malicious
+# package (block-on-any-finding policy). OSV-Scanner exits non-zero when it finds
+# anything, which fails this job.
+#
+# Runs on every PR (incl. Dependabot bumps), on pushes to main, and weekly to
+# catch advisories disclosed after a dependency was already merged.
+#
+# Triage / allow-listing unfixable advisories: see SECURITY.md and osv-scanner.toml
+# (auto-loaded from the repo root by OSV-Scanner).
+#
+# Third-party actions are pinned to a commit SHA (we're a supply-chain tool —
+# practice what we preach).
+name: Supply Chain
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "17 4 * * 1" # Mondays 04:17 UTC
+  workflow_dispatch:
+
+# Least privilege: the scan only needs to read the checked-out source.
+# contents:read is also available to Dependabot PRs (read-only token), so the
+# gate enforces on dependency-bump PRs too.
+permissions:
+  contents: read
+
+jobs:
+  osv-scanner:
+    name: OSV-Scanner
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          # No git ops after checkout; don't leave the token in .git/config.
+          persist-credentials: false
+      - name: Scan bun.lock for known-vulnerable / malicious dependencies
+        uses: google/osv-scanner-action/osv-scanner-action@8dc09193bb540e09b23da07ad7e30bd33bf87018 # v2.3.8
+        with:
+          scan-args: |-
+            --lockfile=bun.lock

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## 0.0.11-beta.3 — 2026-05-25
 
 ### Features
+- Add a supply-chain security CI gate: OSV-Scanner (`.github/workflows/osv-scanner.yml`) scans the resolved `bun.lock` tree against OSV.dev (GitHub/npm advisories + the OpenSSF malicious-packages feed) on every PR (incl. Dependabot bumps), on pushes to `main`, and weekly, and **blocks on any known-vulnerable or malicious dependency**. Adds a Socket GitHub App behavioral early-warning layer, an `osv-scanner.toml` allow-list for unfixable advisories, a README supply-chain status badge, and a `SECURITY.md` policy/runbook. Remediates the 18 pre-existing transitive advisories surfaced by the new gate (brace-expansion, flatted, minimatch, picomatch, postcss, vite, ws) by refreshing `bun.lock` within range, with `overrides` pinning `postcss` to the patched 8.5.x line (Next.js pins the vulnerable 8.4.31) and holding `eslint-plugin-react-hooks` at main's 7.0.1 so the refresh doesn't also bump the linter (#391).
 - Stamp `product: "failproofai-oss"` on every PostHog event across all four telemetry channels — hooks/audit (`trackHookEvent`), server (`trackEvent`), web UI (`captureClientEvent`), and npm-lifecycle install/uninstall (`trackInstallEvent`) — so OSS events stay distinguishable from any future hosted surface. The value lives in a single `POSTHOG_PRODUCT` constant in `src/posthog-key.ts`, reused by the three TypeScript channels; the standalone `scripts/install-telemetry.mjs` inlines the same literal because it can't import the TS module at install time. Honors `FAILPROOFAI_TELEMETRY_DISABLED=1` like all other telemetry (#380).
 
 ### Docs

README.md

@@ -4,6 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
 [![CI](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/failproofai/failproofai/actions)
+[![Supply Chain](https://img.shields.io/github/actions/workflow/status/failproofai/failproofai/osv-scanner.yml?branch=main&style=flat-square&label=supply%20chain)](https://github.com/failproofai/failproofai/actions/workflows/osv-scanner.yml)
 [![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square&logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
 [![Docs](https://img.shields.io/badge/docs-befailproof.ai-002CA7?style=flat-square)](https://docs.befailproof.ai)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](./LICENSE)

SECURITY.md

@@ -0,0 +1,73 @@
+# Security Policy
+
+failproofai is an npm package that installs hooks into AI coding agents (Claude
+Code, Codex, and others) and runs locally in developers' environments, observing
+and gating agent actions. A compromised dependency would therefore run on our
+users' machines, inside their agent sessions — so we treat our supply chain as
+part of our users' trust boundary. This document covers how to report a
+vulnerability and how our dependency supply-chain scanning works.
+
+## Reporting a Vulnerability
+
+Please report security issues privately — do **not** open a public issue.
+
+- Preferred: open a [private vulnerability report](https://github.com/FailproofAI/failproofai/security/advisories/new)
+  via GitHub Security Advisories.
+- Or email **failproofai@exosphere.host**.
+
+We aim to acknowledge reports within 3 business days and will keep you updated as
+we investigate and ship a fix. Please give us a reasonable window to remediate
+before any public disclosure.
+
+## Supply-chain scanning
+
+Every pull request — including automated Dependabot dependency bumps — is scanned
+for supply-chain threats before it can merge, via two complementary layers.
+
+### 1. OSV-Scanner — the blocking CI gate
+
+[`.github/workflows/osv-scanner.yml`](.github/workflows/osv-scanner.yml) runs
+[OSV-Scanner](https://google.github.io/osv-scanner/) against the resolved
+dependency tree (`bun.lock`). It checks every direct and transitive package
+against [OSV.dev](https://osv.dev), which aggregates GitHub/npm security
+advisories **and** the [OpenSSF malicious-packages feed](https://github.com/ossf/malicious-packages)
+(confirmed malware: typosquats, account-takeover injections, and the like).
+
+**Policy: block on any finding.** The gate fails on *any* known-vulnerable or
+malicious package in the tree — not just newly introduced ones. It runs on every
+PR, on pushes to `main`, and weekly (to catch advisories disclosed after a
+dependency was already merged).
+
+### 2. Socket — behavioral early-warning
+
+OSV-Scanner is advisory-based: it can only flag threats already cataloged. To
+catch *novel* attacks (malicious install scripts, suspicious network/filesystem
+access, obfuscation, sudden maintainer changes) before they reach any advisory
+database, we use [Socket](https://socket.dev) via its GitHub App, which comments
+on PRs that introduce risky dependency behavior. Socket is advisory (it
+comments); the deterministic *blocking* gate is OSV-Scanner.
+
+## Triaging a failed scan
+
+When the OSV-Scanner gate fails on a PR:
+
+1. **Prefer fixing it.** Bump the affected dependency to a patched version. For a
+   transitive dependency that a parent pins to a vulnerable version, add a minimal
+   [`overrides`](package.json) entry (as we do for `postcss`) and let CI validate
+   the build.
+2. **Only if there is no fix**, add a justified, time-boxed entry to
+   [`osv-scanner.toml`](osv-scanner.toml) (`id`, `reason`, `ignoreUntil`). Never
+   blanket-ignore. Re-review entries when their `ignoreUntil` date passes.
+
+## Maintainer setup (one-time)
+
+These steps live outside the repo and require admin access:
+
+1. **Install the [Socket GitHub App](https://github.com/apps/socket-security)** on
+   the repository to enable behavioral PR comments.
+2. **Make the OSV-Scanner check required**: in branch protection for `main`, add
+   the OSV-Scanner job (shown as `OSV-Scanner`) as a required status check, so a
+   red scan blocks merge.
+3. *(Optional)* For a Socket CI gate in addition to the App, add a
+   `SOCKET_SECURITY_API_KEY` repository secret and the Socket CI action — deferred
+   until tuned, since behavioral findings can have false positives.