An offline Node build container that logs every internet attempt — point it at any vite/npm project.
Dependency installs run in a short, fully-logged internet window. Builds and dev servers run with the network locked down, and anything that tries to leave the container anyway is rejected and recorded. An AI analyzer (OpenRouter) reads the logs and tells you whether anything smells wrong — supply-chain attacks in npm packages usually reveal themselves exactly there: a postinstall script phoning home, a "build tool" fetching a binary, a dev server leaking telemetry.
- A Linux host (bash, coreutils, util-linux).
- Incus with a working
images:remote (this is the enforcement engine — see Why Incus). python33.9 or newer on the host (standard library only — nothing topip install).- Run as a normal user with
incusaccess — never as root. - Kernel log access. Egress evidence is read with
dmesg, so your user must be allowed to read it. Many distributions restrict that (kernel.dmesg_restrict=1); clean-builder then refuses to run rather than produce silently empty evidence. Lifting the restriction (sudo sysctl kernel.dmesg_restrict=0) lets every local user read the kernel log — on a shared machine, weigh that first. - An OpenRouter API key only if you use the optional
analyzestep.
git clone https://github.com/aimagician/clean-build.git ~/clean-build
cd ~/clean-buildThat's all: clean-builder is a single Bash script, and the helpers in
analyze/ use only the Python standard library. To run a fixed, reviewed
version instead of whatever main holds today, check out a
release tag
(git checkout v0.1.0) — release tags are immutable.
./clean-builder create # one-time: network, ACL, container, node toolchain
./clean-builder provision example # npm install WITH internet — every packet logged
./clean-builder build example # vite build, NO internet
./clean-builder watch example # vite dev server, NO internet (q + Enter quits)
./clean-builder analyze # AI verdict over the logsexample/ is a minimal vite app for smoke-testing; substitute any project
directory that has a package.json.
build and watch accept an optional script name to run a specific
package.json script instead of the defaults (build, and vite/dev
respectively) — useful when a project's full build needs tools the container
doesn't have, or its watcher isn't vite:
./clean-builder build ../myapp build:assets # sass + esbuild only
./clean-builder build ../myapp test:contact-worker # node --test, offline
./clean-builder watch ../myapp watch # project's own watcherTyping ./clean-builder from the repo directory gets old. Drop a small wrapper
into your shell config so you can call it from anywhere as cb:
# ~/.bashrc (or ~/.zshrc)
export CB_HOME="$HOME/clean-build" # where you cloned this repo
cb() { "$CB_HOME/clean-builder" "$@"; }Reload (source ~/.bashrc), then drive it from any directory with the project
path as an argument:
cb create
cb provision ~/code/myapp # install deps (online, logged)
cb build ~/code/myapp # offline build
cb build ~/code/myapp build:assets # a specific script, offline
cb watch ~/code/myapp # offline dev server
cb analyze --project myappThe project path is just an argument, so from inside a project you can run
cb build . to build the current directory.
The container keeps its default route on purpose. Without a route,
internet attempts die inside the container (ENETUNREACH) before a packet
exists — invisible to any network log. With the route up, every attempt
becomes a real packet at the isolated bridge (cb0), where an Incus ACL
decides and logs:
- Lockdown (the resting state): only DHCP may leave. Everything else hits the network's logged default-reject.
- Provision: a temporary ACL profile additionally allows DNS to 1.1.1.1/1.0.0.1 and TCP 80/443 — all logged — and is always restored, even on failure.
- Every phase refuses to start the container unless it holds only what the
script manages: the root disk,
eth0oncb0, theprojectmount andwatch'sproxy<port>tunnels. A second NIC would be a way out the egress log never sees, and an extra mount a folder every build could change outside the output check. Devices from a profile count, and so doraw.*keys (raw.lxccan add interfaces and mounts that aren't devices),security.privilegedand a changedraw.idmap../clean-builder statusruns the same check without starting anything. build/watchrefuse to start unless the network is actually enforcing: the default egress action isreject, egress logging is on, the ACL holds exactly one egress rule — the DHCP allow — and no other ACL is attached to the network (its rules would apply too). They also setnpm_config_offline/COREPACK_ENABLE_NETWORK=0so honest tools fail fast instead of hanging, and clear any leftoverproxydevice (see below) before an offline build.- Private ranges (your host, other containers) are rejected in every profile.
Package manager is detected per project: pnpm-lock.yaml → pnpm (corepack),
yarn.lock → yarn (corepack), otherwise npm (npm ci; a missing
package-lock.json is generated during provision with lifecycle scripts
disabled).
corepack itself comes from npm, pinned (CB_COREPACK, default 0.34.7), not
from Ubuntu: Ubuntu 26.04's packaged corepack (0.24) cannot start pnpm 11.
Every phase checks the container's corepack against the pin and, if it
differs, installs the pin in a logged toolchain window (logs/builder/).
One folder per project, named <basename>-<8-char path hash>
(logs/myapp-3f9c2a1b/, logs/example-a41b02cd/, … — the hash keeps
same-named projects apart, and each folder's project-path file records the
full host path; builder-level work like the toolchain install goes to
logs/builder/):
| file | contents |
|---|---|
install-<stamp>.log |
online download transcript (lifecycle scripts off) |
install-scripts-<stamp>.log |
the lifecycle scripts, run offline |
<script>-<stamp>.log |
offline build/test transcript for that script |
egress-<phase>-<stamp>.log |
every packet that left during that phase |
net-<phase>-<stamp>.log |
who tried to connect: per-process report of every network syscall (strace), naming the exact command behind each attempt |
analysis-<stamp>.md |
saved AI verdicts |
outputs |
the project's own output paths, if it has any (./clean-builder outputs) |
Egress lines come from the host kernel log (nftables):
cb0-egress[-<rule#>] ... SRC=10.23.23.x DST=<ip> PROTO=TCP DPT=<port>
No rule number = the default REJECT fired. Offline-phase egress files must be empty and offline-phase net reports must show no remote attempts — and when they don't, the net report tells you which process is to blame. Prove the pipeline works any time with the deliberate offender:
./clean-builder build example netprobe # tries to fetch — must come back blockedThe probe tries two escape routes — by hostname (the DNS path) and by raw IP (skipping DNS, exercising raw TCP egress) — and exits non-zero if either reaches the network. That makes it a scriptable regression check you can wire into CI, not just a line to spot in the transcript.
Blocking the network stops a dependency from phoning home, but a malicious build
can still inject a backdoor into the output you ship or tamper with your
source — the build legitimately writes to the project tree, which is on your
host. So after every build, clean-builder diffs the project tree
host-side (the build can't forge it) and tells you exactly what changed:
- Layer 1 — writes outside the build output. A clean build only touches its
output dirs (
dist/,build/,.svelte-kit/,.vite/, …). If it writes tosrc/, a config file, a lockfile, or intonode_modules/, that's the injection/tampering signature — reported as an ISSUE. - Layer 2 — suspicious patterns in the output. The files that changed are
scanned for high-signal markers that shouldn't appear in a clean bundle:
sendBeacon/WebSocket, hardcoded IPs,eval/atob/new Function,document.cookie/process.env/clipboardaccess, and wallet-drainer strings. Hits are reported as REVIEW (minified bundles can trip these, so they need eyes — ideally a diff against a trusted build).
Each build writes a changeset-<stamp>.md to its log folder with the verdict
(✓ CLEAN / ▲ REVIEW / ✗ ISSUE) and the exact files/patterns, and the
terminal prints a one-line verdict. CB_NO_SCAN=1 skips the diff for very large
repos.
Some projects write their output somewhere else. A Zola site's style build
writes static/style.css, and a zola serve running beside it copies that
into public/. Every such build would be an ISSUE, which teaches you to
skip the verdict. Name those paths once, for that project:
./clean-builder outputs ../mysite add website/static/style.css website/public
./clean-builder outputs ../mysite # list them
./clean-builder outputs ../mysite remove website/publicWrites there then count as build output for that project only: they're
scanned like dist/, and each changeset lists the extra paths. The list lives
in the project's log folder (logs/<project>/outputs), which is host-only, so
a build can't add to its own list. Name only paths you've checked the
project's own scripts write on purpose: writes there are no longer flagged.
One file shows the latest verdict for every project:
./clean-builder dashboard # regenerates and prints logs/STATUS.md| project | last build | verdict | unexpected writes | scan hits |
|----------------------|------------------|-----------|-------------------|-----------|
| myapp-3f9c2a1b | 2026-10-01T02:25 | ✓ clean | 0 | 0 |
| othersite-a41b02cd | 2026-09-30T18:10 | ✗ ISSUE | 2 | 0 |
logs/STATUS.md is rewritten after every build, so a quick glance tells you
which project needs attention. (✗ ISSUE = files changed outside the build
output — look first.)
Honest limits: this catches source/
node_modulestampering, time-bombs, and the common exfil/drainer patterns. It does not catch a deterministic payload written only intodist/that matches a baseline you don't have yet, and thenode_modulestripwire is mtime-based (a build could backdate to evade it). Treat it as a strong tripwire, not a proof — pin/audit deps and diff output against a trusted CI build for the rest.
analyze is an optional triage step. It reads the logs you already have on
disk and asks a model to flag anything that looks like a supply-chain problem —
a postinstall script that phoned home, a "build tool" that fetched a binary, a
dev server leaking telemetry.
export OPENROUTER_API_KEY=sk-or-...
./clean-builder analyze # newest logs across ALL projects
./clean-builder analyze --project myapp # one project's folder only
./clean-builder analyze --model google/gemini-2.5-flash --last 20
./clean-builder analyze --dry-run # print the exact prompt, no API callThe logs are already on the host: ./logs is host-only, and every file
(transcripts, egress captures, net reports) is written host-side as each phase
runs. So analyze never touches the container — there is no "copy the logs out
with incus" step, because there is nothing left to copy:
- It runs on the host as a small standard-library Python script
(
analyze/analyze_logs.py) — noincus exec, no container access. - It reads the newest log files straight from
./logs. - It sends them, wrapped in a strict triage rubric, in one HTTPS request to
the OpenRouter API (
https://openrouter.ai) using yourOPENROUTER_API_KEY. - The model returns a JSON verdict, printed and saved to
logs/<project>/analysis-<stamp>.md.
The only time
clean-buildercopies anything out of the container is the per-phaseincus file pullof thestracetrace — and that happens when the phase ends, not duringanalyze. By analysis time, every log is a plain file on your host.
analyze uploads the contents of your log files — build transcripts
included — to OpenRouter and the model you pick. Point CB_ANALYZE_MODEL (or
--model) at a provider you are comfortable handing that data to. If build
logs must never leave the machine, skip analyze and read the egress-* and
net-* reports directly; a local-model backend is on the roadmap.
The prompt treats all log content as untrusted data — if a transcript tries
to talk the model into a "clean" verdict (ignore previous instructions…),
that attempt is itself reported as a finding.
A strict JSON verdict — clean / suspicious / critical, plus
evidence-quoting findings. Exit code 0 = clean, 1 = findings, 2 = error,
so a nightly cron job can gate on it.
Offline means your dev server can't call a backend on another container either. Instead of opening the network, forward through the host:
./clean-builder proxy add 8801 10.0.0.5:8801 # <port> <backend-ip>:<port>Now 127.0.0.1:8801 inside the builder reaches that backend via an Incus
proxy device (host-mediated — the ACL still rejects all private-range
traffic). Point your vite server.proxy at http://127.0.0.1:8801.
Be clear-eyed about what this does and doesn't promise. It raises the bar and creates an audit trail — a strong, logged offline default that catches the common supply-chain patterns (postinstall phoning home, a "build tool" fetching a binary, telemetry). It is not an airtight sandbox against code that is actively trying to defeat it specifically.
What holds well:
- Network enforcement is done by the Incus bridge ACL (a host-side,
kernel-level default-reject), which container code running as the build user
cannot change. During
build, egress to the internet and to private ranges is rejected and logged. buildverifies the enforced properties (default-reject + logging on) before running, not just a rule count, and refuses to run if it cannot read the kernel log it depends on for evidence.- The log store is out of the build's reach.
./logsis host-only — never mounted into the container. Thestracetrace is written by root to a root-only container directory (the build runs dropped to uid 1000) and pulled out per phase, so the build can neither erase nor forge its own attribution, and there is no shared writable directory to stage a symlink attack in. - Phases are serialized by a host-side lock, so a
provision(which opens the bridge) can't start mid-buildand open a window the build could use. A second phase waits for the first to finish;watchholds the lock for its whole session. - No side doors. The ACL only sees
cb0and the output check only sees the project folder, so the container may hold nothing else: no second NIC, no extra mount, noraw.lxc, no privileged mode. Anything added by hand (or through a profile) stops every phase, with a list of what to undo. Aprojectmount whose folder has since been deleted is dropped instead, so it no longer keeps the container from starting.
Known limitations:
-
The side-door check runs when a phase starts. A device added while a phase runs is caught by the next phase. Changes inside the container's own filesystem (packages or files installed by hand) aren't checked at all; the toolchain belongs in
create's logged window. -
strace attribution is still best-effort. A build can print misleading content to its own transcript, and evade the trace itself (io_uring, argv spoofing). The trace can no longer be erased, but treat the kernel egress log as the authoritative signal and the
net-*report as attribution. -
proxy addopens a host-mediated tunnel that bypasses the bridge ACL and is therefore unlogged.buildclears proxy devices first, butwatchuses them by design — while a proxy device exists, awatchphase has a network path the egress log won't show. Remove it (proxy remove <port>) when you're done. -
provisiondownloads online, then runs scripts offline. The online window installs with lifecycle scripts disabled (--ignore-scripts, yarn--mode=skip-build); the packages' and the project's install hooks then run in a separate offline, tracedinstall-scriptsphase, where a phone-home is blocked, not just logged. A script that genuinely needs the network (a prebuilt-binary download, node-gyp fetching headers) fails there and names itself;CB_ONLINE_SCRIPTS=1runs scripts online for that install, as before. The download itself is still online — review the install egress. -
The AI verdict is advisory. It reads attacker-influenced text; the rubric treats logs as untrusted, but trust the raw egress log over the model's summary.
-
Run this as a normal user, never root (the uid mapping would make container writes root-owned on the host).
./clean-builder status # container, ACL profile, project mount, side-door check
./clean-builder dashboard # at-a-glance output-integrity status of all projects
./clean-builder outputs <dir> [add|remove <path>...] # a project's own output paths
./clean-builder logs # newest files + live kernel entries
./clean-builder lockdown # force the resting ACL by hand
./clean-builder start # start the builder by hand
./clean-builder stop # stop it now (frees memory)
./clean-builder destroy # remove the container (network/ACL stay)Idle by default. Each phase stops the container when it finishes, so an
idle builder uses no memory — and any process a build left running is killed
rather than surviving to the next phase (a small security win). build runs
once then stops; provision starts, installs, and stops; watch runs until
you quit, then stops. The toolchain and node_modules persist, so the next
phase just restarts the container (~30 s cold start on a slow host). For rapid
back-to-back builds, set CB_KEEP_RUNNING=1 to leave it up, or ./clean-builder stop / start by hand.
Tunables (environment variables — set them yourself; CB_PORT is validated
because it is passed into an in-container command):
| variable | default | what it does |
|---|---|---|
CB_INSTANCE |
clean-builder |
Incus container name (also names the phase lock) |
CB_IMAGE |
images:ubuntu/26.04 |
image the builder is created from |
CB_NETWORK |
cb0 |
isolated bridge the ACL is attached to |
CB_ACL |
clean-builder-egress |
name of the Incus network ACL |
CB_LOG_DIR |
logs/ next to the script |
host-only log folder — never put it inside a project you build, since the project is mounted into the container |
CB_PORT |
5173 |
dev-server port for watch; must be in the ingress-allowed range 5170-5179 |
CB_CPU / CB_MEMORY |
2 / 2GiB |
container limits, applied when create first makes the container |
CB_KEEP_RUNNING |
0 |
1 = don't stop the container after each phase |
CB_NO_SCAN |
0 |
1 = skip the output-integrity diff (very large repos) |
CB_ANALYZE_MODEL |
anthropic/claude-sonnet-4.5 |
OpenRouter model used by analyze |
CB_APP_URL |
this repository's URL | attribution URL analyze sends to OpenRouter |
OPENROUTER_API_KEY |
— | needed only for analyze |
Why it stays safe even during provision: Incus evaluates ACL rules as reject-over-allow, regardless of order, so the private-range reject always wins over the broad
80/443allow — your host and other containers stay unreachable even while the internet window is open.
Forks are welcome — it's MIT-licensed, and nothing in the repository is tied to one machine. If you run or publish a fork:
- Pin what you run. Use a release tag or a commit you have reviewed, not a moving branch: this tool exists to contain code you don't trust, so treat its own updates the same way.
- Set
CB_APP_URLto your fork's URL —analyzesends it to OpenRouter as the attribution header, and it defaults to this repository. - Check the bridge subnet.
cb0uses10.23.23.0/24(NETWORK_CIDRandGATEWAYnear the top ofclean-builder); change both if that overlaps a network you already use. - Publishing your fork? Point the vulnerability-report links in
SECURITY.mdand.github/ISSUE_TEMPLATE/config.ymlat your repository so reports reach you, and update.github/CODEOWNERS.
The CLI is mostly backend-agnostic (exec/mount/proxy map to docker exec,
-v, published ports or socat). The one piece Docker does not provide is
the heart of this design: network ACLs with logged rejects.
--network none and --internal block traffic but record nothing — the
exact blindness this tool exists to avoid. A CB_BACKEND=docker mode would
recreate it with host nftables/iptables rules on the DOCKER-USER chain
(LOG + REJECT on the builder's bridge, toggled between lockdown and
provision profiles), at the cost of:
- sudo for every phase switch (Incus needs none),
- global host firewall state instead of a named per-network ACL object,
- Docker Desktop/WSL networking quirks if not on native dockerd.
Estimated at roughly a day of careful work, most of it testing the firewall toggling. Until then: Incus is the supported backend.
The analyze step is model-agnostic — any OpenRouter model works. It defaults
to anthropic/claude-sonnet-4.5; pick another with --model or
CB_ANALYZE_MODEL. Results from validating the triage rubric across models
will be published here.
Bug reports, new detection patterns, docs fixes and tests are all welcome — start with CONTRIBUTING.md, and please follow the Code of Conduct. Notable changes are listed in CHANGELOG.md.
Found a way for a build to reach the network, forge or erase evidence, or slip past the lockdown? Please report it privately as described in SECURITY.md — not in a public issue.
MIT © Ivan Popov