No description
  • Go 96.6%
  • Dockerfile 2.9%
  • Makefile 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-27 14:11:37 +01:00
assets added logo 2026-10-27 14:08:47 +01:00
cmd/sojujail Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
image Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
internal Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
.containerignore Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
.gitignore Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
go.mod Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
Makefile Two-stage sandboxed file sanitiser with gVisor 2026-10-27 11:56:23 +01:00
README.md edit README.md 2026-10-27 14:11:37 +01:00

sojusafe

sojujail

Makes untrusted files safe to keep, serve and open. Images come out as WebP and PDFs are rebuilt from pixels. Audio and video are remuxed without metadata. Nothing from the original file is parsed on the host.

It is a single Go binary that drives podman, so it works the same from a web application (stdin to stdout) and as a desktop tool (sojujail ~/Downloads/sketchy.pdf).

How it works

                 untrusted                checked pixels only
 file ──▶ [ stage 1: decode ] ──pixels──▶ host check ──▶ [ stage 2: encode ] ──▶ WebP / PDF
           podman + gVisor                (Go, strict)     fresh podman + gVisor

This is the Dangerzone design. Stage 1 parses the file with ImageMagick, librsvg or poppler, and assumes the file may take it over. All it can send on is a trivial stream: a 10-byte header, then width, height, delay and raw RGB(A) bytes for each page or frame (internal/pixels). The host checks every field (page and frame counts, dimensions, exact byte counts, nothing after the last frame) and passes on a copy it re-serialises itself. Stage 2 runs in a new container, never sees the original file, and builds the output from those pixels. A fully compromised stage 1 can therefore only produce wrong pixels, never a malicious file.

Each container runs with --network=none --read-only --cap-drop=ALL --userns=nomap, no-new-privileges, no logging, memory, pids and time limits, and --pull=never. Inside it, the stage runs under gVisor (runsc, nested as in Dangerzone): the converters talk to gVisor's user-space kernel, so a kernel exploit lands in gVisor, not on the host. The only capability the outer container gets is SYS_CHROOT, which runsc needs to start; the stage itself has none. sojujail check shows which kernel a stage sees.

Input Output How
JPEG, PNG, GIF, WebP, SVG WebP (animation and transparency kept) decoded to pixels, re-encoded
PDF PDF of 150 dpi page images, optional OCR text layer rendered to pixels, rebuilt
MP4, QuickTime, WebM, Ogg video same (QuickTime becomes MP4) remuxed without metadata
MP3, WAV, Ogg, WebM audio, AAC, FLAC same remuxed without metadata

sojujail formats --json prints this table with MIME types and extensions, for applications.

Audio and video can't go through pixels without re-encoding, so they are a single stage: ffmpeg copies the streams into a fresh container without metadata (GPS, dates, device, chapters, subtitle and data tracks, cover art), with the input format named explicitly. The result still holds the original compressed streams, which the player decodes.

Install

Needs podman (rootless is fine) and Go 1.25 to build.

make image      # builds localhost/sojujail:<version>; downloads the pinned gVisor release
make install    # bin/sojujail -> ~/.local/bin
sojujail check  # kernel Linux version 4.19.0-gvisor ... / ok: stages run under gVisor

The image is built locally and only ever run by tag; sojujail never pulls it. The gVisor download is pinned by release and SHA-512 in image/Containerfile.

Desktop use

sojujail ~/Downloads/invoice.pdf          # -> ~/Downloads/invoice.safe.pdf
sojujail --ocr eng+nld scan1.pdf scan2.pdf
sojujail -o ~/safe *.jpg                   # -> ~/safe/NAME.safe.webp

The type comes from the file's first bytes (fixed byte patterns only, nothing is parsed on the host). The file is then decoded strictly as that type, so a file posing as another type fails instead of reaching a different decoder. Options come before the file names.

Use from applications

sojujail convert --from MIME reads the file on stdin and writes the converted file on stdout. Progress goes to stderr as progress <done> <total> lines (pages or frames; with --ocr, recognised pages), and an error ends with a sojujail: ... line.

Exit code Meaning
0 converted
1 file refused: malformed, not what it claims, over a limit, or infected
2 usage error
3 sandbox or clamd unavailable (podman, image, gVisor): retry later, do not accept the file

Node:

const { spawn } = require('node:child_process');

function sanitize(path, mime) {
  return new Promise((resolve, reject) => {
    const p = spawn('sojujail', ['convert', '--quiet', '--from', mime]);
    const out = [];
    let err = '';
    p.stdout.on('data', (c) => out.push(c));
    p.stderr.on('data', (c) => (err += c));
    p.on('close', (code) =>
      code === 0 ? resolve(Buffer.concat(out)) : reject(Object.assign(new Error(err.trim()), { code })));
    require('node:fs').createReadStream(path).pipe(p.stdin);
  });
}

PHP:

$result = Process::input(fopen($path, 'rb'))->timeout(300)
    ->run(['sojujail', 'convert', '--quiet', '--from', $mimeType]);
// exitCode() 1 = refuse the upload, 3 = retry the job

The output type and extension per input type are in sojujail formats --json.

Options

Every option can also be set as an environment variable, SOJUJAIL_<NAME> (for example SOJUJAIL_CLAMD, SOJUJAIL_MAX_PAGES).

Option Default
--image localhost/sojujail:<version> sandbox image
--podman podman podman binary
--gvisor true false only where nested gVisor can't start; podman isolation remains
--memory 1g per container
--timeout 120 seconds per stage
--max-pages 100 documents with more pages are refused
--ocr Tesseract languages for a text layer on documents, e.g. eng+nld (the image ships eng)
--ocr-jobs 2 pages recognised in parallel
--ocr-timeout 1800 seconds for the OCR stage
--clamd scan with clamd first, tcp://127.0.0.1:3310 or unix:///run/clamav/clamd.sock

Fixed limits: 10000 px per side, 500 animation frames, 256 MiB of pixels per image, 40 MP per frame (ImageMagick policy).

ClamAV

Not bundled: clamd needs about 1.5 GB of memory for its signatures and network access for updates, so it runs as its own long-lived container, for example:

podman run -d --name clamav -p 127.0.0.1:3310:3310 docker.io/clamav/clamav:stable

With --clamd set, sojujail scans the original before converting and refuses the file when it is infected or clamd can't be reached. sojujail scan FILE scans without converting, for types it doesn't convert. For converted types a scan mostly adds early rejection of known malware, since the output is rebuilt anyway.

Limits of the design

  • Audio and video are not rebuilt (see above).
  • Office documents are not supported yet.
  • OCR in stage 2 reads pixels that came from the untrusted file. Tesseract only ever gets plain PNGs, but it is the largest piece of code in stage 2.
  • Nested gVisor needs a kernel and podman that allow it (it works with rootless podman on Arch). sojujail check tells you.

Development

make test   # unit tests; the sandbox tests in internal/jail run when the image is built
SOJUJAIL_GVISOR=0 go test ./internal/jail   # the same without gVisor