Nullgap.dev Docs

Security and privacy

The sandbox

Where proofs and fix verification run, how each command is isolated, and what a sandboxed command can and cannot reach.

To prove a finding or to check a fix, Nullgap has to run code: a probe that Nullgap AI wrote, or your project's own tests. That code is treated as untrusted, whoever wrote it. It runs in the sandbox: a fresh, disposable container for every command, with no network and nothing of the service in reach.

This page lists the isolation properties as the product sets them, what runs there, and where the limits are. It describes what the product does and what its tests check. It is not a certification and not the result of an independent audit.

#What runs in the sandbox

WhatWhenWho wrote the code
A proof probeWhen a review or a pentest reproduces a finding in your codeNullgap AI
The probe again, after a fixWhen a fix is verified: the probe that reproduced the flaw must no longer succeedNullgap AI
Your project's test commandAfter a fix, when your repository declares one (testCommand in .nullgap/config.json)You
Dependency installationOnly where it is switched on for the service: once per run, at the start, for the probes and tests that need your dependenciesPackage managers and your lockfile
A compile checkAt the start of a pentest, after the dependencies are installed: the code in scope is compiled, with no network, to find out whether it builds in the sandbox at all. See the proof environmentYour build, run by its own build tool
A throw-away database or cacheInside a probe's own container, when your application needs one to start. See Services a proof needsThe database's authors; it holds only what the probe puts in
Lockfile regenerationDuring a dependency fixThe package manager
A tool a skill calls, when the tool executes something: a scanner, a decompilerDuring a review, a pentest or an on-demand skill runThe tool's authors; it reads your code

What does not run in the sandbox:

  • Reading your code. Reviews and pentests read the checkout directly; reading does not execute anything from it.
  • Live testing. Requests to your running application are sent to the hosts on your scope list. That is network traffic to a system you chose, not code execution, and it is governed by the scope rules on that page.

For what a proof is and what "proven" means, see proof and verified fixes.

#Isolation of each command

Every command gets a new container, which is removed when the command ends. Nothing carries over from one command to the next except the working copy.

PropertySettingWhat it means
NetworkNoneThe container has only its own loopback interface. A probe can start a local server and call it; nothing else is reachable. The one exception is described below
Root file systemRead-onlyThe command cannot change the image it runs in
CapabilitiesAll droppedNo privileged kernel operations
Privilege escalationBlocked (no-new-privileges)A setuid binary cannot gain privileges
System callsAn allow-list (seccomp), stricter than the container engine's defaultSee the system-call filter
UserNon-rootThe command runs as an unprivileged user
Processes256 at most, by defaultA fork bomb hits the limit
Memory1 GiB by default, with swap disabledA runaway process is killed
CPU2 cores by default
FilesAt most 8,192 open files; one file at most 2 GiB; core dumps offA crash cannot write a process's memory into the working copy
Shared memory and IPCIts own, with shared memory capped at 64 MiBNothing is shared with another container
OutputKept up to a cap per stream; the rest is dropped as it arrivesA command that prints without end cannot fill the service's memory or disk
Temporary space/tmp is an in-memory file system, 256 MiB by default, mounted without setuid and device filesGone when the container ends
Writable storageOne mount: the working copy, at /workspaceNothing else on the host is mounted
EnvironmentOnly HOME, CI and NODE_ENV, plus proxy settings for the install stepNo variable of the service reaches the command: no keys, tokens or connection strings
TimeA wall-clock limit per command, 120 seconds by default, enforced twice: from outside the container and by a timer inside itA command cannot outlive its limit even if the process that started it dies
Clean-upEvery container carries a deadline. A watchdog removes anything past it, when the service starts and every minute afterA container that survived both timers is still removed

The resource figures are the product's defaults; the service may run with other values for memory, CPU, temporary space and time, and sets them separately for the dependency-install step (which unpacks a whole dependency tree once per run) and for proofs. The isolation properties (network, read-only root, capabilities, privilege escalation, the system-call filter, the user) and the mount and environment rules are fixed. Configuration that would weaken them (extra privileges, capabilities, devices, mounts, host namespaces, environment variables, a different user or network, an unfiltered system-call profile) is refused by the product.

The working copy is a scratch copy of your checkout made for the run. The sandbox refuses to mount a directory outside the service's temporary storage.

#The system-call filter

A container asks the operating system kernel for everything it does, through system calls. The sandbox allows a fixed list and refuses the rest. Compared with a container engine's usual default, the list leaves out, among others:

  • tracing and reading other processes' memory;
  • mounting file systems and changing the root;
  • creating or joining namespaces;
  • kernel features with a history of security flaws that ordinary programs do not need, such as loading programs into the kernel, performance monitoring and asynchronous I/O rings;
  • 32-bit system calls;
  • every kind of socket except local sockets and ordinary internet sockets: no raw packets, no packet capture.

A call that is not on the list fails; the command keeps running. The filter can be relaxed to the container engine's own default by whoever operates the service. It can never be switched off.

#A stronger runtime, where the service has one

Where the machine that runs the containers offers a sandboxed container runtime (one that handles system calls in a user-space kernel, or one that gives each container its own small virtual machine), the sandbox uses it for every run. Whether your service has one is a matter of how it is operated: ask Nullgap. Without one, the properties on this page are what isolates a command.

#What the sandbox cannot reach

A sandboxed command cannot reach:

  • The internet or your network. There is no network interface besides loopback. A probe cannot call out, download anything, or send your code anywhere.
  • Your running systems. A proof in the sandbox exercises your code locally. It never touches your staging or production hosts.
  • The service's secrets. The service's environment is not passed in, and the stored credentials of your integrations and code hosts are never mounted or passed to a command.
  • The database. No network path and no mounted file leads to it.
  • Other working copies. Only the working copy of the run is mounted, so a command cannot read another run's files, yours or anyone else's.
  • The container engine. Its control socket is not exposed inside the container.

What a command can do is read and write its own working copy. That is by design: a fix is produced there. The result is read back by Nullgap, turned into a patch, and offered to you as a pull request. A fix is never pushed straight to one of your branches.

#The one step that has a network

Running your tests or a probe that imports your dependencies needs those dependencies. Fetching them needs a network. Nullgap keeps this to one step:

  • Only the install command gets a network, and only for the lifetime of that one container. Probes, tests and every command written by Nullgap AI always run with no network.
  • That network reaches the package registries of the project's ecosystem and nothing else. The install container sits on a private network made for that one run, with no route out. Its only neighbour is a proxy that opens encrypted connections to a fixed list of registry hosts (for example the public npm registry for npm, the Python package index for pip, the Go module proxy, its download storage and the Go checksum database for Go) and refuses every other name. The lists are tested against the real registries: a real project per ecosystem is installed through the proxy, and the test fails if anything was refused. The install cannot go around it by ignoring its proxy settings or resolving names itself: the limit is the network, not a setting inside the container.
  • If that network or the proxy cannot be set up, the install does not run. It is never given an open network instead.
  • Install scripts are off. Packages are fetched from your lockfile with the package manager's scripts disabled (for example npm ci --ignore-scripts), so downloading a package does not run its code. Python installs are limited to prebuilt wheels for the same reason.
  • Download with a network, build without. Where installing means compiling, the networked command only downloads and a second command builds in a container with no network.
  • The install container has the same hardening as every other: read-only root, no capabilities, non-root, resource limits, none of the service's environment.
  • Once per run. A pentest, a review or a fix run installs your dependencies once and gives each later proof of that run its own copy of the result, without opening the network again. An install that failed is not repeated for every proof either.
  • Nothing is shared between projects or runs: package managers' download caches live in the container's temporary space, and the installed dependencies are kept only for the run that installed them and removed when it ends. A run of another organisation, or of another version of your code, never sees them.
  • A package manager that is not in the sandbox (pnpm, Yarn, uv, Poetry) is fetched by the install step from the same public registry, at a pinned version and checked against a pinned checksum where the registry publishes one, or at the version your package.json names in packageManager. It is not kept.
  • Dependencies from anywhere else are not fetched. A git address, an archive on another host or a private registry is not on the list, and no registry credentials are passed in. Such an install fails and says which host it wanted, and the pentest's proof environment tells you so in the first minutes of the run.
  • Uploads are capped. The proxy limits how much the install may send (32 MiB by default: an install sends requests, not data), how much it may download and how many connections it may open.

Dependency installation is off unless it is switched on for the service. Lockfile regeneration during a dependency fix uses the same single networked command, with install scripts off.

Limits you should know:

  • A listed registry is trusted as a whole. The proxy cannot see inside an encrypted connection, so it cannot tell a download from an upload to the same host, and some registries accept uploads from anyone with an account. The upload cap bounds how much could leave that way; it does not make it zero.
  • The list of hosts, and whether the allow-list is in force at all, are settings of the service. The default is the allow-list.
  • "Fetching does not execute" has exceptions that no installer can avoid: for some ecosystems, resolving dependencies means running the project's own build description (Gradle, Maven extensions, Swift packages, Elixir's mix, Bundler, NuGet project files). That code then runs inside the install container, with its network, though still with nothing of the service in reach.
  • Package code does run later, when a probe or your tests import it. By then the container has no network.

#Services a proof needs

Many applications cannot start without a database, and many flaws only show against the running application. The sandbox has no network, and every command is a container of its own, so a database cannot run as a separate container next to the probe: the two could not reach each other.

Where the sandbox has the database programs, a probe starts a throw-away one inside its own container: PostgreSQL, MySQL (MariaDB), Redis or MongoDB. What that means:

  • It runs as the same unprivileged user as the probe, with the same limits and no additional privilege. It is one more process of the probe.
  • It listens on the loopback address of a container that has no network. Nothing outside the container can connect to it, and it can connect to nothing.
  • It starts empty. It holds only what the probe puts in: your project's migrations and a few test rows. No real data is ever involved, and it never talks to one of your databases.
  • Its data lives in the container's in-memory temporary space and is gone when the command ends.

Which services your code needs is read from the repository at the start of a pentest: compose files, connection strings in .env examples, database drivers among the dependencies, a migrations folder. A real .env file is never opened.

Whether the sandbox of your service can start them is a matter of how it is operated. When it cannot, the pentest's proof environment says "needs PostgreSQL, which the sandbox cannot start", and a flaw that only shows against the running application is confirmed by independent review instead. For those, live testing against a staging deployment is the way to proof.

#Install scripts and dependency fixes

A dependency fix changes a manifest and regenerates the lockfile. No AI processing is involved in computing it. The package manager runs in the sandbox with install scripts off, for example:

npm install --package-lock-only --ignore-scripts
pnpm install --lockfile-only --ignore-scripts
yarn install --ignore-scripts

The new lockfile is then checked by reading it, by installing from it, and by your project's tests when the repository has a test command. What could not be checked is stated on the fix rather than assumed.

#Page-level proofs

Some findings, such as cross-site scripting, can only be proven by rendering a page in a real browser. Where that is enabled for the service, the browser runs in its own container, separate from the service, with the same hardening and larger resource limits. It is given a network so that it can load the page under test, and a filter inside its container limits the page to the addresses in scope. That filter shares the container with the browser, so it is a guard against a page wandering off, not against a compromised browser; the browser container holds no secret of the service, only the test account's session. Where page-level proofs are not enabled, such findings are not proven this way.

#What kind of isolation this is

The sandbox is container isolation. Sandboxed commands share an operating system kernel with the machine that runs the containers; this is not a separate virtual machine per command. The properties above remove the ordinary ways out (network, privileges, mounts, environment), the system-call filter shrinks what of the kernel a command can reach, and a stronger runtime puts another layer in front of the kernel where the service has one. Together they limit what a successful escape through a kernel or container-runtime flaw could do next, but they do not make such a flaw impossible.

All sandbox containers run as the same unprivileged user, and working copies of runs that happen at the same time sit on the same scratch storage. A run cannot reach another run's working copy because it is not mounted into its container, not because of file ownership.

What that means for your code specifically: a probe runs against a copy of your repository only, with no network. Within the sandbox's rules, the worst a misbehaving probe can do is damage its own scratch copy, which is thrown away.

#If a proof or a verification cannot run

  • A probe that exceeds its time or memory limit is stopped, and a stopped probe proves nothing: the finding is not marked proven on the strength of it.
  • A fix whose tests cannot run (no test command, dependencies that cannot be installed, a private registry) says which check did not happen. See verified fixes.
  • A pentest checks at its start whether your code can be built in the sandbox, and says so on the pentest page before the first finding. See the proof environment.
  • The run's log shows what was attempted. See getting help.

Nullgap documentation