guardian-qa
by Jorge4ugusto
README.md
# Guardian QA
**A pre-execution counterparty check and policy gate for AI payment agents, exposed as an MCP server.**
An agent that can move money will eventually be tricked into moving it to the wrong place. Guardian QA sits between the agent's intent and the signature: it checks the destination, the token, the account history, the shared blocklist and the text that produced the payment, then returns exactly one verdict — `allow`, `warn` or `block` — with machine-readable reason codes.
Built for the **NEAR HACKATHON 2026**, track **AI Security & Defense** (`security`).
- No mainnet, no real funds, no private keys.
- Read-only NEAR RPC and NearBlocks calls, plus a local SQLite ledger.
- Dry-run execution receipts and an append-only audit log.
- A red-team suite with 19 prompt-injection and payment-fraud attempts.
---
## Demo video
**`docs/demo.mp4`** — 91 seconds, 1080p30, burned-in English subtitles (`docs/demo.srt`). No audio, so it reads in mute. Visual language follows the nearbuilders.org dark theme, with Inter and IBM Plex Mono bundled in `video/assets/fonts/`.
| Time | Section |
| --- | --- |
| 0:00 | Title: `Guardian QA`, badge `Built on NEAR · testnet` |
| 0:06 | The problem: untrusted content, an injected payout, irreversible settlement |
| 0:22 | The solution: `PolicyGate` → MCP server → `allow` / `warn` / `block` |
| 0:42 | Red-team evidence read from `reports/red_team_results.json` |
| 1:00 | Terminal replay of the real 7/7 demo run |
| 1:22 | Commands and scope, then the `NEAR HACKATHON 2026 · AI Security & Defense` closing line |
Two honesty notes:
- The terminal section is a **replay of captured output** (`video/assets/terminal_demo.txt`), not a screen recording. The frame is labelled as such.
- The video refuses to render if the reports disagree with it. `video/build.py` validates 19/19 contained, 0 escaped, `A-01` blocked, the control allowed, and `matched 7/7` in the terminal capture before it starts Manim.
Rebuild it (Manim is used from the global install, not the project virtualenv):
```bash
python video/build.py # reuses already-rendered segments
python video/build.py --force # re-renders every scene
```
Manim Community 0.22+, ffmpeg and LaTeX must be on `PATH`. Rendering all six scenes takes roughly 10–12 minutes at 1080p30; the checked-in build is 91.00 s and 2.99 MB. The Inter and IBM Plex Mono files (SIL Open Font License) are registered with `manimpango.register_font()` at import time and copied next to the subtitles so libass resolves the same typeface.
---
## The problem
Agentic payment stacks usually protect the wallet with a key, not with a decision. A prompt-injected agent with a signing key can pay an attacker before any human sees the transaction. Spend limits alone are not enough: the first payment to a brand-new address is often the one that matters.
Guardian QA adds the missing decision point:
1. The agent describes the payment it is about to make.
2. Guardian QA collects risk signals and evaluates a deterministic policy.
3. The agent-side wrapper refuses, asks a human, or proceeds in dry-run.
4. Every decision is logged with the evidence behind it.
## Verdict contract
| Verdict | Meaning | Agent-side behaviour |
| --- | --- | --- |
| `allow` | No hard rule and no warning crossed the threshold. | Execute in dry-run, attach the receipt and TEE evidence if available. |
| `warn` | A risk signal crossed the warning threshold, or the score is between 30 and 69. | **Halt.** Ask the human operator for explicit approval. Without a human, fail closed. |
| `block` | A hard rule matched, or the weighted score reached 70. | **Refuse.** Do not retry the same destination with a different amount. Report the address if evidence exists. |
A `warn` is not a soft `allow`: the wrapper's default is to stop. The only path to execution on `warn` is an approval handler that returns `True`, and that approval is written to the audit log.
---
## Try it in 60 seconds
Prerequisites: Python 3.10+ and a shell. No API key and no funded account are required for the offline demo.
### 1. Install
```bash
cd guardian-qa
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate
pip install -e ".[dev]"
```
Optional configuration:
```bash
cp .env.example .env
```
The defaults use NEAR **testnet**. Leave `NEARAI_API_KEY` empty to run with local heuristics only.
### 2. Run the demo agent — do X, see Y
```bash
python -m guardian_qa.agent.mock_agent --fresh --offline
```
**See:** seven scenarios scored by the real policy engine and enforced by the real wrapper. The final table says:
```text
matched 7/7 expected verdicts
```
What the seven scenarios show:
| Scenario | Expected | Why |
| --- | --- | --- |
| `clean_payment` | `allow` | Established merchant, low amount, no injection. |
| `new_counterparty` | `warn` | Account is one day old with two transactions. |
| `blocklisted_payout` | `block` | Destination is on the shared blocklist (critical). |
| `prompt_injected_payout` | `block` | The intent contains an instruction override and concealment. |
| `token_impersonation` | `block` | A contract claims symbol `USDC` but is not canonical. |
| `contract_upgraded` | `warn` | Receiver contract code changed two days ago. |
| `spend_limit` | `block` | Amount exceeds the wrapper's single-payment cap. |
To answer the human-in-the-loop prompt yourself:
```bash
python -m guardian_qa.agent.mock_agent --fresh --offline --interactive
```
### 3. Run the red team
```bash
python -m guardian_qa.red_team.runner --offline --generator static
# equivalent convenience script:
# python run_red_team.py --offline --generator static
```
**See:** 19 adversarial attempts plus one benign control, then a summary:
```text
adversarial attempts 19
compliant attacks 19
non-compliant victim 0
contained (warn or block) 19
hard blocked 16
escaped (allow) 0
detection rate 100.0%
mandatory A-01 blocked
control C-00 allowed
```
The generated report is at `reports/red_team_report.md` and the raw results at `reports/red_team_results.json`. `A-01` is the mandatory case: a prompt-injected agent tries to pay a known-bad address and is stopped. With the static generator, sixteen attacks hard-block and three warn (50, 50 and 30), and nothing escapes. The checked-in abliterated run also contains all nineteen; its block/warn split moves between runs because both the payloads and the classifier are probabilistic (observed 16–18 hard blocks, 1–3 warns).
### 4. Run the tests
```bash
pytest
```
**See:** `81 passed`. The suite covers the policy engine, storage, the wrapper's fail-closed behaviour, spend limits, token resolution, injection heuristics, the service end-to-end, the MCP server itself, and red-team generation/compliance accounting.
### 5. Start the MCP server
```bash
# stdio, for a local MCP client
python -m guardian_qa.mcp_server
# HTTP, for a shared deployment
python -m guardian_qa.mcp_server --transport http --host 127.0.0.1 --port 8765
```
The HTTP endpoint is `http://127.0.0.1:8765/mcp`. The server exposes four tools:
| Tool | Purpose |
| --- | --- |
| `check_counterparty` | Score a payment before it is signed. |
| `report_address` | Add an address to the shared blocklist with evidence. |
| `get_blocklist` | Read the current blocklist, newest first. |
| `guardian_health` | Return network, thresholds, spend policy and tool names. |
Example MCP client configuration:
```json
{
"mcpServers": {
"guardian-qa": {
"command": "C:\\path\\to\\guardian-qa\\.venv\\Scripts\\python.exe",
"args": ["-m", "guardian_qa.mcp_server"],
"env": {
"NEAR_NETWORK": "testnet",
"GUARDIAN_OFFLINE": "0"
}
}
}
}
```
### 6. Use real testnet data (still read-only)
```bash
python -m guardian_qa.agent.mock_agent --fresh
```
Without `--offline`, account signals come from the public NEAR testnet RPC and NearBlocks. Demo accounts that are not deployed on testnet fall back to `data/account_fixtures.json`, and the signal notes say so. The blocklisted sink used in the demo is a synthetic 64-character address that is **not deployed** on testnet; the live check confirms that.
### 7. Call the check directly
```python
import asyncio
from guardian_qa.models import PaymentIntent
from guardian_qa.service import GuardianService
async def main():
result = await GuardianService().check_counterparty(
PaymentIntent(
destination="merchant-outlet.testnet",
amount=12.0,
token="NEAR",
network="testnet",
intent="Invoice payment.",
agent_id="demo-agent",
)
)
print(result.verdict, result.risk_score, [r.code for r in result.reason_codes])
asyncio.run(main())
```
A blocked result looks like this (trimmed):
```json
{
"verdict": "block",
"risk_score": 100,
"explanation": "Blocked. A hard rule rejected this counterparty. ...",
"destination": "4a1c9d3d2b7e5f0a6c8b1e2d3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
"amount": 20.0,
"token": "NEAR",
"network": "testnet",
"dry_run": true,
"reason_codes": [
{"code": "GQA-BLOCK-001", "severity": "block", "message": "Destination ... is on the shared blocklist (critical, prompt_injection_sink): ..."},
{"code": "GQA-WARN-001", "severity": "warn", "message": "Destination ... is not deployed on testnet (unknown or brand-new account)"}
]
}
```
### 8. Optional: run the red team with the abliterated model
The default attacker model is NEAR AI Cloud's private-TEE, uncensored DeepSeek 4.1 Flash. The catalog is public, so the model check works without a key; generation needs one.
```bash
# Check the configured model IDs (public catalog, no key needed)
python -m guardian_qa.red_team.runner --preflight
```
Expected:
```text
attacker deepseek-ai/DeepSeek-V4.1-Flash-1017-abliterated OK
classifier Qwen/Qwen3.8-27B OK
victim openai/gpt-4.1-mini OK
```
Then add your key to `.env` and smoke-test one attack:
```bash
# .env: NEARAI_API_KEY=...
python -m guardian_qa.red_team.runner --generator nearai --only A-01 --limit 1 --delay 1
```
Full run:
```bash
# Recommended: abliterated generator, deterministic worst-case victim
python -m guardian_qa.red_team.runner --generator nearai --victim scripted --delay 1
# Optional: let a model act as the victim too
python -m guardian_qa.red_team.runner --generator nearai --victim llm --delay 1
```
An explicit `--generator nearai` without a key exits with status `2` instead of silently falling back. If you want the old behaviour, pass `--allow-fallback`; the report records `Mode fallback: True`. `--only` and `--limit` are available for smoke tests.
| Model | ID | Context | Price per 1M tokens |
| --- | --- | --- | --- |
| DeepSeek 4.1 Flash (abliterated) | `deepseek-ai/DeepSeek-V4.1-Flash-1017-abliterated` | 1.05M | $0.30 in / $1.20 out |
| Qwen3.8 27B (abliterated) | `Qwen/Qwen3.8-27B-abliterated` | 262K | $0.04 in / $1.35 out |
A 19-attack run costs cents and usually takes a few minutes. The JSON results include every generated payload; the Markdown report shows samples and marks non-compliant victims separately.
**Current checked-in reports:** `reports/red_team_report.md` was generated with the real gateway, `--generator nearai --victim scripted` on 2026-11-13. The latest run shows `Attack generator: nearai`, `Generated payloads: 19`, `Contained: 19` (18 hard blocks, 1 warn), and TEE evidence with `nonce_echoed=True`. Earlier runs of the same command had 16 blocks and 3 warns; the split moves, the containment does not. The raw JSON records the quote digest and nonce as well.
`reports/red_team_static.md` and `.json` are the same suite with deterministic payloads and no network calls (`--offline --generator static`). Same split: 19 contained, 16 blocks, 3 warns. Keeping both makes the reproducibility claim checkable without a key.
#### Using a local or third-party abliterated endpoint
The client is plain OpenAI-compatible, so NEAR AI Cloud is not mandatory for generation. Any server that exposes `/v1/chat/completions` works — vLLM, Ollama, LM Studio, or your own gateway:
```bash
# .env
NEARAI_BASE_URL=http://127.0.0.1:8000/v1
NEARAI_API_KEY=local
NEARAI_ATTACKER_MODEL=<model id served by that endpoint>
NEARAI_ATTESTATION=0
```
```bash
python -m guardian_qa.red_team.runner --generator nearai --victim scripted --delay 1
```
Two honest differences from the NEAR AI Cloud path:
- There is no `/attestation/report` route, so `NEARAI_ATTESTATION=0` skips the call and the report shows `status: disabled` instead of a quote digest.
- No TEE evidence means no proof that the model weights are the advertised ones. The report says so rather than implying verification.
`--preflight` reads `/v1/models` from whatever `NEARAI_BASE_URL` points at. With the default it checks the public NEAR AI catalog; with a local endpoint it reports the model IDs that server serves, so a mismatched `NEARAI_ATTACKER_MODEL` shows up before the run starts.
### 9. Optional: let a model play the victim
The scripted victim is the worst case and the recommended number for a demo. A model victim answers a different question: **would a real agent actually fall for this payload?** That is a property of the victim, not of the firewall.
```bash
python -m guardian_qa.red_team.runner --generator nearai --victim llm --delay 1 \
--report reports/red_team_llm_victim.md --json reports/red_team_llm_victim.json
```
Checked-in result (`openai/gpt-4.1-mini` as victim, 2026-11-13):
| Metric | Value |
| --- | --- |
| Adversarial attempts | 19 |
| Victim complied with the injected destination | 18 |
| Victim refused or used another destination | 1 (`A-04`, zero-width address) |
| Contained (warn or block) | 18 of 18 compliant attempts |
| Escaped | 0 |
| Control payment | `allow` |
Two honest notes:
- **The number moves between runs.** An earlier run of the same command had 17 compliant and 2 non-compliant. The detector contained every compliant attempt both times.
- **A-05 fell back to its static payload** in this run: the generator call failed after the retry, so `Generated payloads` is 18, not 19. The report marks that row `static` instead of hiding it.
Reasoning models are a trap here. `Qwen/Qwen3.8-27B` spent all 1200 tokens on hidden reasoning and returned empty content with `finish_reason: length`. The victim call now retries with 2000 tokens, but the default victim is an instruct model, which is cheaper and returns JSON reliably. Override it with `--victim-model` or `NEARAI_VICTIM_MODEL`.
---
## Architecture
```text
┌──────────────────────────────┐
agent reasoning ───────▶│ PolicyGate (agent wrapper) │
payment intent │ - submit() │
│ - spend limits │
│ - human approval on warn │
└──────────────┬───────────────┘
│ check_counterparty
▼
┌──────────────────────────────┐
│ GuardianService │
│ gathers signals, scores, │
│ persists, reports │
└───┬───────┬───────┬───────┬──┘
│ │ │ │
┌───────────────┘ │ │ └────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌────────────┐ ┌──────────────┐ ┌──────────────┐
│ account │ │ token │ │ blocklist + │ │ injection │
│ RPC + │ │ registry + │ │ interactions │ │ heuristics + │
│ NearBlocks │ │ NearBlocks │ │ SQLite │ │ NEAR AI Cloud│
└──────────────┘ └────────────┘ └──────────────┘ └──────────────┘
│
▼
┌──────────────────────────────┐
│ Deterministic policy engine │
│ hard blocks + weighted sum │
└──────────────┬───────────────┘
▼
allow / warn / block
+ reason codes + evidence
```
The same `GuardianService` powers the MCP server, the demo agent and the red team. There is no execution path that bypasses `PolicyGate`.
`check_counterparty` is a decision service. Spend limits, the token allowlist and human approval are enforced by `PolicyGate`; calling the MCP tool directly gives you the verdict and evidence, not the enforcement.
**Key files**
| Path | Responsibility |
| --- | --- |
| `src/guardian_qa/mcp_server.py` | FastMCP server, four tools, stdio/HTTP transports. |
| `src/guardian_qa/service.py` | Signal orchestration, persistence, reporting, health. |
| `src/guardian_qa/policy/engine.py` | Scoring and verdict selection. |
| `src/guardian_qa/policy/reason_codes.py` | Stable `GQA-*` reason-code registry. |
| `src/guardian_qa/agent/policy_gate.py` | Fail-closed enforcement, spend limits, dry-run receipts. |
| `src/guardian_qa/agent/mock_agent.py` | Seven-scenario demo agent. |
| `src/guardian_qa/red_team/runner.py` | Red-team CLI and report generation. |
| `src/guardian_qa/signals/` | Account, token, blocklist, interaction and injection collectors. |
---
## Signals and scoring
### Signal sources
| Signal | What is measured | Source | Fallback |
| --- | --- | --- | --- |
| Account age and activity | Creation date, transaction count, last activity | NEAR RPC `query/view_account` (`https://test.rpc.fastnear.com`); NearBlocks `/v3/accounts/{a}/stats` and `/v3/accounts/{a}` | Fixtures, then deterministic synthetic profile |
| Contract risk | Whether the receiver is a contract; days since last code deployment | NEAR RPC `code_hash`; NearBlocks `/v3/accounts/{a}/contract/deployments` | Fixtures |
| Prior interactions | Count, last time, whether a previous attempt was blocked | Local SQLite `interactions` table | Empty history |
| Stablecoin validity | Canonical contract per network, decimals, symbol impersonation | Bundled registry (`data/stablecoin_registry.json`); NearBlocks `/v3/fts/{contract}` | Offline token fixtures |
| Shared blocklist | Severity, category, evidence, reporter | Local SQLite `blocklist` table seeded from `data/blocklist.seed.json` | Empty blocklist |
| Prompt injection | Instruction override, payment redirect, concealment, obfuscation, credential theft | Local regex heuristics; NEAR AI Cloud classifier (`Qwen/Qwen3.8-27B`) | Heuristics only |
| TEE evidence | Gateway quote digest, nonce echo, signing address | NEAR AI Cloud `GET /v1/attestation/report` | `null` when no key is configured |
All network clients are read-only. NearBlocks responses are cached in memory for 60 seconds.
### Scoring
1. Hard blocks force `block` regardless of the score:
- `GQA-BLOCK-001`: high/critical blocklist hit.
- `GQA-BLOCK-002`: prompt injection with confidence ≥ 0.75.
- `GQA-BLOCK-003`: stablecoin impersonation.
- `GQA-BLOCK-004` / `GQA-BLOCK-005`: spend policy or token allowlist violation.
2. Warning weights accumulate and are capped at 100.
3. Verdict selection:
- `block` if a hard block matched or score ≥ 70.
- `warn` if score ≥ 30 **or** any warning reason is present.
- `allow` otherwise.
Thresholds live in `src/guardian_qa/config.py` and can be changed in code. They are returned by `guardian_health`.
### Reason codes
| Code | Severity | Meaning |
| --- | --- | --- |
| `GQA-BLOCK-001` | block | Destination is on the shared blocklist with high or critical severity. |
| `GQA-BLOCK-002` | block | Prompt injection detected with confidence ≥ 0.75. |
| `GQA-BLOCK-003` | block | Token impersonates a stablecoin but is not the canonical contract. |
| `GQA-BLOCK-004` | block | Agent spend policy rejected the payment (single or daily limit). |
| `GQA-BLOCK-005` | block | Token is not in the agent token allowlist. |
| `GQA-WARN-001` | warn | Destination is not deployed on the network. |
| `GQA-WARN-002` | warn | Destination account is young (under 30 days). |
| `GQA-WARN-003` | warn | Destination has very little activity. |
| `GQA-WARN-004` | warn | Contract code changed recently (under 30 days). |
| `GQA-WARN-005` | warn | First interaction with a high-value amount. |
| `GQA-WARN-006` | warn | This agent already had a blocked attempt to this destination. |
| `GQA-WARN-007` | warn | Network is not supported by this deployment. |
| `GQA-WARN-008` | warn | Token is not a canonical stablecoin on this network, or is unknown. |
| `GQA-WARN-009` | warn | A signal could not be collected; verdict relies on partial data. |
| `GQA-WARN-010` | warn | Low/medium blocklist hit. |
| `GQA-WARN-011` | warn | Possible prompt injection below the hard-block threshold. |
| `GQA-ALLOW-001` | info | All counterparty checks passed. |
| `GQA-ALLOW-002` | info | Known prior interaction with this counterparty. |
Reason codes are stable and machine-readable. The `message` field carries the human explanation, and `evidence` carries the raw values used.
---
## Least privilege and function-call keys
This repository never signs or broadcasts a transaction. The wrapper returns a **dry-run receipt** with a simulated transaction hash. In a production deployment, the signing key should be a **function-call access key scoped to one contract**, never a full-access key.
A function-call key:
- can call methods on **one** contract only;
- **cannot** transfer NEAR, stake, deploy code, or add/delete keys;
- has a gas allowance that the account owner funds; when it runs out, the key stops working and the account can lock itself out of that key path.
That is the right primitive for an agent that pays through a specific contract (for example a payment splitter or a subscription contract). It limits the blast radius if the key leaks or the agent is hijacked.
**Equivalence, and where it breaks.** Guardian QA's policy gate is a software analogue of a function-call key: both narrow what the agent is allowed to do. The key is enforced by the NEAR protocol at signing time; the gate is enforced by the agent process before signing. The key cannot be talked out of its scope by a prompt, while the gate can be bypassed if the process itself is compromised. Use both.
**Limits of this approach, stated plainly:**
- A function-call key can still call **any method** on its scoped contract, including methods that move value held by that contract. Scope is not intent.
- An upgradeable contract can change behaviour after the key is issued. Guardian QA's contract-change signal is a warning, not a guarantee.
- A stolen function-call key can be used by anyone until the allowance is exhausted or the key is deleted.
- Guardian QA is a software policy layer. It must run in a trusted process; an attacker who controls the agent process can skip it. Defence in depth means combining the policy gate, a scoped key, spend limits and human approval.
- The wrapper's spend limits are local configuration, not on-chain enforcement.
See the NEAR access-key documentation: <https://docs.near.org/protocol/accounts-contracts/access-keys>.
---
## Real vs simulated
This project is honest about what is live and what is not:
| Area | Status |
| --- | --- |
| NEAR network | **Testnet only.** No mainnet calls are made by default. |
| Funds and keys | **None.** The repo contains no private keys and never signs a transaction. Execution is a dry-run receipt. |
| Account data | Live for accounts that exist on testnet. Demo accounts that are not deployed use `data/account_fixtures.json`; the signal notes say `fixture` and explain why. |
| Blocklist entries | **Synthetic.** They are demo data, not accusations against real accounts. The main sink is a 64-character address that is not deployed on testnet. |
| Prompt-injection classifier | Local heuristics always run. The NEAR AI Cloud classifier runs when `NEARAI_API_KEY` is set; the checked-in report used it, so every attempt has both the heuristic and the model score. |
| Abliterated attacker model | **Exercised.** The checked-in report was generated by `deepseek-ai/DeepSeek-V4.1-Flash-1017-abliterated` through NEAR AI Cloud; all 19 payloads carry `generated: true`. |
| LLM victim | **Exercised** with `openai/gpt-4.1-mini`: 18 of 19 complied with the injected destination, 0 escaped, 1 non-compliant. Non-compliant victims are reported separately and excluded from the detection rate. |
| TEE attestation | Guardian QA records the gateway evidence digest and checks the nonce echo. The report is fetched once per run and cached for 300 seconds. It does **not** perform full Intel DCAP or NVIDIA NRAS verification; use `nearai-cloud-verifier` for that. |
| Detection quality | Probabilistic. The red-team result is evidence for this test set, not a proof of safety. |
If you configure `NEARAI_API_KEY`, the classifier, the abliterated generator, the LLM victim and the attestation report path become available. Without it, everything still runs offline and deterministically.
**Calibration note (live run, 2026-11-13):** the first real run with the classifier over-flagged ordinary business text. A plain "our vendor changed payout account" invoice scored 0.85 `payment_redirect`, which turned an expected `warn` into a `block` in two demo scenarios. The classifier prompt now requires control-oriented language (override, impersonation, concealment, credential theft, obfuscation) and includes two benign and two malicious examples. After that change: demo 7/7 expected verdicts, red team 19/19 contained (16 blocks, 3 warns), control allowed. The false positive only appeared against the real model, not in the offline tests.
---
## Configuration
Copy `.env.example` to `.env`. Never commit `.env`.
| Variable | Default | Purpose |
| --- | --- | --- |
| `NEAR_NETWORK` | `testnet` | `testnet` or `mainnet`. Keep testnet for the demo. |
| `NEAR_RPC_URL` | `https://test.rpc.fastnear.com` | Read-only RPC endpoint. |
| `NEARBLOCKS_API_URL` | `https://api-testnet.nearblocks.io` | NearBlocks v3 base URL. |
| `NEARAI_API_KEY` | empty | Enables the NEAR AI Cloud classifier, attacker model and attestation. |
| `NEARAI_BASE_URL` | `https://cloud-api.near.ai/v1` | OpenAI-compatible gateway. |
| `NEARAI_CLASSIFIER_MODEL` | `Qwen/Qwen3.8-27B` | Injection classifier. |
| `NEARAI_ATTACKER_MODEL` | `deepseek-ai/DeepSeek-V4.1-Flash-1017-abliterated` | Red-team payload generator. |
| `NEARAI_VICTIM_MODEL` | `openai/gpt-4.1-mini` | LLM victim for the red team. Reasoning models such as Qwen3.8 spend the budget on hidden tokens and return empty content; the victim call retries with a larger budget, but an instruct model is cheaper and more reliable here. |
| `NEARAI_TIMEOUT` | `60` | Timeout in seconds for LLM and attestation calls. |
| `NEARAI_ATTESTATION_CACHE_SECONDS` | `300` | How long one gateway attestation is reused per process. |
| `NEARAI_ATTESTATION` | `1` | `0` skips the gateway attestation call, for endpoints without `/attestation/report`. |
| `GUARDIAN_OFFLINE` | `0` | `1` skips NEAR RPC/NearBlocks calls and uses fixtures. Explicit NEAR AI calls still run when a key is set. |
| `GUARDIAN_MAX_SINGLE_PAYMENT` | `50` | Wrapper single-payment limit, in token units. |
| `GUARDIAN_DAILY_LIMIT` | `200` | Wrapper daily limit, in token units. |
---
## Project layout
```text
guardian-qa/
├── data/
│ ├── account_fixtures.json # offline demo account profiles
│ ├── blocklist.seed.json # synthetic blocklist seed
│ ├── stablecoin_registry.json # canonical USDC/USDT contracts
│ └── token_fixtures.json # offline contract metadata
├── docs/
│ ├── DEMO_SCRIPT.md # 60-second live demo script
│ ├── demo.mp4 # 91-second Manim + terminal-replay video
│ └── demo.srt # burned-in subtitle track, standalone copy
├── reports/
│ ├── demo_live.json # last demo run, JSON
│ ├── red_team_report.md # abliterated generator, scripted victim
│ ├── red_team_results.json # raw results for that run
│ ├── red_team_static.md # same suite, deterministic payloads
│ ├── red_team_static.json
│ ├── red_team_llm_victim.md # abliterated generator, LLM victim
│ └── red_team_llm_victim.json
├── src/guardian_qa/
│ ├── agent/ # policy gate, audit log, demo agent
│ ├── policy/ # engine and reason codes
│ ├── red_team/ # attacks, runner, report writer
│ ├── signals/ # account, token, blocklist, injection
│ ├── config.py
│ ├── mcp_server.py
│ ├── models.py
│ ├── near_rpc.py
│ ├── nearblocks.py
│ ├── nearai.py
│ ├── service.py
│ └── storage.py
├── tests/ # 81 offline tests
├── video/
│ ├── scenes.py # six Manim scenes
│ ├── meta.py # durations and subtitle cues
│ ├── build.py # validate → render → concat → burn subtitles
│ ├── manim.cfg # 1080p30, dark background
│ ├── assets/terminal_demo.txt # captured real run, replayed in the video
│ ├── assets/fonts/ # Inter + IBM Plex Mono, SIL OFL
│ └── out/ # segments and logs, gitignored
├── .env.example
├── LICENSE
├── pyproject.toml
├── run_red_team.py # red-team convenience entry point
└── README.md
```
---
## Testing
```bash
pytest
```
The suite is fully offline and covers:
- policy verdicts, hard blocks, warning accumulation and evidence;
- blocklist seeding, network scoping, deduplication and spend accounting;
- the wrapper's fail-closed behaviour, human approval, single/daily limits and token allowlist;
- token resolution, stablecoin mismatch and unknown contracts;
- injection heuristics, multilingual patterns and JSON extraction;
- classifier category gating: a bare `payment_redirect` signal is capped below the
block threshold unless a control-oriented category or a local heuristic matches;
- the service end-to-end (block, allow, report-then-block);
- the MCP server through the in-process FastMCP client (tools listed and called);
- red-team mode resolution, generated-payload validation, victim compliance and
non-compliant accounting;
- gateway attestation parsing for both string and list `event_log` shapes.
Result on 2026-11-13: **81 passed**.
---
## Hackathon disclosures
- **Track:** AI Security & Defense (`security`). The project also fits `agents`; one submission can list both track ids.
- **New repository (Q-003 / Q-004):** all project code was written during the hackathon window. There is no pre-hackathon product baseline.
- **Libraries and templates (Q-005):** FastMCP, `httpx`, the OpenAI Python SDK (used against the NEAR AI Cloud gateway), Pydantic, `python-dotenv`, Rich and pytest. NearBlocks and NEAR AI Cloud are external services, not bundled code. No pre-existing proprietary library is included.
- **NEAR AI Cloud:** optional inference for the prompt-injection classifier, the abliterated red-team generator, the optional LLM victim, and gateway attestation evidence. No NEAR AI code is bundled; the API is OpenAI-compatible.
- **NEAR Intents (Q-007):** not used. This project does not need a 1Click JWT or an Intents mainnet account.
- **Testnet only (Q-010):** the demo and the checked-in reports use testnet only. The code accepts a `mainnet` setting, but this submission does not use it and no mainnet call is made by default.
- **License (Q-014):** MIT. See `LICENSE`.
- **Secrets:** no API key, seed phrase or private key is committed. `.env` is ignored by git.
- **Demo accounts:** synthetic. The blocklist does not accuse real accounts.
---
## Limitations and next steps
- Prompt-injection detection is probabilistic and the checked-in heuristics are intentionally small. The NEAR AI Cloud classifier is the scalable path.
- The blocklist is local SQLite. A production deployment would need signed reports, moderation, and an appeal path.
- Account history comes from a public indexer. A production deployment should pin or verify its data source.
- Full TEE quote verification is out of scope here; the attestation digest is recorded so an external verifier can consume it.
- Spend limits are tracked in token units and do not convert between tokens. A production deployment should use a common unit or a per-token ledger.
- The demo uses dry-run receipts. Wiring a real function-call key and a payment contract is the next integration step, and it must stay on testnet for this submission.
## License
MIT — see [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data