DocFirewall

DocFirewall is a specialized security library designed to deeply scan and sanitize modern document formats (PDFs and ZIP-based Office files like DOCX, PPTX, and XLSX) against hidden threats. It goes beyond standard malware scanning by deeply parsing the structural content of files to detect advanced attack vectors such as prompt injection, credential and secrets leakage, embedded payloads, hidden text, and denial-of-service (Zip Bomb) attempts. The engine allows for highly configurable profiles, including the ability to apply custom YARA rules, utilize machine-learning-based detectors, and integrate seamlessly with traditional antivirus engines like ClamAV. Upon scanning a doc, it outputs a comprehensive risk score, a definitive safety verdict, and structured forensic evidence pinpointing the exact location of any malicious findings. Ultimately, it acts as a robust first line of defense for applications that need to safely ingest user-uploaded documents and feed clean telemetry to security operation centers (SIEMs).

In the context of DocFirewall, an embedded payload refers to hidden executable code or malicious components smuggled inside an otherwise normal-looking document. Attackers frequently use techniques like embedding raw scripts, Windows executables (PE files), or Linux binaries (ELF files) within the deep structural layers of PDFs or Office files. DocFirewall detects these threats by tearing apart the document's internal objects and scanning for distinct binary signatures or unnatural entropy levels. It actively flags recognizable malware headers (like the "MZ" stub for Windows) and unusually large blocks of Base64 or Hex-encoded data, which are often used to obfuscate a smuggled virus. By exposing these hidden elements, the engine prevents the document from acting as a Trojan horse that silently drops malware when opened.

Key Capabilities

Performance

DocFirewall is optimized for high-throughput environments using a dual-stage scanning architecture:

1. Fast Scan: 10ms-range byte-level analysis for known signatures and structural anomalies.
2. Deep Scan: Full document parsing (powered by Docling) for semantic analysis.

Basic Usage

from doc_firewall import scan

# Scan a document
report = scan("resume.pdf")

if report.verdict == "BLOCK":
    print(f"🚫 Blocked! Score: {report.risk_score}")
    print("Findings:", report.findings)
else:
    print("✅ Safe to process")

Get Started