Agent-Ready Files

A files collection takes files your end users upload and turns each one into visible text and page images that an agent can read, search and cite over the Flux API and MCP. Every file arrives in a labelled untrusted envelope with a verdict. The agent sees what a person sees: text hidden in the file is not delivered and is reported as a finding.


What an agent receives

An agent receivesAn agent never receives
Visible text, read by OCR from FoxNose's own rendering of the file, as page-anchored markdown.The original file, or a link to it.
Page images of that rendering, as short-lived links on request (include_links), with unreadable and hidden regions redacted.Text the rendering does not draw: hidden layers and runs, comments, metadata, off-page text, a PDF's own text layer.
A verdict, clean or suspicious, with the finding kinds behind it.Text below the legibility floor.
Flags for unreliable text and redacted regions, with page and box.blocked or rejected files. Their bytes are purged.
A taint map, tainted_paths, naming every file-derived value.Findings evidence and detector scores.

FoxNose renders every file with its own pinned renderer: documents become PDFs, PDF pages are rasterised, images are re-encoded. That rendering defines what a person sees. Text comes only from OCR of it, never from the file's text layer, and is delivered unaltered: the PII screen reports personal data but does not mask it.

Redaction. A region located as unreadable, hidden or below the legibility floor is painted over in the page images (redacted_png) and listed in redacted. Tiny text that OCR misses inside a line it otherwise read is not located, so it is not redacted.

Unreliable text. Latin and Cyrillic text is delivered. A line or page in another script is replaced by text not recognised: unsupported script. Low-confidence words and pages below the minimum text height are delivered and flagged. See content_flags.

Supported inputs

An agent_ready collection accepts the kinds its policy allows (allowed_kinds): image and document. Anything else is rejected as unsupported_format. A storage_only collection also accepts other file types and archives. The format is identified from content, not from the MIME type or extension. Details are on File Checks.

  • Images: JPEG, PNG, WebP, GIF and HEIC/HEIF, single frame.
  • Documents: PDF (up to 100 pages), DOCX, ODT, RTF, TXT and Markdown.
  • Rejected: encrypted or XFA PDFs, password-protected documents, documents with macros, embedded objects or linked external content, animated images, empty files.
  • storage_only only: archives, spreadsheets, presentations and .doc.

How a file becomes agent-ready

  1. Scan. The original is malware-scanned before anything parses it. An infected file is blocked and purged.
  2. Render. The file is rendered in a disposable sandbox with no network access.
  3. Read and check. OCR reads the pages. Detectors look for hidden text, unreadable regions, Unicode smuggling, explicit imagery, prompt attacks, sexual content and PII.
  4. Verdict. The findings and the collection's policy produce a verdict.
  5. Safe copy. An image-only PDF of the redacted pages is stored (a PNG for an image).
  6. Publish. The record, its search rows and embeddings go live in one transaction. From here, agents can read and search the file.

Trust model

Everything that comes from the file is untrusted, the filename included, and is marked so twice:

  • For the model: the value sits inside an <<untrusted-upload:BOUNDARY>> block that says to treat it as data, not instructions. The boundary is random per response and cannot be closed from inside.
  • For your code: tainted_paths lists every file-derived path, and over MCP each such value in structuredContent is wrapped as {"$untrusted": …}.

The verdict, its reasons and the flags travel with the content. Fields your application writes, such as file.name and the collection's own fields, are not tainted. The exact format is in the references: over MCP and over the Flux API.

Isolation. End-user uploads go only into strict-reference collections, where every file belongs to an owner record the calling key can access. A non-strict files collection is shared by everyone who can read it; use it for your own team's files.


Processing modes

agent_ready (default)storage_only
Malware scanYesYes, the only automatic block
Rendering, OCR, detectors, moderationYesNo
SearchPage text, chunk-level, with embeddingsMetadata and your fields only
Agents receiveText, flags, verdict, page-image linksMetadata, marked content not processed: storage-only collection
Safe copyYesNo
Moderation rulesAvailableNot available

In both modes agents never get the original; people download it through the dashboard or the Management API. processing can be changed only while the collection holds no files. A storage_only collection refuses a file whose content contradicts its declared type or extension, such as a program named invoice.pdf.


Verdicts and findings

Each analysis records findings, each with a severity: info, suspicious or block. The highest severity sets the verdict:

VerdictMeaning
cleanNothing suspicious or block.
suspiciousAt least one suspicious finding. With suspicious_action: deliver (default) the file is published with the verdict; with quarantine it waits for a reviewer.
blockedAt least one block finding. The bytes are purged and a tombstone remains.
rejectedUnsupported format, disallowed kind, over a limit, or processing failed.

Agents see only clean and suspicious records, with reasons listing the finding kinds. A customer moderation rule appears as policy_rule:<rule id>. The uploader never sees verdicts: the status endpoint returns processing, accepted or rejected with one of malware, prohibited_content, unsupported_format, too_large, processing_failed.

Finding kinds

KindWhat it reportsDefaultCan be set to
malwareThe malware scan found an infection.blockNot overridable
explicitExplicit imagery (label Explicit, confidence 50+) on any page. agent_ready only.blocksuspicious, info, with acknowledge_explicit_delivery: true
moderationAnother moderation label.suspiciousblock, info
policy_ruleOne of your moderation rules failed. Needs moderation turned on.The rule's actionSet by the rule
hidden_text (concealment)Text the rendering does not draw: invisible PDF text, zero-area clipping, hidden runs, fields and sections, text in the background colour, tiny fonts, collapsed scale, text lost in conversion.suspiciousblock
hidden_text (annotations)Comments, tracked changes, field instructions, alt text.infosuspicious, block
low_legibility_textText in the image below the legibility floor. Redacted.suspiciousblock
unicode_smugglingInvisible or direction-changing code points. Stripped.suspiciousblock, info
prompt_attackThe prompt-attack screen flagged the text.suspiciousblock
sexual_textSexual prose.suspiciousblock
piiPersonal data. Lists entity types only, never values.infosuspicious, block
text_unreliableunsupported_script, low_confidence or low_resolution.infosuspicious, block
unread_text_regionA text-like region OCR did not read. Redacted.infosuspicious, block
mixed_scriptWords mixing Latin and Cyrillic letters.infosuspicious, block
active_contentA PDF carries active content. Management API only.infoNot overridable

An override outside the listed range is refused when the policy is saved.

Explicit imagery is blocked by default, which also blocks some legitimate files, such as clinical photos. Lowering explicit requires acknowledge_explicit_delivery: true, because the page images then reach your agent and its model provider. It does not restore files already blocked. Explicit prose is sexual_text, suspicious by default, so literature and health material is not rejected.

Active content

active_content reports what a PDF viewer could run: JavaScript, launch actions, embedded files, rich media, form submissions and automatic actions. FoxNose runs none of it. The finding is info, never affects the verdict or reaches agents, and holds only counts per kind, never a script or address. It is returned by the Management API in the file's findings. A PDF whose active-content check did not complete is not clean for original_access: when_clean.

Policy

Each files collection has a policy: what to do with suspicious files (deliver or quarantine), severity overrides within the ranges above, which kinds are allowed, when to analyse tables, moderation rules, and original access. Read and replace it with the files policy endpoints.

Every change to the policy is saved as a version. A stricter policy withholds files verdicted under the old version from delivery and search until they are re-verdicted; a looser one withholds nothing and can release quarantined files. Changes reach delivery within about a minute.


A hosted upload link lets someone without a FoxNose account upload up to 10 files to a record. Your application creates one with the Management API, or an agent requests one with request_upload. The link expires (30 minutes by default, up to 24 hours) and its token sits in the URL fragment, so it never reaches a server log.

The page shows each file as uploading, checking, received or not accepted, with the reason when the sender can fix it (format, size, failed processing). Security and policy outcomes are never shown to the sender.


Safe copy and downloads

People download files through the Management API or the dashboard. Agents never do.

Safe copy

Every agent_ready file has a safe copy: its redacted page images in a PDF (a PNG for an image). It has no scripts, forms, annotations, fonts, metadata or text layer, so nothing in it can run. It is not searchable and is at screen resolution. Its pages are also available one by one as PNGs.

Downloads

The Management API returns the original, the safe copy and single pages, each as a link that expires within five minutes. The original carries a warning when the file has active content or a suspicious finding. The record's file block says whether each download is available, and a refused download answers 409 with a reason.

While a newer analysis is processing, failed or quarantined, the last published version is served. A file quarantined on its first analysis is served to reviewers only. Downloads of a quarantined file are audited.

Original access

original_access controls whether the original can be downloaded, for every caller, reviewers included. It changes nothing else, and switching back to allowed restores downloads.

ValueThe original is downloadable
allowedWhenever a download is allowed at all.
when_cleanOnly with no active_content and no suspicious or higher finding; a PDF also needs a complete active-content check. Otherwise 409 original_withheld.
disabledNever. 409 original_disabled.

storage_only collections do not accept when_clean (409 original_access_requires_agent_ready).


Moderation

Base moderation checks every page of an agent_ready collection and keeps its labels internal. Turn on moderation for a files collection to expose those labels and act on them. It is a setting of the collection: Settings → Files in the dashboard, or Turn On Moderation in the API. It adds no file units, and it adds:

  • a read-only moderation field on each record, written once its labels are stored, with the model version and the highest confidence of each label;
  • moderation_rules in the policy.

A rule names a label or category, a confidence threshold and an action (info, suspicious or block); see the rule format. Up to 50 rules per collection. Rules only add findings and never lower explicit.

Turning it on creates no rules and changes no verdict; published files that already have moderation results get their stored labels without being re-processed. It works in agent_ready collections only (409 addon_requires_agent_ready). Turning it off removes the rules; values already written stay on the record until the file is re-analysed or erased.


Where file data lives

DataWhere
Upload, malware scan, conversion of some image formatsUnited States
Original, staged copy, rendered pages, OCR output, moderation and screening results, safe copyFoxNose storage in the project's region
Content, findings, embeddings, search rowsFoxNose databases in the project's region

Each upload uses a single-use token FoxNose issues. Once the scan is clean, the file is copied into FoxNose's encrypted storage in the project's region (Frankfurt for the EU zone), and all further processing happens there.

Erasure. Deleting a record or its collection erases every FoxNose copy of the file: all versions of the original, every derivative, search rows, embeddings, file-derived content and findings evidence. Incomplete erasures are retried and alerted on. Database backups expire on their own schedule.


Was this page helpful?