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

@@ -37,6 +37,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:
@@ -282,14 +286,111 @@ 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_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_use_cache:
+        description: 'Cache the sfw binary between runs. Unrelated to the package-manager cache, which is always purged before the guarded install.'
+        type: boolean
+        default: true
+      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_enable_app_gate:
+        description: >-
+          Turn the Socket GitHub App checks into an enforceable gate. The App analyses the dependency graph and
+          posts advisory checks; this makes an adverse verdict block the pull request. Needs no token.
+        type: boolean
+        default: true
+      socket_app_slug:
+        description: 'GitHub App slug whose checks the gate reads'
+        type: string
+        default: 'socket-security'
+      socket_app_timeout:
+        description: 'Seconds to wait for the Socket App checks to complete before treating the result as inconclusive'
+        type: number
+        default: 300
+      socket_app_fail_on_findings:
+        description: 'Fail the Socket job when the App reports adverse checks'
+        type: boolean
+        default: true
+      socket_app_on_inconclusive:
+        description: >-
+          What to do when the App ran but reached no verdict (neutral/skipped/timeout): "block" (default) or "warn".
+          A conflicted pull request is the common cause, and it must not read as clean.
+        type: string
+        default: 'block'
+      socket_enable_api_report:
+        description: >-
+          Read the full scan the Socket App already computed and report per-package alerts, vulnerabilities and
+          scores in the pull request comment. Requires SOCKET_SECURITY_API_KEY with the full-scans:list scope.
+          Advisory only — it never gates the merge.
+        type: boolean
+        default: true
+      socket_api_max_rows:
+        description: 'Maximum package rows kept in the dependency findings table'
+        type: number
+        default: 25
+      socket_api_include_actions:
+        description: >-
+          Comma-separated Socket alert actions reported as findings. Socket marks roughly 99% of alerts as "ignore"
+          (capability observations such as envVars), so reporting unfiltered buries a handful of findings in
+          thousands of lines.
+        type: string
+        default: 'error,warn,monitor'
+      socket_comment_when:
+        description: >-
+          "findings" (the default) posts the Socket comment only when there is something to act on. "always" posts
+          every run. Operational state — whether the scan ran, which checks passed — is never in the comment; it
+          lives in the job log and the Socket status check.
+        type: string
+        default: 'findings'
+      socket_api_fail_on_actions:
+        description: >-
+          Comma-separated Socket alert actions that block the pull request. Empty (the default) reports without
+          blocking. Set to e.g. "error" to own the merge decision in this workflow rather than deferring it to the
+          Socket App's verdict.
+        type: string
+        default: ''
+      socket_app_on_missing:
+        description: >-
+          What to do when the App published no checks, which is what a repository without it installed looks like:
+          "warn" (default) keeps those repositories green, "block" requires the App.
+        type: string
+        default: 'warn'
     secrets:
       MANAGE_TOKEN:
         required: false
       SLACK_WEBHOOK_URL:
         required: false
+      # Declared but not consumed by any job today: the Socket layers here run
+      # token-free (the firewall inspects traffic locally, the App gate reads the
+      # GitHub checks API). It is declared so an organization secret reaches this
+      # workflow through `secrets: inherit` without a release, which a reusable
+      # workflow cannot do for an undeclared secret. Do not delete as dead —
+      # Socket Firewall enterprise is the intended consumer.
+      SOCKET_SECURITY_API_KEY:
+        required: false
 
 permissions:
   actions: read
+  checks: read
   contents: read
   id-token: write
   issues: write
@@ -351,6 +452,9 @@ jobs:
       path_level: ${{ inputs.path_level }}
       normalize_to_filter: ${{ inputs.normalize_to_filter }}
       app_name_prefix: ${{ inputs.app_name_prefix }}
+      enable_socket_firewall: ${{ inputs.socket_enable_firewall }}
+      socket_firewall_version: ${{ inputs.socket_firewall_version }}
+      socket_fail_on_block: ${{ inputs.socket_fail_on_block }}
       enable_lint: ${{ inputs.enable_lint }}
       enable_typecheck: ${{ inputs.enable_typecheck }}
       enable_security: ${{ inputs.enable_security }}
@@ -427,6 +531,169 @@ 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
+      checks: read
+      issues: write
+      pull-requests: write
+    env:
+      SOCKET_APP_NAME: ${{ inputs.app_name_prefix != '' && inputs.app_name_prefix || github.event.repository.name }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
+        with:
+          persist-credentials: false
+
+      # This install is the reporting source of truth for the Socket Firewall
+      # row below. Enforcement itself is broader: every install in
+      # frontend-pr-analysis.yml also runs through the firewall, so a malicious
+      # package cannot execute install scripts in any analysis job either.
+      - name: Socket Firewall
+        id: firewall
+        if: inputs.socket_enable_firewall
+        continue-on-error: true
+        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 }}
+          use-cache: ${{ inputs.socket_use_cache }}
+          fail-on-block: ${{ inputs.socket_fail_on_block }}
+          dry-run: ${{ inputs.dry_run }}
+
+      - name: Socket App Gate
+        id: app-gate
+        if: inputs.socket_enable_app_gate && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-app-gate@v1
+        with:
+          github-token: ${{ secrets.MANAGE_TOKEN || github.token }}
+          # The App reports against the pull request head, not the merge commit.
+          commit-sha: ${{ github.event.pull_request.head.sha }}
+          app-slug: ${{ inputs.socket_app_slug }}
+          timeout-seconds: ${{ inputs.socket_app_timeout }}
+          fail-on-findings: ${{ inputs.socket_app_fail_on_findings }}
+          on-inconclusive: ${{ inputs.socket_app_on_inconclusive }}
+          on-missing-app: ${{ inputs.socket_app_on_missing }}
+
+      # Reads the scan the App already produced, addressed by the dashboard URL the
+      # gate captured — no new scan, one quota unit, no duplicate analysis.
+      # The App publishes the diff scan id in its own comment. Looking it up by
+      # after_full_scan_id does not work: the App diffs against a different full
+      # scan than the one its Project Report check links to.
+      - name: Resolve Socket diff scan id
+        id: diff-scan
+        if: always() && inputs.socket_enable_api_report && github.event_name == 'pull_request'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.MANAGE_TOKEN || github.token }}
+          PR: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          JQ='[.[] | select(.user.login == "socket-security[bot]") | .body] | last // ""'
+          BODY=$(gh api "repos/$REPO/issues/$PR/comments" --paginate --jq "$JQ")
+          ID=$(printf '%s' "$BODY" \
+            | grep -oE 'diff-scan/[0-9a-fA-F-]{36}' | head -1 | cut -d/ -f2 || true)
+          if [ -n "$ID" ]; then
+            echo "Resolved diff scan $ID from the Socket App comment."
+          else
+            echo "No diff scan id in the Socket App comment — it only posts one when dependencies change."
+          fi
+          echo "id=$ID" >> "$GITHUB_OUTPUT"
+
+      - name: Socket API Report
+        id: api-report
+        if: always() && inputs.socket_enable_api_report && github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-api-report@v1
+        with:
+          socket-api-key: ${{ secrets.SOCKET_SECURITY_API_KEY }}
+          report-url: ${{ steps.app-gate.outputs.report-url }}
+          max-rows: ${{ inputs.socket_api_max_rows }}
+          include-actions: ${{ inputs.socket_api_include_actions }}
+          fail-on-actions: ${{ inputs.socket_api_fail_on_actions }}
+          # The baseline: findings already on the target branch are reported as
+          # pre-existing and never block, so a repository carrying debt does not
+          # fail every pull request for something none of them caused.
+          base-branch: ${{ github.base_ref }}
+          head-sha: ${{ github.event.pull_request.head.sha }}
+          diff-scan-id: ${{ steps.diff-scan.outputs.id }}
+
+      - name: Post Socket report to PR
+        if: always() && github.event_name == 'pull_request' && !inputs.dry_run
+        uses: LerianStudio/github-actions-shared-workflows/src/security/socket-reporter@v1
+        with:
+          github-token: ${{ secrets.MANAGE_TOKEN || github.token }}
+          app-name: ${{ env.SOCKET_APP_NAME }}
+          comment-when: ${{ inputs.socket_comment_when }}
+          firewall-blocked: ${{ steps.firewall.outputs.blocked || 'false' }}
+          firewall-fail-on-block: ${{ inputs.socket_fail_on_block }}
+          firewall-findings-file: ${{ steps.firewall.outputs.findings-file }}
+          api-findings-file: ${{ steps.api-report.outputs.findings-file }}
+          api-blocking-count: ${{ steps.api-report.outputs.blocking-count || '0' }}
+          # yamllint disable-line rule:line-length
+          run-url: ${{ format('{0}/{1}/actions/runs/{2}', github.server_url, github.repository, github.run_id) }}
+
+      # continue-on-error above keeps the report reachable even when a layer
+      # fails, so the verdict is re-applied here.
+      # dry_run is a preview across the whole umbrella, so the gate reports the
+      # verdict it would have applied instead of applying it.
+      - name: Gate - Fail on Socket findings
+        if: always() && !inputs.dry_run
+        env:
+          FIREWALL_OUTCOME: ${{ steps.firewall.outcome }}
+          APP_GATE_OUTCOME: ${{ steps.app-gate.outcome }}
+          API_BLOCKING: ${{ steps.api-report.outputs.blocking-count }}
+        run: |
+          FAILED=""
+          [ "$FIREWALL_OUTCOME" = "failure" ] && FAILED="$FAILED Socket-Firewall"
+          [ "$APP_GATE_OUTCOME" = "failure" ] && FAILED="$FAILED Socket-App-Gate"
+          # Only real findings from the API layer block. Its API-failure paths
+          # report zero here by construction, so an unreachable Socket cannot
+          # fail a pull request.
+          if [ "${API_BLOCKING:-0}" -gt 0 ] 2>/dev/null; then
+            FAILED="$FAILED Socket-Dependency-Findings"
+          fi
+          if [ -n "$FAILED" ]; then
+            echo "::error::Socket supply chain gate failed:$FAILED. See the Socket comment on the pull request."
+            exit 1
+          fi
+          echo "Socket supply chain gate passed."
+
+      - name: Gate - Socket findings (dry run)
+        if: always() && inputs.dry_run
+        env:
+          FIREWALL_OUTCOME: ${{ steps.firewall.outcome }}
+          APP_GATE_OUTCOME: ${{ steps.app-gate.outcome }}
+          API_BLOCKING: ${{ steps.api-report.outputs.blocking-count }}
+        run: |
+          echo "::notice::DRY RUN — Socket gate not enforced"
+          echo "  Socket Firewall  : $FIREWALL_OUTCOME"
+          echo "  Socket App gate  : $APP_GATE_OUTCOME"
+          echo "  Blocking findings: ${API_BLOCKING:-0}"
+
+  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

.gitignore

@@ -37,3 +37,6 @@ go.list
 # ── Temporary files ────────────────────────────────────────────────────────────
 tmp/
 temp/
+
+# Linter binaries fetched ad hoc for local verification
+/typos

docs/frontend-pr-analysis-workflow.md

@@ -140,6 +140,14 @@ jobs:
     secrets: inherit
 ```
 
+## Guarded dependency installs
+
+Every job that installs dependencies does so through [`setup-node-guarded`](../src/setup/setup-node-guarded/README.md), which runs `sfw npm ci` (or the `yarn`/`pnpm` equivalent) under [Socket Firewall](https://github.com/SocketDev/sfw-free) instead of a bare install. A malicious package is refused mid-fetch, so it never reaches disk and its install scripts never execute — in **any** of these jobs, not just one.
+
+Guarded installs deliberately run **without a package-manager cache**: Socket Firewall only inspects what crosses the network, and a cached tarball produces no request. The cache is also purged before each install, since runner images can arrive pre-warmed. Measured cost is roughly 20s for a cold install of ~2000 packages.
+
+Set `enable_socket_firewall: false` to restore the previous behaviour (cached, unguarded) — necessary for repositories that install from a private registry, which the free edition does not support.
+
 ## Inputs
 
 | Input | Description | Required | Default |
@@ -152,6 +160,9 @@ jobs:
 | `app_name_prefix` | Prefix for app names in matrix output | No | `''` |
 | `node_version` | Node.js version to use | No | `22` |
 | `package_manager` | Package manager (npm, yarn, pnpm) | No | `npm` |
+| `enable_socket_firewall` | Route every dependency install through Socket Firewall (free tier, no token) so a malicious package is refused before any install script runs. `false` restores the previous behaviour, package-manager cache included | No | `true` |
+| `socket_firewall_version` | Socket Firewall binary version | No | `latest` |
+| `socket_fail_on_block` | Fail the job when Socket Firewall blocks a package | No | `true` |
 | `eslint_args` | Additional ESLint arguments | No | `''` |
 | `audit_level` | npm audit severity level (low, moderate, high, critical) | No | `high` |
 | `coverage_threshold` | Minimum coverage percentage (0-100) | No | `80` |