feat(js-pr-validation): add socket.dev supply chain gate

.github/dependabot.yml

@@ -74,6 +74,10 @@ updates:
           - "trufflesecurity/trufflehog"
           - "anchore/sbom-action"
           - "sigstore/cosign-installer"
+          # Only reachable if SocketDev/action is ever referenced from a workflow;
+          # its current use is in src/security/socket-firewall, which the
+          # github-actions ecosystem does not scan (see note at the top).
+          - "SocketDev/action"
         update-types:
           - "minor"
           - "patch"

.github/workflows/js-pr-validation.yml

@@ -27,6 +27,10 @@ on:
         description: 'Run the security scan pipeline (Trivy, CodeQL, prerelease checks)'
         type: boolean
         default: true
+      run_socket:
+        description: 'Run the Socket supply-chain pipeline (Socket Firewall and, when enabled, the Socket CLI scan)'
+        type: boolean
+        default: true
 
       # ----------------- Change gate -----------------
       ignore_globs:
@@ -272,11 +276,55 @@ on:
         description: 'Comma-separated directories to skip in every Trivy filesystem scan (appended to the built-in skip list).'
         type: string
         default: ''
+
+      # ----------------- Socket supply chain (src/security/socket-*) -----------------
+      socket_enable_firewall:
+        description: 'Run Socket Firewall (free tier, no token) and install dependencies through it, blocking malicious packages at install time.'
+        type: boolean
+        default: true
+      socket_enable_scan:
+        description: 'Run the Socket CLI scan (paid tier). Requires the SOCKET_SECURITY_API_KEY secret; without it the step skips with a notice.'
+        type: boolean
+        default: false
+      socket_working_dir:
+        description: 'Directory holding the package.json and lockfile scanned by the Socket jobs'
+        type: string
+        default: '.'
+      socket_firewall_version:
+        description: 'Socket Firewall binary version. Empty or "latest" tracks the newest release.'
+        type: string
+        default: 'latest'
+      socket_job_summary:
+        description: 'Socket Firewall job summary verbosity (all, errors, none)'
+        type: string
+        default: 'all'
+      socket_fail_on_block:
+        description: 'Fail the Socket job when Socket Firewall blocks a package. Set to false to report the block as a warning instead.'
+        type: boolean
+        default: true
+      socket_fail_on_findings:
+        description: 'Fail the Socket job when the Socket CLI scan reports blocking alerts. Default false keeps the scan advisory until a repository is clean.'
+        type: boolean
+        default: false
+      socket_sarif_file:
+        description: 'Path where the Socket CLI scan writes its SARIF report. Empty = no SARIF.'
+        type: string
+        default: ''
+      socket_ignore_commit_files:
+        description: 'Scan every manifest instead of only the ones touched by the commit (--ignore-commit-files)'
+        type: boolean
+        default: false
+      socket_python_version:
+        description: 'Python version used to run the Socket CLI'
+        type: string
+        default: '3.12'
     secrets:
       MANAGE_TOKEN:
         required: false
       SLACK_WEBHOOK_URL:
         required: false
+      SOCKET_SECURITY_API_KEY:
+        required: false
 
 permissions:
   actions: read
@@ -417,6 +465,66 @@ jobs:
           result: ${{ needs.changes.result != 'success' && needs.changes.result || needs.security.result }}
           label: Security
 
+  # ----------------- Socket Supply Chain -----------------
+  socket:
+    name: Socket (checks)
+    needs: changes
+    if: inputs.run_socket && needs.changes.outputs.code == 'true'
+    runs-on: ${{ vars.GENERAL_RUNNERS || inputs.runner_type }}
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+        with:
+          # socketcli diffs the commit to decide which manifests changed.
+          fetch-depth: 2
+          persist-credentials: false
+
+      - name: Socket Firewall
+        if: inputs.socket_enable_firewall
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-firewall@v1
+        with:
+          package-manager: ${{ inputs.package_manager }}
+          node-version: ${{ inputs.node_version }}
+          working-dir: ${{ inputs.socket_working_dir }}
+          firewall-version: ${{ inputs.socket_firewall_version }}
+          job-summary: ${{ inputs.socket_job_summary }}
+          fail-on-block: ${{ inputs.socket_fail_on_block }}
+          dry-run: ${{ inputs.dry_run }}
+
+      - name: Socket Scan
+        if: always() && inputs.socket_enable_scan
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-scan@v1
+        with:
+          # Token presence is resolved inside the composite rather than in an
+          # `if:` — the secrets context is unavailable in step conditions.
+          socket-api-key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          github-token: ${{ secrets.MANAGE_TOKEN || github.token }}
+          target-path: ${{ inputs.socket_working_dir }}
+          pr-number: ${{ github.event.pull_request.number || 0 }}
+          python-version: ${{ inputs.socket_python_version }}
+          fail-on-findings: ${{ inputs.socket_fail_on_findings }}
+          sarif-file: ${{ inputs.socket_sarif_file }}
+          ignore-commit-files: ${{ inputs.socket_ignore_commit_files }}
+          dry-run: ${{ inputs.dry_run }}
+
+  socket-gate:
+    name: Socket
+    needs: [changes, socket]
+    if: always()
+    runs-on: ${{ vars.GENERAL_RUNNERS || inputs.runner_type }}
+    permissions:
+      contents: read
+    steps:
+      - name: Aggregate Socket result
+        uses: LerianStudio/github-actions-shared-workflows/src/validate/result-gate@v1
+        with:
+          result: ${{ needs.changes.result != 'success' && needs.changes.result || needs.socket.result }}
+          label: Socket
+
   # ----------------- Org ruleset compatibility stubs -----------------
   # Go Analysis and Lib Version are required status checks in the Lerian org
   # branch-protection ruleset (designed for Go repos). These stubs are

docs/js-pr-validation.md

@@ -11,8 +11,9 @@ Umbrella reusable workflow for JavaScript/TypeScript repositories. A caller refe
 2. **Change gate** — detects whether the PR touches anything beyond docs/meta (`src/config/non-doc-changes`); documentation-only PRs skip the heavy pipelines.
 3. **Frontend analysis** — lint, typecheck, npm audit, tests, coverage and build (delegates to `frontend-pr-analysis.yml`), opt-in via `run_frontend_analysis`.
 4. **Security scan** — Trivy, CodeQL, prerelease checks (delegates to `pr-security-scan.yml`), opt-in via `run_security`.
+5. **Socket supply chain** — blocks malicious packages at install time and, optionally, runs the full Socket CLI report (`src/security/socket-firewall`, `src/security/socket-scan`), opt-in via `run_socket`.
 
-The `frontend-analysis` and `security` pipelines each have a `*-gate` aggregator job that exposes a single stable status-check name (`Frontend Analysis`, `Security`) for branch protection, regardless of the internal job names. Both are gated by the change detector, so documentation-only PRs skip them (and the aggregators still report success). If the change detector (`changes`) job itself fails, the aggregators propagate that failure instead of passing.
+The `frontend-analysis`, `security` and `socket` pipelines each have a `*-gate` aggregator job that exposes a single stable status-check name (`Frontend Analysis`, `Security`, `Socket`) for branch protection, regardless of the internal job names. All are gated by the change detector, so documentation-only PRs skip them (and the aggregators still report success). If the change detector (`changes`) job itself fails, the aggregators propagate that failure instead of passing.
 
 ## Inputs
 
@@ -22,6 +23,7 @@ The `frontend-analysis` and `security` pipelines each have a `*-gate` aggregator
 | `dry_run` | Preview metadata validations without posting comments/labels | boolean | `false` |
 | `run_frontend_analysis` | Run the frontend analysis pipeline | boolean | `true` |
 | `run_security` | Run the security scan pipeline | boolean | `true` |
+| `run_socket` | Run the Socket supply-chain pipeline | boolean | `true` |
 | `ignore_globs` | Space-separated globs treated as docs/meta for the change gate | string | `*.md docs/* .github/* LICENSE* .gitignore` |
 | `pr_title_types` | Allowed commit types (pipe-separated) | string | `feat\|fix\|docs\|style\|refactor\|perf\|test\|chore\|ci\|build\|revert` |
 | `pr_title_scopes` | Allowed scopes (pipe-separated, empty = any) | string | `''` |
@@ -78,6 +80,16 @@ The `frontend-analysis` and `security` pipelines each have a `*-gate` aggregator
 | `codeql_languages` | CodeQL languages (comma-separated, e.g. `javascript-typescript`) | string | `''` |
 | `ignore_file` | Path to Trivy ignore file (e.g. `.trivyignore.yaml`) | string | `''` |
 | `trivy_skip_dirs` | Comma-separated directories to skip in every Trivy filesystem scan | string | `''` |
+| `socket_enable_firewall` | Run Socket Firewall (free tier, no token) and install dependencies through it | boolean | `true` |
+| `socket_enable_scan` | Run the Socket CLI scan (paid tier, needs `SOCKET_SECURITY_API_KEY`) | boolean | `false` |
+| `socket_working_dir` | Directory holding the `package.json` and lockfile scanned by the Socket job | string | `.` |
+| `socket_firewall_version` | Socket Firewall binary version | string | `latest` |
+| `socket_job_summary` | Socket Firewall job summary verbosity (`all`, `errors`, `none`) | string | `all` |
+| `socket_fail_on_block` | Fail the Socket job when Socket Firewall blocks a package | boolean | `true` |
+| `socket_fail_on_findings` | Fail the Socket job when the Socket CLI scan reports blocking alerts | boolean | `false` |
+| `socket_sarif_file` | Path where the Socket CLI scan writes its SARIF report (empty = none) | string | `''` |
+| `socket_ignore_commit_files` | Scan every manifest instead of only the ones touched by the commit | boolean | `false` |
+| `socket_python_version` | Python version used to run the Socket CLI | string | `3.12` |
 
 > **Monorepo note:** `filter_paths`/`shared_paths`/`path_level`/`normalize_to_filter` scope the `frontend-analysis` job only. They are not passed to the `security` job because `frontend-pr-analysis.yml` and `pr-security-scan.yml` use different formats for that input (JSON array vs. newline-separated). For a path-scoped security scan too, call `pr-security-scan.yml` directly.
 
@@ -87,6 +99,7 @@ The `frontend-analysis` and `security` pipelines each have a `*-gate` aggregator
 |--------|-------------|----------|
 | `MANAGE_TOKEN` | Token for PR operations and private package access | No |
 | `SLACK_WEBHOOK_URL` | Slack webhook for pipeline notifications | No |
+| `SOCKET_SECURITY_API_KEY` | Socket API token for the Socket CLI scan (paid tier). Absent = the scan skips with a notice | No |
 
 All other secrets required by the underlying primitives (e.g. `DOCKER_USERNAME`, `DOCKERHUB_IMAGE_PULL_TOKEN`, `NPMRC_TOKEN`) are forwarded automatically via `secrets: inherit`.
 
@@ -150,9 +163,59 @@ jobs:
     secrets: inherit
 ```
 
+## Socket supply chain
+
+`npm audit`, Trivy and CodeQL find known CVEs and insecure code. None of them find a **supply-chain attack** — a package with a malicious install script, a typosquat, a dependency hijacked in a patch release. [Socket](https://socket.dev) covers that gap by analyzing package behavior, and it is wired here in two independent layers.
+
+> Not to be confused with `socket.io`, the WebSocket library. Unrelated project, no scanning capability.
+
+### Free tier — Socket Firewall (on by default)
+
+[`src/security/socket-firewall`](../src/security/socket-firewall/README.md) installs Socket Firewall's free edition, which shims `npm`/`yarn`/`pnpm`, then runs the project's install through it. A malicious package makes the install exit non-zero and the `Socket` check goes red. No token, no account, no cost.
+
+The shim only protects installs in the same job, so this runs a clean install of the same lockfile in the dedicated `socket` job. The 12 install steps inside `frontend-pr-analysis.yml` are not shimmed — the gate here is what blocks the PR.
+
+**Monorepos:** the install needs a lockfile in `socket_working_dir` (default `.`). If none is found the layer skips with a warning instead of failing, so point it at the right directory:
+
+```yaml
+with:
+  socket_working_dir: 'ui'
+```
+
+Unlike `filter_paths`, this is a single directory — the Socket job is not matrixed per component. Repositories with several independently-locked apps should call the composite directly from their own matrixed job.
+
+To report blocks as warnings instead of failing:
+
+```yaml
+with:
+  socket_fail_on_block: false
+```
+
+An install that fails for an ordinary reason (bad lockfile, unreachable registry) always fails the job — `socket_fail_on_block` only softens confirmed Socket blocks.
+
+### Paid tier — Socket CLI scan (off by default)
+
+[`src/security/socket-scan`](../src/security/socket-scan/README.md) runs `socketcli`, which posts the full alert report on the PR and enforces the organization's Socket policy. It needs the `SOCKET_SECURITY_API_KEY` secret; **without the secret it skips with a `::notice::` and the job stays green**, so enabling it early breaks nothing.
+
+```yaml
+with:
+  socket_enable_scan: true          # opt-in
+  socket_fail_on_findings: false    # default — advisory until the repo is clean
+secrets: inherit                    # carries SOCKET_SECURITY_API_KEY
+```
+
+Socket API errors (`exit 3`) and unmet reachability prerequisites (`exit 5`) are always advisory — they say nothing about the dependencies under review.
+
+### Turning the whole thing off
+
+```yaml
+with:
+  run_socket: false
+```
+
 ## Branch protection
 
-Require the aggregator checks `Frontend Analysis` and `Security` (plus the PR metadata checks from `pr-validation.yml`). These names are stable even when the underlying analysis steps change.
+Require the aggregator checks `Frontend Analysis`, `Security` and `Socket` (plus the PR metadata checks from `pr-validation.yml`). These names are stable even when the underlying analysis steps change.
 
 ## Related
 

src/security/socket-firewall/README.md

@@ -0,0 +1,101 @@
+<table border="0" cellspacing="0" cellpadding="0">
+  <tr>
+    <td><img src="https://github.com/LerianStudio.png" width="72" alt="Lerian" /></td>
+    <td><h1>socket-firewall</h1></td>
+  </tr>
+</table>
+
+Composite action that installs [Socket Firewall](https://github.com/SocketDev/sfw-free) (free edition, no account required) and then runs the project's dependency install through it. Socket Firewall shims `npm`, `yarn` and `pnpm`, inspects each package as it is fetched and refuses the ones whose behavior matches a supply-chain attack — malicious install scripts, credential exfiltration, typosquats, hijacked patch releases.
+
+This is the free tier of Socket. It catches malicious packages at install time but produces no PR report and enforces no central policy — for that, see [`socket-scan`](../socket-scan/README.md).
+
+## Inputs
+
+| Input | Description | Required | Default |
+|---|---|:---:|---|
+| `package-manager` | Package manager used to install dependencies (`npm`, `yarn`, `pnpm`) | No | `npm` |
+| `node-version` | Node.js version used for the guarded install | No | `22` |
+| `working-dir` | Directory holding the `package.json` and lockfile | No | `.` |
+| `firewall-version` | Socket Firewall binary version. `latest` tracks the newest release | No | `latest` |
+| `job-summary` | Socket Firewall job summary verbosity (`all`, `errors`, `none`) | No | `all` |
+| `use-cache` | Cache the Socket Firewall binaries between runs | No | `true` |
+| `github-token` | Token used by Socket Firewall to download its binaries. Empty falls back to `github.token` | No | `''` |
+| `fail-on-block` | Fail the step when Socket Firewall blocks a package | No | `true` |
+| `dry-run` | Print the resolved configuration and never fail the step | No | `false` |
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `skipped` | `true` when no lockfile was found in `working-dir`, so nothing was installed or inspected |
+| `blocked` | `true` when the install failed and the output carries a Socket Firewall block marker |
+| `install-exit-code` | Exit code returned by the package manager install |
+| `report-path` | Path to the Socket Firewall report JSON produced by the underlying action |
+
+## No lockfile, no run
+
+Before touching the toolchain the action checks for the lockfile matching `package-manager` (`package-lock.json`, `yarn.lock` or `pnpm-lock.yaml`) inside `working-dir`. If it is absent, everything is skipped with a `::warning::` and `skipped=true`.
+
+That keeps monorepos — whose manifests live under a subdirectory — from going red on a configuration gap: they get a warning pointing at `working-dir` instead of a failed install.
+
+## How the verdict is decided
+
+The shims make a blocked package surface as a non-zero exit from the package manager itself, so a failing install is either a Socket block or an ordinary dependency resolution problem. The action separates the two by looking for a Socket block marker in the install output:
+
+| Install exit | Block marker | `fail-on-block` | Result |
+|---|---|---|---|
+| `0` | — | any | Step passes |
+| non-zero | present | `true` | `::error::` + step fails |
+| non-zero | present | `false` | `::warning::` + step passes |
+| non-zero | absent | any | `::error::` + step fails |
+
+A broken install is **always** a failure. Swallowing it would hide a genuine problem behind a security toggle, so `fail-on-block: false` only softens confirmed Socket blocks.
+
+With `dry-run: true` the install still runs through the firewall and everything is reported, but the step never fails.
+
+## Usage
+
+### As a composite step
+
+```yaml
+jobs:
+  socket:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Socket Firewall
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-firewall@v1
+        with:
+          package-manager: 'npm'
+          node-version: '22'
+          working-dir: '.'
+```
+
+### Via the reusable workflow
+
+Socket Firewall is wired into the `js-pr-validation` umbrella and enabled by default:
+
+```yaml
+jobs:
+  pr-validation:
+    uses: LerianStudio/github-actions-shared-workflows/.github/workflows/js-pr-validation.yml@v1.x.x
+    with:
+      run_socket: true                # default
+      socket_enable_firewall: true    # default
+      socket_fail_on_block: true      # default
+    secrets: inherit
+```
+
+## Permissions required
+
+```yaml
+permissions:
+  contents: read
+```
+
+## Why this action
+
+Socket Firewall ships as a binary plus package-manager shims, which is awkward to install correctly inline. [`SocketDev/action`](https://github.com/SocketDev/action) is the vendor-maintained installer, so this composite wraps it (pinned by commit SHA) and adds the parts it does not cover: the toolchain setup, the guarded install itself, block-versus-failure attribution and the advisory mode.