- Go 96.6%
- Dockerfile 2.9%
- Makefile 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| assets | ||
| cmd/sojujail | ||
| image | ||
| internal | ||
| .containerignore | ||
| .gitignore | ||
| go.mod | ||
| Makefile | ||
| README.md | ||
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 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 checktells 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