eep0x10/Lodestone

## 为什么需要它 侦察总是在重复进行。上一次测试的成果往往散落在某个人的 `~/loot` 目录里、Burp 的项目文件中，或是 Slack 的某条聊天线索里。如果不重新做一遍这些工作，没人能回答关于 *我们对这台主机究竟了解多少*。 Lodestone 就是用来承载这个答案的地方。它被设计为 **由 AI 读写**，通过 MCP 进行交互——Web 界面虽然存在，但只是辅助角色。 **它是一个目录，而不是扫描器。** 它记录某个域名未配置 DMARC 的情况，与记录其 nameservers 的方式如出一辙：作为关于该资产的一项客观事实。至于这是否会引发安全问题，则由操作员在目录无法触及的具体业务上下文中自行判断。 ### 没有其他工具能做到 | 工具 | 涵盖功能 | 缺失部分 | |---|---|---| | [Nemesis](https://github.com/SpecterOps/Nemesis) | 文件富化、LLM agents、Postgres | 侦察、HTTP、图谱、业务上下文。它的 MCP 仅限内部 chatbot 使用 | | [Cervantes](https://github.com/CervantesSec/cervantes) | 项目管理、报告、真正的 MCP | 仅支持 CRUD——没有语义搜索、没有图谱、没有 artifacts | | [DefectDojo](https://github.com/DefectDojo/django-DefectDojo) | 200 多种工具解析器 | 专注于 AppSec 漏洞管理，而非知识库 | | [Faraday](https://github.com/infobyte/faraday) | 80 多种工具的协作导入 | 没有图谱、没有语义搜索、没有 MCP | | [reNgine](https://github.com/yogeshojha/rengine) | 自动化侦察 + 关联分析 | 它是一个 *scanner*，被死绑在自己的 pipeline 上 | | [Graphiti](https://github.com/getzep/graphiti) · [Cognee](https://github.com/topoteretes/cognee) | Knowledge graph + MCP | 与领域无关——它们不知道什么是 IP 或 APK | 所有工具都有同样的痛点：没有谁能将 **图谱 + 语义搜索 + 数 GB 的 artifacts + 可供外部调用的 MCP + 业务上下文 + 外网/内网的划分** 结合在一起。 实体的分类法遵循 [OWASP Amass Open Asset Model](https://github.com/owasp-amass/open-asset-model)，而不是自己另起炉灶。 ## 它存储什么 **图谱。** 约 70 种实体类型以及自由连接的边。基于 `(kind, natural_key)` 保证幂等性——Agent 重复发送同一台主机一百次，最终也只会生成一条记录。业务上下文 (`organization → business_unit → product → journey → application`) 与技术资产存在于同一个图谱中，因此你可以顺藤摸瓜，从一个孤立的 IP 找到它所服务的收入来源。 **两个视角。** 每个实体都带有 `exposure` 属性——external、DMZ、internal、partner 或 cloud——而每次工具运行都会记录其执行位置的 `vantage`（视点）。这使得那种只有同时具备这两个维度才具有意义的查询成为可能：找出所有外网暴露触达内部资产的关联关系。 **真实的拓扑结构。** Sites → networks → subnets → hosts，使用 Postgres 的 `inet` 类型结合 GiST 索引和 `ltree` 路径。*“哪个子网包含 10.42.7.19”* 是一次基于索引的包含查询，而且即便三个办公室复用同一段 RFC1918 地址，结果依然准确。主机会以双向方式自动绑定到网段——在主机录入后再导入子网，会自动将它们重新关联。 **HTTP 请求。** 完整的 requests 和 responses，包含参数清单，并为每个 endpoint 提供清晰的 `purpose` 描述。按哈希分区，分为 16 个分区。 **凭证。** 用户名、任何格式的哈希、破解出的密码、API 密钥、tokens、私钥。明文数据在静态存储时使用加密保护，密钥仅存在于 API 环境中。全盘的密码复用情况是基于 SHA-256 指纹计算的，因此在内网测试中最有价值的查询完全不需要解密任何内容。读取明文需要独立的权限并会记录审计日志。 **Artifacts。** APKs、IPAs、二进制文件、内存转储、工具的原始输出。通过流式传输存入 S3 兼容的 storage，并基于内容寻址——来自三个不同操作员的同一个 APK 在磁盘上只占用一个对象。 **Insights。** 它的用途、存在原因、连接方式。正是这一层让整个目录物有所值，经得起时间的考验。 ### 范围控制，以及为何在写入时校验 每次任务都需声明 `scope.in_scope`——包含 domains 和 CIDRs。每次 `ingest` 都会将批次数据与声明范围进行比对，并返回 `out_of_scope` 及具体的命名示例。 在标准模式下，数据不会被丢弃：侦察经常会发现超出声明范围的内容，如果直接静默丢弃，无异于另一种形式的数据丢失。但具体数字会出现在返回结果中，这样解析错误在写入时就能立刻暴露，而不是等到六个月后才被发现。 这绝非危言耸听。在一次真实的侦察中，一次错误的 eTLD+1 缩减操作将 `empresa.com.ar` 错认成了公共后缀 `com.ar`，导致在历史记录中查询 `*.com.ar` 时，带出了 17000 个毫不相干的阿根廷主机。它们距离进入客户的目录仅有一步之遥，而在那里，之后将没有任何人能把它们与真正的发现区分开来。**目录中的错误数据比缺失数据更可怕**，因为这抹去了两者之间的界限。 当有错误数据混入时，我们提供专门的修正流程，而无须直接敲 `psql`： ``` curl -X POST "$L/api/entities/purge?engagement=acme&run_id=" -H "$AUTH" # 默认安全；使用 &confirm=true 重复 ``` ## 安装说明 ``` git clone https://github.com/eep0x10/Lodestone.git && cd Lodestone cp .env.example .env # preencha os quatro segredos docker compose up -d --build ``` · API 文档位于 `/api/docs` · MCP 位于 `/mcp` ### 首次访问 空数据库会创建 **一个** 账户：`admin` / `admin`。它不会静静躺在那里等你记起来去修改——**只要它还处于初始状态，服务器就会拒绝所有 endpoint 请求**。列出 engagements、签发 API 密钥、创建用户、与 MCP 通信：所有操作都会返回 403。它唯一能做的，就是替换掉它自己。

使用 `admin` / `admin` 登录，设置真正的用户名和密码（至少 12 个字符），种子账户就会自动消失。你无法跳过这一界面，而且密码替换只接受一次——重复调用会返回 409。 这取代了以前将初始密码写在 `.env` 文件中的做法。放在文件里的凭证最终往往会被复制到各处服务器、粘贴到聊天记录中，甚至被意外 commit 到代码库。一个**公开已知、且在被修改前毫无作用**的弱密码，反而在失效时更加安全：如果有人在你配置好之前发现了你的实例，他们也做不了什么。 接下来，连接你的 Agent： ``` claude plugin install https://github.com/eep0x10/Lodestone --path plugin claude mcp add --transport http lodestone http://localhost:7800/mcp \ --header "Authorization: Bearer lode_sua_chave" ``` 想在接入前看看运行效果？ ``` python demo/seed.py --email voce@exemplo.com --password '...' ``` 完整的说明——包括 TLS、为团队成员分配独立密钥、实例间的数据迁移等——详见 [plugin/skills/lodestone/reference/setup.md](plugin/skills/lodestone/reference/setup.md)。 ## 使用说明 绝大多数情况下，你会通过 Agent 进行操作： ``` > ingira o output desse nmap no engagement acme-2026 > o que a gente já sabe sobre o portal de pagamentos? > quais contas compartilham senha com alguém que é admin? > como o perímetro alcança o SQL01? ``` 位于 [`plugin/`](plugin/) 的 Skill 教会 Agent 解析约 20 种工具格式并将其导入图谱，如实标记暴露情况，并妥善处理凭证。它与服务器打包在一起，因此新加入团队的成员只需从同一个仓库安装即可。 ### MCP 工具 | 工具 | 用途 | |---|---| | `explore` | **从这里开始。** 混合搜索 + 图谱邻居节点查询 + insights | | `get_entity` | 查看某项事物的所有信息及其来源 | | `graph_neighbors` | 从某个节点开始遍历 | | `network_topology` · `locate_address` | 查询 sites、networks、subnets；找出某个地址所属的网段 | | `exposure_bridges` | 查找外网触达内网的路径 | | `query_exchanges` | 按 host、path、status、参数筛选 HTTP 请求 | | `query_credentials` · `credential_reuse` | 搜索凭证；查找共享的密码 | | `reveal_secret` | 解密明文——受审计追踪 | | `ingest` · `add_insight` | 写入操作 | | `list_engagements` · `engagement_stats` | 全局概览 | ## 偶尔供人类使用的界面

Atlas — o parque inteiro de uma vez, filtrado por camada, exposição, criticidade ou tag. Quatro layouts, porque nenhum sobrevive a todo formato de grafo.	Topologia — sites, redes e segmentos à esquerda; toda relação que cruza o perímetro à direita.
Credenciais — mascaradas até serem reveladas, com grupos de reuso calculados por fingerprint. Grupos que contêm uma conta admin são destacados.	Detalhe — atributos, insights, observações com o run que as produziu, artefatos, vizinhos.

## 架构设计 只需一个 PostgreSQL，不需要四个数据库。 | 需求 | 解决方案 | 为什么不用显而易见的方案 | |---|---|---| | 图谱 | `edges` 表 + 递归 CTE | 图谱遍历通常很浅，且锚定在极小的种子节点集上。对于能在毫秒内通过索引 CTE 完成的查询，引入 Neo4j 只会增加运维负担 | | 语义搜索 | `pgvector`, HNSW | 独立的向量数据库会引入额外的数据一致性问题 | | 文本搜索 | Postgres FTS + `pg_trgm` | 为这个语料库专门维护一个 Elasticsearch 集群不划算 | | 排序 | Reciprocal Rank Fusion (RRF) | `ts_rank` 数值无界且依赖于语料库，余弦相似度在 `[0,2]` 之间。将两者互相归一化需要不断调参；而 RRF 只读取 *排名* | | Embeddings | 本地 ONNX，支持多语言 | 无需按 token 付费，且客户数据永远不会离开本地机器 | | 任务队列 | `FOR UPDATE SKIP LOCKED` | 仅为单一消费组引入 Redis + Celery 得不偿失 | | Artifacts | MinIO，基于内容寻址 | 几个 GB 的二进制大文件不适合存放在关系型数据库中 | | MCP | 直接实现的传输层 | SDK 的挂载接口变动频繁，而且身份验证必须基于每次请求——bearer token *本身即是* API 密钥 | 技术栈：Python 3.12 · FastAPI · asyncpg · PostgreSQL 17 + pgvector · MinIO · React 19 · Vite · Tailwind v4 · Cytoscape.js。全部基于 Docker 运行。 ## 跨实例共享 位于不同服务器上的两名操作员，可以通过 ZIP bundle 将各自的发现合并在一起。

导入界面只会显示 **如果不导入就会丢失的内容**。新的资产、边和 insights 都是增量叠加的，因此仅显示计数值——把它们全列出来反而会掩盖重点。界面会并排完整展示旧值与即将导入的新值，并且在你确认之前，应用按钮会处于锁定状态。 合并规则的设计使得几乎所有操作都是非破坏性的：tags 会合并，criticality 取最大值，名称和暴露属性保留第一个真实值。只有 **属性** 和 **凭证明文** 会覆盖原有内容——而这正是预览界面重点列出供你审核的部分。 ``` curl -X GET "$L/api/transfer/export?engagement=acme" -H "$AUTH" -o acme.zip curl -X POST "$L/api/transfer/preview?engagement=acme" -H "$AUTH" --data-binary @acme.zip curl -X POST "$L/api/transfer/apply?engagement=acme&bundle=&accept_overwrites=true" -H "$AUTH" ``` 如果不加 `accept_overwrites=true`，任何会造成数据破坏的 apply 操作都会返回 409，并且什么都不会写入。重复导入相同的 bundle 是无效操作（no-op）。 ## 运维须知 **`SECRETS_KEY` 无法找回。** 请将它与数据库分开备份。丢失此密钥会导致所有明文变得不可读——虽然哈希和密码复用关联分析依然可用，但明文密码将彻底丢失。 **修改 `EMBED_MODEL` 需要重新处理。** 向量维度在迁移（migration）发生时就已固定：执行 `docker compose exec api python -m app.worker --reembed`。 **备份。** 数据库使用 `pg_dump` 备份，artifacts 使用 MinIO 的 volume 备份。这两者是相互独立的——如果仅恢复了数据库而没有恢复 storage，系统会保留所有 blob 的元数据，但会丢失实际的字节数据。 ## 范围与合规性 这是一个用于记录授权安全测试工作的系统。它会如实存储你输入的所有内容，包括客户的凭证。请在你自己的基础设施上运行它，置于 TLS 加密之后，为每个人分配独立的 API 密钥，并且请像对待它所保护的密码一样，谨慎备份 `SECRETS_KEY`。 `demo/` 中的所有截屏和字节数据均为虚构合成。示例域名均位于 `.invalid` 和 `.test` 之下，根据 RFC 2606 和 RFC 6761 的规定，这些域名被专门保留，以确保示例永远不会解析到任何人的真实基础设施中。 ## 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。

标签：CNCF毕业项目, LLM, MCP, Unmanaged PE, 占用监测, 数据展示, 红队, 语义搜索, 请求拦截, 资产管理