Docs / Surface / scan-profiles

Scan Profiles

Scan profiles let you customize scanning behavior per use case: controlling which file types are accepted, size limits, automatic threat response, and what happens when a scan completes.

Each API key is linked to a scan profile, so different keys can have different scanning rules. No middleware, no conditionals in your code; scans made with a given key automatically apply that key's profile rules.

Profile settings

In the Surface dashboard, go to Scan Profiles in the sidebar and expand any profile to edit it:

Expanding a profile reveals its settings. File types are chosen by category, not typed in.

Auto-block IPs

When enabled on a profile, any IP address that uploads a file classified as malicious is automatically blocked from further uploads. This is the kind of threat response logic that normally takes days to build (rate limiting, block lists, enforcement middleware), and it is a single checkbox in the profile settings.

Reviewing blocked addresses

Blocks land on the Blocked IPs page in the sidebar, which lists every address auto-blocked for uploading a malicious file. Until you turn Auto-block IP on for at least one profile, the page stays empty.

Blocked IPs with auto-blocking not yet enabled. The page itself explains the prerequisite.

Blocked addresses are kept for your plan's retention window — see Data Retention if you need to look up why an address was blocked.

Why restrict file types?

Your users probably only need to upload a narrow set of file types: profile photos, PDFs, spreadsheets. Accepting everything means a user could upload an executable or script you never intended to receive. Restricting by type stops unexpected files before they ever reach the scanner and gives users a clear error if they accidentally select the wrong file.

Common use-case presets

New accounts start with a default profile that covers images, documents, config files, web content, archives, fonts, email, firmware, and mobile packages. Executables and scripts are excluded by default.

Built-in profiles

Every account starts with three profiles:

Engine configuration

Scroll down within the profile editor to the Engine Configuration section and use the toggles to choose which scan engines run for that profile. The Enable payload scanning switch above it controls whether raw text payloads can be scanned at all under this profile.

YARA and ML Classifier are core engines that always run. The toggleable engines below are for agentic/content security analysis:

• Prompt Injection: detects prompt injection attempts in text payloads
• Code Extraction: identifies embedded code, including SQL injection and XSS patterns
• Sensitive Data: finds credentials, PII, and API keys
• Tool Call Analysis: detects suspicious tool/function call patterns

Each of these engines also supports a sensitivity setting that filters what gets surfaced:

The detector itself always runs in full; sensitivity just post-filters the result. All engines are enabled by default.

<details> <summary>Configure via API</summary>

Each profile carries an engine_config JSON object that controls per-engine behaviour. Pair it with enable_payload_scan (boolean, default true) to toggle payload scanning per profile.

{
  "enable_payload_scan": true,
  "engine_config": {
    "prompt_injection":   { "enabled": true, "sensitivity": "strict" },
    "code_extraction":    { "enabled": true },
    "sensitive_data":     { "enabled": true, "sensitivity": "normal" },
    "tool_call_analysis": { "enabled": true, "sensitivity": "strict" }
  }
}

Set "enabled": false to skip an engine. code_extraction is a simple on/off toggle; the others support sensitivity.

</details>

Webhooks

Set a Webhook URL on a profile and Surface POSTs the full scan result to your server when each scan completes, signed with HMAC-SHA256. You can choose an auth type (API Key, Bearer Token, or Custom Header) and test the webhook from the profile panel before enabling it.

See Webhooks for the payload shape, signature verification examples, and handler patterns.

← Back to Surface docs