sebastianspicker/rootstock

# Rootstock [](https://github.com/sebastianspicker/rootstock/actions) [](https://app.codacy.com/gh/sebastianspicker/rootstock/dashboard) [](https://www.bestpractices.dev/projects/13235) [](https://scorecard.dev/viewer/?uri=github.com/sebastianspicker/rootstock) Rootstock 是一个 macOS 安全分析工具的代码库。其核心工作流会将本地安全元数据收集到 JSON 制品中，将该制品导入 Neo4j，推导出安全关系，并提供查询、报告和本地图查看器。 该代码库还包含独立构建的 Red 和 Blue 包。它们与核心共享 macOS 安全词汇表，但使用独立的制品，除非操作员运行明确的桥接命令，否则不会输入到核心图中。 ## 当前功能 | 组件 | 已实现的角色 | 主要制品 | |---|---| | 核心收集器 | 读取本地 TCC、entitlement、代码签名、持久化、Keychain 元数据、XPC、MDM、身份及相关主机证据 | `scan.json` | | 核心图 | 验证并导入扫描，推导关系，运行 Cypher 查询，编写报告，并提供仅限回环且经过身份验证的查看器 API | Neo4j 数据、报告或查看器 HTML | | cve-scan | 收集明确范围内的包、服务、Web、TLS 和 IaC 证据，并可写入图桥接制品 | `rootstock-export.json` | | Rootstock Red | 执行只读主机评估并写入结构化发现结果；其独立的实验室可执行文件包含受授权控制、默认为 dry-run 的验证操作 | JSON、JSONL、SARIF 或 Markdown 格式的发现结果 | | Rootstock Blue | 将离线 macOS 制品解析为事件响应案例、时间线、检测和报告；可选的实时 Endpoint Security 功能具有额外的平台要求 | `.rsbcase` 案例包 | 有关制品边界和可选的互操作命令，请参阅[产品系列](docs/FAMILY.md)。 ## 已知限制 - 核心收集仅限 macOS，且表示的是某一时间点的主机快照。 - 如果没有完全磁盘访问权限，收集器返回的 TCC 数据可能不完整。 - 图导入、推理、查询、报告和 API 行为需要 Neo4j 5.x。 - 在此 alpha 版本中，核心 API 及其 Neo4j 连接特意设计为仅限回环访问。 - 推导出的攻击路径描述的是建模的先决条件。它们并不能证明漏洞利用一定会成功。 - Red Lab 仅能通过其独立的可执行文件和明确的授权控制来修改系统状态。它不属于默认的评估二进制文件。 - Blue 实时 Endpoint Security 操作需要签名、entitlement 和系统批准。离线 fixture 支持的行为比实时扩展路径具有更广泛的测试覆盖率。 - 在 `0.1.0-alpha.1` 核心发布程序中，Red 和 Blue 保留独立的版本标签，并且是仅包含源代码的组件。 ## 要求 | 表面 | 要求 | |---|---| | 核心收集器 | macOS 14 或更高版本；Xcode 26.6 中的 Swift 6.3 | | Rootstock Red | macOS 13 或更高版本；Swift 6.2 或更高版本 | | Rootstock Blue | macOS 14 或更高版本；Swift 6.2 或更高版本 | | RootstockMacFacts | macOS 13 或更高版本；与 Swift tools 6.0 兼容的工具链 | | 核心图 | Python 3.10 或更高版本；`uv`；Neo4j 5.x | | cve-scan | Python 3.11 或更高版本；用于锁定开发环境的 `uv` | | 查看器开发 | `.node-version` 中指定的 Node.js；npm 11.17.0 | | Neo4j 集成测试 | Docker 或其他可访问的 Neo4j 5.26 社区版实例 | 收集器清单需要 Swift tools 6.3。Swift 6.2 工具链无法构建它。 ## 安装和构建 ### 核心收集器 ``` cd collector swift build -c release cd .. ``` 发布的可执行文件是 `collector/.build/release/RootstockCLI`。 ### 核心图环境 ``` uv sync --project graph --locked --all-extras ``` ### cve-scan 环境 ``` uv sync --project modules/cve-scan --locked --all-extras ``` ### 查看器开发环境 ``` npm ci --no-audit --no-fund --ignore-scripts npx --no-install playwright install chromium ``` ## 配置 核心图使用这些环境变量： - `NEO4J_URI`，默认为本地 Bolt endpoint - `NEO4J_USER` - `NEO4J_PASSWORD` - `ROOTSTOCK_API_TOKEN`，`/api/*` 路由必需，且至少为 32 字节 使用以下命令生成临时查看器 API token： ``` export ROOTSTOCK_API_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" ``` 已提交的 `.env.example` 仅作为公开示例。请勿提交包含具体内容的环境文件。CVE 刷新和范围内的网络证据是可选的；核心收集器本身没有网络收集路径。 ## 核心用法 运行扫描： ``` collector/.build/release/RootstockCLI --output scan.json ``` 当仅需较小范围的扫描时，选择模块： ``` collector/.build/release/RootstockCLI --output scan.json --modules tcc collector/.build/release/RootstockCLI \ --output scan.json --modules entitlements,codesigning ``` 验证制品： ``` uv run --project graph --locked \ python scripts/validate-scan.py scan.json ``` 启动 Neo4j 并运行图 pipeline： ``` (cd graph && NEO4J_AUTH=neo4j/CHANGE_ME docker compose up -d) NEO4J_PASSWORD=CHANGE_ME uv run --project graph --locked \ bash graph/pipeline.sh scan.json ``` 启动经过身份验证的本地查看器 API： ``` NEO4J_PASSWORD=CHANGE_ME uv run --project graph --locked \ bash graph/pipeline.sh scan.json --serve 8000 ``` 停止 Compose 服务而不删除图数据： ``` (cd graph && NEO4J_AUTH=neo4j/CHANGE_ME docker compose down) ``` Neo4j 将数据库和日志数据存储在 `graph/docker-compose.yml` 声明的命名卷中。`docker compose down` 会保留这些卷。 要删除本地数据库和日志，请在确认 Compose 项目不包含您需要的数据后，使用以下破坏性命令： ``` (cd graph && NEO4J_AUTH=neo4j/CHANGE_ME docker compose down --volumes) ``` 在同一次 pipeline 运行中导入现有的 cve-scan 桥接： ``` NEO4J_PASSWORD=CHANGE_ME uv run --project graph --locked \ bash graph/pipeline.sh scan.json \ --cve-scan-export modules/cve-scan/runs/local/rootstock-export.json ``` 无需收集真实主机即可使用[合成示例](examples/README.md)。报告和查看器文件属于被忽略的输出目录。 ## 界面截图 这些图像是所维护的 Graphite Laboratory 查看器在使用公开的七节点合成 fixture 时的 Playwright 捕获。它们在不读取真实扫描的情况下测试了生产模板、样式表、bundle、证据档案、路径构建器和图过滤器。它们并不证明实时 Neo4j 或 API 的行为。 选择截图以打开全尺寸捕获。 | 概览 | 证据档案 | |---|---| | [](docs/screenshots/viewer-overview.png) | [](docs/screenshots/viewer-node-inspector.png) | | 建模路径 | 风险过滤器 | |---|---| | [](docs/screenshots/viewer-attack-path.png) | [](docs/screenshots/viewer-risk-filter.png) | 捕获说明和隐私规则在 [docs/screenshots/README.md](docs/screenshots/README.md) 中。 ## 开发和验证 运行受更改影响的组件检查。完整的本地候选集为： ``` # Core collector，需要 Swift 6.3 (cd collector && \ swift build -Xswiftc -strict-concurrency=complete -Xswiftc -warnings-as-errors && \ swift test --parallel \ -Xswiftc -strict-concurrency=complete -Xswiftc -warnings-as-errors) # 共享与家庭 Swift packages (cd packages/RootstockMacFacts && swift build && swift test) (cd rootstock-red && swift build --product rootstock-red && swift test) (cd rootstock-blue && \ swift build --product rootstock-blue && swift test && \ make content-validate && make check-non-goals) # Core graph 和 contracts uv run --project graph --locked ruff check graph/ scripts/ examples/ docs/ \ --exclude docs/archive --exclude docs/private uv run --project graph --locked pytest graph/tests python3 scripts/check-scan-contract-fields.py python3 scripts/check-technique-catalog.py uv run --project graph --locked \ python scripts/validate-scan.py examples/demo-scan.json # cve-scan (cd modules/cve-scan && uv run --locked ruff check . && uv run --locked pytest) # Viewer npm run typecheck npm run bundle npm run test:viewer:unit npm run test:viewer:bundle npm run test:viewer:performance npm run test:browser # Script contracts bash tests/scripts/test_benchmark.sh # Release 结构 python3 scripts/check-release.py ``` 需要 Neo4j 的流程是独立的： ``` (cd graph && ROOTSTOCK_REQUIRE_NEO4J=1 NEO4J_PASSWORD=CHANGE_ME \ uv run --locked pytest tests -v --tb=short) NEO4J_PASSWORD=CHANGE_ME uv run --project graph --locked \ bash tests/integration/test_full_pipeline.sh ``` 如果此流程未运行，请勿将快速测试概括为实时图验证。请参阅[质量门禁](docs/QUALITY.md) 和[发布程序](docs/RELEASING.md)。 ## 代码库结构 ``` collector/ Core Swift collector graph/ Neo4j import, analysis, reports, API, and viewer modules/cve-scan/ Optional scoped CVE evidence module packages/RootstockMacFacts Shared read-only macOS vocabulary rootstock-red/ Assessment and gated lab Swift packages rootstock-blue/ DFIR and incident-response Swift packages examples/ Synthetic contract fixtures tests/browser/ Playwright end-to-end tests tests/integration/ Cross-component integration tests tests/scripts/ Repository script contract tests tests/viewer/ Viewer unit, bundle, and performance contracts tests/fixtures/ Generators for cross-package test fixtures docs/ Maintained public documentation scripts/ Validation, operational, release, and screenshot tools ``` ## 故障排除 - `package ... is using Swift tools version 6.3.0`：在构建收集器之前选择 Swift 6.3 工具链。CI 使用 Xcode 26.6。 - 在最近的 macOS 版本上 TCC 结果为空：授予运行收集器的终端完全磁盘访问权限，然后重新扫描。 - Neo4j 连接失败：确认容器健康，Bolt endpoint 是回环地址，并且配置的用户和密码匹配。设置 `NEO4J_PASSWORD` 后，运行 `uv run --project graph --locked python scripts/check-neo4j-connection.py`。 - 查看器返回 `401`：创建一个新的 `ROOTSTOCK_API_TOKEN` 并在查看器会话中输入相同的值。 - 图测试被跳过：将 `ROOTSTOCK_REQUIRE_NEO4J=1` 设置为可访问的 Neo4j 实例，以将必需的集成流程转换为硬失败。 更多案例记录在 [FAQ](docs/FAQ.md) 中。 ## 许可证 此代码库包含多个许可范围： - 核心收集器、图、查看器和根文档使用 [LICENSE](LICENSE) 下的 GPL-3.0； - `modules/cve-scan/` 使用其自身的 [license](modules/cve-scan/LICENSE) 下的 MIT； - `rootstock-red/` 和 `rootstock-blue/` 使用其自身许可文件下的 Apache-2.0。 共享的 `packages/RootstockMacFacts/` 许可范围尚未明确。在发布包含该共享包的公开源代码之前，必须解决此歧义。 核心候选版本的引用元数据位于 [CITATION.cff](CITATION.cff) 中。

标签：MITM代理, 反取证, 命令控制, 安全评估, 库, 应急响应, 数据采集, 暗色界面, 特征检测, 请求拦截, 逆向工具