ShreyanshVaibhaw/Leaflyst

# Leaflyst [](https://github.com/ShreyanshVaibhaw/Leaflyst/actions/workflows/ci.yml) **AI agent 的飞行记录仪和凭证图谱。** Leaflyst 为 agent 活动创建独立且防篡改的记录，并映射出 agent 可触达的凭证、权限和资源。当发生安全事件时，团队可以在不信任 agent 自身日志的情况下，重建时间线、衡量爆炸半径，并遵循引导式的遏制工作流。 ## 为什么选择 Leaflyst 传统的应用日志通常由正在被调查的同一个 agent 生成。Leaflyst 通过 MCP tap、Python SDK 或 OTLP endpoint 进行带外记录，然后对敏感 payload 进行脱敏，并对事件流进行 hash-chain（哈希链）处理。 - 以完整性和间隙验证的方式重放 agent 会话。 - 使用只读身份扫描 AWS、GitHub 和 Google Cloud。 - 在凭证图谱中连接 agent、凭证、权限和资源。 - 在采取遏制措施之前评估爆炸半径。 - 导出无需运行 Leaflyst 服务即可验证的证据。 ## 核心能力 | 领域 | 包含内容 | | --- | --- | | 飞行记录仪 | MCP tap、Python SDK、OTLP 摄取、payload 脱敏、hash-chained 事件、重放 | | 凭证图谱 | 只读 AWS、GitHub 和 GCP 扫描，包含凭证和权限触达范围 | | 检测 | 基于规则的异常、记录间隙检测、Slack 和电子邮件警报 | | 响应 | 爆炸半径分析、事件报告、使用独立凭证的引导式撤销 | | 运维 | 多租户仪表板、使用量控制、公开隔离演示、独立证据验证器 | ## 工作原理 ``` flowchart LR A["AI agent"] --> C["MCP tap / Python SDK / OTLP"] C --> I["Write-only ingest API"] I --> R["Redaction + hash chain"] R --> S["PostgreSQL / ClickHouse / object storage"] P["AWS / GitHub / GCP"] --> W["Read-only scanner"] W --> G["Credential graph + blast radius"] S --> D["Replay, alerts, and evidence reports"] G --> D D --> V["Guided containment"] X["Separate revocation credentials"] --> V ``` ## 安全模型 - 记录使用仅写入（write-only）的摄取 token；agent 无法读取或重写历史记录。 - 凭证图谱中绝不存储任何密钥值。 - payload 在存储前会被脱敏，并使用逐 payload 数据密钥进行加密。 - 扫描器凭证是只读的，且绝不会用于撤销操作。 - Tap 和 SDK 故障会降级记录功能，但不会阻塞 agent。 - 捕获到的 agent 输入和输出始终被视为不受信任的内容。 ## 布局 ``` apps/api FastAPI: ingest, app API, chain verification apps/web Next.js dashboard packages/schemas Canonical event schema (JSON Schema) + generated Pydantic/TS types packages/abx-sdk Python SDK (LangGraph instrumentor) packages/abx-tap MCP tap CLI services/scanner Credential scanner workers (AWS, GitHub, Google Cloud) services/rules Anomaly rule engine + alerts infra docker compose, migrations, DDL demo End-to-end demo scenario tools/abx_verify.py Standalone standard-library evidence verifier ``` ## 快速开始 要求：Python 3.12、[uv](https://docs.astral.sh/uv/)、Node.js 24、 [pnpm](https://pnpm.io/) 和 Docker。 ``` uv sync --all-packages pnpm -C apps/web install docker compose -f infra/docker-compose.dev.yml up -d uv run python infra/migrate.py ``` 在不同的终端中启动 API 和仪表板： ``` uv run uvicorn abx_api.main:app --reload pnpm -C apps/web dev ``` 打开 [http://localhost:3000/onboarding](http://localhost:3000/onboarding) 以创建工作区及其仅写入的摄取 token。当 `ABX_DEMO_ENABLED=true` 时，可以通过 [http://localhost:3000/demo](http://localhost:3000/demo) 访问公开的 PocketOS 演示。 运行完整的本地检查： ``` uv run pytest uv run ruff check . && uv run mypy uv run python packages/schemas/scripts/codegen.py --check uv run python packages/schemas/scripts/api_contracts.py --check pnpm -C apps/web lint pnpm -C apps/web test pnpm -C apps/web exec tsc --noEmit pnpm -C apps/web build ``` ## 发布镜像 API、迁移运行器（migration runner）、扫描器 worker 和警报 worker 共享一个锁定的非 root Python 镜像。独立的 Next.js 镜像包含用于生成事件报告 PDF 的匹配 Playwright Chromium 运行时： ``` docker build -f infra/docker/python.Dockerfile -t leaflyst-python:local . docker build -f infra/docker/web.Dockerfile -t leaflyst-web:local . uv run python demo/container_smoke.py ``` 冒烟检查会拒绝以 root 运行的镜像和已配置的密钥，然后验证两个容器的健康检查、公开的安全页面以及打包的 Chromium 二进制文件。运行时凭证必须由部署平台注入。有关一键发布拓扑，请参阅 [`docs/deployment.md`](docs/deployment.md)。 ## 仪表板和引导流程 服务端渲染的仪表板可以读取数据，而无需将 API admin key 暴露给浏览器： ``` ABX_API_URL=http://localhost:8000 ABX_ADMIN_KEY=dev-admin-key ``` 打开 `/onboarding` 以创建工作区并接收仅写入的摄取 token。 `ABX_TENANT_ID` 仍然可用作本地开发的兜底方案。有关冷启动和生产路径，请参阅 [`docs/onboarding.md`](docs/onboarding.md)；有关 tap、SDK、OTLP、AWS、local-scanner、GitHub 和 Google Cloud 的设置，请参阅 [`docs/integrations.md`](docs/integrations.md)。 在接入支付控制平面（payment control plane）之前，每日记录限制由运营商环境分配： ``` uv run python -m abx_api.admin set-plan [per-token-payloads|unlimited] ``` 超过配置的限制不会导致记录被拒绝。事件依然会被脱敏、摘要、链接和索引。租户/日聚合计数驱动计划报告；另外的可选参数控制每个仅写入 token 独立的 payload 额度。当某个 token 额度耗尽时，它将切换为仅记录元数据，且不会影响其他记录器。 对于 GitHub App 连接流程，请设置 `ABX_GITHUB_APP_SLUG`、 `ABX_GITHUB_APP_ID`、`ABX_GITHUB_PRIVATE_KEY` 以及生产环境的 `ABX_GITHUB_STATE_SECRET`。将 App 设置 URL 配置为 `/v1/integrations/github/setup`，然后使用 `uv run abx-scanner-worker` 运行扫描器 worker。Provider 密钥保留在 API/worker 环境中；PostgreSQL 仅存储安装标识符。 Google Cloud 扫描仅在扫描器 worker 内部使用 Application Default Credentials。将 `ABX_GCP_SCANNER_PRINCIPAL` 设置为托管的 IAM 成员，授予“集成”页面上列出的读取角色，并输入项目 ID 以排队进行首次扫描。作业仅存储项目标识符；图谱仅存储服务账号密钥 ID 和 IAM 可触达范围，绝不存储 token 或私钥材料。 ## Python SDK 和 OTLP LangGraph 使用标准的 callback 配置： ``` from abx import instrument callback = instrument(agent_id="billing-bot") result = graph.invoke(inputs, {"callbacks": [callback]}) ``` 设置 `ABX_INGEST_TOKEN` 以及可选的 `ABX_OTLP_ENDPOINT`（默认： `http://localhost:8000/v1/otlp/traces`）。消息内容默认处于禁用状态；使用 `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` 可将其开启。 在应用程序关闭期间调用 `callback.shutdown()` 以刷新缓冲的 span。 现有的 OTLP exporter 可以将 protobuf traces 发送至 `/v1/otlp/traces`，并在 `Authorization: Bearer ...` header 中附带仅写入的摄取 token。系统会对当前及旧版的 OTel GenAI、OpenLLMetry 和 OpenInference 属性进行标准化处理。 ## 警报与遏制 运行 `uv run abx-alert-worker` 以评估队列中的事件，这不会给记录路径增加额外工作。Slack 和电子邮件发送使用部署密钥 `ABX_SLACK_WEBHOOK_URL` 和 `ABX_RESEND_API_KEY`；仪表板仅存储非敏感的频道设置和电子邮件收件人。 撤销操作绝不重用扫描器凭证。AWS 遏制要求使用独立的 `ABX_AWS_REVOKE_ACCESS_KEY_ID` 和 `ABX_AWS_REVOKE_SECRET_ACCESS_KEY` 身份，并使用 `infra/aws/revoker-policy.yaml` 将其权限限制为 `iam:UpdateAccessKey` 和 `iam:DeleteAccessKey`。GitHub 遏制使用独立的 `ABX_GITHUB_REVOKE_TOKEN`，并具备 Personal access tokens 写入和 repository Administration 写入权限。无论配置如何，预热凭证（Warm credentials）始终保持仅限引导模式。Google Cloud 服务账号密钥在现阶段也仅限引导模式：影响分析屏幕会生成禁用/删除命令，而仅有 GET 权限的扫描器身份则没有写入适配器。

标签：AI代理监控, StruQ, 事故响应, 云安全态势管理, 凭证图谱, 前端应用, 审计日志, 攻击面分析, 数据防泄露, 测试用例, 特征检测, 请求拦截, 逆向工具