test(security): real-process regression suite for the bsdtar extraction guard [DEVA11Y-484]

Adds local integration tests (no mocks) that exercise the decompression-bomb
guards against real curl/bsdtar/head and the real Swift watchdog, plus hardens
the guard itself based on what the tests surfaced.

Guard hardening (Plugins/BrowserStackAccessibilityLint.swift):
- The watchdog now also terminates bsdtar on an entry-count ceiling, closing the
  "millions of tiny files" bomb that stays small on disk (previously only
  locateExecutable caught it, after the fact).
- Added a post-extraction footprint check so detection is deterministic on fast
  disks: a bomb that finishes decompressing within a single 200ms poll interval
  is now caught and cleaned up rather than slipping past the live watchdog.
- Refactored the guard into a self-contained, marked block of free functions so
  it can be mirrored and drift-checked.

Tests (scripts/test/, run via run_tests.sh):
- Shell: extracts the REAL download_binary from bash/zsh/fish verbatim and runs it
  against a local server (only the hardcoded URL is redirected, via a curl shim).
- Swift: a mirror harness compiles the guard block verbatim and drives real
  curl/bsdtar; check_drift.sh fails CI if the mirror diverges from the plugin
  (SwiftPM command plugins can't be imported by a test target).
- Scenarios: legit (downloads/extracts/runs), 400MB bomb, 20k-entry bomb,
  oversized (>100MB) download, corrupt archive, multi-file, missing URL.
- Fixtures are bounded (≤400MB, gitignored) and bomb tests use a small cap, so a
  regressed guard can never exhaust the disk. Full run ~9s, disk usage flat.
- CI: .github/workflows/extraction-guard-tests.yml runs the suite on macOS for PRs
  touching the download/extract path.

53/53 assertions green locally; real production artifact (34MB/64MB) verified to
pass through the new extraction path and run.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: maunilm

.github/workflows/extraction-guard-tests.yml

@@ -0,0 +1,36 @@
+# Regression tests for the DEVA11Y-484 decompression-bomb extraction guard.
+# Runs the real-process integration suite (curl/bsdtar/Swift watchdog) on every PR
+# that touches the download/extract path. macOS runner: it ships curl, bsdtar
+# (libarchive), python3, and the Swift toolchain.
+name: Extraction Guard Tests
+
+on:
+  pull_request:
+    branches: ["master", "main"]
+    paths:
+      - "Plugins/BrowserStackAccessibilityLint/**"
+      - "scripts/bash/cli.sh"
+      - "scripts/zsh/cli.sh"
+      - "scripts/fish/cli.sh"
+      - "scripts/test/**"
+      - ".github/workflows/extraction-guard-tests.yml"
+  push:
+    branches: ["master", "main"]
+
+permissions:
+  contents: read
+
+jobs:
+  extraction-guard:
+    name: extraction-guard / integration
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+      - name: Show toolchain
+        run: |
+          swift --version
+          bsdtar --version
+          curl --version | head -1
+          python3 --version
+      - name: Run DEVA11Y-484 extraction-guard regression suite
+        run: bash scripts/test/run_tests.sh

Plugins/BrowserStackAccessibilityLint/BrowserStackAccessibilityLint.swift

@@ -275,10 +275,8 @@ private struct BrowserStackCLIDownloader {
             throw PluginError("Unable to launch bsdtar: \(error.localizedDescription)")
         }
 
-        // bsdtar writes decompressed bytes straight to disk, so a cap on the curl→bsdtar
-        // pipe would only bound the *compressed* size — useless against a decompression
-        // bomb. Guard the *decompressed* footprint instead (DEVA11Y-484).
-        let limitState = enforceExtractionSizeLimit(on: bsdtar, extractingInto: directory)
+        // See the DEVA11Y-484 EXTRACTION GUARD block below for the rationale.
+        let limitState = startExtractionWatchdog(on: bsdtar, directory: directory, maxBytes: Self.maxDecompressedBytes, maxEntries: Self.maxArchiveEntries)
 
         do {
             try curl.run()
@@ -292,9 +290,13 @@ private struct BrowserStackCLIDownloader {
         pipe.fileHandleForWriting.closeFile()
         bsdtar.waitUntilExit()
 
+        // Catch a bomb that completed within a single watchdog poll interval (fast disk).
+        if !limitState.exceeded, let reason = footprintExceeded(at: directory, maxBytes: Self.maxDecompressedBytes, maxEntries: Self.maxArchiveEntries) {
+            limitState.markExceeded(reason)
+        }
         if limitState.exceeded {
             try? fileManager.removeItem(at: directory)
-            forwardExit(code: 1, message: "BrowserStack CLI archive exceeds the maximum allowed decompressed size of \(Self.maxDecompressedBytes / (1024 * 1024)) MB. Aborting to prevent disk exhaustion.")
+            forwardExit(code: 1, message: "BrowserStack CLI archive rejected: \(limitState.reason). Aborting to prevent disk exhaustion.")
         }
 
         if curl.terminationStatus != 0 {
@@ -308,39 +310,6 @@ private struct BrowserStackCLIDownloader {
         }
     }
 
-    /// Starts a background watchdog that terminates `bsdtar` if the decompressed footprint in
-    /// `directory` exceeds `maxDecompressedBytes`. Returns the shared state to inspect afterwards.
-    private func enforceExtractionSizeLimit(on bsdtar: Process, extractingInto directory: URL) -> ExtractionLimitState {
-        let state = ExtractionLimitState()
-        let watchdog = Thread {
-            while bsdtar.isRunning {
-                if Self.directorySize(at: directory) > Self.maxDecompressedBytes {
-                    state.markExceeded()
-                    bsdtar.terminate()
-                    break
-                }
-                Thread.sleep(forTimeInterval: 0.2)
-            }
-        }
-        watchdog.start()
-        return state
-    }
-
-    private static func directorySize(at url: URL) -> Int64 {
-        let fm = FileManager.default
-        guard let enumerator = fm.enumerator(at: url, includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey]) else {
-            return 0
-        }
-        var total: Int64 = 0
-        for case let element as URL in enumerator {
-            let values = try? element.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey])
-            if values?.isRegularFile == true, let size = values?.fileSize {
-                total += Int64(size)
-            }
-        }
-        return total
-    }
-
     private func extractLocalArchive(at archiveURL: URL, into directory: URL) throws {
         let process = Process()
         process.executableURL = URL(fileURLWithPath: "/usr/bin/env")
@@ -351,16 +320,20 @@ private struct BrowserStackCLIDownloader {
         let limitState: ExtractionLimitState
         do {
             try process.run()
-            // Decompressed-size guard (DEVA11Y-484): same rationale as the remote path.
-            limitState = enforceExtractionSizeLimit(on: process, extractingInto: directory)
+            // Decompressed-size/entry guard (DEVA11Y-484): same rationale as the remote path.
+            limitState = startExtractionWatchdog(on: process, directory: directory, maxBytes: Self.maxDecompressedBytes, maxEntries: Self.maxArchiveEntries)
             process.waitUntilExit()
         } catch {
             throw PluginError("Failed to launch bsdtar: \(error.localizedDescription)")
         }
 
+        // Catch a bomb that completed within a single watchdog poll interval (fast disk).
+        if !limitState.exceeded, let reason = footprintExceeded(at: directory, maxBytes: Self.maxDecompressedBytes, maxEntries: Self.maxArchiveEntries) {
+            limitState.markExceeded(reason)
+        }
         if limitState.exceeded {
             try? fileManager.removeItem(at: directory)
-            forwardExit(code: 1, message: "BrowserStack CLI archive exceeds the maximum allowed decompressed size of \(Self.maxDecompressedBytes / (1024 * 1024)) MB. Aborting to prevent disk exhaustion.")
+            forwardExit(code: 1, message: "BrowserStack CLI archive rejected: \(limitState.reason). Aborting to prevent disk exhaustion.")
         }
 
         if process.terminationReason != .exit || process.terminationStatus != 0 {
@@ -670,14 +643,30 @@ private func isAlpineLinux() -> Bool { false }
 
 // MARK: - Error
 
+// === DEVA11Y-484 EXTRACTION GUARD: shared block ===
+// This block is mirrored verbatim in
+//   scripts/test/swift-harness/Sources/ExtractionHarness/Guard.swift
+// so the integration harness exercises the real logic. scripts/test/check_drift.sh
+// fails CI if the two copies diverge. Edit both, or neither.
+//
+// Rationale: bsdtar writes decompressed bytes straight to disk, so a cap on the
+// curl→bsdtar pipe would only bound the *compressed* size — useless against a
+// decompression bomb. Instead we poll the destination directory while bsdtar runs
+// and terminate it if the decompressed footprint crosses a byte OR entry ceiling
+// (the entry ceiling stops a "millions of tiny files" bomb that stays small on disk).
+
 /// Thread-safe flag shared between the extraction watchdog and the main flow.
-private final class ExtractionLimitState {
+final class ExtractionLimitState {
     private let lock = NSLock()
     private var didExceed = false
+    private var why = ""
 
-    func markExceeded() {
+    func markExceeded(_ reason: String) {
         lock.lock()
-        didExceed = true
+        if !didExceed {
+            didExceed = true
+            why = reason
+        }
         lock.unlock()
     }
 
@@ -686,7 +675,64 @@ private final class ExtractionLimitState {
         defer { lock.unlock() }
         return didExceed
     }
+
+    var reason: String {
+        lock.lock()
+        defer { lock.unlock() }
+        return why
+    }
+}
+
+/// Total bytes and entry count of all regular files under `url`.
+func extractionFootprint(at url: URL) -> (bytes: Int64, entries: Int) {
+    let fm = FileManager.default
+    guard let enumerator = fm.enumerator(at: url, includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey]) else {
+        return (0, 0)
+    }
+    var total: Int64 = 0
+    var count = 0
+    for case let element as URL in enumerator {
+        count += 1
+        let values = try? element.resourceValues(forKeys: [.isRegularFileKey, .fileSizeKey])
+        if values?.isRegularFile == true, let size = values?.fileSize {
+            total += Int64(size)
+        }
+    }
+    return (total, count)
+}
+
+/// Returns a rejection reason if the footprint under `directory` exceeds either ceiling.
+func footprintExceeded(at directory: URL, maxBytes: Int64, maxEntries: Int) -> String? {
+    let footprint = extractionFootprint(at: directory)
+    if footprint.bytes > maxBytes {
+        return "decompressed size exceeds \(maxBytes / (1024 * 1024)) MB"
+    }
+    if footprint.entries > maxEntries {
+        return "archive contains more than \(maxEntries) entries"
+    }
+    return nil
+}
+
+/// Starts a background watchdog that terminates `process` (bsdtar) if the decompressed
+/// footprint in `directory` exceeds the byte or entry ceiling. The watchdog bounds peak
+/// disk use during a large/slow bomb; callers MUST also run `footprintExceeded` once the
+/// process exits, to catch a fast bomb that finished within a single poll interval.
+func startExtractionWatchdog(on process: Process, directory: URL, maxBytes: Int64, maxEntries: Int) -> ExtractionLimitState {
+    let state = ExtractionLimitState()
+    let watchdog = Thread {
+        while process.isRunning {
+            if let reason = footprintExceeded(at: directory, maxBytes: maxBytes, maxEntries: maxEntries) {
+                state.markExceeded(reason)
+                process.terminate()
+                break
+            }
+            Thread.sleep(forTimeInterval: 0.2)
+        }
+    }
+    watchdog.start()
+    return state
 }
+// === END DEVA11Y-484 EXTRACTION GUARD ===
 
 private struct PluginError: Error, CustomStringConvertible {
     let message: String

scripts/test/.gitignore

@@ -0,0 +1,4 @@
+# Generated by make_fixtures.sh — large/binary, never commit
+fixtures/
+# SwiftPM build output for the mirror harness
+swift-harness/.build/

scripts/test/README.md

@@ -0,0 +1,59 @@
+# DEVA11Y-484 — decompression-bomb guard regression tests
+
+Real, local integration tests for the size/entry guards added to the CLI download path.
+**No mocks** — every test runs actual `curl`, `bsdtar`, `head`, and (for the plugin) real
+`Process`/watchdog logic against crafted archives served from a local HTTP server.
+
+## Run everything
+
+```bash
+scripts/test/run_tests.sh
+```
+
+This generates fixtures (first run only), checks guard sync, then runs the shell and
+Swift suites. Exit code is non-zero if anything fails.
+
+Requirements: `bash`, `curl`, `bsdtar` (libarchive), `python3`, and the Swift toolchain
+(`swift`). All present on the macOS CI image.
+
+## What is covered
+
+| Scenario | Shell (`download_binary`) | Swift plugin (extract paths) |
+| --- | --- | --- |
+| Legit binary downloads, extracts, **runs**, `0775` | ✅ | ✅ |
+| Decompression bomb (400 MB) → abort + cleanup | ✅ | ✅ (remote + local) |
+| Entry-count bomb (20k files) | n/a — `-O` streams, nothing per-entry on disk | ✅ flagged on entry cap |
+| Multi-file archive (pre-existing behavior unchanged) | ✅ | ✅ |
+| Oversized download (>100 MB) rejected before extraction | ✅ | ✅ (`curl --max-filesize`) |
+| Corrupt archive → clean failure, no false bomb-positive | ✅ | ✅ |
+| Missing URL / network failure → abort, no hang | ✅ | — |
+
+All fixtures are **bounded** (nothing decompresses beyond ~400 MB) so a regressed guard
+can never exhaust the disk during a test run; bomb tests additionally use a small byte cap.
+
+## Why a "mirror" for the Swift side
+
+SwiftPM **command plugins cannot be imported by a test target** (they run sandboxed and
+compile only their own sources), so the plugin's guard logic cannot be unit-tested
+directly. Instead:
+
+- The guard lives in a clearly-marked block in
+  `Plugins/BrowserStackAccessibilityLint/BrowserStackAccessibilityLint.swift`
+  (`=== DEVA11Y-484 EXTRACTION GUARD ===`).
+- `swift-harness/Sources/ExtractionHarness/Guard.swift` is a **verbatim mirror** of that
+  block, compiled into a small executable that drives real `curl`/`bsdtar`.
+- `check_drift.sh` diffs the two and **fails if they diverge**, so the mirror can never
+  silently rot. If you edit the guard, copy the block into both — the drift check enforces it.
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `run_tests.sh` | Orchestrator — run this |
+| `make_fixtures.sh` | Generates the bounded test archives into `fixtures/` (gitignored) |
+| `check_drift.sh` | Fails if the plugin guard and harness mirror diverge |
+| `test_shell_extraction.sh` | Runs the real `download_binary` from all 3 wrappers |
+| `test_swift_extraction.sh` | Runs the Swift guard via the mirror harness |
+| `lib/assert.sh` | Assertion helpers + local server management |
+| `_shim/curl` | Test-only curl shim; redirects the hardcoded URL to the local server |
+| `swift-harness/` | Standalone SwiftPM executable mirroring the guard |

scripts/test/_shim/curl

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Test-only curl shim. Lets the real, unmodified download_binary() run while
+# redirecting ONLY the hardcoded api.browserstack.com download URL to the local
+# test server. Every other argument (--max-filesize, -L, -o, -z, ...) is preserved,
+# so the security-relevant pipeline is exercised verbatim. Interception happens at
+# curl's CLI boundary; the shell function itself is never edited.
+set -u
+: "${REAL_CURL:?REAL_CURL must point at the real curl}"
+: "${TEST_DOWNLOAD_URL:?TEST_DOWNLOAD_URL must be set}"
+
+args=()
+for a in "$@"; do
+  case "$a" in
+    https://api.browserstack.com/sdk/v1/download_cli*) a="$TEST_DOWNLOAD_URL" ;;
+  esac
+  args+=("$a")
+done
+exec "$REAL_CURL" "${args[@]}"

scripts/test/check_drift.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Fails if the DEVA11Y-484 EXTRACTION GUARD block in the SPM plugin has drifted from
+# the mirrored copy the Swift harness compiles. SwiftPM command plugins can't be
+# imported by a test target, so the harness mirrors the guard verbatim; this check is
+# what keeps the mirror honest.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="$(cd "$HERE/../.." && pwd)"
+PLUGIN="$REPO/Plugins/BrowserStackAccessibilityLint/BrowserStackAccessibilityLint.swift"
+MIRROR="$HERE/swift-harness/Sources/ExtractionHarness/Guard.swift"
+
+block() {
+  awk '/=== DEVA11Y-484 EXTRACTION GUARD: shared block ===/,/=== END DEVA11Y-484 EXTRACTION GUARD ===/' "$1"
+}
+
+tmp_plugin="$(mktemp)"; tmp_mirror="$(mktemp)"
+trap 'rm -f "$tmp_plugin" "$tmp_mirror"' EXIT
+block "$PLUGIN" > "$tmp_plugin"
+block "$MIRROR" > "$tmp_mirror"
+
+if [ ! -s "$tmp_plugin" ]; then echo "DRIFT CHECK ERROR: guard markers not found in plugin"; exit 2; fi
+if [ ! -s "$tmp_mirror" ]; then echo "DRIFT CHECK ERROR: guard markers not found in mirror"; exit 2; fi
+
+if diff -u "$tmp_plugin" "$tmp_mirror"; then
+  echo "drift check: OK — plugin guard and harness mirror are identical ($(wc -l < "$tmp_plugin" | tr -d ' ') lines)"
+else
+  echo
+  echo "DRIFT DETECTED: the harness mirror no longer matches the plugin guard block."
+  echo "Re-sync by copying the block between the markers, then re-run the tests."
+  exit 1
+fi