IsMalicious gateway filters

A Python 3.11+ server implementing Obot's MCP filter contract and ToolHive's request validation webhook. It has no runtime dependencies beyond the standard library.

This applies an administrator-configured policy to selected tools/call fetch tools. It is not an optional scanner tool offered to the model. Configure only tool names and URL arguments you know, for example {"fetch":"url"}.

Policy and limits

• Before a selected fetch: send the original HTTP(S) URL to GET /gate/url?u=.... Query, commas and fragments are preserved. The reputation check does not fetch the destination.

• Obot selected responses: serialize the whole result, including nested structuredContent and text blocks, to POST /gate/scan in fast mode before forwarding. Refuse image/audio/embedded resource content rather than claiming to inspect it.

• ToolHive inspects requests only. Its validating webhook does not inspect tool results, streaming response content or tool metadata.

• Admit only a valid top-level allow; refuse warn, block, malformed data, API errors, timeout, quota 429, redirected API calls and links_truncated. Never retry a 429 or silently truncate input.

• Enforce 1 MiB on the UTF-8 serialized envelope and scan body. TLS verification is enabled for Gate; credentialed requests never follow redirects. Timeout is 15 seconds per Gate request.

• allow means this policy did not block. Unknown inner link reputation may still be present and does not prove a URL or content benign. No detector accuracy claim is made by the synthetic fixtures.

• MCP error responses, notifications, malformed/unmatched messages, binary media, uncorrelated responses and other MCP methods are outside the supported response scope. Obot's native gateway may pass malformed/uncorrelated traffic without invoking a filter; it must not be advertised as universally inspected.

• Gate /gate/scan and /gate/url use the separate scan quota. Do not substitute /check quota counts or freeze plan prices into configuration.

• The original authorized payload is returned without mutation. sanitized_content is never substituted.

Related MCP server: MCP-Gatekeeper

Run

Clone this repository at a release tag or commit, then:

python3 -m pip install .
ismalicious-gateway-filter --port 8099

Supply ISMALICIOUS_API_KEY, ISMALICIOUS_API_SECRET, and ISMALICIOUS_FETCH_TOOLS using your secret/deployment manager. The latter is a JSON map such as {"fetch":"url"}. Credentials are available from your IsMalicious account.

The server binds to 127.0.0.1 by default. For remote HTTP use, place it behind an authenticated TLS reverse proxy and restrict network access. Never expose the plain HTTP listener to an untrusted network.

Obot

The recommended Obot hosted deployment is uvx, which uses stdio and does not expose an HTTP listener. Import/configure the fields in examples/obot-filter.json, set the key/secret and tool mapping through Obot's sensitive configuration fields, and ensure the selector identifier matches the actual upstream tool name.

The tool name is ismalicious_filter. Obot sends a SessionMessageHook envelope whose message contains the JSON-RPC request or response. The filter returns accept, mutated:false, the original message, and a generic reason. Use only supported selected tool traffic; do not apply a wildcard selector to all MCP methods.

For a remote deployment, /mcp implements stateless Streamable HTTP with JSON replies and requires Authorization: Bearer <ISMALICIOUS_FILTER_TOKEN>. Configure that same header as a sensitive Obot remote-server field. This is not the older Obot HTTP webhook accept-by-status contract. Do not configure /mcp as an HTTP webhook.

Native validation uses a real HTTP upstream and ReverseProxy with Obot's hook processor, not a running full Obot service. It covers same-exchange correlation; it does not cover deployed multi-replica correlation. Native validation pins Obot to cf4337b8966c8e76a6e5e896c8f122a8fa4e3305. It starts this server and connects the actual MCP Go SDK before exercising the native gateway hook processor for request refusal and JSON/SSE response suppression.

ToolHive

Set ISMALICIOUS_WEBHOOK_SECRET on this service and put the same secret in the file referenced by examples/toolhive-webhooks.yaml. The service requires ToolHive's HMAC-SHA256 signature and a timestamp within five minutes. This checks expiration, not unique nonce consumption: a valid signed payload can be replayed within the window. Protect this endpoint with TLS and restrict access to ToolHive.

thv run --webhook-config examples/toolhive-webhooks.yaml <your-fetch-server-image>

Use failure_policy: fail, TLS validation, and a 20-second webhook timeout. The ToolHive chain must parse MCP requests before the validating webhook; the native middleware bypasses a request with no parsed MCP context. Configuration that omits the webhook provides no enforcement. Unselected tools are admitted without a Gate call.

Native validation pins ToolHive to 3ca3c8f71152ad6e109dbb881be13ceb17a2cf3c. It starts this webhook, uses the real signing client and validating middleware, and asserts the next handler is never called for block/warn/429/invalid decisions. Loopback HTTP/TLS bypass is enabled only in these synthetic local tests; production examples use HTTPS.

Verification

python3 -m unittest discover -s tests -v

For native validation, place clones named obot-native and toolhive-native beside this directory at the SHAs above, then run:

python3 native-tests/run.py

The runner copies an integration test into each isolated clone, invokes the actual native package, and removes the temporary test. ToolHive uses a generated targeted Taskfile with its native macOS linker/race flags, via pinned go-task 3.45.4. This does not install a system binary. Full ToolHive API/CLI container E2E and Obot multi-replica deployment remain separate validation scopes; these tests do not claim to cover them.

All API decisions in the native tests come from a local deterministic server with dummy credentials. They test protocol/enforcement behavior, not production account access or scanner accuracy. No real credentials are written to this repository or logged.

This contribution was developed with an AI assistant. The supported scope and limitations are explicit so operators and maintainers can assess it.