Download the PHP package twarimitswe-aaron/gatekeeper-cdr without Composer

Table of Contents

• What is Gatekeeper?
• Why CDR?
• Architecture
  • Memory Model
  • Typestate Pipeline
  • Error Model
• Supported Formats
• Project Structure
• Getting Started
  • Prerequisites
  • Build
  • Run Tests
  • Run the CLI Example
• Using Gatekeeper as a Library
  • As a Rust Dependency
  • API Reference
• FFI Bindings (Planned)
• Roadmap
• Contributing
• License

What is Gatekeeper?

Gatekeeper is a static library that accepts multi-format file byte streams, surgically removes all non-pixel content, and reconstructs an immaculate output binary from the raw colour matrix upward. It is designed to be embedded directly into application source repositories via native FFI bindings — no infrastructure changes required.

It does not scrub files in place. The entire philosophy is:

Decode to naked pixels. Re-encode from zero. Share nothing with the original.

Why CDR?

A file that "looks" clean to a human viewer can carry:

Classic AV scanning misses all of these. CDR eliminates the attack surface entirely by making it structurally impossible for the output to contain anything other than colour values.

Architecture

Memory Model

Gatekeeper enforces a strict zero-copy architecture at the format-detection layer:

The sniffer compares magic bytes using direct subslice equality (payload[..2] == JPEG_SOI). No intermediate buffers or Vec are constructed during format detection — the comparison resolves in a single register-level load.

Typestate Pipeline

Every sanitizer enforces its stage transitions at compile time using Rust's typestate pattern with newtype tuple structs. Calling stages out of order is a compile error, not a runtime panic. Passing raw bytes to a save routine is also a compile error — only SanitizedOutput is accepted.

Inside the crate, inner values are always extracted via the formal pattern:

Error Model

All errors are defined in src/errors.rs as a single CdrError enum backed by thiserror. No String allocations occur at any error variant — every branch carries fixed-size typed data.

Dual-Output Contract

Every call to disarm() returns a DisarmResult containing two buffers:

Why is the sanitized file a different size?

Gatekeeper never scrubs bytes in place. Every image passes through:

The output shares zero bytes with the input. Size changes are normal and come from three separate causes:

1. Format change (often much larger — expected)

2. Lossy generation loss (JPEG / GIF native buffer)

3. Re-compression of lossless formats (PNG native buffer)

PNG sanitization decodes pixels and writes a new PNG containing only IHDR + PLTE/tRNS (if needed) + IDAT + IEND. All metadata chunks (tEXt, iCCP, eXIf, trailing polyglot bytes) are removed — which reduces size.

The remaining IDAT size depends on deflate level and PNG filter strategy:

PNG outputs may still be slightly larger than files passed through slow offline optimizers (optipng -o7, Zopfli, brute-force filter search). Gatekeeper targets real-time sanitization, not maximum offline compression.

Quick reference: which buffer should I use?

Size fields on DisarmResult

To log both outputs: result.buffer.len() and result.png_buffer.as_ref().map(|p| p.len()).

Enterprise Readiness Analysis

What Gatekeeper Already Does Right

Known Gaps vs. Enterprise CDR

Commercial CDR products (Glasswall, Votiro, OPSWAT MetaDefender) address the following that Gatekeeper does not yet:

Is the Current Approach Production-Ready?

For embedded / edge deployments (IoT gateways, upload proxies, CI artifact scanning) — yes. The architecture is sound: zero-copy parsing, compile-time stage enforcement, bomb guards, and dual-output with no wasted allocations.

For enterprise SaaS at scale (100k+ files/day), the single highest-impact change is eliminating the double decode for JPEG:

This single change halves CPU cost for all JPEG inputs. Everything else in the roadmap is additive.

Supported Formats

Project Structure

Getting Started

Prerequisites

• Rust 1.85+ (Edition 2024 requires Rust ≥ 1.85)

Build

This produces:

• target/debug/libgatekeeper.rlib — Rust linkable library
• target/debug/libgatekeeper.so — Native shared library (cdylib)

For a release (optimised) build:

Run Tests

Expected output:

Run the CLI Example

The examples/disarm_image.rs driver lets you test the full pipeline against any real file:

Sample output:

Using Gatekeeper as a Library

As a Rust Dependency

Add to your Cargo.toml:

Or for a local checkout:

API Reference

gatekeeper::disarm(payload: &[u8]) -> Result<SanitizedOutput, CdrError>

The primary entry point. Detects format, runs the full CDR pipeline, and returns a SanitizedOutput token — a distinct type that can only be produced by a completed pipeline run.

To enforce that a save function only ever accepts sanitised data:

gatekeeper::sniff_format(payload: &[u8]) -> Result<FileFormat, CdrError>

Identify the format of a byte slice without modifying or decoding it. Useful for routing in larger pipelines.

gatekeeper::sanitizers::jpeg::sanitize_jpeg(input: &[u8]) -> Result<SanitizedOutput, CdrError>

Call the JPEG sanitizer directly, bypassing the format sniffer.

FFI Bindings (Planned)

The cdylib target is already compiled and emits a native shared library (.so / .dll / .dylib). The sections below show the planned import and usage API for each target language. These bindings do not exist yet — they are the design target for Phases 7–11.

Node.js (via napi-rs)

Python (via PyO3)

PHP (via ext-php-rs)

C / C++ (Raw FFI)

Go (via CGo)

Roadmap

• [x] Phase 1 — Cargo manifest, error model, format sniffer
• [x] Phase 2 — JPEG sanitization pipeline (typestate + zune-jpeg + png)
• [x] Phase 3 — PNG sanitization pipeline
• [x] Phase 4 — GIF and WebP support
• [x] Phase 5 — PDF sanitization (remove embedded JavaScript, OLE streams)
• [x] Phase 6 — Office format sanitization (DOCX / XLSX / PPTX)
• [x] Phase 7 — napi-rs Node.js bindings → publish to npm
• [x] Phase 8 — PyO3 Python bindings → publish to PyPI
• [x] Phase 9 — ext-php-rs PHP bindings + C/C++ raw header → publish to Packagist
• [x] Phase 10 — CGo Go bindings → publish Go module to pkg.go.dev
• [x] Phase 11 — JNI Java bindings → pending Maven Central publish
• [ ] Phase 12 — Single-pass JPEG dual-output (sanitize_jpeg_dual) to eliminate double-decode
• [ ] Phase 13 — CdrPolicy struct: configurable size limits, quality, format allowlist
• [x] Phase 14 — Async pipeline via Tokio for streaming large files
• [ ] Phase 15 — WASM target for browser-side CDR

Contributing

Gatekeeper is open-source under AGPLv3 and actively welcomes contributions. Please read the full guide before opening a PR:

👉 CONTRIBUTING.md

Quick summary:

1. Fork the repository
2. Create a branch — git checkout -b feat/png-sanitizer
3. Write tests — new code must include unit tests
4. Check — cargo test && cargo clippy && cargo fmt --check
5. Open a PR against main using the PR template

For larger changes (new format support, architectural changes), please open an issue first to discuss the approach before writing code.

License

Gatekeeper is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

This means:

• ✅ You may use, modify, and distribute this code freely
• ✅ You may use it in commercial applications
• ⚠️ If you modify it and run it as a network service, you must publish your modifications under the same license
• ⚠️ All derivative works must carry the AGPLv3 license

See LICENSE for the full text.