Give the scan
its own boundary.

Docker: use the signed release image

Docker mode is opt-in. Start Docker Desktop on macOS or Windows, or Docker Engine on Linux, and verify the daemon responds to docker version. Each GitHub release includes repyy-sandbox-image.txt with the exact image reference and digest. Run repyy version, open the matching release, and use its published digest. Do not substitute mutable latest.

Verify the image signature

The release workflow signs and verifies the image with Sigstore Cosign. Replace the placeholders with the matching release values:

cosign verify 'ghcr.io/kevin-umali/repyy-sandbox@sha256:<published-digest>' --certificate-identity 'https://github.com/Kevin-Umali/repyy/.github/workflows/release.yml@refs/tags/v<version>' --certificate-oidc-issuer https://token.actions.githubusercontent.com

Verify the binary’s signed checksum and image signature separately. A missing daemon or pinned image is a preflight error; repyy never silently falls back to host mode.

Docker with a local folder

repyy mounts the input read-only into a temporary analysis container, disables networking, and writes bounded JSON back to the host. The host validates the result and writes the final report.

Keep output in a narrow directory and treat it as sensitive local review data.

Docker with an HTTPS remote

An HTTPS remote uses a disposable networked fetch stage for a shallow clone. A separate analysis stage has no Git credentials and no network. The host validates the bounded result before rendering the report.

Private HTTPS access uses GITHUB_TOKEN, GITLAB_TOKEN, or BITBUCKET_TOKEN from the scanner environment. Tokens do not enter the clone URL or report. Docker rejects SSH URLs.

Know the edge cases

For multiple targets, one failed target remains visible as SCAN INCOMPLETE while successful targets retain their findings.

Manual VM workflows

Install repyy in the guest before introducing the repository. Copy the repository into the guest or expose a narrow read-only share. Disable guest networking for local analysis, write only the report to a separate writable output location, and destroy the guest or discard its snapshot afterward. These workflows do not enable --sandbox=vm or --sandbox=auto.

Windows Sandbox

Windows Sandbox is available on supported Pro, Enterprise, and Education editions; Windows Home does not include it. Enable it from “Turn Windows features on or off”. See Microsoft’s requirements ↗.

1. Create C:\review\input\repo and C:\review\output on the host.
2. Put the repository under repo and verified repyy.exe in C:\review\input.
3. Save the following as repyy-review.wsb, then double-click it to launch the sandbox.

<Configuration>
  <MappedFolders>
    <MappedFolder>
      <HostFolder>C:\review\input</HostFolder>
      <SandboxFolder>C:\review\input</SandboxFolder>
      <ReadOnly>true</ReadOnly>
    </MappedFolder>
    <MappedFolder>
      <HostFolder>C:\review\output</HostFolder>
      <SandboxFolder>C:\review\output</SandboxFolder>
      <ReadOnly>false</ReadOnly>
    </MappedFolder>
  </MappedFolders>
  <Networking>Disable</Networking>
</Configuration>

Inside the sandbox, run:

& C:\review\input\repyy.exe version
& C:\review\input\repyy.exe scan C:\review\input\repo --format html --output C:\review\output\report.html

4. Copy C:\review\output\report.html out after the scan completes.
5. Close the sandbox; its writable state is discarded.

Do not map credentials, SSH directories, package caches, or a broad home directory.

macOS with UTM

Create a disposable Linux VM in UTM ↗ and install repyy in the guest first.

1. Remove the Network device for local analysis; a host-only network still permits guest-to-host traffic.
2. Attach only a dedicated input directory or read-only disk image, then check the guest mount flags.
3. Run the scan with the report on the guest’s writable disk:

repyy scan /mnt/review --format html --output "$HOME/report.html"

4. Copy out only the finished report through a separate temporary output disk or explicit copy step.
5. Shut down and delete the disposable VM after review.

For a remote HTTPS URL, fetch in a separate networked VM and transfer only the checkout to the network-disabled analysis VM.

Linux with QEMU/KVM

Create a disposable QEMU/KVM guest with your distribution’s normal cloud image or VM tooling.

1. Attach a dedicated repository directory as a read-only 9p, virtiofs, or ISO share.
2. Keep report output on a separate writable share and disable networking for local analysis.
3. Run the scan:

repyy scan /mnt/review --format html --output /mnt/output/report.html

4. Export only the finished report.
5. Remove the temporary disk or snapshot.

For an HTTPS remote, clone in a disposable networked guest, shut it down, and transfer only the checkout into the analysis guest. Do not attach the host Docker socket, home directory, SSH agent, or package-manager cache.