# gucci-on-fleek/lockdown-browser architecture

> Architecture diagram of the GitHub repository gucci-on-fleek/lockdown-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gucci-on-fleek/lockdown-browser
- Repository: https://github.com/gucci-on-fleek/lockdown-browser

## Overview

1. **Repository purpose**
   - This is a Windows-only proof-of-concept that lets the Respondus LockDown Browser run inside **Windows Sandbox** by altering the browser’s environment and intercepting one Windows API call.
   - The architecture is split between **build-time tooling on the host** and **runtime components inside the sandbox**.

2. **Top-level subsystem layout**
   - `src/` contains the actual bypass code and sandbox configuration files.
   - `runtime_directory/` is the launch/runtime payload that gets copied into the sandbox and used to start the browser.
   - `Detours/` is an external submodule used to hook a Windows DLL function.
   - `build.ps1` assembles everything into a runnable package.

3. **Host-side build pipeline**
   - `build.ps1` is the orchestration entrypoint for compiling the hook and preparing the runtime bundle.
   - The build depends on **Visual Studio C++ toolchain** and the **Windows SDK**.
   - The host never runs the target browser directly; it prepares files that will later execute inside the sandbox boundary.

4. **Sandbox boundary**
   - The core isolation boundary is **Windows Sandbox**, which acts as the execution environment for the browser.
   - The repo’s design assumes the browser runs only inside that ephemeral VM-like container, so no persistent state is retained between sessions.
   - Two `.wsb` launch configurations exist: one standard and one that also passes **microphone/camera** devices through.

5. **Runtime launcher layer**
   - `runtime_directory/sandbox_run.ps1` is the main sandbox-side bootstrap script.
   - It performs environment preparation before starting the browser, including removing or obscuring artifacts that the browser uses for virtualization checks.
   - This script is the primary coordination point between the sandbox config and the browser launch.

6. **Environment suppression logic**
   - One bypass mechanism is registry cleanup under `HKLM:\HARDWARE\DESCRIPTION`, which removes BIOS-related indicators the browser checks.
   - Another is handling process detection of `VmComputeAgent.exe` by deleting the image file so the browser’s process inspection sees nothing meaningful.
   - These actions happen inside the sandbox and are meant to change what the browser can observe about its environment.

7. **API hook subsystem**
   - `src/GetSystemMetrics-Hook.cpp` implements a small DLL hook for `GetSystemMetrics(SM_REMOTESESSION)`.
   - This is used to stop the browser from detecting an RDP-like / remote-session condition.
   - The hook is injected with help from **Microsoft Detours**, which supplies the detouring framework and is vendored as a submodule.

8. **Browser launch path**
   - The actual Respondus browser executable is **not included in the repo**; the user must supply it in `runtime_directory/`.
   - The sandbox launcher and runtime scripts assume that binary is present and then start it after the environment patches and hook injection are in place.
   - This creates a simple flow: sandbox starts → bootstrap script prepares environment → hook is applied → browser launches.

9. **Installer and packaging**
   - `runtime_directory/setup.iss` indicates an installer-style packaging step for staging the runtime directory contents.
   - The repo is structured to produce a self-contained sandbox payload rather than a traditional installable application on the host.
   - `runtime_directory/` is effectively the deployment artifact boundary.

10. **Documentation and operational modes**
   - `Readme.md` documents the supported launch variants, troubleshooting, and the distinction between the release/master/dev branches.
   - `docs/Example_1.webm` is a demo artifact only; it does not affect runtime architecture.
   - The repo’s architecture is intentionally minimal: one build script, one hook DLL, one sandbox bootstrap script, and one sandbox configuration layer.

11. **External dependencies that materially shape the design**
   - **Windows Sandbox** is the execution platform and is central to the threat model.
   - **Microsoft Detours** is the enabling technology for DLL/API interception.
   - **Respondus LockDown Browser** is the external target binary the whole pipeline is built around.

12. **High-level data/control flow**
   - Source code and scripts are built on the host.
   - The resulting runtime files are placed into a shared sandbox directory.
   - Windows Sandbox boots using a `.wsb` file, runs the PowerShell bootstrap, applies the hook, and launches the supplied browser executable.
   - The browser runs isolated from the host, while the hook and environment changes influence the browser only within the sandbox boundary.

Main entry points: [`build.ps1`](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/build.ps1) (Build script), [`runtime_directory/sandbox_run.ps1`](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/runtime_directory/sandbox_run.ps1) (Bootstrap), [`Readme.md`](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/Readme.md) (Readme), [`src/GetSystemMetrics-Hook.cpp`](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/GetSystemMetrics-Hook.cpp) (Metrics hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_host["Host build"]
  node_n_build["Build script<br/>PowerShell orchestrator<br/>[build.ps1]"]
  node_n_toolchain["VS toolchain<br/>C++ build deps"]
end

subgraph group_grp_runtime["Sandbox runtime"]
  node_n_runtime_dir["Runtime bundle<br/>sandbox payload"]
  node_n_wsb_std["Sandbox config<br/>WSB launch config<br/>[Sandbox.xml]"]
  node_n_wsb_audio["A/V config<br/>WSB launch config"]
  node_n_bootstrap["Bootstrap<br/>PowerShell launcher<br/>[sandbox_run.ps1]"]
  node_n_env_suppress["Env cleanup<br/>sandbox prep"]
  node_n_registry["Registry cleanup<br/>HKLM suppression"]
  node_n_vmcompute["VmComputeAgent<br/>process artifact"]
  node_n_hook_dll["Metrics hook<br/>DLL hook"]
  node_n_setup["Installer script<br/>Inno Setup<br/>[setup.iss]"]
end

subgraph group_grp_target["External target"]
  node_n_detours["Detours<br/>hooking framework"]
  node_n_sandbox[("Windows Sandbox<br/>execution boundary")]
  node_n_browser["Browser<br/>target executable"]
end

subgraph group_grp_docs["Docs"]
  node_n_readme["Readme<br/>documentation<br/>[Readme.md]"]
  node_n_demo["Demo video<br/>media artifact<br/>[Example_1.webm]"]
end

node_n_build -->|"requires"| node_n_toolchain
node_n_build -->|"builds"| node_n_hook_dll
node_n_build -->|"assembles"| node_n_runtime_dir
node_n_build -->|"links"| node_n_detours
node_n_setup -->|"packages"| node_n_runtime_dir
node_n_wsb_std -->|"boots"| node_n_sandbox
node_n_wsb_audio -->|"boots"| node_n_sandbox
node_n_sandbox -->|"runs"| node_n_bootstrap
node_n_bootstrap -->|"prepares"| node_n_env_suppress
node_n_env_suppress -->|"cleans"| node_n_registry
node_n_env_suppress -->|"obscures"| node_n_vmcompute
node_n_bootstrap -->|"loads"| node_n_hook_dll
node_n_hook_dll -->|"uses"| node_n_detours
node_n_bootstrap -->|"launches"| node_n_browser
node_n_browser -->|"contained by"| node_n_sandbox
node_n_readme -.->|"documents"| node_n_wsb_std
node_n_readme -.->|"documents"| node_n_wsb_audio
node_n_readme -.->|"documents"| node_n_build
node_n_demo -.->|"illustrates"| node_n_readme

click node_n_build "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/build.ps1"
click node_n_runtime_dir "https://github.com/gucci-on-fleek/lockdown-browser/tree/release/runtime_directory"
click node_n_wsb_std "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/Sandbox.xml"
click node_n_wsb_audio "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/Sandbox-with-Microphone-Camera.xml"
click node_n_bootstrap "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/runtime_directory/sandbox_run.ps1"
click node_n_hook_dll "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/GetSystemMetrics-Hook.cpp"
click node_n_detours "https://github.com/gucci-on-fleek/lockdown-browser/tree/release/Detours"
click node_n_browser "https://github.com/gucci-on-fleek/lockdown-browser/tree/release/runtime_directory"
click node_n_setup "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/runtime_directory/setup.iss"
click node_n_readme "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/Readme.md"
click node_n_demo "https://github.com/gucci-on-fleek/lockdown-browser/blob/release/docs/Example_1.webm"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_build,node_n_toolchain toneBlue
class node_n_runtime_dir,node_n_wsb_std,node_n_wsb_audio,node_n_bootstrap,node_n_env_suppress,node_n_registry,node_n_vmcompute,node_n_hook_dll,node_n_setup toneAmber
class node_n_detours,node_n_sandbox,node_n_browser toneMint
class node_n_readme,node_n_demo toneRose
```

## Components

### Host build

Build-time tooling and assembly on the Windows host.

- [Build script](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/build.ps1): PowerShell orchestrator · Assembles the hook DLL and runtime payload into a runnable package. · `build.ps1`
- **VS toolchain**: C++ build deps · Visual Studio C++ compiler and Windows SDK required to compile the hook.

### Sandbox runtime

Files and scripts that execute inside Windows Sandbox.

- [Runtime bundle](https://github.com/gucci-on-fleek/lockdown-browser/tree/release/runtime_directory): sandbox payload · Deployment boundary copied into the sandbox and used to launch the target browser. · `runtime_directory`
- [Sandbox config](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/Sandbox.xml): WSB launch config · Standard Windows Sandbox launch configuration. · `src/Sandbox.xml`
- [A/V config](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/Sandbox-with-Microphone-Camera.xml): WSB launch config · Windows Sandbox launch configuration that passes microphone and camera devices. · `src/Sandbox-with-Microphone-Camera.xml`
- [Bootstrap](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/runtime_directory/sandbox_run.ps1): PowerShell launcher · Prepares the sandbox environment and starts the browser inside the sandbox. · `runtime_directory/sandbox_run.ps1`
- **Env cleanup**: sandbox prep · Removes or obscures environment artifacts used for virtualization and VM checks.
- **Registry cleanup**: HKLM suppression · Cleans BIOS-related indicators under HKLM:\HARDWARE\DESCRIPTION.
- **VmComputeAgent**: process artifact · Deletes the image file so process inspection sees no useful VM agent artifact.
- [Metrics hook](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/src/GetSystemMetrics-Hook.cpp): DLL hook · Intercepts GetSystemMetrics(SM_REMOTESESSION) to suppress remote-session detection. · `src/GetSystemMetrics-Hook.cpp`
- [Installer script](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/runtime_directory/setup.iss): Inno Setup · Packaging script for staging the runtime directory contents. · `runtime_directory/setup.iss`

### External target

Supplied browser and platform dependencies the repo is built around.

- [Detours](https://github.com/gucci-on-fleek/lockdown-browser/tree/release/Detours): hooking framework · Vendored Microsoft Detours submodule used to inject the API hook. · `Detours`
- **Windows Sandbox**: execution boundary · Ephemeral VM-like environment that isolates the browser run from the host.
- [Browser](https://github.com/gucci-on-fleek/lockdown-browser/tree/release/runtime_directory): target executable · Respondus LockDown Browser binary supplied by the user at runtime. · `runtime_directory`

### Docs

Documentation and demo material.

- [Readme](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/Readme.md): documentation · Documents launch variants, troubleshooting, and branch usage. · `Readme.md`
- [Demo video](https://github.com/gucci-on-fleek/lockdown-browser/blob/release/docs/Example_1.webm): media artifact · Example recording used for illustration only. · `docs/Example_1.webm`

## Connections

- Build script → VS toolchain: requires · Compilation depends on the Visual Studio C++ toolchain and Windows SDK.
- Build script → Metrics hook: builds · Produces the hook DLL from source.
- Build script → Runtime bundle: assembles · Stages the runtime payload for sandbox execution.
- Build script → Detours: links · Uses Detours to support API interception.
- Installer script → Runtime bundle: packages · Stages runtime directory contents for deployment.
- Sandbox config → Windows Sandbox: boots · Launches the standard sandbox session.
- A/V config → Windows Sandbox: boots · Launches the sandbox session with microphone/camera passthrough.
- Windows Sandbox → Bootstrap: runs · Starts the bootstrap script inside the sandbox boundary.
- Bootstrap → Env cleanup: prepares · Coordinates environment changes before browser launch.
- Env cleanup → Registry cleanup: cleans · Removes BIOS indicators from registry keys.
- Env cleanup → VmComputeAgent: obscures · Deletes the VmComputeAgent image artifact.
- Bootstrap → Metrics hook: loads · Ensures the hook is applied before launch.
- Metrics hook → Detours: uses · Relies on Detours to install the GetSystemMetrics hook.
- Bootstrap → Browser: launches · Starts the supplied browser executable after preparation.
- Browser → Windows Sandbox: contained by · Runs only inside Windows Sandbox.
- Readme → Sandbox config: documents · Explains the standard launch mode.
- Readme → A/V config: documents · Explains the audio/video passthrough launch mode.
- Readme → Build script: documents · Covers build and packaging workflow.
- Demo video → Readme: illustrates · Provides an example of the workflow in action.
