Repository navigation
Releases
v0.1.0 - first public release
First public release of AgentGuard: a vendor-neutral transaction guardrail layer for AI agents that hold crypto wallets.
An agent proposes a transaction → AgentGuard simulates it → evaluates the outcome against policy and counterparty reputation → returns allow | block | escalate with an operator-readable explanation and a hash-chained, Ed25519-signed audit record.
What's in the box
| Package | Purpose |
|---|---|
| @agentguard/core | Shared types, canonical JSON, hashing |
| @agentguard/policy | Chain-agnostic rule engine (11 rule kinds + custom rules), risk scoring, explanations |
| @agentguard/sim-evm | EVM adapter: calldata decoding, eth_call simulation, balance/approval diffs (viem) |
| @agentguard/sim-solana | Solana adapter: simulateTransaction, SPL token diffs, SetAuthority/CloseAccount detection |
| @agentguard/reputation | Pluggable address reputation (static lists, on-chain heuristics, HTTP intel), fail-closed |
| @agentguard/api | Fastify server: POST /v1/check, audit log + verify endpoint, HMAC request signing, rate limiting |
| @agentguard/sdk | TypeScript client + guard(signer) proxy that gates any signer |
Security properties
- Fails closed everywhere. Simulation outage, reputation outage, engine error, cache miss →
escalate, neverallow. Ablockis never downgraded. - Untrusted text is data. The agent's
descriptionandmetadataare sanitized, length-capped, and can never influence a verdict or forge an explanation. - Counterparties are decoded, not declared. Recipients inside ERC-20
transfer/transferFrom, swap routers, and SPL instructions are screened the same asto. - Tamper-evident audit. Every record is hash-chained and Ed25519-signed;
GET /v1/audit/verifyandscripts/verify-audit.tsdetect truncation or edits. - Timing-safe auth, SHA-256-hashed API keys, HMAC request signing with nonce/replay window, strict zod schemas with size limits, log redaction, production refuses to boot without keys.
- STRIDE threat model in
docs/THREAT_MODEL.md; residual risks documented there.
Adversarial findings fixed before release
Found by the in-repo adversarial + seeded fuzz suite (200 cases: zero 500s, zero allow on failed simulation):
- Denylisted recipient hidden behind a trusted token contract (
USDC.transfer(bad, x)) bypassed every address check - Reputation layer failed open on total provider outage
- "Unlimited" approval threshold was
2^255; Permit2'suint160::MAXand2^200passed as bounded (now≥ 2^128) - Solana
SetAuthorityon an agent-owned token account (full takeover, no transfer instruction) only warned - Bounded approval to an EOA only warned (new
no_eoa_approvalsrule) - Negative native value passed the schema as a no-op
allow - Prompt injection via
descriptioncould forge a clean-looking explanation - Trailing calldata bytes silently ignored by the decoder
Numbers
307 tests across 7 packages · npm run demo exercises 7 end-to-end cases on EVM and Solana with mock RPC clients (no network) · Node 22, TypeScript, ESM.
Not included
The per-agent behavioral baseline (@agentguard/behavior), which learns what "normal" looks like for each agent and blocks policy-compliant-but-anomalous transactions, is a separately licensed package. It plugs in through ServerOptions.behavior / AGENTGUARD_PROFILE_FILE; the public bootstrap degrades gracefully without it.
Known limitations
- Recipients reachable only through undecoded internal calls need a
traceCall-capable RPC. - Audit chain truncation is detectable only with an externally anchored head hash.
- Policy files are not yet signed.
- Audit reads are not yet tenant-scoped.
Licensed under Apache-2.0.
First public release of AgentGuard: a vendor-neutral transaction guardrail layer for AI agents that hold crypto wallets.An agent proposes a transaction → AgentGuard simulates it → evaluates the outcome against policy and counterparty reputation → returns allow | block | escalate with an operator-readable explanation and a hash-chained, Ed25519-signed audit record.
What's in the box
| Package | Purpose |
|---|---|
@agentguard/core |
Shared types, canonical JSON, hashing |
@agentguard/policy |
Chain-agnostic rule engine (11 rule kinds + custom rules), risk scoring, explanations |
@agentguard/sim-evm |
EVM adapter: calldata decoding, eth_call simulation, balance/approval diffs (viem) |
@agentguard/sim-solana |
Solana adapter: simulateTransaction, SPL token diffs, SetAuthority/CloseAccount detection |
@agentguard/reputation |
Pluggable address reputation (static lists, on-chain heuristics, HTTP intel), fail-closed |
@agentguard/api |
Fastify server: POST /v1/check, audit log + verify endpoint, HMAC request signing, rate limiting |
@agentguard/sdk |
TypeScript client + guard(signer) proxy that gates any signer |
Security properties
- Fails closed everywhere. Simulation outage, reputation outage, engine error, cache miss →
escalate, neverallow. Ablockis never downgraded. - Untrusted text is data. The agent's
descriptionandmetadataare sanitized, length-capped, and can never influence a verdict or forge an explanation. - Counterparties are decoded, not declared. Recipients inside ERC-20
transfer/transferFrom, swap routers, and SPL instructions are screened the same asto. - Tamper-evident audit. Every record is hash-chained and Ed25519-signed;
GET /v1/audit/verifyandscripts/verify-audit.tsdetect truncation or edits. - Timing-safe auth, SHA-256-hashed API keys, HMAC request signing with nonce/replay window, strict zod schemas with size limits, log redaction, production refuses to boot without keys.
- STRIDE threat model in
docs/THREAT_MODEL.md; residual risks documented there.
Adversarial findings fixed before release
Found by the in-repo adversarial + seeded fuzz suite (200 cases: zero 500s, zero allow on failed simulation):
- Denylisted recipient hidden behind a trusted token contract (
USDC.transfer(bad, x)) bypassed every address check - Reputation layer failed open on total provider outage
- "Unlimited" approval threshold was
2^255; Permit2'suint160::MAXand2^200passed as bounded (now≥ 2^128) - Solana
SetAuthorityon an agent-owned token account (full takeover, no transfer instruction) only warned - Bounded approval to an EOA only warned (new
no_eoa_approvalsrule) - Negative native value passed the schema as a no-op
allow - Prompt injection via
descriptioncould forge a clean-looking explanation - Trailing calldata bytes silently ignored by the decoder
Numbers
307 tests across 7 packages · npm run demo exercises 7 end-to-end cases on EVM and Solana with mock RPC clients (no network) · Node 22, TypeScript, ESM.
Not included
The per-agent behavioral baseline (@agentguard/behavior), which learns what "normal" looks like for each agent and blocks policy-compliant-but-anomalous transactions, is a separately licensed package. It plugs in through ServerOptions.behavior / AGENTGUARD_PROFILE_FILE; the public bootstrap degrades gracefully without it.
Known limitations
- Recipients reachable only through undecoded internal calls need a
traceCall-capable RPC. - Audit chain truncation is detectable only with an externally anchored head hash.
- Policy files are not yet signed.
- Audit reads are not yet tenant-scoped.
Licensed under Apache-2.0.
