Guardrails for Collections

Guardrails record who wrote every revision of a record, mark the fields whose content came from an untrusted source, check those fields for hidden characters, hidden markup and risky links, and tell agents which fields are tainted when they read the record.


Writers

Every revision records the writer that produced it.

WriterWhoTrusted by default
memberA team member, through the dashboard or the Management API with a user sessionYes
management_keyA Management API keyYes
systemFoxNose itselfYes
flux_keyA Flux API key writing through Flux RESTNo
mcp_agentA Flux API key writing through MCP create_record or update_recordNo

Content from an untrusted writer is tainted. Content from a trusted writer is trusted: FoxNose does not look at what a trusted writer stores, so a backend that stores text written by someone else declares it untrusted (see Declaring untrusted content).

Trusting a key

A collection's policy lists Flux API keys whose writes are trusted in trusted_keys, for example your own backend writing through Flux REST.

A key listed in trusted_keys is trusted for Flux REST writes. For MCP writes it is trusted only when the policy also sets acknowledge_agent_trust to true; otherwise its mcp_agent writes stay untrusted. A policy with a non-empty trusted_keys and no acknowledgement is rejected with acknowledge_required.

A writer FoxNose cannot identify is never trusted.


Declaring Untrusted Content

Two mechanisms mark content as untrusted regardless of who writes it. Both can only add taint.

The provenance object. A Management API or Flux REST write accepts an optional top-level provenance object next to data:

{
  "data": { "subject": "Refund", "body": "..." },
  "provenance": { "untrusted_fields": ["body"], "source": "support-inbox" }
}
  • untrusted_fields lists top-level fields of the collection's schema. A name that is not a top-level field returns 422 with invalid_provenance.
  • source is an optional label matching [a-z0-9_-]{1,32}. It is stored with each field the declaration taints and appears per path in the trust object.
  • A malformed provenance returns 422 with invalid_provenance.
  • MCP create_record and update_record take no provenance argument.

The untrusted field flag. A schema field with untrusted: true is always tainted, whoever writes it. Use it for fields such as customer_message.

untrusted is a flag on top-level fields only.


The Taint Map

Taint is tracked per top-level field. A tainted field is tainted in full: every locale, array item and nested value. Paths are JSON Pointers: /body, /a.b for a key containing a dot, /x~1y for a key containing /.

Each write is compared with the published revision of the record:

  • A field whose value differs from the published revision, or is new, takes the origin of this write: its writer, whether that writer is trusted, and its source.
  • A field whose value is unchanged keeps its origin.
  • A field the write removes leaves the map.
  • Declared fields and untrusted fields are tainted.
  • A trusted edit of a tainted field clears its taint. A trusted edit of another field does not. An untrusted write to a trusted field taints it.

Drafts keep their own map, maintained the same way, and publishing a draft reconciles it with the published revision.


Modes

The collection policy has a mode:

ModeBehaviour
offProvenance is recorded. Nothing is checked and no trust metadata is delivered.
provenanceProvenance is recorded, tainted fields are checked in process, and agents receive trust metadata.

A collection starts in provenance when it is created. A collection that predates guardrails is off until changed. Files collections have no guardrails policy.

In provenance mode writes are never held. A write is readable at once, together with its taint.

Reading and changing the policy

GET /v1/:env/collections/:collection/guardrails-policy/
PUT /v1/:env/collections/:collection/guardrails-policy/

GET requires read access to the collection structure and PUT requires update access. Each change creates a new numbered version; the response carries version, body, config_hash and created_at. A PUT identical to the live body changes nothing. GET on a collection without a policy returns version, config_hash and created_at as null, with mode off. A collection holds up to 10,000 policy versions; beyond that PUT returns 409 with policy_version_limit. A Files collection returns 409 with guardrails_not_for_files.

{
  "mode": "provenance",
  "overrides": { "hidden_markup": "block" },
  "trusted_keys": ["3f1c2a64-8d6b-4a71-9e0f-5b2f0c7d1a10"],
  "acknowledge_agent_trust": true,
  "link_allowlist": ["example.com", "*.example.org"]
}
  • Name
    mode
    Type
    string
    Description

    off or provenance. If omitted, keeps the collection's current mode.

  • Name
    overrides
    Type
    object
    Default
    default:{}
    Description

    Severity per finding kind. See Severities and overrides.

  • Name
    trusted_keys
    Type
    array<string>
    Default
    default:[]
    Description

    Flux API key uids whose writes are trusted. Up to 100.

  • Name
    acknowledge_agent_trust
    Type
    boolean
    Default
    default:false
    Description

    Required to be true when trusted_keys is not empty. Makes the listed keys trusted for MCP writes as well.

  • Name
    link_allowlist
    Type
    array<string>
    Default
    default:[]
    Description

    Hosts exempt from external_link and remote_image findings (not from lookalike_host). external_link is reported only when this list is not empty. example.com matches that host only. *.example.com matches its subdomains, not example.com itself. Up to 100.


The In-Process Checks

In provenance mode, the tainted fields of every write are checked inside the write. The stored value is never changed. A check produces findings; each finding has a kind, a severity and the path it was found in.

KindWhat it finds
unicode_smugglingInvisible and control characters, bidirectional overrides, and other characters that change what a reader sees without showing in the text
mixed_scriptWords that mix Latin letters with Cyrillic or Greek ones
hidden_markupHTML that hides text from a reader but not from a model: comments, text inside template, script, noscript and style elements, the hidden attribute, aria-hidden="true" elements with text, and inline styles that hide text (display:none, zero size or opacity, far off-screen positions)
linkLinks in text, Markdown and HTML attributes: script URLs (javascript:, vbscript:, file:, and data: URLs that are not small images), oversized data: images, remote images, lookalike hosts, and links to hosts outside a non-empty link_allowlist

Legitimate markup is flagged too: aria-hidden="true" elements with text and link titles are reported as hidden_markup.

Severities and overrides

Each kind has a default severity. A policy overrides it in overrides, using a kind or kind:sub_kind.

KindDefaultA policy may set
unicode_smugglingsuspiciousinfo, suspicious, block
mixed_scriptinfoinfo, suspicious, block
hidden_markupsuspiciousinfo, suspicious, block
link:script_urlsuspicioussuspicious, block
link:data_url_oversizedsuspiciousinfo, suspicious, block
link:remote_imagesuspiciousinfo, suspicious, block
link:lookalike_hostsuspiciousinfo, suspicious, block
link:external_linkinfoinfo, suspicious, block

Findings below block are recorded and reported; the write succeeds. overrides accepts only the keys in this table; link alone, or any other key, is refused with unsupported_in_this_phase. A severity outside the allowed range returns override_out_of_range.

Refusals

A write with a tainted field carrying a block finding is refused with 422, and nothing is stored:

{
  "code": "content_refused",
  "public_reason": "hidden_markup",
  "message": "The content was refused by the collection's guardrails policy",
  "error_code": "content_refused",
  "detail": { "public_reason": "hidden_markup" }
}

public_reason is the finding kind: unicode_smuggling, hidden_markup, link, or mixed_script when a policy raises it to block. The response does not say which field or which characters matched.


Where Agents See Trust

MCP

Every MCP result that carries a record from a collection in provenance mode has trust metadata in _meta["foxnose.net/trust"]. _meta is additive in MCP; clients that do not know the key ignore it. For get_record the value is the trust object. For lists and search hits it is:

{
  "version": 1,
  "source": "record_write",
  "items": [
    {
      "index": 0,
      "record_key": "refund-4821",
      "version": 1,
      "source": "record_write",
      "provenance": "recorded",
      "screened": false,
      "path_format": "json_pointer",
      "tainted_paths": ["/body"],
      "writers": { "/body": "mcp_agent" },
      "sources": { "/body": "support-inbox" }
    }
  ]
}

Each item is the trust object of the record at structuredContent.items[index].

The hosted MCP endpoint returns guardrailed records with _meta. The opt-in FastMCP transport cannot deliver _meta, so it refuses reads of guardrailed collections with trust_requires_native_transport.

REST and structured content

A Flux API with trust_delivery set to metadata adds the trust object as _sys.trust to records in REST bodies and in MCP structuredContent. With off, _sys.trust is absent. New Flux APIs start with trust_delivery: metadata; existing ones are off until changed.

{
  "_sys": {
    "key": "refund-4821",
    "revision": "7b1e9c",
    "trust": {
      "version": 1,
      "source": "record_write",
      "provenance": "recorded",
      "screened": false,
      "path_format": "json_pointer",
      "tainted_paths": ["/body"],
      "writers": { "/body": "mcp_agent" },
      "sources": { "/body": "support-inbox" }
    }
  },
  "data": { "subject": "Refund", "body": "..." }
}
  • Name
    version
    Type
    integer
    Description

    Always 1.

  • Name
    source
    Type
    string
    Description

    Always record_write. A consumer treats a value it does not recognise as untrusted.

  • Name
    provenance
    Type
    string
    Description

    recorded when the revision's writers were recorded; unknown for a revision written before recording, in which case tainted_paths is empty.

  • Name
    screened
    Type
    boolean
    Description

    false: the in-process checks run at write time and their findings are visible to the team, not to agents.

  • Name
    path_format
    Type
    string
    Description

    Always json_pointer.

  • Name
    tainted_paths
    Type
    array<string>
    Description

    The record's tainted top-level fields, also when a read narrows the returned fields.

  • Name
    writers
    Type
    object
    Description

    Writer type per tainted path. Principal ids are never delivered to agents.

  • Name
    sources
    Type
    object
    Description

    Declared source label per tainted path, where one was declared.

tainted_paths, and the keys of writers and sources, are JSON Pointers relative to the record's data: the data object of a REST response, record.data for get_record, and items[i].data for list and search results in structuredContent.

Values of populated (referenced) records carry no trust metadata.

Team view

GET /v1/:env/collections/:collection/resources/:resource/revisions/:revision/guardrails/

Returns a revision's provenance and findings: provenance holds writers (with principal ids and the surface and tool of each write), writers_truncated, declared_fields, origins and tainted_paths; findings lists each finding's kind, sub_kind, severity, path, detector, detector_version, policy_version, detail and created_at. A revision keeps its most recent 100 writer entries; writers_truncated counts the older ones dropped.


What the Checks Do Not Do

  • Detectors are signals. A writer who knows the checks can write text none of them flags.
  • Visible prompt injection is delivered. The checks look for hidden characters, hidden markup and risky links. Text that asks a model to ignore its instructions, written in plain view, is not flagged and is returned like any other content.
  • Trusted content is trusted. Content from a trusted writer is not checked and carries no taint unless it was declared.
  • Enforcement is the agent's architecture. Trust metadata tells an agent which fields to treat as data. Whether the agent obeys is decided by how you build it: a model without tools that reads untrusted content, capability-based designs such as CaMeL, or the Rule of Two.
  • Policy changes apply to new writes. Existing revisions keep their recorded provenance and findings.

Was this page helpful?