AgentAvow Trust

AgentAvow

前身为 AgentGraph。签名证明格式、JWKS 和现有徽章均保持不变。

对于任何工具、MCP 服务、程序包或技能，AgentAvow 都能回答“我的 Agent 连接这个安全吗？”，并给出可以放心连接、连接前请先检查或请勿连接的结论及原因。它基于经过签名的 0–100 信任评分，你可以离线重新计算并验证；此外还提供单独的采用度评分。

MCP 服务 — 面向 AI Agent 的信任与安全

在 Agent 连接工具之前，先检查其是否安全。你可以通过 Claude、ChatGPT、Cursor、VS Code 或任何 MCP 客户端进行检查。若要本地安装：

pip install agentavow-trust

设置说明和完整工具列表请参阅 sdk/mcp-server/。

从 Claude 连接

Claude Code 插件（推荐）。 AgentAvow Trust 插件已列入 Anthropic 插件目录。该插件包含 MCP 连接器、/scan 命令、一个会在 Claude 添加或安装服务或程序包前扫描它的技能、一个 SessionStart 钩子（首次发现你配置的 MCP 服务时会检查每个服务；仅发出警告，检查失败时仍放行），以及一个 PreToolUse 门控（每次调用 MCP 工具前都会检查文件中的结果：若服务被判定为“请勿连接”，则拒绝调用；若工具定义自检查后发生变化，则会先询问）。你也可以直接从此仓库安装：

/plugin marketplace add AgentAvow/AgentAvow
/plugin install agentavow-trust@agentavow

然后试试 /scan npm chalk。该钩子会跳过 localhost 或私有网络上的服务，不会传输路径看起来可能包含密钥的 URL，并会在 URL 离开你的设备前移除其中的凭据和查询字符串。读取和发送的内容。源代码：plugins/agentavow-trust/。

仅连接器。 在 Claude（网页版或桌面版）中，通过连接器目录添加 AgentAvow。在 Claude Code 中不使用插件时：

claude mcp add --transport http agentavow https://agentavow.com/mcp

从 ChatGPT 连接

AgentAvow 已列入 ChatGPT 插件目录：在此添加。它提供相同的八种只读工具和信任卡片，另附一个连接前扫描技能。无需登录。

从编辑器连接

远程 MCP 服务已上线，地址为 https://agentavow.com/mcp（Streamable HTTP，无需身份验证，只读）——无需安装。

一键连接：

• Cursor — cursor://anysphere.cursor-deeplink/mcp/install?name=agentavow&config=eyJ1cmwiOiAiaHR0cHM6Ly9hZ2VudGF2b3cuY29tL21jcCJ9
• VS Code — vscode:mcp/install?%7B%22name%22%3A%20%22agentavow%22%2C%20%22type%22%3A%20%22http%22%2C%20%22url%22%3A%20%22https%3A//agentavow.com/mcp%22%7D

或者手动添加。 Cursor（~/.cursor/mcp.json，或项目级 .cursor/mcp.json）：

{ "mcpServers": { "agentavow": { "url": "https://agentavow.com/mcp" } } }

VS Code（.vscode/mcp.json，或 MCP: Open User Configuration）：

{ "servers": { "agentavow": { "type": "http", "url": "https://agentavow.com/mcp" } } }

若要改用本地 stdio 服务：pip install agentavow-trust。

主要功能

• 免费匿名扫描 — 将任意 GitHub 仓库、MCP 服务、npm 或 PyPI 软件包、OpenClaw 技能（或可解析到其中某一项的钱包地址）交给 AgentAvow，即可获得以下三种答复之一及其理由。无需账号，无需安装。结果缓存 1 小时；?force=true 会重新扫描。
• 双评分：信任度 + 采用度 — 每次扫描都会先给出三种答复之一及其理由（可安全连接 / 连接前请先审核 / 请勿连接），然后给出 0–100 的信任度评分（并附上信任等级）和基于真实使用情况（下载量、星标数、安装量）的 采用度评分。信任度评分根据扫描结果计算；五项分类子评分（密钥卫生、代码安全、数据处理、文件系统访问、依赖健康度）作为独立维度与之并列报告。每条扫描结果都包含严重程度，并指向确切的行或清单条目。
• 签名、可验证的证明 — 每项结果都附带一份基于规范化判定（RFC 8785 JCS）的 JWS 证明（EdDSA / Ed25519，RFC 7515）。任何人都可以根据 agentgraph.co/.well-known/jwks.json 上的公开 JWKS 离线重新计算并验证——评分是产品，签名则是其依据。
• 信任等级 → 建议限制 — 每个信任度评分都会映射到一个信任等级（verified → blocked），并提供建议的执行策略（请求/分钟数、令牌预算、确认提示），以便网关或 Agent 框架自动采取相应措施。
• 信任徽章 — 可添加到 README 的单行、兼容 shields.io 的 SVG 徽章，会显示仓库当前的答复和已签名的信任度评分，并链接到完整的可验证报告。徽章通过开放 CORS 提供，并根据每小时扫描缓存刷新，因此始终保持最新。
• 监视与变更提醒 — 监视某个工具；当其评分下降或其 已签名的工具定义发生变化（tool_manifest_digest 漂移）时，AgentAvow 会重新扫描并提醒你——这能发现你原本可能会错过的暗中调包。
• 认领你拥有的仓库 — 通过添加 GitHub topic 证明公开仓库的所有权（不存储令牌），或使用你临时提供的 GitHub 令牌运行 私有扫描（绝不持久化，也绝不添加到公开目录）。
• 公开信任目录 — 提供一个可分页、可筛选的扫描目录，涵盖所有扫描结果（初始语料库及社区按需扫描），可按接入面、严重程度和评分浏览。
• MCP 服务与 CI 门禁 — AgentAvow Trust MCP 服务（agentavow-trust）向 Claude Code 和其他客户端开放扫描功能；GitHub Action、GitLab CI 组件、Bitbucket Pipe、Azure Pipelines 模板或本地 CLI 则可在答复为“请勿连接”时使构建失败（fail_on: do_not_connect）。npm 软件包 agentavow-trust 为 Vercel AI SDK、Flue、Claude Agent SDK 和 OpenAI Agents SDK 添加逐次调用门禁；Python 的 LangChain、Google ADK、Claude Agent SDK 和 OpenAI Agents SDK 门禁位于 src/bridges/。对于策略引擎和网关，integrations/opa/ 提供 Open Policy Agent 策略（附 Envoy ext_authz 示例），integrations/litellm/ 则提供 LiteLLM MCP 网关的护栏。可运行的暗中调包演示位于 demos/rugpull/。

技术栈

层级	技术
后端	FastAPI、SQLAlchemy 2.0（异步）、Pydantic 2.0、Uvicorn
数据库	PostgreSQL 16（asyncpg）
缓存/事件	Redis 7（缓存、速率限制、发布/订阅）
前端	React 19、TypeScript、Vite 7、Tailwind CSS 4、TanStack Query 5
身份验证	JWT（访问令牌 + 刷新令牌）、面向 Agent 的 API 密钥、bcrypt
加密/签名	Ed25519（JWS/EdDSA，RFC 7515）、RFC 8785 JCS 规范化
UI/动画	Tailwind CSS、framer-motion
基础设施	Docker、Docker Compose、Nginx、GitHub Actions CI

快速开始

前置条件

• Python 3.11+（生产环境使用 3.12）
• Node.js 20+
• PostgreSQL 16
• Redis 7
• Docker 和 Docker Compose（可选，用于容器化配置）

选项 1：Docker Compose（推荐）

# Clone the repo
git clone https://github.com/AgentAvow/AgentAvow.git
cd AgentAvow

# Copy environment files
cp .env.example .env
cp .env.secrets.example .env.secrets

# Edit .env and .env.secrets with your values (see Environment Variables below)

# Start everything
docker-compose up

此操作会启动：

• 后端 API：http://localhost:8000
• 前端：http://localhost（端口 80）
• PostgreSQL：localhost:5432
• Redis：localhost:6379

数据库迁移会在启动时自动运行。

选项 2：本地开发

# Clone and enter the repo
git clone https://github.com/AgentAvow/AgentAvow.git
cd AgentAvow

# Setup Python environment, install deps, start DB services
make setup

# Copy and configure environment
cp .env.example .env
cp .env.secrets.example .env.secrets
# Edit both files with your values

# Run database migrations
make migrate

# Start the backend dev server (hot reload)
make dev

在另一个终端中，启动前端：

cd web
npm install
npm run dev

• 后端运行于 http://localhost:8000
• 前端运行于 http://localhost:5173（将 API 请求代理到后端）

环境变量

必需（.env）

DATABASE_URL=postgresql+asyncpg://postgres:yourpassword@localhost:5432/agentgraph
POSTGRES_PASSWORD=yourpassword
REDIS_URL=redis://localhost:6379/0
JWT_SECRET=change-me-to-a-random-64-char-string

可选（.env）

APP_NAME=AgentAvow
DEBUG=false
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
CORS_ORIGINS=["http://localhost:3000","http://localhost:80"]
RATE_LIMIT_READS_PER_MINUTE=100
RATE_LIMIT_WRITES_PER_MINUTE=20
RATE_LIMIT_AUTH_PER_MINUTE=5

密钥（.env.secrets）

ANTHROPIC_API_KEY=your_key_here   # Optional — LLM-assisted features (not required for scanning)

前端（web/.env）

# Optional. Defaults to /api/v1, which the Vite dev server proxies to the backend.
VITE_API_BASE_URL=http://localhost:8000/api/v1

API 概览

公共扫描 API 无需身份验证。所有应用端点都使用 /api/v1 前缀；交互式 API 文档位于 /api/v1/docs（Swagger）和 /api/v1/redoc（/docs 是产品文档）。GET /health（无前缀）用于检查数据库和 Redis 的连接状态。

公共扫描 API（无需身份验证）

端点	路径	说明
扫描	GET /public/scan/{owner}/{repo}	扫描仓库/工具；返回判定结果（decision）及其原因、信任分数、等级、发现项和签名的 JWS 证明。?force=true 可绕过 1 小时缓存。
徽章	GET /public/scan/{owner}/{repo}/badge	20px SVG README 徽章（开放 CORS）：判定结果、带分数的信任条和带数量的采用度仪表。?style=card 可显示 360×230 卡片，?style=classic 可显示旧版徽章，?theme=light|dark 可设置主题。在浏览器中缓存 1 小时，在边缘缓存 1 天。
卡片	GET /public/scan/{owner}/{repo}/card.svg	widget.js 嵌入内容所显示的信任卡片。在浏览器中缓存 5 分钟，在边缘缓存 1 小时。
检查项	GET /public/scan/{owner}/{repo}/checks	采用度信号：检查项数量、活跃关注者、GitHub 星标数、分数历史记录。
历史记录	GET /public/scan/{owner}/{repo}/history	仓库的过往扫描时间线。
钱包查询	GET /public/scan/wallet/{address}	将钱包地址解析为其关联的仓库并扫描该仓库。
目录	GET /public/scan-catalog	所有扫描的分页、可筛选目录（按表面、严重程度和分数筛选）。
OG 页面	GET /og/check/{owner}/{repo}	扫描结果页面的 Open Graph 元数据（可分享页面本身为 agentavow.com/check/{owner}/{repo}）。

验证与证明

端点	路径	说明
JWKS	GET /.well-known/jwks.json	用于离线验证证明的公钥（EdDSA/Ed25519）。由 agentgraph.co 提供。
证明	/attestations	为实体签发、列出和撤销签名证明。
安全证明	GET /entities/{id}/attestation/security	已签名的安全状况证明（兼容 A2A trust.signals[]）。
组合槽位	GET /entities/{id}/attestation/composed-slot	用于 APS composed-v1 信封的 agentgraph-scan-v1-structural 槽位。
聚合验证	GET /aggregate/{subject_did}/verify	验证已签名的 Trust Score v2 聚合信封。

账户（需身份验证）

端点	路径	说明
身份验证	/auth	注册、登录、JWT 令牌、电子邮件验证
认领	/account/claims	通过 GitHub topic 证明认领你拥有的公共仓库（不存储令牌）
私有扫描	POST /account/private-scan	使用临时提供的 GitHub 令牌扫描私有仓库（绝不持久化令牌）
关注	/watches	创建/列出/删除工具关注项，以接收等级和签名定义变更提醒
提醒 webhook	/account/alert-webhook	配置（并测试）用于接收变更提醒的 HMAC 签名 webhook

项目结构

AgentAvow/
├── src/                     # Backend (FastAPI)
│   ├── api/                 # API router modules (public scan, badge, watches, claims, attestations)
│   ├── scanner/             # Static-analysis engine + detection patterns
│   ├── signing.py           # Ed25519 signing, JWS, JCS canonicalization
│   ├── attestation/         # CTEF envelopes, APS composed slot
│   ├── trust/               # Trust score computation, aggregate envelopes, action_ref vectors
│   ├── safety/              # Anomaly / collusion / propagation controls
│   ├── source_import/       # Fetchers (GitHub, npm, PyPI, MCP, crates, Docker, HF, …)
│   ├── jobs/                # Scheduled jobs (watch re-scan loop, population scan)
│   ├── bridges/             # Framework adapters (MCP, LangChain, CrewAI, AutoGen)
│   ├── models.py            # SQLAlchemy models
│   ├── main.py              # FastAPI app entry point
│   ├── config.py            # Settings (Pydantic)
│   ├── database.py          # Async PostgreSQL sessions
│   ├── redis_client.py      # Redis connectivity
│   ├── cache.py             # Caching layer
│   └── audit.py             # Audit logging
├── web/                     # Frontend (React + TypeScript)
│   └── src/
│       ├── rebrand/         # Live cutover UI (pages, docs, components)
│       ├── pages/           # Legacy page components
│       ├── components/      # Reusable UI components
│       ├── hooks/           # Custom React hooks
│       └── lib/             # Utilities and API client
├── ios/                     # iOS app (SwiftUI)
├── tests/                   # Test suite (pytest)
├── migrations/              # Alembic migrations
├── docker-compose.yml       # Full stack orchestration
├── Makefile                 # Development commands
└── docs/                    # PRD and architecture docs

开发

常用命令

make dev            # Start backend with hot reload
make test           # Run full test suite
make lint           # Lint with ruff
make lint-fix       # Auto-fix lint issues
make ast-verify     # Verify Python syntax
make migrate        # Run pending migrations
make migration      # Create a new migration
make db-start       # Start PostgreSQL + Redis (Homebrew)
make db-stop        # Stop database services
make clean          # Clean build artifacts

运行测试

# Full suite
make test

# Verbose output
.venv/bin/python3 -m pytest tests/ -v

# Single test file
.venv/bin/python3 -m pytest tests/test_auth.py -v

# With coverage
.venv/bin/python3 -m pytest tests/ --cov=src

代码规范

• Python 3.11+（生产环境使用 3.12）——联合类型使用 from __future__ import annotations
• Lint 检查——ruff（E、F、I、N、W、UP 规则），行长限制为 100 个字符
• AST 验证——所有 Python 文件都必须能正常解析
• 必须编写测试——所有新增或修改的代码都需要单元测试

安全性

• 支持配置来源的 CORS
• 速率限制（读取、写入和身份验证专用限制）
• 安全标头（HSTS、X-Frame-Options、X-Content-Type-Options 等）
• 请求 ID 关联追踪
• 内容过滤与 HTML 清理
• 使用 HMAC-SHA256 对 webhook 签名
• 使用 Bcrypt 对密码进行哈希处理
• 用户登出时将 JWT 令牌列入黑名单
• 记录所有敏感操作的审计轨迹

架构

AgentAvow 是一个分层的扫描与证明流水线：扫描生成证据，对证据进行评分和规范化处理，并将判定签名为证明，任何人都可以离线重新计算并验证该证明。

┌─────────────────────────────────────────────────────────┐
│  Clients — check page, trust badge, MCP server, CLI,    │
│            GitHub Action, third-party verifiers         │
├─────────────────────────────────────────────────────────┤
│  Public API — /public/scan · /badge · /checks ·         │
│               scan-catalog · watches · claims           │
├─────────────────────────────────────────────────────────┤
│  Scan & score — static analysis (findings by category), │
│  per-category subscores, trust tier, adoption score,    │
│  tool-definition digests (drift / rug-pull detection)   │
├─────────────────────────────────────────────────────────┤
│  Attestation — Ed25519/JWS (RFC 7515) over a canonical  │
│  verdict (RFC 8785 JCS); CTEF envelopes; action_ref     │
├─────────────────────────────────────────────────────────┤
│  Verification — public JWKS (agentgraph.co/.well-known),│
│  offline byte-for-byte recompute, DID:web identity      │
└─────────────────────────────────────────────────────────┘

监视功能形成闭环：后台重新扫描任务会将每个受监视工具的新评分和签名定义摘要与上次结果进行比较，并在其中任一项发生变化时触发带 HMAC 签名的 webhook 告警。

许可证

专有。保留所有权利。