Skip to content

The headless browser for AI agents and web scraping

Bundle and validate Windows runtime dependencies

Anirudh Sharma673f522e57ad
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 01b8c434..c73883c0 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,6 +1,13 @@
name: Release
on:
+ # Manual validation uses Windows only and cannot publish a release.
+ workflow_dispatch:
+ inputs:
+ windows_only:
+ description: Validate only the Windows distribution
+ type: boolean
+ default: true
push:
tags:
- 'v*'
@@ -27,33 +34,17 @@ jobs:
strategy:
fail-fast: false
matrix:
- include:
- - target: x86_64-unknown-linux-gnu
- # Build on Ubuntu 22.04 so the Linux release binary works on
- # common LTS servers with glibc 2.35 instead of requiring the
- # newer glibc shipped by ubuntu-latest.
- os: ubuntu-22.04
- name: obscura-x86_64-linux
- - target: aarch64-unknown-linux-gnu
- # Native build on GitHub's ARM runner.
- os: ubuntu-22.04-arm
- name: obscura-aarch64-linux
- - target: aarch64-apple-darwin
- os: macos-latest
- name: obscura-aarch64-macos
- - target: x86_64-apple-darwin
- # Must run on a native Intel runner. obscura-js bakes a V8 startup
- # snapshot at build time, and that snapshot is architecture specific.
- # macos-latest is Apple Silicon, so building x86_64 there embeds an
- # arm64 snapshot into the Intel binary and V8 crashes deserializing
- # it at isolate init (issue #290). macos-15-intel is the last x86_64
- # image (available until Aug 2027); there is no cross-build that
- # produces a correct snapshot.
- os: macos-15-intel
- name: obscura-x86_64-macos
- - target: x86_64-pc-windows-msvc
- os: windows-latest
- name: obscura-x86_64-windows
+ # Linux retains glibc 2.35 compatibility. Both macOS architectures must
+ # build natively because V8 snapshots are architecture-specific (#290).
+ # macos-15-intel remains available until August 2027.
+ include: >-
+ ${{ fromJSON(inputs.windows_only &&
+ '[{"target":"x86_64-pc-windows-msvc","os":"windows-latest","name":"obscura-x86_64-windows"}]' ||
+ '[{"target":"x86_64-unknown-linux-gnu","os":"ubuntu-22.04","name":"obscura-x86_64-linux"},
+ {"target":"aarch64-unknown-linux-gnu","os":"ubuntu-22.04-arm","name":"obscura-aarch64-linux"},
+ {"target":"aarch64-apple-darwin","os":"macos-latest","name":"obscura-aarch64-macos"},
+ {"target":"x86_64-apple-darwin","os":"macos-15-intel","name":"obscura-x86_64-macos"},
+ {"target":"x86_64-pc-windows-msvc","os":"windows-latest","name":"obscura-x86_64-windows"}]') }}
runs-on: ${{ matrix.os }}
@@ -183,17 +174,15 @@ jobs:
tar czf ${{ matrix.name }}-no-render.tar.gz -C dist/no-render obscura obscura-worker
tar czf ${{ matrix.name }}-no-render-stealth.tar.gz -C dist/no-render-stealth obscura obscura-worker
- - name: Package (Windows)
+ - name: Package and verify Windows runtime dependencies
if: runner.os == 'Windows'
+ shell: pwsh
run: |
- cd dist/default
- 7z a ../../${{ matrix.name }}.zip obscura.exe obscura-worker.exe
- cd ../stealth
- 7z a ../../${{ matrix.name }}-stealth.zip obscura.exe obscura-worker.exe
- cd ../no-render
- 7z a ../../${{ matrix.name }}-no-render.zip obscura.exe obscura-worker.exe
- cd ../no-render-stealth
- 7z a ../../${{ matrix.name }}-no-render-stealth.zip obscura.exe obscura-worker.exe
+ ./scripts/ci/test_package_windows.ps1
+ ./scripts/ci/package_windows.ps1 dist/default '${{ matrix.name }}.zip'
+ ./scripts/ci/package_windows.ps1 dist/stealth '${{ matrix.name }}-stealth.zip'
+ ./scripts/ci/package_windows.ps1 dist/no-render '${{ matrix.name }}-no-render.zip'
+ ./scripts/ci/package_windows.ps1 dist/no-render-stealth '${{ matrix.name }}-no-render-stealth.zip'
- name: Upload packaged binaries
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -212,6 +201,7 @@ jobs:
retention-days: 1
publish:
+ if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
needs: build
runs-on: ubuntu-22.04
permissions:
diff --git a/.github/workflows/windows-package.yml b/.github/workflows/windows-package.yml
new file mode 100644
index 00000000..7a554d58
--- /dev/null
+++ b/.github/workflows/windows-package.yml
@@ -0,0 +1,58 @@
+name: Windows packaging regression
+on:
+ workflow_dispatch:
+ pull_request:
+ paths:
+ - '.github/workflows/release.yml'
+ - '.github/workflows/windows-package.yml'
+ - 'scripts/ci/*windows*.ps1'
+ push:
+ branches: [main]
+ paths:
+ - '.github/workflows/release.yml'
+ - '.github/workflows/windows-package.yml'
+ - 'scripts/ci/*windows*.ps1'
+permissions:
+ contents: read
+concurrency:
+ group: windows-package-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+jobs:
+ package:
+ runs-on: windows-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+ with:
+ persist-credentials: false
+ - name: Test dependency validation
+ shell: pwsh
+ run: ./scripts/ci/test_package_windows.ps1
+ - name: Regress the four Windows archives from issue 1491
+ shell: pwsh
+ run: |
+ . ./scripts/ci/package_windows.ps1
+ $tools = Get-WindowsDistributionTools
+ # These immutable fixtures reproduce missing runtimes without Rust/V8 builds.
+ $fixtures = @{
+ '' = '0a110d0693753a252ed7ffd61e682363e8622caf79697f564c529099a31a6242'
+ '-stealth' = 'a32a26fc73fcc21850a67d9cd0d0cd7caf7b400a0e20aa91703126f0fc47c33f'
+ '-no-render' = 'a9b88f38eb1f1efdbbb0adf1f526140dbbd4866d01f35d3452f899f5eb7c4442'
+ '-no-render-stealth' = '11bb447a7b4b38e596cba8ec10754f46eb4dae55046b68cb09d82d4b2d4d32bf'
+ }
+ foreach ($suffix in $fixtures.Keys) {
+ $name = "obscura-x86_64-windows$suffix"
+ $archive = "$env:RUNNER_TEMP\$name.zip"
+ Invoke-WebRequest "https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.6/$name.zip" -OutFile $archive
+ if ((Get-FileHash $archive -Algorithm SHA256).Hash -ne $fixtures[$suffix]) { throw "Fixture checksum mismatch: $name" }
+ $stage = "$env:RUNNER_TEMP\$name"
+ Expand-Archive $archive $stage
+ try {
+ Resolve-WindowsDependencies $stage $tools.Dumpbin
+ throw 'Baseline unexpectedly has complete runtime distribution'
+ } catch {
+ if ($_.Exception.Message -notlike '*Unbundled non-system dependency*') { throw }
+ Write-Host "EXPECTED BASELINE FAILURE: $_"
+ }
+ New-WindowsPackage $stage "$env:RUNNER_TEMP\fixed-$name.zip"
+ }
diff --git a/README.md b/README.md
index 3302efca..0c0ae5c8 100644
--- a/README.md
+++ b/README.md
@@ -140,7 +140,8 @@ x86_64 Windows only (no 32-bit build).
Download `obscura-x86_64-windows.zip` from
[Releases](https://github.com/h4ckf0r0day/obscura/releases),
-extract it, and add the folder to your PATH. No C++ build tools are required.
+extract it, and add the folder to your PATH. Keep the bundled runtime DLLs beside
+both executables. No C++ build tools are required.
Alternatively, with [Scoop](https://scoop.sh/) installed:
diff --git a/scripts/ci/package_windows.ps1 b/scripts/ci/package_windows.ps1
new file mode 100644
index 00000000..ad10a9a3
--- /dev/null
+++ b/scripts/ci/package_windows.ps1
@@ -0,0 +1,172 @@
+param(
+ [string]$StageDirectory,
+ [string]$ArchivePath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Get-WindowsDistributionTools {
+ $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
+ $vs = & $vswhere -latest -products * -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath
+ if ($LASTEXITCODE -ne 0 -or !$vs) { throw 'MSVC installation not found' }
+ $tools = Get-ChildItem "$vs\VC\Tools\MSVC" -Directory |
+ Sort-Object { [version]$_.Name } -Descending | Select-Object -First 1
+ $redist = Get-ChildItem "$vs\VC\Redist\MSVC" -Directory |
+ Where-Object { $_.Name -match '^\d+\.\d+\.\d+$' } |
+ Sort-Object { [version]$_.Name } -Descending | Select-Object -First 1
+ $crt = @(Get-ChildItem "$($redist.FullName)\x64\Microsoft.VC*.CRT" -Directory)
+ if ($crt.Count -ne 1) { throw 'Expected one x64 MSVC release CRT directory' }
+ return @{
+ Dumpbin = Join-Path $tools.FullName 'bin\Hostx64\x64\dumpbin.exe'
+ Redist = $crt[0].FullName
+ }
+}
+
+function ConvertFrom-PeDependencies([string[]]$Output) {
+ $dependencies = @($Output | ForEach-Object {
+ # /DEPENDENTS includes ordinary and delay-load imports.
+ if ("$_" -match '^\s+(.+?\.dll)\s*$') {
+ $name = $Matches[1].ToLowerInvariant()
+ if ($name -notmatch '^[\w.-]+\.dll$') { throw "Invalid DLL import: $name" }
+ $name
+ }
+ } | Sort-Object -Unique)
+ if (!$dependencies.Count) { throw 'No DLL imports parsed' }
+ return $dependencies
+}
+
+function Get-PeDependencies([string]$Path, [string]$Dumpbin) {
+ $output = & $Dumpbin /DEPENDENTS $Path 2>&1
+ if ($LASTEXITCODE -ne 0) { throw "dumpbin failed for ${Path}: $output" }
+ $dependencies = @(ConvertFrom-PeDependencies $output)
+ Write-Host "DEPENDENTS ${Path}: $($dependencies -join ', ')"
+ return $dependencies
+}
+
+function Test-WindowsSystemDll([string]$Name) {
+ # Windows 10/11 supply the UCRT and API-set contracts, not the VC++ runtime.
+ return $Name -match '^(api-ms-win-|ext-ms-win-)[\w.-]+\.dll$' -or $Name -in @(
+ 'advapi32.dll', 'bcrypt.dll', 'bcryptprimitives.dll', 'crypt32.dll',
+ 'dbghelp.dll', 'gdi32.dll', 'iphlpapi.dll', 'kernel32.dll', 'kernelbase.dll',
+ 'msvcrt.dll', 'ncrypt.dll', 'ntdll.dll', 'ole32.dll', 'oleaut32.dll',
+ 'powrprof.dll', 'propsys.dll', 'rpcrt4.dll', 'secur32.dll', 'shell32.dll',
+ 'shlwapi.dll', 'ucrtbase.dll', 'user32.dll', 'userenv.dll', 'version.dll',
+ 'winhttp.dll', 'winmm.dll', 'ws2_32.dll'
+ )
+}
+
+function Resolve-WindowsDependencies([string]$Directory, [string]$Dumpbin, [string]$Redist = '') {
+ foreach ($name in @('obscura.exe', 'obscura-worker.exe')) {
+ if (!(Test-Path -LiteralPath (Join-Path $Directory $name) -PathType Leaf)) {
+ throw "Missing packaged executable: $name"
+ }
+ }
+ $queue = [Collections.Generic.Queue[string]]::new()
+ Get-ChildItem -LiteralPath $Directory -File | Where-Object Extension -in '.exe', '.dll' |
+ ForEach-Object { $queue.Enqueue($_.FullName) }
+ $visited = [Collections.Generic.HashSet[string]]::new([StringComparer]::OrdinalIgnoreCase)
+ while ($queue.Count) {
+ $path = $queue.Dequeue()
+ if (!$visited.Add($path)) { continue }
+ foreach ($name in @(Get-PeDependencies $path $Dumpbin)) {
+ $local = Join-Path $Directory $name
+ if (Test-Path -LiteralPath $local -PathType Leaf) {
+ $queue.Enqueue($local)
+ } elseif (Test-WindowsSystemDll $name) {
+ continue
+ } elseif ($Redist -and $name -match '^(vcruntime140(?:_\d+)?|msvcp140(?:_\w+)?|concrt140)\.dll$') {
+ # Only Microsoft's release redistributables, never System32 or debug DLLs.
+ # https://learn.microsoft.com/cpp/windows/redistributing-visual-cpp-files
+ $source = Join-Path $Redist $name
+ if (!(Test-Path -LiteralPath $source -PathType Leaf)) { throw "Redistributable missing: $name" }
+ Copy-Item -LiteralPath $source -Destination $local
+ Write-Host "APP-LOCAL $source -> $local"
+ $queue.Enqueue($local)
+ } else {
+ throw "Unbundled non-system dependency: $name (from $path)"
+ }
+ }
+ }
+}
+
+function Test-WindowsPackageStartup([string]$Directory) {
+ # These are runner smoke tests, not evidence of a clean Windows installation.
+ foreach ($name in @('obscura.exe', 'obscura-worker.exe')) {
+ $info = [Diagnostics.ProcessStartInfo]::new((Join-Path $Directory $name))
+ $info.UseShellExecute = $false
+ $info.RedirectStandardInput = $true
+ $info.RedirectStandardOutput = $true
+ $info.RedirectStandardError = $true
+ $info.CreateNoWindow = $true
+ $info.WorkingDirectory = $Directory
+ if ($name -eq 'obscura.exe') {
+ foreach ($arg in @('fetch', 'data:text/html,<title>runtime</title>', '--eval', '1+1')) {
+ $info.ArgumentList.Add($arg)
+ }
+ }
+ $process = [Diagnostics.Process]::Start($info)
+ $stderr = $process.StandardError.ReadToEndAsync()
+ if ($name -eq 'obscura-worker.exe') {
+ $process.StandardInput.WriteLine('{"cmd":"navigate","url":"data:text/html,<title>runtime</title>"}')
+ $process.StandardInput.WriteLine('{"cmd":"evaluate","expression":"1+1"}')
+ $responses = @(foreach ($index in 0..1) {
+ $line = $process.StandardOutput.ReadLineAsync()
+ if (!$line.Wait(60000)) {
+ $process.Kill($true)
+ throw 'Worker response timed out'
+ }
+ $line.GetAwaiter().GetResult() | ConvertFrom-Json
+ })
+ # Keep stdin open while checking the live process. A successful
+ # launch alone could have used a CRT already installed on the runner.
+ $modules = @($process.Modules)
+ foreach ($dll in Get-ChildItem -LiteralPath $Directory -Filter '*.dll') {
+ $loaded = @($modules | Where-Object ModuleName -eq $dll.Name)
+ if ($loaded.Count -ne 1 -or $loaded[0].FileName -ne $dll.FullName) {
+ throw "Worker did not load app-local $($dll.Name)"
+ }
+ Write-Host "LOADED APP-LOCAL $($loaded[0].FileName)"
+ }
+ }
+ $stdout = $process.StandardOutput.ReadToEndAsync()
+ $process.StandardInput.Close()
+ if (!$process.WaitForExit(60000)) {
+ $process.Kill($true)
+ throw "$name startup timed out"
+ }
+ $out = $stdout.GetAwaiter().GetResult()
+ $err = $stderr.GetAwaiter().GetResult()
+ if ($process.ExitCode -ne 0) { throw "$name exited $($process.ExitCode): $err" }
+ if ($name -eq 'obscura-worker.exe') {
+ if ($responses.Count -ne 2 -or $responses[0].ok -ne $true -or
+ $responses[1].ok -ne $true -or $responses[1].result -ne 2) {
+ throw "Worker runtime smoke failed: $($responses | ConvertTo-Json -Compress) $err"
+ }
+ } elseif (($out | ConvertFrom-Json) -ne 2) { throw "CLI runtime smoke failed: $out $err" }
+ Write-Host "STARTUP PASS $name"
+ $process.Dispose()
+ }
+}
+
+function New-WindowsPackage([string]$Directory, [string]$Archive) {
+ $Directory = (Resolve-Path -LiteralPath $Directory).Path
+ $tools = Get-WindowsDistributionTools
+ Resolve-WindowsDependencies $Directory $tools.Dumpbin $tools.Redist
+ if (Test-Path -LiteralPath $Archive) { throw "Archive already exists: $Archive" }
+ Compress-Archive -Path "$Directory\*" -DestinationPath $Archive
+ $extract = Join-Path ([IO.Path]::GetTempPath()) ([Guid]::NewGuid().ToString())
+ try {
+ Expand-Archive -LiteralPath $Archive -DestinationPath $extract
+ # Verification cannot consult the redist directory or the runner's PATH.
+ Resolve-WindowsDependencies $extract $tools.Dumpbin
+ Test-WindowsPackageStartup $extract
+ } finally {
+ if (Test-Path -LiteralPath $extract) { Remove-Item -LiteralPath $extract -Recurse -Force }
+ }
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+ if (!$StageDirectory -or !$ArchivePath) { throw 'StageDirectory and ArchivePath are required' }
+ New-WindowsPackage $StageDirectory $ArchivePath
+}
diff --git a/scripts/ci/test_package_windows.ps1 b/scripts/ci/test_package_windows.ps1
new file mode 100644
index 00000000..4b3cd6e0
--- /dev/null
+++ b/scripts/ci/test_package_windows.ps1
@@ -0,0 +1,63 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+. "$PSScriptRoot/package_windows.ps1"
+
+function Assert-Fails([scriptblock]$Action, [string]$Expected) {
+ try { & $Action } catch {
+ if ($_.Exception.Message -notlike "*$Expected*") { throw }
+ return
+ }
+ throw "Expected failure containing: $Expected"
+}
+
+$parsed = @(ConvertFrom-PeDependencies @(
+ ' KERNEL32.dll', ' Image has the following delay load dependencies:',
+ ' VCRUNTIME140_1.dll', ' 1000 .rdata', ' KERNEL32.dll'
+))
+if ($parsed.Count -ne 2 -or $parsed -notcontains 'vcruntime140_1.dll') { throw 'Import parser failed' }
+Assert-Fails { ConvertFrom-PeDependencies @('unrecognized dumpbin output') } 'No DLL imports'
+Assert-Fails { ConvertFrom-PeDependencies @(' ..\outside.dll') } 'Invalid DLL import'
+foreach ($name in @('kernel32.dll', 'ucrtbase.dll', 'api-ms-win-crt-runtime-l1-1-0.dll')) {
+ if (!(Test-WindowsSystemDll $name)) { throw "System DLL rejected: $name" }
+}
+foreach ($name in @('vcruntime140.dll', 'vcruntime140_1.dll', 'msvcp140.dll', 'unknown.dll')) {
+ if (Test-WindowsSystemDll $name) { throw "Non-system DLL accepted: $name" }
+}
+
+# Model transitive imports independently of DLLs preinstalled on the runner.
+function Get-PeDependencies([string]$Path, [string]$Dumpbin) {
+ return $script:imports[[IO.Path]::GetFileName($Path)]
+}
+$root = Join-Path $env:RUNNER_TEMP ([Guid]::NewGuid().ToString())
+$stage = Join-Path $root 'stage'
+$redist = Join-Path $root 'redist'
+New-Item -ItemType Directory -Path $stage, $redist | Out-Null
+foreach ($name in @('obscura.exe', 'obscura-worker.exe')) { Set-Content (Join-Path $stage $name) 'fixture' }
+foreach ($name in @('msvcp140.dll', 'vcruntime140.dll', 'vcruntime140_1.dll')) {
+ Set-Content (Join-Path $redist $name) 'redistributable fixture'
+}
+$script:imports = @{
+ 'obscura.exe' = @('kernel32.dll', 'msvcp140.dll')
+ 'obscura-worker.exe' = @('kernel32.dll', 'vcruntime140_1.dll')
+ 'msvcp140.dll' = @('vcruntime140.dll', 'vcruntime140_1.dll')
+ 'vcruntime140.dll' = @('kernel32.dll', 'api-ms-win-crt-runtime-l1-1-0.dll')
+ 'vcruntime140_1.dll' = @('vcruntime140.dll')
+}
+Assert-Fails { Resolve-WindowsDependencies $stage 'unused' } 'Unbundled non-system dependency'
+Resolve-WindowsDependencies $stage 'unused' $redist
+Resolve-WindowsDependencies $stage 'unused'
+$script:imports['vcruntime140.dll'] += 'vcruntime140_1.dll'
+Resolve-WindowsDependencies $stage 'unused'
+foreach ($name in @('msvcp140.dll', 'vcruntime140.dll', 'vcruntime140_1.dll')) {
+ if (!(Test-Path (Join-Path $stage $name))) { throw "Transitive runtime missing: $name" }
+}
+Remove-Item (Join-Path $stage 'vcruntime140.dll')
+Assert-Fails { Resolve-WindowsDependencies $stage 'unused' } 'vcruntime140.dll'
+Resolve-WindowsDependencies $stage 'unused' $redist
+$script:imports['vcruntime140.dll'] = @('unexpected.dll')
+Assert-Fails { Resolve-WindowsDependencies $stage 'unused' $redist } 'unexpected.dll'
+$script:imports['vcruntime140.dll'] = @('vcruntime140d.dll')
+Assert-Fails { Resolve-WindowsDependencies $stage 'unused' $redist } 'vcruntime140d.dll'
+Remove-Item (Join-Path $stage 'obscura-worker.exe')
+Assert-Fails { Resolve-WindowsDependencies $stage 'unused' } 'Missing packaged executable'
+Write-Host 'Windows packaging helper regression checks passed'