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,6 +276,62 @@ 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_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
@@ -341,6 +401,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 }}
@@ -417,6 +480,110 @@ jobs:
           result: ${{ needs.changes.result != 'success' && needs.changes.result || needs.security.result }}
           label: Security
 
+  # ----------------- Socket Supply Chain -----------------
+  # TEMPORARY: the two composite refs below point at this feature branch so the
+  # new actions resolve during end-to-end validation. Revert to @v1 before merge
+  # — the tag does not carry them yet, and the internal pinning policy requires
+  # a floating major tag for composites.
+  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@feat/js-pr-validation-socket
+        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@feat/js-pr-validation-socket
+        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 }}
+
+      - 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@feat/js-pr-validation-socket
+        with:
+          github-token: ${{ secrets.MANAGE_TOKEN || github.token }}
+          app-name: ${{ env.SOCKET_APP_NAME }}
+          firewall-enabled: ${{ inputs.socket_enable_firewall }}
+          firewall-blocked: ${{ steps.firewall.outputs.blocked || 'false' }}
+          firewall-exit-code: ${{ steps.firewall.outputs.install-exit-code || '0' }}
+          firewall-fail-on-block: ${{ inputs.socket_fail_on_block }}
+          app-gate-enabled: ${{ inputs.socket_enable_app_gate }}
+          app-findings-file: ${{ steps.app-gate.outputs.findings-file }}
+          app-fail-on-findings: ${{ inputs.socket_app_fail_on_findings }}
+          # 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.
+      - name: Gate - Fail on Socket findings
+        if: always()
+        env:
+          FIREWALL_OUTCOME: ${{ steps.firewall.outcome }}
+          APP_GATE_OUTCOME: ${{ steps.app-gate.outcome }}
+        run: |
+          FAILED=""
+          [ "$FIREWALL_OUTCOME" = "failure" ] && FAILED="$FAILED Socket-Firewall"
+          [ "$APP_GATE_OUTCOME" = "failure" ] && FAILED="$FAILED Socket-App-Gate"
+          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."
+
+  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/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` |