A hardened, self-contained Content Disarm & Reconstruction (CDR) appliance for Ubuntu 24.04. Drop a file on an SMB share, get a sanitized PDF back on a separate share. The actual disarming is done by Dangerzone (pixel-rebuild inside a rootless Podman + gVisor sandbox); this project is the operations layer around it — recursive folder-watching, EDR coexistence, structure-preserving delivery, retention, hardening, and an interactive installer that gets you from a blank VM to a working appliance.
You give a user (or a workflow, or a partner integration) a network share. They drop untrusted files in it:
\\fileserver\downloads\in\contracts\suspicious.pdf
\\fileserver\downloads\in\anything\photo.png
\\fileserver\downloads\in\nested\folders\work.docx
The appliance picks each one up, runs it through Dangerzone's sandbox, and delivers a flattened safe PDF at the matching path on the output share:
\\fileserver\downloads\out\contracts\suspicious.pdf
\\fileserver\downloads\out\anything\photo.pdf
\\fileserver\downloads\out\nested\folders\work.pdf
Originals are deleted from the input share once a clean output is provably on disk. Failed conversions are kept locally on the appliance for triage. Files an EDR (e.g. CrowdStrike Falcon) quarantines mid-flight are logged as expected events, never as failures.
Accepted inputs: PDF, PNG, JPG/JPEG, GIF, BMP, TIFF, DOCX/DOC, XLSX/XLS, PPTX/PPT, ODT/ODS/ODP. Output is always PDF.
- Not a Dangerzone replacement. Dangerzone is the security boundary; this is the operations wrapper.
- Not multi-tenant. One pair of shares per appliance. Run multiple VMs if you need isolation between consumers.
- Not a network sandbox / proxy / mail gateway. It's a folder-watcher.
- Not high-throughput. Real Dangerzone conversions are CPU-heavy (one container per file). Spec the VM accordingly.
Dangerzone is desktop software. Running it on a hardened dedicated VM gets you:
- The disarm process is isolated from the systems that consume the safe PDFs.
- A line-1 EDR (Falcon, SentinelOne, etc.) can still scan files in transit on the file server; the appliance is line-2 and tolerates the line-1 race.
- SMB ACLs enforce "only this appliance writes to
out/" — consumers can't be fooled by adversaries dropping things directly into the output share. - Hardening, firewall, logging, and retention are scoped to one purpose, with a known-good baseline (Lynis index ~82 on a clean install).
The appliance needs /dev/kvm accessible inside the guest. gVisor uses hardware
virtualisation to isolate each conversion; without it the sandbox cannot start.
Enable the following on your hypervisor before creating the VM:
| Platform | What to do |
|---|---|
| Proxmox | VM → CPU → Type = host; verify nested=Y on the hypervisor. Full stop+start the VM (reboot is not enough). |
| VMware ESXi/vSphere | Edit VM → CPU → Expose hardware-assisted virtualization to the guest OS. Stop+start. |
| VMware Workstation/Fusion | VM Settings → Processors → Virtualize Intel VT-x/EPT or AMD-V/RVI. Stop+start. |
| GCP | Pass --enable-nested-virtualization at VM creation. Cannot be added later. |
| Azure | Use a v3+ series VM (Dv3, Ev3, Dsv3, Esv3 or newer). Nested virt is available on these automatically. |
| AWS standard | ✗ Nitro does not expose /dev/kvm. Bare metal instances work but are expensive. A gVisor ptrace-mode variant (no KVM required) is a known future gap — not implemented. |
The installer refuses to proceed at Phase 1 if /dev/kvm is absent, so a
misconfigured hypervisor fails in seconds, not after a 20-minute install.
The surrounding perimeter (security group, NSG, corporate firewall) must permit the following before and during install:
| Direction | Port(s) | Destination | Purpose |
|---|---|---|---|
| Outbound | 53 UDP/TCP | DNS servers | Package resolution |
| Outbound | 123 UDP | NTP servers | Time sync |
| Outbound | 80, 443 TCP | Any | apt mirrors, FPF Dangerzone repo, Ubuntu security updates |
| Outbound | 445 TCP | File server IP(s) | SMB share mounting |
| Inbound | 22 TCP | Admin subnet | SSH access |
After install, 80/443 can be scoped to specific update repos if you have an
internal mirror. All other inbound traffic should be blocked. The appliance's
own UFW is configured automatically by setup-vm.sh; the table above is for
your network edge. Full details: INSTALL.md.
You need a fresh Ubuntu 24.04 VM with KVM exposed to the guest (on Proxmox: CPU type = host, plus nested virtualization enabled on the hypervisor — gVisor needs /dev/kvm). Then:
# Option A — self-extracting installer
sha256sum cdr-appliance-X.Y.Z.run # verify against the release SHA
chmod +x cdr-appliance-X.Y.Z.run
sudo ./cdr-appliance-X.Y.Z.run # extracts and launches setup-vm.sh
sudo ./harden.sh # run from the extracted cdr/ directory
# Option B — tarball
sha256sum cdr-appliance-X.Y.Z.tgz # verify against the release SHA
tar xzf cdr-appliance-X.Y.Z.tgz && cd cdr
sha256sum -c SHA256SUMS # verify per-file SHAs
sudo ./setup-vm.sh
sudo ./harden.shsetup-vm.sh refuses to proceed if /dev/kvm isn't present (Phase 1 preflight), so a misconfigured hypervisor fails in seconds, not after a 20-minute install. The full end-to-end gate at the last phase drops a real PDF on the input share and confirms a sanitized one appears on output — if you see "End-to-end OK" you're done.
Full install walkthrough: INSTALL.md.
The watcher and its timers run as systemd user services under cdr's own user manager (via loginctl enable-linger). Logs go to the user journal, not the system journal:
# the one command you'll use 95% of the time:
sudo journalctl _UID=$(id -u cdr) --no-pager -n 50
# service status:
sudo -u cdr XDG_RUNTIME_DIR=/run/user/$(id -u cdr) \
DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u cdr)/bus \
systemctl --user status cdr-watcher
# what failed (preserved at mirrored path):
sudo ls -laR /var/lib/cdr/failed/
# files an EDR pulled mid-flight (expected events):
sudo cat /var/lib/cdr/edr_events.json 2>/dev/null | tail -20
# last conversion failure dump (full Dangerzone output + env):
sudo cat /var/lib/cdr/last_fail.json 2>/dev/nullThree timers run automatically under cdr's user manager:
cdr-health.timer— every 10 min: mount check, service check, disk check, backlog check.cdr-input-sweep.timer— every hour: deletes files in input/ and failed/ older than 2h (tunable viaCDR_INPUT_SWEEP_HOURS), prunes empty subdirs, skips.processing/.cdr-retention.timer— daily: prunes output/failed/logs past their age thresholds.
All tunables live in /etc/cdr/cdr.env.
The actual document sanitization — the part that protects you from malicious files — is Dangerzone, by the Freedom of the Press Foundation. Dangerzone is licensed under AGPLv3 and is installed independently from the official FPF APT repository during setup. This project does not bundle, modify, or redistribute Dangerzone; it invokes the dangerzone-cli binary as a separate subprocess. Users of this project should follow Dangerzone's upstream and respect AGPLv3 for that component.
This project is licensed under the MIT License — see LICENSE. The MIT/AGPL combination is permitted because of the arms-length subprocess boundary; the LICENSE file documents this explicitly.
Inspired by the architectural ideas in Qubes OS's "trusted PDF" pattern, which Dangerzone itself adapted for non-Qubes systems.
This is operational software in real production use at CatSec. It was developed iteratively over many sessions against a real workload (an Israeli card issuer's payment-security and fraud team), with extensive debugging baked into the comments — there's a reason setup-vm.sh does a KVM preflight in Phase 1, and that reason is documented in the script. Pull requests welcome; see CONTRIBUTING.md.
Ram Prass — CatSec — cybersecurity consulting and security awareness training. Open issues here on GitHub for bugs or operational questions.