signafAIde
Documentation menu

Checks file and wrapping by hand

signafaide protect writes the code change and the checks file for you (Quickstart). This page is the reference for doing it by hand, and for projects that still use the checks file version 1, wrapTools with strict (a protected tool), or the checks and rules commands. Everything here keeps working.

Version 2 #

signafaide protect and signafaide pull write version 2. SIGNAFAIDE_CHECKS=<path> names another file, and SIGNAFAIDE_CHECKS=0 turns checks off. The file is read again when it changes, and the new version applies from the next call, without a restart.

keymeaning
formatsignafaide-checks/2
checkseach of secret, address, changed_tool, fingerprint and hidden_instruction, true or false
toolsper tool: protect (true or false), mode (optional, watch or enforce) and disclose (only with protect: true)
addressesthe allowlists of the address check, below
rulesnull, or local rules: {"default", "rules"}, as in Rules, without limit, state or exceptions
ruling_timeout_msoptional: how long a protected call waits for its ruling, 1 to 60,000 ms; 10,000 by default
  • **protect: true** makes the tool's calls wait for a ruling, stop when none comes (unless the console says let it run), and send exactly the fields in disclose that a rule can use.
  • **mode** is the state of the checks on your machine for that tool: "enforce" (On) blocks what they find, "watch" (Calibrating) notes it. It is "enforce" for a protected tool and "watch" for any other tool unless the file says otherwise. A tool protected by local rules alone, with no account, is "protect": false, "mode": "enforce".
  • **disclose** is the list of fields you approved for sending, as JSON Pointers (/amount, /to/0), written by signafaide pull. At most 64.

Unknown keys are errors. A key, check, operator or value the format does not have, a key of the other version, or disclose on a tool that is not protected makes the file invalid: every checked call then fails with the error code state, naming the file and the key, and signafaide checks status exits 1. An edit that breaks a file already in use leaves the previous version in force and prints one error line.

Version 1 #

A version 1 file keeps its meaning, and the SDK reads both. It has one mode for every tool, and strict, fail and disclose per tool:

JSON
{
  "format": "signafaide-checks/1",
  "mode": "watch",
  "checks": {
    "secret": true,
    "address": true,
    "changed_tool": true,
    "fingerprint": true,
    "hidden_instruction": true
  },
  "tools": {
    "refund": {"strict": true, "fail": "closed", "disclose": ["/amount"]}
  },
  "addresses": {
    "hosts": [],
    "cidrs": [],
    "resolve": false
  },
  "rules": null
}
  • **mode**: "watch" (Calibrating) never blocks; a finding is a note with what On would have done. "enforce" (On) blocks. It applies to the checks on your machine and the local rules; the rules in the console have their own state, Calibrating or On.
  • **strict: true** makes a protected tool, as protect: true does in version 2: the tool asks the witness for a ruling and runs only on allow.
  • **fail** is "If signafAIde can't be reached": "closed" (Stop, the default) stops a protected call that gets no ruling, with no_ruling (rules_unavailable when the witness could not load the rules, no_key without an API key). "open" (Let it run) runs it, and the outcome says no ruling was received. A setting made in the console wins.
  • **disclose**: as in version 2, but written by hand.

signafaide protect and signafaide pull rewrite a version 1 file as version 2.

Internal address allowlists #

Allow hosts and networks your agent is meant to reach in addresses: hosts takes exact lowercase names or *. and a suffix, cidrs takes IPv4 or IPv6 networks. The project's rules have the same allowlists, set in the console. A name that does not resolve is never a finding.

JSON
"addresses": {
  "hosts": ["billing.internal", "*.svc.cluster.local"],
  "cidrs": ["10.20.0.0/16"],
  "resolve": false
}

With "resolve": true the client also looks up names that are on no allowlist, and a name that resolves to an internal address is a finding. It is off by default, because a lookup takes time.

Wrapping by hand #

  • One function. record(fn) records it; protect(fn, { args: [...] }) records and protects it. In Python, @signafaide.record and @signafaide.protect. args names positional arguments so a rule can find them by name.
  • Framework tools. wrapTools(tools) (Python wrap_tools) records LangChain, OpenAI Agents SDK and Vercel AI SDK tools; protect one with "protect": true in the checks file. Frameworks.
  • Protected wrappers. record(fn, { strict: true }) (Python strict=True), and the gateway's --strict and --strict-tools a,b, protect a tool as version 1 does. In TypeScript a protected call returns a Promise, so the checks file cannot protect a plain synchronous wrapped function: its calls fail with state, naming the tool and the fix (make it async, or protect it in code).
  • Install, wrap and verify, step by step: TypeScript and Python, and one page for each framework.

Errors in code #

A call that did not run raises CheckError (a block is its subclass SignafaideBlocked), with code, check, rule, the rule set version and the missing fields:

Python

from signafaide.checks_runtime import CheckError

try:
    refund("A-1002", 900)
except CheckError as e:
    print(e.code, e.check, e.rule, e.rules_version, e.missing)

TypeScript

import { CheckError } from "signafaide";

try {
  await refund({ orderId: "A-1002", amount: 900 });
} catch (e) {
  if (e instanceof CheckError) console.log(e.code, e.check, e.rule, e.rulesVersion, e.missing);
}

The codes are blocked, no_ruling, rules_unavailable, no_key, withheld and state; each is in Errors.

The checks and rules commands #

commanddoes
signafaide checks statuswhether checks are on, each protected tool with the fields it sends, the fields the rules need that it does not send, the held rules and list of known bad tools, and any problem (exit 1)
signafaide checks approve <tool>approves a changed tool again, when approvals are kept on this machine
signafaide rules pullfetches the project's rules now, without changing the checks file
signafaide rules showprints the held rule set version, as the signed JSON document
signafaide rules test <tool> '<arguments JSON>'evaluates a call against the held rules and local rules, like signafaide check with the arguments as JSON