NullRabbitLabs/ferret

# Ferret 现有工具只能发现那些主动广播自身的节点。Ferret 专于发现那些不广播的基础设施。 这是一款由 LLM 驱动的区块链网络验证者基础设施发现工具。它从链上数据入手，利用 OSINT —— 证书透明度日志、WHOIS、ASN 关联、GitHub 代码搜索 —— 来寻找那些从未出现在 gossip 协议或节点表中的相关主机。 Sui 和 Solana 等网络虽然在链上公开了验证者 IP 地址，但运营者实际运行的不仅仅是用于投票的节点。RPC 端点、监控服务器、备份节点、Sentry 层 —— 这些“影子基础设施”对于协议原生的爬虫来说是不可见的，且往往缺乏监控。Ferret 能发现它们。 ## 功能 - **链上种子获取 (On-chain seeding)** - 直接从链上 RPC (Sui, Solana, Cosmos Hub) 拉取验证者地址 - **批量富化 (Batch enrichment)** - 无需 LLM 即可进行 ASN 查询、反向 DNS 和 IP 聚类 - **LLM OSINT 循环** - 自主 Agent 利用 CT 日志、WHOIS、GitHub 搜索来发现相关主机 - **工具预算控制** - 可配置的工具调用、空闲轮次和新主机上限，以防止成本失控 - **CDN 过滤** - 自动剔除 Cloudflare、Fastly 和 Akamai 的边缘 IP - **多网络支持** - 可扩展架构，只需实现一个类即可添加新链 - **差异追踪** - 对比不同运行的资产快照以检测基础设施变更 - **Discovery API 集成** - 结果持久化到 REST API，供下游扫描流水线使用 ## 安装 ``` git clone https://github.com/NullRabbitLabs/ferret.git cd ferret python -m venv venv source venv/bin/activate pip install -r requirements.txt ``` **Docker:** ``` docker build -t ferret . docker run --env-file .env ferret discover --network sui ``` ## 用法 ``` # 发现 Sui validator 基础设施 ferret discover --network sui # 使用 focus 指令发现 Solana ferret discover --network solana --focus "new validators this week" # 查看当前清单 ferret inventory --network sui # 显示最近的发现运行 ferret runs --network sui --last 5 # Diff 自指定日期以来的清单 ferret diff --network sui --since 2026-02-17 ``` ### 本地模式 (无需 API 后端) 在未运行 `discovery-service` 的情况下运行发现会话。结果存储在内存中并打印到 stdout。适用于一次性运行、CI 流水线或测试新网络。 ``` # 仅打印结果到 stdout python -m src.cli discover --network cosmos --local # 保存结果到 JSON 文件 python -m src.cli discover --network cosmos --local --output cosmos.json ``` `--output` 蕴含了 `--local` —— 您不需要同时使用这两个标志。JSON 文件包含完整的运行记录：主机、验证者、统计信息和 Agent 的摘要。 ## 工作原理 Ferret 分两个阶段运行： **阶段 1 - 代码。** 以链上验证者地址为种子，对采样 IP 批量执行 ASN 和反向 DNS 富化。无需 LLM。生成关于哪些 ASN 托管验证者以及哪些 IP 范围值得关注的聚类摘要。 **阶段 2 - LLM。** 将聚类摘要和少量工具预算提供给自主 Agent。该 Agent 执行 OSINT —— 证书透明度搜索、WHOIS 查询、GitHub 代码搜索、子网探测 —— 并报告其发现的新主机。当预算耗尽、达到空闲阈值或达到新主机上限时，Agent 会自动终止。 结果将写入 Discovery API，供下游扫描和保护系统使用。 ## 配置 | 变量 | 默认值 | 描述 | |---|---|---| | `DISCOVERY_API_URL` | `http://localhost:8092` | Discovery API 基础 URL | | `LLM_GATEWAY_URL` | `http://localhost:8090` | OpenAI 兼容的 LLM 网关 | | `DISCOVERY_LLM_MODEL` | `deepseek-chat` | 模型 (必须支持工具调用) | | `DISCOVERY_EMBEDDING_MODEL` | `text-embedding-3-small` | 用于假设搜索的 OpenAI embedding 模型 | | `DISCOVERY_SUI_RPC` | `https://fullnode.mainnet.sui.io:443` | Sui RPC 端点 | | `DISCOVERY_SOLANA_RPC` | `https://api.mainnet-beta.solana.com` | Solana RPC 端点 | | `DISCOVERY_COSMOS_RPC` | `https://cosmos-rpc.publicnode.com` | Cosmos Hub RPC 端点 | | `DISCOVERY_MAX_TOOL_CALLS` | `30` | 每次运行的 LLM 工具调用预算 | | `DISCOVERY_MAX_NEW_HOSTS` | `10` | 发现 N 个新主机后停止 | | `DISCOVERY_MAX_IDLE_CALLS` | `15` | 连续 N 次调用无发现后停止 | | `DISCOVERY_PROBE_RATE_LIMIT` | `50` | 最大并发 TCP 连接数 | | `GITHUB_TOKEN` | - | GitHub API token (可选) | | `SERP_API_KEY` | - | SerpAPI key (可选) | ## 添加网络 添加一条新链只需修改 **2 个文件**。其他所有内容 —— 批量富化、LLM OSINT 循环、上下文管理、API 持久化 —— 均为通用逻辑。 ### 1. 实现 `ChainTools` 创建 `src/tools/blockchain/.py`: ``` from src.tools.blockchain.base import ChainTools class AptosTools(ChainTools): def schemas(self) -> list[dict]: ... def primary_tool_name(self) -> str: ... def get_tool_map(self) -> dict[str, Callable]: ... async def get_seed_hosts(self, network: str) -> list[dict]: ... ``` `get_seed_hosts()` 返回包含以下字段的主机字典：`ip_address`、`port`、`service_type`、`confidence`、`discovery_method`、`validator_pubkey`、`reasoning`。 该类在启动时通过 `__init_subclass__` 自动发现 —— 无需注册步骤。 请参阅 `sui.py`、`solana.py` 和 `cosmos.py` 以获取参考实现。 ### 2. 将数据添加到 `src/networks.json` ``` "aptos": { "env_var": "DISCOVERY_APTOS_RPC", "default_rpc_url": "https://fullnode.mainnet.aptoslabs.com/v1", "allowed_ports": [6180, 6181, 8080], "description": "Aptos mainnet validator nodes" } ``` 就这样。cli.py、server.py、config.py 和子网探测白名单都会自动更新。 ## 架构 ``` src/ ├── agent.py # LLM discovery loop with tool budget management ├── cli.py # CLI: discover, inventory, runs, diff ├── config.py # Environment configuration ├── gateway_client.py # OpenAI-format LLM gateway client ├── api_client.py # Discovery API HTTP client ├── db.py # Data models ├── networks.json # Network registry — edit here to add a chain ├── networks.schema.json # JSON Schema for IDE validation ├── networks.py # Loads networks.json, exports NETWORK_DEFINITIONS └── tools/ ├── base.py # BaseTool with rate limiting ├── schemas.py # OpenAI tool schemas ├── dns.py # DNS + reverse DNS ├── network.py # ASN, cert transparency, WHOIS, subnet probe ├── osint.py # GitHub code search, web search ├── state.py # Inventory read/write via API ├── registry.py # Network + tool dispatch └── blockchain/ ├── base.py # ChainTools abstract base ├── sui.py # Sui mainnet ├── solana.py # Solana mainnet └── cosmos.py # Cosmos Hub mainnet ``` ## 运行测试 ``` pytest pytest -m "not integration" # skip tests requiring a live API ``` ## Ferret 为何存在 像 [Nebula](https://github.com/dennis-tra/nebula) 和 [ethereum/node-crawler](https://github.com/ethereum/node-crawler) 这样的协议原生爬虫只能发现参与 gossip 的节点。像 [solanamonitoring](https://github.com/stakeconomy/solanamonitoring) 这样的监控工具只能跟踪您自己节点的健康状况。它们都无法发现运营者在验证者 *旁边* 运行的基础设施 —— 而这些主机往往暴露程度最高且监控最少。 Ferret 由 [NullRabbit](https://nullrabbit.ai) 构建，我们发现 **主要网络中 40% 的验证者存在运营者未知的严重漏洞** —— 这些漏洞大多位于从未出现在任何节点表中的基础设施上。 ## 社区 Ferret 是开源软件，遵循 [MIT License](LICENSE)。 - 🐛 [提交 Issue](https://github.com/NullRabbitLabs/ferret/issues) 反馈 Bug 或功能需求 - 💬 [讨论区](https://github.com/NullRabbitLabs/ferret/discussions) 用于提问和交流想法 - 🔧 欢迎提交 PR —— 特别是新的链实现 由 [NullRabbit](https://nullrabbit.ai) 构建 · NullRabbit 开源安全工具集的一部分

标签：ASN分析, DLL 劫持, Docker, ESC4, GitHub, OSINT, Python, Solana, Sui, Web3安全, WHOIS查询, 区块链安全, 协议探测, 基础设施侦察, 大语言模型, 威胁情报, 安全防御评估, 实时处理, 开发者工具, 无后门, 检测规则, 网络安全, 网络资产发现, 自动化安全工具, 证书透明度日志, 请求拦截, 资产测绘, 逆向工具, 隐私保护, 验证节点