Skip to content

v0.1.0 - first public release

Latest

Choose a tag to compare

@Radmo3 Radmo3 released this 10 Nov 21:29
· 11 commits to main since this release
afd66a9

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.

demo

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, never allow. A block is never downgraded.
  • Untrusted text is data. The agent's description and metadata are 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 as to.
  • Tamper-evident audit. Every record is hash-chained and Ed25519-signed; GET /v1/audit/verify and scripts/verify-audit.ts detect 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):

  1. Denylisted recipient hidden behind a trusted token contract (USDC.transfer(bad, x)) bypassed every address check
  2. Reputation layer failed open on total provider outage
  3. "Unlimited" approval threshold was 2^255; Permit2's uint160::MAX and 2^200 passed as bounded (now ≥ 2^128)
  4. Solana SetAuthority on an agent-owned token account (full takeover, no transfer instruction) only warned
  5. Bounded approval to an EOA only warned (new no_eoa_approvals rule)
  6. Negative native value passed the schema as a no-op allow
  7. Prompt injection via description could forge a clean-looking explanation
  8. 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.

demo

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, never allow. A block is never downgraded.
  • Untrusted text is data. The agent's description and metadata are 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 as to.
  • Tamper-evident audit. Every record is hash-chained and Ed25519-signed; GET /v1/audit/verify and scripts/verify-audit.ts detect 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):

  1. Denylisted recipient hidden behind a trusted token contract (USDC.transfer(bad, x)) bypassed every address check
  2. Reputation layer failed open on total provider outage
  3. "Unlimited" approval threshold was 2^255; Permit2's uint160::MAX and 2^200 passed as bounded (now ≥ 2^128)
  4. Solana SetAuthority on an agent-owned token account (full takeover, no transfer instruction) only warned
  5. Bounded approval to an EOA only warned (new no_eoa_approvals rule)
  6. Negative native value passed the schema as a no-op allow
  7. Prompt injection via description could forge a clean-looking explanation
  8. 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.