signafAIde
Documentation menu

Tool fingerprints

A tool fingerprint is a hash of what an agent is shown about a tool. It holds no text of the tool. Two checks use fingerprints: the changed tool check compares a tool with the version you approved, and the fingerprint check looks a tool up on the list of known bad tools, reported as malicious and reviewed. Every checked call records its tool's fingerprints, so they are also the only thing about a tool that leaves your machine by default.

How these checks fit with the others: Tool-call checks.

The four fingerprints #

fingerprintofcatches
toolthe tool's name, description and input schema togethera known tool, exactly
descriptionthe description text the agent is showna malicious description reused under another name
schemathe input schema, without its description and title wordinga change in what the tool accepts, not in how it is worded
serverthe MCP server's name and versiona known server; none for a tool that does not come from an MCP server

The framework adapters take the description and schema from the tool object. The gateway takes them from the MCP server's tool list and its name and version from the server's own greeting.

Changed tools and approving them again #

The first time a client sees a tool, it approves the tool's description and schema as they are. On every later call it compares them:

  • Only the description changed: a note. Someone should read the new wording and approve the tool again.
  • The schema changed: on a protected tool, a block until the tool is approved again, because the tool now accepts something it did not. On a tool that is only recorded it is a note that says it would have blocked.
  • At list time: the gateway approves a tool the first time a tools/list answer shows it and checks it each time one does, so a tool that changed between calls is caught before the agent sees it. On a protected tool, a changed schema or a tool that is not approved is left out of the list; a changed description alone is shown, with a line on stderr asking you to approve it again.
  • Tool approvals in the rule set: when the project's rule set lists approved tools, a tool missing from the list is blocked as not approved.

Approve it again in one step: on the console's Rules page (a new version of the rules), or on the machine with

Terminal
npx signafaide checks approve refund

when approvals are local. The block message names the command.

The shared list #

The list of known bad tools: fingerprints reported as malicious and accepted after review, shared by every project. Every plan reads it, and sandbox projects read the same list. It is what lets a tool reported at one customer be recognised by every customer's checks within minutes of its review.

  • Signed. The list changes by numbered updates, each signed by the service and chained to the one before; the service also serves signed snapshots. A client checks the signature, the sequence and the state of the whole list after each update, and refuses anything that does not fit.
  • Fetched every 60 seconds with an API key, and kept on the machine: a client that cannot fetch keeps the list it holds. Without an API key there is no list, and the fingerprint check finds nothing.
  • Fingerprints only. The list never holds a report's reason, description or who reported it.

On your machine a match blocks a protected tool and is a note on any other. At the witness, for a protected call, a match is a ruling of block with basis fingerprint.

Exceptions for your project #

When the shared list stops a tool you reviewed and trust, an owner or admin can accept it for one project: on the Rules page, Tools seen, the tool's Add exception, with a reason. That publishes a new signed rule set version whose fingerprint_exceptions names the fingerprint and the reason. Your clients and the witness then skip that one match; every other check still applies, and other projects and the shared list do not change. Removing the exception from the draft and publishing ends it. A whole-draft publish can drop an exception, never add one.

Report a tool #

On the console's Fingerprints page, or POST /v1/fingerprints/report with an API key (API reference), report a fingerprint you found malicious, with a reason.

  • Reviewed first. A report never changes the list by itself: signafAIde staff review it, so nobody can put a fingerprint on every customer's list alone. An accepted report reaches the list as an update.
  • The description is optional. You may add the tool's description text to help the review. For a description fingerprint the text must be the one it was made from (its SHA-256 equals the fingerprint), or the report is refused. Staff see it only to review the report, it is never shared, and it is deleted once the report is reviewed, or after 30 days if it is still waiting. The report keeps its row: the fingerprint, the reason, the outcome and the reviewer.
  • Counted by organisation. Staff see how many organisations reported a fingerprint, not how many reports, and whether only sandboxes did. Reports are limited per API key and per address.
  • Sandbox reports go into the same review queue, marked as from a sandbox.

The Fingerprints page also shows the list's last update and size, and which tools of your project the list matches.