Quickstart #
Install both the repository root and the reference Python client from the same source checkout. The similarly named package on PyPI is unrelated.
python -m pip install -e . -e sdk/python
from warden_guard import WardenClient
safe = WardenClient(local=True, fail_open=False).guard(untrusted_text)
execute(safe)Reason-code matrix
Observed regression outcomes for each implemented reason code. They are not guarantees for every payload.
11 reason codes shown
| Reason | Fast | Thorough | Context | Caller action |
|---|---|---|---|---|
| PROMPT_INJECTIONPrompt injection | SANITIZE | SANITIZE | None | Use the sanitized payload and keep the original instruction untrusted. |
| ROLE_OVERRIDERole override | SANITIZE | SANITIZE | None | Preserve the caller's role and review the sanitized payload. |
| WEB3_INJECTIONWeb3 injection | SANITIZE | SANITIZE | None | Require explicit policy authorization before any wallet action. |
| HIDDEN_UNICODEHidden Unicode | SANITIZE | SANITIZE | None | Inspect the detection and use normalized or sanitized text. |
| ENCODING_TRICKEncoding trick | SANITIZE | SANITIZE | None | Treat the encoded block as data and inspect before use. |
| STATISTICAL_ANOMALYStatistical anomaly | SANITIZE | SANITIZE | None | Review the combined signals before allowing an action. |
| CORPUS_MATCHCorpus similarity match | ALLOW | SANITIZE | None; thorough depth required | Use thorough mode when corpus-similarity coverage is required. |
| DRAIN_ADDRESSDrain address | BLOCK | BLOCK | context.expected_addresses | Stop the transfer and verify the intended recipient out of band. |
| TOOL_HIJACKTool-call hijack | SANITIZE | SANITIZE | None | Keep the payload separate from the real tool dispatcher. |
| SECRET_EXFILSecret exfiltration | BLOCK | BLOCK | None | Do not reveal the requested secret; stop the action. |
| MALICIOUS_LINKMalicious link | SANITIZE | SANITIZE | None | Do not follow the flagged link; use the sanitized payload. |
No reason codes match these filters. Clear a filter to restore the full matrix.
Core concepts #
| Action boundary | Warden evaluates untrusted output before the caller invokes a consequential handler. |
|---|---|
| Decision | ALLOW continues under caller policy, SANITIZE returns transformed text, and BLOCK withholds the proposed action. |
| Evidence | A qualifying decision may produce a signed APA record separate from the live response. |
| Signature boundary | A valid signature proves record integrity under the applicable key. It does not prove universal safety. |
Decision model #
| Field | How to use it |
|---|---|
| Decision | ALLOW, SANITIZE, or BLOCK is the operational result. |
| Risk | The severity band comes from deterministic scoring and hard gates; it is not the decision. |
| Reason | The machine-readable code names the detector that fired. Threat classes deduplicate related reasons. |
| Confidence and score | Diagnostic evidence used by the engine, not a probability of safety. |
| Depth | Fast and thorough do not run identical checks. CORPUS_MATCH is thorough-only. |
Integration patterns #
Python supports local in-process enforcement. The source-built TypeScript client calls the hosted endpoint and has no local scanner engine. LangChain and LlamaIndex guards ship with the Python SDK; direct HTTP, x402, OnchainOS, and MCP paths are documented on the integration route.
Evidence and APA #
An Agent Protection Attestation binds a canonical record to an issuer signature. Local verification can establish whether the bytes match the signature under an applicable key. Freshness, revocation, subject identity, and issuer-key provenance remain separate checks.
Transparency verification #
The public log exposes hash-chained entries and checkpoint state. A continuous unanchored chain detects local inconsistency, but cannot by itself expose a complete, internally consistent rewrite.
Endpoint audit contract #
The endpoint service runs a fixed battery against a public endpoint the caller is authorized to test. Its output is point-in-time evidence, not certification, and does not predict every future response.
Known patterns are not the full attack space #
- Fast and thorough depth do not run identical checks.
- Novel phrasing can evade deterministic and corpus-backed coverage.
- Expected-recipient context is required for the strongest recipient-mismatch gate.
- Hosted availability and timeout policy belong in the caller's enforcement design.
- Do not log pasted secrets or private payloads to analytics.
Troubleshooting #
- Timeout or network error
- Fail closed on consequential paths, surface the unavailable state, and retry only under caller policy.
- Malformed response
- Reject it as unusable evidence; do not infer a verdict.
- Unexpected ALLOW
- Confirm depth, context, payload limits, and the documented detector boundary.
- Invalid signature
- Stop using the record and inspect version, issuer key, canonicalization, freshness, and revocation independently.