Skip to content
DazzanovaPublic

About

Jaegr — red-team Solana AI agents before they touch funds. Devnet-only authorization workbench with explicit wallet-signed execution.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Jaegr

Red-team your Solana AI agent before it touches funds.

Track Solana SDK Framework Live LLM License


What Jaegr is

Jaegr is a security testing workbench for Solana AI agents. It runs a reference agent against adversarial scenarios, captures the Solana action the agent proposes, inspects the actual instruction bytes, evaluates them against a deterministic authorization mandate, and — only when explicitly approved in a connected wallet — simulates and executes on Solana Devnet.

The question it answers is deliberately narrow:

"Can this agent be manipulated into proposing a transaction the user never authorized — and if so, does an independent policy layer stop it?"

What Jaegr is not

  • Not a wallet. It never holds keys, never signs automatically, and never asks for a seed phrase.
  • Not a mainnet execution tool. Preparation, simulation, signing checks, submission, and confirmation are Devnet-only and enforced server-side.
  • Not an LLM-as-judge system. Authorization is decided by deterministic code, never by a model.
  • Not a production audit. It is a developer workbench for testing agent behavior and authorization boundaries before deployment.

Why this matters

AI agents are moving from suggesting actions to executing them: payroll, treasury operations, trading, and on-chain automation. An LLM that can propose a transaction is exposed to a class of failures traditional software does not have:

  • Prompt injection hidden in token metadata, invoices, web pages, or RPC responses.
  • Social engineering that persuades the agent to raise an amount or change a recipient.
  • Malicious context poisoning that redirects funds to an attacker address.
  • Replay and duplicate actions that repeat a previously approved transfer.

A model that "usually behaves" is not a security control. If the agent can directly sign, a single successful injection is a fund loss. The defense that scales is architectural: separate the proposal from the authorization decision, and make the authorization layer deterministic, inspectable, and independent of the model.

Jaegr exists to test exactly that boundary.


How it works

[ Adversarial scenario + untrusted context ]
                    │
                    ▼
       ┌─────────────────────────────────┐
       │        Reference AI agent       │ ──► Metric 1: Agent Resistance
       │  Groq / Gemini / Deterministic  │     RESISTED vs COMPROMISED
       └─────────────────────────────────┘
                    │  ActionProposal JSON (validated with Zod)
                    ▼
       ┌─────────────────────────────────┐
       │  Solana instruction adapter     │ ──► Builds & decodes the real
       │        @solana/kit              │     instruction binary
       └─────────────────────────────────┘
                    │  Decoded instruction
                    ▼
       ┌─────────────────────────────────┐
       │  Independent policy evaluator   │ ──► Metric 2: Authorization
       │  Integer-lamport invariants     │     PASSED vs BLOCKED
       └─────────────────────────────────┘
                    │  Authorized instruction
                    ▼
       ┌─────────────────────────────────┐
       │  Devnet simulation service      │ ──► Metric 3: Simulation
       │      simulateTransaction        │     SUCCESS / FAILED / RPC_ERROR
       └─────────────────────────────────┘
                    │
                    ▼
       Optional, explicit wallet-approved execution (Devnet only)

Three independent results, never one ambiguous score

Metric Outcomes What it measures
Agent Resistance RESISTED / COMPROMISED Did the model withstand the adversarial context and follow the legitimate task?
Authorization Enforcement PASSED / BLOCKED Did the deterministic evaluator permit or reject the proposed instruction under the mandate?
Devnet Simulation SUCCESS / EXECUTION_FAILED / RPC_ERROR / NOT_RUN Does the exact transaction execute against Devnet state?

These outcomes are independent by design. A proposal can be policy-blocked even though it would have simulated successfully. A policy-approved proposal can still fail simulation because of balance or account state. Collapsing them into a single score would hide the exact signal a security engineer needs.


Core features

  • Reference agent profiles — a deliberately naive assistant and a hardened, defensively prompted assistant, compared side by side.
  • Live and offline evaluation — Groq or Gemini for live model behavior; a deterministic adapter for reproducible, network-free runs.
  • Five adversarial scenarios — prompt injection, spend escalation, recipient substitution, unauthorized program calls, and replay.
  • Real instruction inspection — @solana/kit, @solana-program/system, and @solana-program/token build and decode the actual compiled bytes. The agent's prose is never trusted.
  • Deterministic authorization — integer-lamport limits, recipient allowlists, program allowlists, permitted action types, and duplicate action IDs.
  • Cumulative enforcement — multi-instruction proposals are summed, so several small transfers cannot collectively exceed the mandate.
  • Wire-level re-inspection — prepared and signed transactions are decoded from their real bytes; recipient, source, authority, amount, program, instruction count, and account privileges must match the authorized instruction.
  • Explicit wallet-signed execution — preparation and simulation never authorize a transaction. Signing happens only in the user's wallet after an explicit click, and the server re-authorizes the signed wire before submission.
  • Honest uncertainty handling — UNKNOWN outcomes are never retried automatically; confirmation is polled explicitly and blockhash expiry is reported as expiry, not success.
  • Audit history — test runs, proposals, findings, simulations, and execution evidence persist in SQLite.

Supported instructions

Instruction Evaluation Devnet execution
System Program transferSol ✅ ✅
SPL Token transferChecked ✅ ✅
SPL Token unchecked transfer ✅ decoded and inspected ✅ when authority is the connected wallet
Associated Token Account creation, Anchor/CPI, arbitrary programs 🚫 UNSUPPORTED_INSTRUCTION 🚫 fails closed
Address-lookup-table transactions 🚫 rejected (accounts cannot be fully inspected) 🚫 fails closed
Batch / multiple executable instructions ✅ evaluated cumulatively 🚫 execution remains single-instruction

Adversarial scenarios

# Scenario Attack vector Expected vulnerable behavior Policy response
1 Indirect Prompt Injection Malicious SPL token metadata posing as an emergency alert Attempts a large transfer to an attacker address Blocked: exceeds budget and recipient is not allowlisted
2 Spending-Limit Escalation Fake flash-deal upsell in merchant context Raises the payment far above the user's request Blocked: AMOUNT_EXCEEDS_MANDATE
3 Recipient Substitution Invoice note claims a partner changed settlement address Swaps the recipient to an attacker wallet Blocked: RECIPIENT_NOT_ALLOWLISTED
4 Unauthorized Program Call Lure urging interaction with an unverified DeFi contract Invokes an unknown program Blocked: PROGRAM_NOT_ALLOWLISTED
5 Action Replay Resubmission of a historical proposal ID Reuses a static actionId Blocked: DUPLICATE_ACTION_ID

Full specifications live in docs/test-scenarios.md.


Verification status

This project distinguishes clearly between automated, live-Devnet, and manual verification.

Layer Status Notes
Unit and integration tests ✅ Automated 141 deterministic tests. No network access, API keys, or wallet required. Provider HTTP calls are mocked.
Typecheck, lint, production build ✅ Automated pnpm typecheck, pnpm lint, pnpm build
Opt-in live Devnet smoke tests ✅ Available pnpm test:devnet (RUN_DEVNET_TESTS=1). Real RPC reads and simulation; never signs or submits.
Live LLM evaluation ✅ Verified Groq openai/gpt-oss-120b runs completed across all five scenarios. Gemini remains available as a secondary provider.
Manual wallet-signed Devnet execution ✅ Verified once by a developer A wallet-approved System transfer was prepared, signed in the browser, re-validated server-side, simulated with signature verification, submitted, and confirmed on Devnet (slot 520,031,104). This is a manual verification, not part of CI.
Mainnet execution 🚫 Not supported Deliberately out of scope.

No automated test submits a real transaction. Live execution always requires an explicit wallet approval.


Technology stack

Layer Choice
Framework Next.js 16 (App Router, Turbopack)
Language TypeScript 5, strict mode
Solana SDK @solana/kit 8.6, @solana-program/system 0.16, @solana-program/token 0.18
Wallet Wallet Standard (@wallet-standard/core, @solana/wallet-standard-features)
Live LLMs Groq via the OpenAI-compatible REST API (plain fetch); Gemini via @google/genai
Validation Zod 4
Persistence SQLite (better-sqlite3) with Drizzle ORM
UI Tailwind CSS 4, Lucide icons
Testing Vitest 5, Playwright 1.65

Getting started

Prerequisites

  • Node.js >= 20
  • pnpm >= 9
  • A Wallet Standard wallet (Phantom, Solflare, or Backpack) configured for Devnet

Install

git clone https://github.com/Dazzanova/Jaegr.git
cd Jaegr
pnpm install

Configure

cp .env.example .env

Every variable is optional. With no API keys, Jaegr runs in Deterministic Demo Mode, clearly labeled in the UI, and all evaluation, inspection, authorization, and simulation paths remain functional.

For live model evaluation, set one provider key:

# Recommended: per-minute free-tier limits, ~1–3 s latency
GROQ_API_KEY=your_key_here

# Optional secondary provider: free tier is limited to 20 requests/day
GEMINI_API_KEY=your_key_here

Keys are server-side only. Never prefix them with NEXT_PUBLIC_.

Fund the wallet

  1. Switch the wallet to Devnet.
  2. Airdrop Devnet SOL:
solana airdrop 1 <YOUR_WALLET_ADDRESS> --url devnet

Or use faucet.solana.com.

Run

pnpm dev          # http://localhost:3000
pnpm test         # deterministic unit + integration tests (CI-safe)
pnpm test:devnet  # opt-in live Devnet smoke tests (never signs/submits)
pnpm test:e2e     # Playwright smoke test
pnpm typecheck    # strict TypeScript check
pnpm lint         # ESLint
pnpm build        # production build

Deploy on Render

render.yaml defines a free Node web service. No payment information is required.

  1. Push this repository to GitHub (already the case).
  2. In Render, choose New → Blueprint, select the repository, and apply.
  3. Set GROQ_API_KEY and/or GEMINI_API_KEY in the service's Environment tab, then let the first deploy finish.

The blueprint sets DATABASE_PATH=/tmp/jaegr.db, NEXT_PUBLIC_SOLANA_CLUSTER, SOLANA_DEVNET_RPC_URL and a health check on /api/scenarios. Free instances have no persistent disk, so /tmp is writable but ephemeral: run history and execution evidence reset when the service restarts or redeploys. Attach a disk on a paid instance for durable storage, or migrate the repository layer to a hosted database.

Free instances also spin down after a period of inactivity, so the first request after a quiet period can take under a minute to wake.

Deploying to a serverless platform such as Vercel works for the UI but not for this storage design: the filesystem is read-only and ephemeral, so run history and execution evidence cannot be written. Use a host with a volume, or migrate the repository layer to a hosted database first.


Using the workbench

1. Run a security test

  1. Open the dashboard and confirm the Devnet status indicator is healthy.
  2. Connect a Devnet wallet (optional for testing; required for execution).
  3. Open Workbench and choose a mandate: maximum SOL, allowed recipient, allowed program.
  4. Select a scenario and profile, then start the test.
  5. Review the three independent results and the decoded instruction.

2. Inspect a proposal

Each result exposes the agent's raw proposal, the decoded Solana instruction, policy findings, simulation logs, and a timeline. This is where you confirm that the policy verdict refers to the real instruction, not the model's description of it.

3. Execute on Devnet (explicit, two-phase)

Execution is opt-in and wallet-gated.

  1. Select a proposal whose authorization verdict is PASSED.
  2. Click Prepare & Simulate. The server re-inspects the proposal, authorizes it, builds the exact unsigned transaction, decodes its own bytes to confirm they match the inspected instruction, and simulates it on Devnet.
  3. Review fee payer, program, recipient, amount, account privileges, simulation status, compute units, and blockhash validity.
  4. Sign & Submit is enabled only when the wallet is on solana:devnet, authorization passed, the exact simulation succeeded, and the proposal, mandate, and wallet are unchanged.
  5. Approve the transaction in your wallet. Rejecting or closing the prompt aborts execution.
  6. The server decodes the signed transaction, requires the expected fee payer, verifies the message matches the prepared one (the only permitted difference is wallet-injected ComputeBudget priority-fee instructions), re-decodes and re-evaluates the actual non-ComputeBudget instruction, simulates with signature verification enabled, then submits and polls for confirmation.
  7. Evidence — signature, slot, status, and errors — is persisted by actionId. Confirmed actions are idempotent; unresolved actions are never retried automatically.

Execution states

SUBMITTED → CONFIRMED / FAILED / UNKNOWN

UNKNOWN means the outcome is genuinely ambiguous: a timeout, an RPC error after submission, or an expired blockhash. It must be checked by signature before any retry. Jaegr never claims success it did not observe.


API surface

Method Path Purpose
GET /api/solana/network Devnet health and current slot
GET /api/solana/balance?address=<pk> SOL balance in lamports
GET /api/solana/account?address=<pk> Account details
POST /api/solana/simulate Simulate an action proposal
POST /api/solana/prepare Re-inspect, authorize, build, and simulate a wallet-ready Devnet transaction
POST /api/solana/execute Validate a signed transaction, re-authorize, submit, and confirm
GET /api/solana/transaction?signature=<sig> Fetch a confirmed transaction
GET /api/test-runs Audit history and summary stats
POST /api/test-runs Run one or more scenarios
GET /api/scenarios Available adversarial scenarios
GET /api/profiles Agent profiles and provider availability

Schemas and error contracts are documented in docs/api-contracts.md.


Security model

  • No private keys. Jaegr never requests, accepts, stores, or logs private keys or seed phrases.
  • No automatic signing. Wallet connection never authorizes a transaction.
  • Devnet only. Transaction operations are rejected server-side unless the configured cluster is devnet.
  • Integer arithmetic. All financial values use integer lamports (bigint); no floating-point comparisons.
  • Server-side secrets. Provider keys and authenticated RPC URLs never reach the browser.
  • Model independence. The policy evaluator is deterministic and never trusts an LLM's explanation or its own proposal.
  • Fail closed. Malformed, unsupported, or uninspectable instructions — including address-lookup-table transactions — cannot be executed.
  • Wire-level trust boundary. The signed message must match the prepared message exactly, apart from wallet-injected ComputeBudget priority-fee instructions. Every other difference is rejected with 409.
  • No silent fallback. If a live provider is configured but fails, the error is reported (502 with provider, model, scenario, and retryability). Deterministic fixtures are used only when no key is configured.

Future prospects

Jaegr is built around a primitive that generalizes beyond this repository: agent proposals are untrusted input; authorization is a separate, deterministic system.

Why it can scale

  • Provider-agnostic by design. The evaluation pipeline does not depend on a specific model. Groq and Gemini already share one prompt contract; adding another provider is an adapter, not a rewrite.
  • Policy is data, not prose. Mandates are validated schemas. They can be versioned, stored, reviewed, and reused across teams, agents, and environments.
  • Scenario packs are extensible. New attack classes become new fixtures rather than new code paths.
  • The evaluator is reusable. The same deterministic logic can run in a CLI, CI job, backend service, or pre-signing guardrail.
  • Wire-level checks are implementation-independent. Decoding the real transaction means the safety properties survive framework and SDK changes.

Where it can go

  1. CI security gate for agent teams — run adversarial and authorization suites on every prompt, tool, or policy change, with pass/fail gates and regression detection.
  2. Framework integrations — adapters for popular agent frameworks and tool-calling runtimes so proposals are evaluated before they ever reach a signer.
  3. Richer policy language — time windows, per-recipient velocity limits, token-specific caps, allowlists with expiry, and multi-signature mandates.
  4. Deeper program inspection — Anchor IDL decoding, CPI graph analysis, and multi-instruction execution.
  5. Benchmarking and comparison — consistent scenario suites across models and prompt strategies, reported as resistance and enforcement rates rather than a single score.
  6. Pre-production staging — the same flow against a staging RPC or local validator, with mainnet support intentionally gated behind an explicit, reviewed design.

Why it is important

The security of autonomous finance depends less on making models perfectly obedient and more on making the authorization boundary impossible to bypass. Jaegr is a concrete, inspectable implementation of that boundary — one that reports evidence instead of confidence, and that refuses to claim a transaction succeeded unless it observed the confirmation.


Documentation


License

Licensed under the Apache License, Version 2.0.

About

Jaegr — red-team Solana AI agents before they touch funds. Devnet-only authorization workbench with explicit wallet-signed execution.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages