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

CyberEdge实战教程cyberedge-agent JSON桥接与gRPC协议契约上手【免费下载链接】CyberEdge互联网资产综合扫描/攻击面测绘项目地址: https://gitcode.com/gh_mirrors/cy/CyberEdgeCyberEdge 是一个面向互联网资产综合扫描与攻击面测绘的 AI 原生外部攻击面管理平台。它的控制平面只有一条契约gRPC ProtobufAI 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-agentJSON 桥接的设计思路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 容器内通过桥接创建一个扫描范围Scopeprintf %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中该阶段的statecomplete/partial/unavailable/blocked。unavailable通常意味着对应适配器如 Nuclei、CVE、截图未启用用GetReadiness可确认各组件可用状态。Q返回了ok:false怎么办检查错误详情中的code与retryable字段并核对三元组agent_id/skill_name/skill_version是否精确匹配策略文件中的授权条目——能力不匹配是最常见的失败原因。延伸阅读运维与部署细节容器编排、各适配器 sidecar、通知 Webhookdocs/operations.md实现架构任务队列、事务边界、传输层docs/architecture.md产品架构与评估流水线语义docs/ai-native-architecture.md桥接行为测试示例tests/bridge.rsgRPC 契约源文件proto/cyberedge/v1/cyberedge.proto【免费下载链接】CyberEdge互联网资产综合扫描/攻击面测绘项目地址: https://gitcode.com/gh_mirrors/cy/CyberEdge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考