Open source

repo-quarantine

A host-side shell toolkit that clones and runs an untrusted repository inside a disposable VirtualBox VM, as a non-sudo runner user, and restores a clean-base snapshot after every run. One guarantee, honestly stated: your host filesystem stays out of reach, and every run is thrown away.

View repo-quarantine on GitHub

The problem

You want to read a repository you don't trust. Maybe it's a dependency you're evaluating, a takehome you've been sent, or a proof-of-concept from a stranger. Cloning it is already a decision: npm install, go generate, a Makefile, or an editor plugin can execute code before you've read a line of it. The usual answer — "just look at it first" — does not survive contact with a build step.

repo-quarantine moves that first contact off your machine. The repository is cloned and run inside a VirtualBox VM that is reset to a known-clean snapshot after every single run, so nothing a repo does can persist and nothing it does can reach your host's disk.

What it guarantees

Exactly one thing, and it is worth stating precisely because security tools are usually oversold:

  • A host-filesystem boundary with disposable rollback. The untrusted code runs in a VM, as an unprivileged runner user with no sudo. When the run finishes, the VM is rolled back to a clean-base snapshot, so any change the repo made — files, packages, persistence, cron entries — is discarded.

That is the whole promise. Everything below is a limit on it.

What it does not do

  • The network is not isolated. The VM can reach the internet, so code inside it can exfiltrate anything it can read. Therefore: nothing secret may ever enter the VM. No credentials, no tokens, no SSH keys, no .env, no private repositories. Treat everything you put inside as already published.
  • A clean run proves nothing about the code. Malicious code can detect a VM, wait, target a different architecture, or simply do nothing on the first execution. "It ran and nothing happened" is not a verdict. This buys you a safe place to look — it does not do the looking.
  • It does not defend against hypervisor escapes. The boundary is VirtualBox. If an attacker holds a VirtualBox escape, this toolkit is not what stops them. It is built for opportunistic and careless code, not a targeted attacker spending an 0-day on you.

How it works

Three steps. The first two happen once; the third repeats for every repository you look at.

  1. Harden once. Run vm-harden.sh against a fresh VM. It creates the non-sudo runner user and strips the VM down to the state you want every run to start from.
  2. Capture a baseline. Run vm-cycle.sh --snapshot to record that hardened state as the clean-base snapshot. This is the point every future run returns to.
  3. Cycle per repo. For each untrusted repository, run vm-cycle.sh. It clones the repo into the VM, runs it as runner, and restores the clean-base snapshot afterwards. The next repo starts from the same known state as the first.

The scripts run on the host. There is nothing to install inside the VM beyond what hardening puts there, and no agent, daemon, or account to sign up for.

Who it's for

Anyone who reads other people's code and would rather not run it on their laptop: engineers evaluating dependencies, reviewers opening takehome submissions, and researchers triaging samples that are probably boring and occasionally not. It is a small amount of shell that makes "I'll just clone it and see" a survivable sentence.

It is open source and lives on GitHub. Read the scripts before you trust them — that is, after all, the entire point.

github.com/pigfox/repo-quarantine

Related: the Prompt-Injection & System-Prompt-Leak Tester applies the same instinct to LLM systems — assume the input is hostile and bound what it can reach. More on how I build and secure production systems in AI engineering, or get in touch.