CyberEdge实战教程：cyberedge-agent JSON桥接与gRPC协议契约上手-迪斯科星球

CyberEdge实战教程：cyberedge-agent JSON桥接与gRPC协议契约上手

【免费下载链接】CyberEdge互联网资产综合扫描/攻击面测绘项目地址: https://gitcode.com/gh_mirrors/cy/CyberEdge

CyberEdge 是一个面向互联网资产综合扫描与攻击面测绘的 AI 原生外部攻击面管理平台。它的控制平面只有一条契约：gRPC + Protobuf；AI Agent 通过 Skills 和类型化 RPC 调用它，人类则通过可选的只读 Web 界面观察结果。本教程带你快速上手 CyberEdge 的核心入口——cyberedge-agentJSON 桥接，并读懂整套 gRPC 协议契约，5 分钟完成第一次资产测绘调用。

为什么 CyberEdge 把 gRPC 协议契约放在核心

CyberEdge 的技术栈可以一句话说清：Rust 模块化单体 + gRPC/Protobuf 控制平面 + PostgreSQL 持久化。所有写入操作（建 Scope、启动扫描、上报 Finding）都必须经过类型化 RPC，且每一笔调用都携带调用方身份，受能力门控约束。

这种设计带来两个直接好处：

🛡️契约即边界：AI Agent 无法提供端口、模板、路径等敏感参数，攻击面只由服务端固定的策略集驱动；
📋全程可审计：每个 RPC 都带有request_id、agent_id、skill_name等上下文，可追溯每一次调用。

完整的产品架构见docs/ai-native-architecture.md，实现架构见docs/architecture.md。

cyberedge-agent：JSON 桥接的设计思路

cyberedge-agent是一个独立的桥接程序，专为 Skills / AI Agent 设计（不是给人用的交互命令行）：

特性	说明
输入	stdin 接收一个 JSON 信封
输出	stdout 输出 JSON Lines
交互模式	无，写一段 JSON 即执行一次调用
默认传输	连接本地 Unix Domain Socket（默认`unix:///tmp/cyberedge.sock`）

请求信封的核心字段如下：

字段	作用
`request_id`	请求唯一标识，用于审计关联
`idempotency_key`	幂等键，重复提交同一键不会产生重复副作用
`agent_id`/`skill_name`/`skill_version`	调用方身份三元组，是能力门控的依据
`action`	要执行的操作，如`create_scope`、`start_assessment`
业务参数	按 action 不同而不同，如`targets`、`scope_id`、`profile`

桥接的输入输出行为可以在测试用例 tests/bridge.rs 中看到完整示例：它发送一个create_scope请求，断言返回的 JSON 中ok为true，且域名Example.COM被服务端自动规范为example.com。服务端进程本体在 src/main.rs 中启动 RPC 监听。

3分钟跑通：Docker 部署与第一次调用

第 1 步，克隆仓库并启动：

git clone https://gitcode.com/gh_mirrors/cy/CyberEdge cd CyberEdge docker compose up --build -d

第 2 步，在 service 容器内通过桥接创建一个扫描范围（Scope）：

printf '%s' '{"request_id":"req_health_scope","idempotency_key":"idem_health_scope","agent_id":"codex-main","skill_name":"cyberedge-discover-assets","skill_version":"0.1.0","action":"create_scope","name":"Example","authorization_ref":"authorization:change-1234","targets":[{"kind":"domain","value":"example.com"}]}' \ | docker compose exec -T cyberedge cyberedge-agent

第 3 步，解读响应。你会得到类似这样的 JSON：

{"ok":true,"result":{"id":"scope_...","name":"Example","targets":[{"kind":"domain","value":"example.com"}]}}

拿到scope_id后，就可以启动一次端到端评估（standard使用固定基线端口，thorough覆盖 1-1024 端口加高价值端口）：

printf '%s' '{"request_id":"req_assess_1","idempotency_key":"idem_assess_1","agent_id":"codex-main","skill_name":"cyberedge-assess-scope","skill_version":"0.1.0","action":"start_assessment","scope_id":"scope_...","profile":"thorough"}' \ | docker compose exec -T cyberedge cyberedge-agent

评估流程会串联被动 DNS、证书透明度、主动服务盘点、TLS/HTTP 观察、漏洞基线、公开代码情报、CPE 精确 CVE 关联与备案情报，最后通过GetTaskReport一次性取回结果。

gRPC 协议契约：一次看懂核心 RPC

全部契约定义在 proto/cyberedge/v1/cyberedge.proto，共 22 个 RPC。按用途分组如下：

分组	RPC	用途
健康检查	`Health`	探活
范围管理	`CreateScope`/`GetScope`	定义可授权扫描的资产范围
任务执行	`StartScan`/`StartAssessment`/`GetTask`/`WatchTask`/`CancelTask`	启动与跟踪任务（`WatchTask`是流式推送）
就绪探测	`GetReadiness`	查看各适配组件（截图/Nuclei/CVE 等）是否可用
周期监控	`CreateSchedule`/`SearchSchedules`/`SearchAssetChanges`/`SearchExposureChanges`	定时巡检与资产/暴露面变化追踪
资产查询	`SearchAssets`/`SearchServices`/`SearchCertificates`/`SearchWebsites`	只读查询四类核心资产
结果取证	`SearchFindings`/`SearchObservations`/`GetEvidence`/`GetTaskReport`/`SearchAudit`	发现项、观察记录、证据与审计

几个理解契约的关键点：

InvocationContext：几乎每个请求都内嵌request_id、idempotency_key、agent_id、skill_name、skill_version五个字段——这就是能力门控和审计的数据来源；
任务状态机：QUEUED → RUNNING → COMPLETED / FAILED / CANCELED。注意COMPLETED只表示"流程正常结束"，不代表所有可选适配器都运行过，各阶段覆盖情况要看GetTaskReport.coverage；
证据与报告分离：GetTaskReport只带 Evidence 的标识、哈希和时间戳（保证报告有界），真正要调取证据内容时用GetEvidence；
目标类型：Scope 支持domain、ip、cidr、organization四种 TargetKind，且必须由授权引用（authorization_ref）背书。

权限模型：能力门控如何生效

CyberEdge 要求显式的 Agent 能力策略文件，通过环境变量CYBEREDGE_AGENT_POLICY注入。参考配置见 config/agents.example.toml，其结构是"按 Agent + Skill + 版本"三段绑定能力：

[[grants]] agent_id = "codex-main" skill_name = "cyberedge-discover-assets" skill_version = "0.1.0" capabilities = [ "scope.manage", "scan.passive", "task.read", "asset.read", "report.read", "audit.read", ]

⚠️ 实践建议：不要给被动发现类 Skill 授予scan.active能力，把主动扫描的授权放在单独的 Skill 绑定中，调用前务必先核对 Scope 的授权引用。

进阶：本地 UDS 与远程 mTLS 两种传输

本地（默认）：RPC 服务监听 Unix Domain Socket，路径可用CYBEREDGE_RPC_SOCKET覆盖，默认/tmp/cyberedge.sock；
远程：设置CYBEREDGE_RPC_ADDR启用 TCP HTTP/2 传输，此时强制双向 mTLS，服务端需提供证书、私钥、客户端 CA 三个 PEM 文件（CYBEREDGE_TLS_CERT/CYBEREDGE_TLS_KEY/CYBEREDGE_TLS_CLIENT_CA）。cyberedge-agent设置CYBEREDGE_RPC_ENDPOINT并配齐CYBEREDGE_TLS_DOMAIN/CYBEREDGE_TLS_CA/CYBEREDGE_TLS_CERT/CYBEREDGE_TLS_KEY后即可远程桥接。

安全提示：Agent 客户端 CA 不要与 Web 反向代理的 CA 混用，Agent 身份应独立轮换。

常见问题排查

Q：桥接能交互多轮对话吗？不能。cyberedge-agent只接受 stdin 上的一个 JSON 信封，输出 JSON Lines 后退出，没有交互模式。

Q：任务 COMPLETED 了，但某阶段没有结果？查看GetTaskReport.coverage中该阶段的state：complete/partial/unavailable/blocked。unavailable通常意味着对应适配器（如 Nuclei、CVE、截图）未启用，用GetReadiness可确认各组件可用状态。

Q：返回了ok:false怎么办？检查错误详情中的code与retryable字段，并核对三元组（agent_id/skill_name/skill_version）是否精确匹配策略文件中的授权条目——能力不匹配是最常见的失败原因。

企业官网建设流程全解析