okf-guard: A Security Layer for Open Knowledge Format (OKF) Pipelines

AI agents often consume information from sources they did not author and cannot independently verify, such as PDF policy documents, scraped web pages, or spreadsheet exports from other systems. The typical method of extracting text from these sources and feeding it directly into a knowledge base or context window for an AI agent to treat as factual has an overlooked weakness. Text extraction tools capture all content within a source document, including text that might not be visible to a human reviewer.

Certain common features of popular file formats, such as PDFs, Word documents, PowerPoint slides, spreadsheets, and HTML pages, allow text to remain hidden from casual viewers. For example, a PDF can render invisible text using a rendering mode that matches the page background color, or a Word document can have text marked as "hidden."

Similarly, PowerPoint files contain speaker notes that are parsed by most extraction tools but do not appear to the audience. Spreadsheets can hide entire rows, columns, or sheets, or embed invisible comments within cells. HTML pages can employ CSS properties to conceal elements entirely from browser rendering.

These features are not obscure or uncommon; they are standard formatting tools used for benign purposes like hiding helper columns in spreadsheets or private presenter notes. The issue arises when an extraction pipeline does not differentiate between content that is intentionally hidden and content that is genuinely part of the document's visible information.

An attacker could embed malicious instructions within these hidden areas, and the extraction process would treat them as regular text once the document is ingested into a knowledge base.

This type of attack is a variant of indirect prompt injection, where the attacker embeds a prompt disguised within the document's hidden content. This threat is particularly concerning for systems like Google's Open Knowledge Format (OKF), which is designed to allow AI agents to read organizational knowledge directly from markdown files without any intermediate processing. The directness of OKF means there is no intermediate layer to catch potential issues before the AI treats the content as trustworthy.

Okf-guard is a Python library designed to address this vulnerability. It functions at the stage where source documents are extracted before they are incorporated into a trusted knowledge base. Okf-guard performs two types of inspections on each scan: hidden-content detection, which is format-aware, and pattern-based detection of language characteristic of instructions aimed at AI systems, including checks for encoding-based obfuscation.

The library supports six document formats: plain text, Markdown, HTML, PDF, DOCX, and PPTX. Each format has an adapter that understands its specific mechanisms for hiding text. If content is both hidden and contains potentially malicious phrasing, the library records two separate findings, recognizing that either finding alone is significant and the combination strengthens the evidence of a security threat.

The results provide an action (pass, quarantine, or block), a risk score, and details of any detected flags, explicitly marking the content as machine-processed and unverified.

Okf-guard is a lightweight, rule-based tool with no dependencies on large language models or external network calls. Its deterministic nature makes it suitable for security-relevant applications where reproducibility and auditability are crucial. Despite its focus on detecting malicious content, the tool does not claim to assess the accuracy of the information it flags. It explicitly includes provenance metadata to indicate that the content has been machine-processed and not reviewed by a human.

Currently, version 0.1.0 of okf-guard covers document- and web-sourced content, addressing the most plausible origins of external content. Future releases will expand to include structured technical sources, collaboration-tool connectors, and content generated by AI agents' own reasoning processes. Feedback from security professionals familiar with document security or LLM safety is encouraged, as the library is designed to evolve through community contributions.