parthrohit22/kalyx
GitHub: parthrohit22/kalyx
一个执行证据完整性系统，通过哈希链账本、本地检查点和树莓派外部锚定来验证执行历史是否被篡改或截断。
Stars: 1 | Forks: 0
# KALYX
**执行证据完整性系统**
KALYX 是一个执行证据完整性系统，用于捕获、验证和外部锚定执行历史。
KALYX 不是 EDR、SIEM、防病毒软件、恶意软件拦截器或完整的主机证明系统。它不能防止攻击。其目的是保证证据的完整性和进行信任验证。
## 问题描述
本地日志很有用，但它们并不能自然而然地获得信任。
如果攻击者能够修改、重新排序、截断或替换本地历史记录，那么普通的日志文件可能看起来仍然合情合理。审查者可能会看到命令、时间戳和进程名，但却不知道早期的记录是否被更改或删除。
证据完整性之所以重要，是因为调查工作依赖于连续性：
- 这条记录是在前一条记录之后追加的吗？
- 记录在写入后是否发生了改变？
- 已验证的边界是否被移除或替换？
- 当前的账本可信度是否足以进行检测？
- 独立的锚点是否仍然与主机保持一致？
KALYX 通过将执行事件转换为可验证的、哈希链式的证据来解决这个问题。
## KALYX 的功能
| 能力 | 描述 |
|---|---|
| 执行摄入 | 接受示例日志事件、原始 execsnoop 样式的行、结构化 API 事件以及实时 eBPF execsnoop 输出 |
| 处理流水线 | 通过共享的后端服务对事件进行验证、丰富、规范化和链接 |
| 哈希链式账本 | 将执行记录存储在 `logs/exec_chain.jsonl` 中，包含序列号、前一个哈希和规范记录哈希 |
| 验证引擎 | 重新计算账本链并报告第一个不受信任的边界 |
| 本地检查点 | 使用链式检查点哈希将已验证的账本边界存储在 `logs/checkpoints.jsonl` 中 |
| 信任状态强制执行 | 当账本或检查点状态不受信任时，阻止新的摄入 |
| 检测引擎 | 仅在成功验证后运行确定性的行为规则 |
| 告警持久化 | 将去重后的告警存储在 `logs/alerts.jsonl` 中 |
| FastAPI 主机后端 | 暴露状态、摄入、验证、检测、告警和账本检查功能 |
| Angular 仪表盘 | 在 FastAPI 后端之上提供一个本地操作控制台 |
| Raspberry Pi 锚定机构 | 在独立的 Pi 端哈希链中存储检查点边界 |
| 锚点比较 | 将最新的本地检查点与最新的 Raspberry Pi 锚点进行比较 |
## 系统架构
KALYX 分为三层：
1. **接口层**：CLI、FastAPI 主机 API 和 Angular 仪表盘负责访问系统。
2. **主机证据核心层**：负责摄入、验证、规范化、账本链接、验证、检查点、检测、告警和锚点提交。
3. **外部锚定机构层**：一个 Raspberry Pi 服务，在独立的锚点链中存储检查点边界。
接口层属于访问层。它们不实现单独的完整性逻辑；它们调用共享的主机证据核心。
```
flowchart TD
subgraph Interfaces["Interfaces"]
CLI["CLI
kalyx"] API["FastAPI Host API
kalyx-api"] UI["Angular Dashboard
frontend"] end subgraph Host["Host Evidence Core"] Ingest["Ingestion + Normalization"] TrustGate["Trust Gate"] Ledger["Hash-Chained Ledger"] Verify["Verification Engine"] Checkpoints["Checkpoint Chain"] Detect["Detection Engine"] Alerts["Alert Log"] AnchorClient["Anchor Client"] end subgraph Pi["Raspberry Pi Anchor Authority"] AnchorAPI["Anchor API
kalyx-anchor"] AnchorChain["Pi Anchor Chain"] end UI --> API CLI --> Ingest API --> Ingest CLI --> Verify API --> Verify CLI --> Detect API --> Detect CLI --> AnchorClient Ingest --> TrustGate TrustGate --> Ledger Verify --> Ledger Verify --> Checkpoints Ledger --> Detect Detect --> Alerts AnchorClient --> Checkpoints AnchorClient --> AnchorAPI AnchorAPI --> AnchorChain AnchorAPI -. latest anchor .-> AnchorClient ``` | 层级 | 组件 | 实现 | 职责 | |---|---|---|---| | 接口层 | CLI | `kalyx/cli/app.py` | 用于摄入、验证、检查点、检测、告警和锚定的操作命令 | | 接口层 | FastAPI 主机 API | `kalyx/api/main.py` | 提供对共享主机服务的 HTTP 访问 | | 接口层 | Angular 仪表盘 | `frontend/` | 用于显示信任状态、账本检查、验证、摄入、检测、告警和证据 JSON 的本地界面 | | 主机证据核心层 | 流水线 | `kalyx/services/pipeline.py` | 验证、丰富、规范化和信任门控追加 | | 主机证据核心层 | 账本服务 | `kalyx/services/ledger.py` | 账本验证、检查点、信任状态、状态显示和导出 | | 主机证据核心层 | 检测服务 | `kalyx/services/detection.py` | 验证门控的检测和告警持久化 | | 主机证据核心层 | 锚点客户端 | `kalyx/services/anchor_client.py` | 检查点提交和锚点状态比较 | | 外部锚定机构层 | Raspberry Pi 锚点 API | `kalyx/anchor/api.py` | 用于检查点锚定和最新锚点查询的独立 API | | 外部锚定机构层 | Raspberry Pi 锚点存储 | `kalyx/anchor/storage.py` | Pi 端仅追加锚点链的验证和持久化 | ## 端到端工作流 ``` flowchart LR A["Capture event"] --> B["Validate
Enrich
Normalize"] B --> C["Trust gate"] C --> D["Append to
hash-chained ledger"] D --> E["Verify ledger"] E --> F["Create checkpoint"] F --> G["Anchor checkpoint
to Raspberry Pi"] G --> H["Compare anchor status"] E --> I["Run detection
only if trusted"] I --> J["Persist alerts"] ``` - **捕获**：事件通过示例日志、原始 execsnoop 样式的行、结构化 API 请求或实时 eBPF 摄入进入系统。 - **链接**：接受的事件在通过信任门控后，经过验证、丰富、规范化，并追加到哈希链式账本中。 - **验证**：验证引擎重新计算账本哈希，并报告第一个不受信任的边界。 - **检查点**：受信任的账本边界被记录在本地检查点链中。 - **锚定**：检查点边界可以提交给 Raspberry Pi 机构，并与最新的外部锚点进行比较。 - **检测**：确定性规则仅在受信任的证据上运行，并持久化去重后的告警。 ## 信任模型 KALYX 验证证据的连续性。它不能证明事件的真实性。 ### KALYX 可以验证的内容 | 声明 | 方式 | |---|---| | 账本记录在追加后被更改 | 重新计算规范记录哈希 | | 前一个哈希链接被破坏 | 将每个 `prev_hash` 与预期的前一个记录哈希进行比较 | | 账本 JSON 格式错误 | 解码并验证每一行账本 | | 第一个不受信任的记录边界 | 报告 `failure_index`、`valid_until_index` 和 `last_valid_hash` | | 本地检查点被编辑 | 验证检查点自哈希 | | 检查点历史记录被重新排序或破坏 | 验证前一个检查点的哈希链 | | 账本落后于之前的检查点 | 将当前账本与最新的检查点边界进行比较 | | 检测仅在受信任的证据上运行 | 检测服务在重放记录之前进行验证 | | 检查点已进行外部锚定 | 将本地检查点与最新的 Raspberry Pi 锚点进行比较 | ### KALYX 无法验证的内容 | 超出范围 | 原因 | |---|---| | 事件来源真实性 | KALYX 验证的是事件结构，而非事件真实性 | | 内核级信任 | 原始 execsnoop 行被视为输入，而非证据 | | 完全抵抗主机被完全控制 | 被完全控制的主机可以更改本地运行时和文件 | | 恶意软件防御 | KALYX 记录并验证证据；它不拦截进程 | | 完整的远程证明 | Raspberry Pi 锚定存储的是检查点边界，而不是完整的主机状态 | | 持续的锚点可用性 | 锚点比较依赖于 Pi 服务可达 | 核心边界： ``` KALYX verifies records it accepted. KALYX does not prove the original event source was truthful. ``` ## 信任状态 | 信任状态 | 含义 | |---|---| | `VERIFIED` | 账本验证成功，且与最新的本地检查点不冲突 | | `PARTIALLY_TRUSTED` | 验证失败，但失败之前的早期记录仍然受信任 | | `UNTRUSTED` | 账本或检查点的连续性不受信任 | | `EMPTY` | 账本文件存在但不包含任何记录 | | `NO_LEDGER` | 尚不存在账本文件 | 当当前账本或检查点状态不受信任时，摄入将被阻止。当验证失败时，检测将被跳过。 ## 外部锚点工作流 KALYX 包含一个独立的 Raspberry Pi 锚定机构。 主机创建本地检查点。Pi 在其自己仅追加的哈希链中存储检查点边界。这为主机提供了一个独立的机构，以便在发生本地更改、截断或替换后进行比较。 ### 启动锚点服务 在 Raspberry Pi 上，或在本地进行测试： ``` kalyx-anchor ``` 默认服务端口： ``` http://127.0.0.1:8081 ``` Pi 锚点将记录存储在： ``` anchors/anchor_chain.jsonl ``` ### 提交检查点 创建本地证据和检查点： ``` kalyx ingest kalyx verify --format json kalyx checkpoint ``` 将最新的检查点提交到锚点服务： ``` kalyx anchor --anchor-url http://127.0.0.1:8081 --ledger-id kalyx-main-host ``` `kalyx anchor` 会验证账本，创建或重用一个安全的本地检查点，然后将检查点边界发送到 Pi 服务。 锚点提交状态包括： | 状态 | 含义 | |---|---| | `ACCEPTED` | 新的检查点边界已存储 | | `ALREADY_ANCHORED` | 相同的账本/检查点哈希已被存储 | | `REJECTED_STALE` | 检查点索引早于该账本的最新 Pi 锚点 | | `REJECTED_INVALID` | Payload 或现有的 Pi 锚点链验证失败 | ### 比较本地和 Pi 的状态 ``` kalyx anchor-status --anchor-url http://127.0.0.1:8081 --ledger-id kalyx-main-host ``` 比较状态： | 状态 | 含义 | |---|---| | `MATCH` | 本地检查点和 Pi 锚点具有相同的检查点索引和哈希 | | `BEHIND` | Pi 锚点比本地检查点新 | | `AHEAD` | 本地检查点比最新的 Pi 锚点新 | | `DIVERGENCE` | 检查点索引匹配，但检查点哈希不同 | | `NO_ANCHOR` | 所选账本不存在 Pi 锚点 | | `UNREACHABLE` | 无法联系到 Pi 锚点服务 | 环境默认值： ``` export KALYX_ANCHOR_URL=http://127.0.0.1:8081 export KALYX_LEDGER_ID=kalyx-main-host ``` ## 仪表盘 Angular 仪表盘是位于 FastAPI 主机 API 之上的本地操作控制台。它不在浏览器中决定信任。它显示后端验证、账本、检查点、检测和告警状态。 | 页面 | 用途 | |---|---| | 概览 | 当前信任状态、账本状态、检查点状态、近期记录、近期告警 | | 账本 | 可搜索/可过滤的账本记录，带有完整的 JSON 抽屉 | | 验证 | 运行后端验证并检查信任元数据 | | 摄入 | 提交结构化事件或原始 execsnoop 样式的行 | | 检测 | 运行验证门控的检测 | | 告警 | 搜索和过滤已持久化的告警 | | 证据 | 检查原始后端 JSON 响应 | 在本地运行： ``` cd frontend npm ci npm start ``` 打开： ``` http://127.0.0.1:4200/ ``` 默认前端 API 目标： ``` http://127.0.0.1:8000 ``` 配置位于： ``` frontend/src/environments/environment.ts ``` ## 快速开始 从本地检出版本安装： ``` python3 -m venv .venv source .venv/bin/activate python3 -m pip install -U pip python3 -m pip install -e . pytest ``` 运行后端检查： ``` python3 -m compileall kalyx python3 -m pytest -q ``` 创建并验证示例账本： ``` kalyx ingest kalyx verify --format json kalyx status ``` 运行检测： ``` kalyx detect kalyx alerts ``` 启动主机 API： ``` kalyx-api ``` 启动仪表盘： ``` cd frontend npm ci npm start ``` ## CLI 参考 | 命令 | 用途 | |---|---| | `kalyx ingest` | 从 `sample_exec.log` 摄入示例事件 | | `kalyx ingest-live` | 使用 `execsnoop-bpfcc` 运行实时 eBPF 摄入 | | `kalyx verify` | 验证账本并在安全时写入/重用检查点 | | `kalyx verify --format json` | 打印结构化的验证输出 | | `kalyx status` | 显示账本、验证、信任和检查点状态 | | `kalyx checkpoint` | 创建或重用本地检查点 | | `kalyx checkpoint --format json` | 以 JSON 格式打印检查点操作 | | `kalyx anchor` | 将最新的本地检查点提交到锚点服务 | | `kalyx anchor-status` | 将本地检查点与最新的 Pi 锚点进行比较 | | `kalyx inspect` | 以可读形式打印账本条目 | | `kalyx export` | 导出账本记录和验证状态 | | `kalyx audit` 显示 `kalyx_ledger_watch` 的 auditd 账本访问事件 | | `kalyx detect` | 针对受信任的账本证据运行确定性检测 | | `kalyx alerts` | 打印已持久化的告警 | | `kalyx --help` | 显示命令帮助 | ## API 概览 KALYX 有两个 FastAPI 应用程序：主机 API 和锚点 API。 ### 主机 API 启动： ``` kalyx-api ``` 基础 URL： ``` http://127.0.0.1:8000 ``` | 方法 | 路由 | 保护 | 用途 | |---|---|---|---| | `GET` | `/` | 开放 | 极简的 API 运行页面 | | `GET` | `/status` | 开放 | 账本状态、信任状态、检查点元数据 | | `POST` | `/verify` | 配置时需要 API 密钥 | 验证账本并在安全时写入/重用检查点 | | `POST` | `/ingest` | 配置时需要 API 密钥 | 摄入原始行或结构化事件 | | `POST` | `/detect` | 配置时需要 API 密钥 | 运行验证门控的检测 | | `GET` | `/alerts` | 开放 | 返回已持久化的告警 | | `GET` | `/ledger` | 开放 | 返回最近解析的账本记录 | 可选的本地 API 密钥保护： ``` export KALYX_API_KEY=example-dev-key kalyx-api ``` 受保护的主机路由随后需要： ``` X-KALYX-API-Key: example-dev-key ``` 这是针对操作路由的轻量级本地保护。它不是用户身份验证、RBAC、OAuth、JWT 或来源证明。 ### 锚点 API 启动： ``` kalyx-anchor ``` 基础 URL： ``` http://127.0.0.1:8081 ``` | 方法 | 路由 | 用途 | |---|---|---| | `POST` | `/anchor` | 在 Pi 锚点链中存储检查点边界 | | `GET` | `/anchor/latest?ledger_id=...` | 返回为一个账本接受的最新锚点 | 详细的主机 API 文档位于 [docs/API_ENDPOINTS.md](docs/API_ENDPOINTS.md)。 ## 检测规则 检测是确定性的且基于规则的。它仅在账本成功验证后运行。 | 规则 | 严重性 | 触发条件 | |---|---|---| | `DELETE_CREATE` | 高 | 在 300 秒内对同一已知目标先执行 `DELETE` 后执行 `CREATE` | | `MODIFY_BURST` | 中 | 在短时间窗口内对同一已知目标重复执行 `MODIFY` 操作 | | `DESTRUCTIVE_BURST` | 高 | 同一用户/会话在 15 秒内执行多个破坏性操作 | | `SCRIPTED_DESTRUCTIVE_ACTION` | 高 | 在交互式会话之外由脚本父进程启动的 `DELETE` 或 `MODIFY` | 告警通过稳定的签名进行持久化，以避免在重复或并发的检测运行中产生重复写入。 ## 测试与验证 KALYX 测试侧重于支持其完整性声明的正确性属性。 运行： ``` python3 -m compileall kalyx python3 -m pytest -q ``` 前端构建检查： ``` cd frontend npm ci npm run build ``` | 领域 | 覆盖的行为 | |---|---| | 账本完整性 | 有效追加、确定性验证、哈希不匹配检测 | | 损坏处理 | 无效 JSON、无效记录类型、前一个哈希不匹配、Payload 哈希不匹配 | | 并发追加 | 并行写入下的文件锁保护序列和哈希连续性 | | 流水线验证 | 缺失字段、无效 PID/PPID、空命令拒绝 | | 摄入信任门控 | 在发生篡改或检查点不一致后阻止摄入 | | 检查点 | 创建、去重、自哈希验证、链验证、截断检测 | | 信任状态 | `VERIFIED`、`PARTIALLY_TRUSTED`、`UNTRUSTED`、`EMPTY`、`NO_LEDGER` 行为 | | 检测规则 | 删除/创建、修改突发、破坏性突发、脚本化破坏性操作 | | 告警持久化 | 去重和并发写入安全 | | 主机 API | 状态、摄入、验证、检测、告警、账本、API 密钥行为 | | 锚点服务 | 锚点创建、锚点链完整性、陈旧拒绝、最新查找 | | 锚点 CLI/客户端 | `kalyx anchor`、`kalyx anchor-status`、环境覆盖、比较状态 | | Angular 服务/状态 | API 密钥标头行为和信任状态显示映射 | GitHub Actions 会在向 `main` 分支推送和提交 Pull Request 时运行后端编译/测试以及 Angular 生产构建。 ## 项目结构 ``` kalyx/ anchor/ api.py storage.py api/ app.py dashboard.html main.py static/ style.css cli/ app.py core/ alerts.py chain.py detector.py normalize.py verify.py engine/ enrichment.py ingest_execsnoop.py ingest_execsnoop_live.py parser.py models/ schema.py services/ anchor_client.py detection.py ledger.py pipeline.py tests/ test_alert_persistence.py test_anchor_service.py test_anchor_status.py test_api_auth.py test_api_endpoints.py test_checkpoint_integrity.py test_cli_anchor.py test_detection_rules.py test_ingestion_trust_gate.py test_ledger_corruption.py test_ledger_integrity.py test_pipeline_validation.py docs/ API_ENDPOINTS.md ARCHITECTURE.md CONFIGURATION.md DETECTION_ENGINE.md TESTING_SUMMARY.md THREAT_MODEL.md frontend/ angular.json package.json proxy.conf.json src/ app/ core/ features/ layout/ shared/ environments/ pyproject.toml setup.py requirements.txt sample_exec.log ``` 运行时文件在本地创建并被 git 忽略： ``` logs/exec_chain.jsonl logs/checkpoints.jsonl logs/alerts.jsonl logs/.kalyx_status.json anchors/anchor_chain.jsonl reports/ledger_export.json ``` ## 配置 | 变量 | 必需 | 用途 | |---|---:|---| | `KALYX_API_KEY` | 否 | 配置后保护主机 API 操作路由 | | `KALYX_ANCHOR_URL` | 否 | `kalyx anchor` 和 `kalyx anchor-status` 的默认锚点 URL | | `KALYX_LEDGER_ID` | 否 | 用于锚点提交和比较的默认账本 ID | 示例： ``` export KALYX_API_KEY=example-dev-key export KALYX_ANCHOR_URL=http://127.0.0.1:8081 export KALYX_LEDGER_ID=kalyx-main-host ``` 前端 API 设置位于： ``` frontend/src/environments/environment.ts ``` 默认的前端 API 配置指向： ``` http://127.0.0.1:8000 ``` 前端配置在构建的 JavaScript 中可见。请勿将其视为机密存储。 ## 局限性 - KALYX 不能防止攻击或拦截进程。 - KALYX 不能证明摄入的事件来自真实的来源。 - 原始 execsnoop 行和结构化 API Payload 被视为输入，而非证据。 - 主机被完全攻陷可能会使仅限本地的证据失效。 - Raspberry Pi 锚定存储的是检查点边界，而不是完整的主机状态。 - 锚点比较依赖于 Pi 服务可达。 - 实时 eBPF 摄入需要具有 `execsnoop-bpfcc` 和适当权限的兼容 Linux 环境。 - 账本存储是本地 JSONL，而不是索引数据库。 - 验证的时间复杂度为 O(n)，因为每条账本记录都是按顺序重新计算的。 - 检测使用确定性规则，而不是 ML 或外部威胁情报。 ## 设计权衡 - **JSONL 账本**：简单、易于追加、可检查，且易于逐行验证。 - **规范化哈希**：确定性的序列化使得验证可重现。 - **本地检查点**：在外部锚定之前记录已验证的边界。 - **Raspberry Pi 锚点**：提供独立的检查点机构，而无需引入庞大的分布式系统。 - **基于规则的检测**：可解释、确定且可测试。 - **轻量级接口**：CLI、API 和 Angular 调用共享的后端服务，而不是重复信任逻辑。 - **无数据库**：保持原型可检查，并在需要索引存储之前避免操作复杂性。 ## 更多文档 | 文档 | 用途 | |---|---| | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 后端架构、服务层、请求流 | | [docs/API_ENDPOINTS.md](docs/API_ENDPOINTS.md) | 主机 API 路由详情 | | [docs/DETECTION_ENGINE.md](docs/DETECTION_ENGINE.md) | 检测规则、语义、限制 | | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | 信任边界和超出范围的假设 | | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 环境和前端 API 配置 | | [docs/TESTING_SUMMARY.md](docs/TESTING_SUMMARY.md) | 测试覆盖率和验证方法 | ## 路线图 当前存储库中尚未实现的未来工作： - 主机和锚点之间的签名检查点交换 - 账本分段和增量验证 - 经过身份验证的事件源摄入 - 索引告警和重放存储 - 更强的 Raspberry Pi 锚点强化 - CI 中基于浏览器的 Angular 测试覆盖率
kalyx"] API["FastAPI Host API
kalyx-api"] UI["Angular Dashboard
frontend"] end subgraph Host["Host Evidence Core"] Ingest["Ingestion + Normalization"] TrustGate["Trust Gate"] Ledger["Hash-Chained Ledger"] Verify["Verification Engine"] Checkpoints["Checkpoint Chain"] Detect["Detection Engine"] Alerts["Alert Log"] AnchorClient["Anchor Client"] end subgraph Pi["Raspberry Pi Anchor Authority"] AnchorAPI["Anchor API
kalyx-anchor"] AnchorChain["Pi Anchor Chain"] end UI --> API CLI --> Ingest API --> Ingest CLI --> Verify API --> Verify CLI --> Detect API --> Detect CLI --> AnchorClient Ingest --> TrustGate TrustGate --> Ledger Verify --> Ledger Verify --> Checkpoints Ledger --> Detect Detect --> Alerts AnchorClient --> Checkpoints AnchorClient --> AnchorAPI AnchorAPI --> AnchorChain AnchorAPI -. latest anchor .-> AnchorClient ``` | 层级 | 组件 | 实现 | 职责 | |---|---|---|---| | 接口层 | CLI | `kalyx/cli/app.py` | 用于摄入、验证、检查点、检测、告警和锚定的操作命令 | | 接口层 | FastAPI 主机 API | `kalyx/api/main.py` | 提供对共享主机服务的 HTTP 访问 | | 接口层 | Angular 仪表盘 | `frontend/` | 用于显示信任状态、账本检查、验证、摄入、检测、告警和证据 JSON 的本地界面 | | 主机证据核心层 | 流水线 | `kalyx/services/pipeline.py` | 验证、丰富、规范化和信任门控追加 | | 主机证据核心层 | 账本服务 | `kalyx/services/ledger.py` | 账本验证、检查点、信任状态、状态显示和导出 | | 主机证据核心层 | 检测服务 | `kalyx/services/detection.py` | 验证门控的检测和告警持久化 | | 主机证据核心层 | 锚点客户端 | `kalyx/services/anchor_client.py` | 检查点提交和锚点状态比较 | | 外部锚定机构层 | Raspberry Pi 锚点 API | `kalyx/anchor/api.py` | 用于检查点锚定和最新锚点查询的独立 API | | 外部锚定机构层 | Raspberry Pi 锚点存储 | `kalyx/anchor/storage.py` | Pi 端仅追加锚点链的验证和持久化 | ## 端到端工作流 ``` flowchart LR A["Capture event"] --> B["Validate
Enrich
Normalize"] B --> C["Trust gate"] C --> D["Append to
hash-chained ledger"] D --> E["Verify ledger"] E --> F["Create checkpoint"] F --> G["Anchor checkpoint
to Raspberry Pi"] G --> H["Compare anchor status"] E --> I["Run detection
only if trusted"] I --> J["Persist alerts"] ``` - **捕获**：事件通过示例日志、原始 execsnoop 样式的行、结构化 API 请求或实时 eBPF 摄入进入系统。 - **链接**：接受的事件在通过信任门控后，经过验证、丰富、规范化，并追加到哈希链式账本中。 - **验证**：验证引擎重新计算账本哈希，并报告第一个不受信任的边界。 - **检查点**：受信任的账本边界被记录在本地检查点链中。 - **锚定**：检查点边界可以提交给 Raspberry Pi 机构，并与最新的外部锚点进行比较。 - **检测**：确定性规则仅在受信任的证据上运行，并持久化去重后的告警。 ## 信任模型 KALYX 验证证据的连续性。它不能证明事件的真实性。 ### KALYX 可以验证的内容 | 声明 | 方式 | |---|---| | 账本记录在追加后被更改 | 重新计算规范记录哈希 | | 前一个哈希链接被破坏 | 将每个 `prev_hash` 与预期的前一个记录哈希进行比较 | | 账本 JSON 格式错误 | 解码并验证每一行账本 | | 第一个不受信任的记录边界 | 报告 `failure_index`、`valid_until_index` 和 `last_valid_hash` | | 本地检查点被编辑 | 验证检查点自哈希 | | 检查点历史记录被重新排序或破坏 | 验证前一个检查点的哈希链 | | 账本落后于之前的检查点 | 将当前账本与最新的检查点边界进行比较 | | 检测仅在受信任的证据上运行 | 检测服务在重放记录之前进行验证 | | 检查点已进行外部锚定 | 将本地检查点与最新的 Raspberry Pi 锚点进行比较 | ### KALYX 无法验证的内容 | 超出范围 | 原因 | |---|---| | 事件来源真实性 | KALYX 验证的是事件结构，而非事件真实性 | | 内核级信任 | 原始 execsnoop 行被视为输入，而非证据 | | 完全抵抗主机被完全控制 | 被完全控制的主机可以更改本地运行时和文件 | | 恶意软件防御 | KALYX 记录并验证证据；它不拦截进程 | | 完整的远程证明 | Raspberry Pi 锚定存储的是检查点边界，而不是完整的主机状态 | | 持续的锚点可用性 | 锚点比较依赖于 Pi 服务可达 | 核心边界： ``` KALYX verifies records it accepted. KALYX does not prove the original event source was truthful. ``` ## 信任状态 | 信任状态 | 含义 | |---|---| | `VERIFIED` | 账本验证成功，且与最新的本地检查点不冲突 | | `PARTIALLY_TRUSTED` | 验证失败，但失败之前的早期记录仍然受信任 | | `UNTRUSTED` | 账本或检查点的连续性不受信任 | | `EMPTY` | 账本文件存在但不包含任何记录 | | `NO_LEDGER` | 尚不存在账本文件 | 当当前账本或检查点状态不受信任时，摄入将被阻止。当验证失败时，检测将被跳过。 ## 外部锚点工作流 KALYX 包含一个独立的 Raspberry Pi 锚定机构。 主机创建本地检查点。Pi 在其自己仅追加的哈希链中存储检查点边界。这为主机提供了一个独立的机构，以便在发生本地更改、截断或替换后进行比较。 ### 启动锚点服务 在 Raspberry Pi 上，或在本地进行测试： ``` kalyx-anchor ``` 默认服务端口： ``` http://127.0.0.1:8081 ``` Pi 锚点将记录存储在： ``` anchors/anchor_chain.jsonl ``` ### 提交检查点 创建本地证据和检查点： ``` kalyx ingest kalyx verify --format json kalyx checkpoint ``` 将最新的检查点提交到锚点服务： ``` kalyx anchor --anchor-url http://127.0.0.1:8081 --ledger-id kalyx-main-host ``` `kalyx anchor` 会验证账本，创建或重用一个安全的本地检查点，然后将检查点边界发送到 Pi 服务。 锚点提交状态包括： | 状态 | 含义 | |---|---| | `ACCEPTED` | 新的检查点边界已存储 | | `ALREADY_ANCHORED` | 相同的账本/检查点哈希已被存储 | | `REJECTED_STALE` | 检查点索引早于该账本的最新 Pi 锚点 | | `REJECTED_INVALID` | Payload 或现有的 Pi 锚点链验证失败 | ### 比较本地和 Pi 的状态 ``` kalyx anchor-status --anchor-url http://127.0.0.1:8081 --ledger-id kalyx-main-host ``` 比较状态： | 状态 | 含义 | |---|---| | `MATCH` | 本地检查点和 Pi 锚点具有相同的检查点索引和哈希 | | `BEHIND` | Pi 锚点比本地检查点新 | | `AHEAD` | 本地检查点比最新的 Pi 锚点新 | | `DIVERGENCE` | 检查点索引匹配，但检查点哈希不同 | | `NO_ANCHOR` | 所选账本不存在 Pi 锚点 | | `UNREACHABLE` | 无法联系到 Pi 锚点服务 | 环境默认值： ``` export KALYX_ANCHOR_URL=http://127.0.0.1:8081 export KALYX_LEDGER_ID=kalyx-main-host ``` ## 仪表盘 Angular 仪表盘是位于 FastAPI 主机 API 之上的本地操作控制台。它不在浏览器中决定信任。它显示后端验证、账本、检查点、检测和告警状态。 | 页面 | 用途 | |---|---| | 概览 | 当前信任状态、账本状态、检查点状态、近期记录、近期告警 | | 账本 | 可搜索/可过滤的账本记录，带有完整的 JSON 抽屉 | | 验证 | 运行后端验证并检查信任元数据 | | 摄入 | 提交结构化事件或原始 execsnoop 样式的行 | | 检测 | 运行验证门控的检测 | | 告警 | 搜索和过滤已持久化的告警 | | 证据 | 检查原始后端 JSON 响应 | 在本地运行： ``` cd frontend npm ci npm start ``` 打开： ``` http://127.0.0.1:4200/ ``` 默认前端 API 目标： ``` http://127.0.0.1:8000 ``` 配置位于： ``` frontend/src/environments/environment.ts ``` ## 快速开始 从本地检出版本安装： ``` python3 -m venv .venv source .venv/bin/activate python3 -m pip install -U pip python3 -m pip install -e . pytest ``` 运行后端检查： ``` python3 -m compileall kalyx python3 -m pytest -q ``` 创建并验证示例账本： ``` kalyx ingest kalyx verify --format json kalyx status ``` 运行检测： ``` kalyx detect kalyx alerts ``` 启动主机 API： ``` kalyx-api ``` 启动仪表盘： ``` cd frontend npm ci npm start ``` ## CLI 参考 | 命令 | 用途 | |---|---| | `kalyx ingest` | 从 `sample_exec.log` 摄入示例事件 | | `kalyx ingest-live` | 使用 `execsnoop-bpfcc` 运行实时 eBPF 摄入 | | `kalyx verify` | 验证账本并在安全时写入/重用检查点 | | `kalyx verify --format json` | 打印结构化的验证输出 | | `kalyx status` | 显示账本、验证、信任和检查点状态 | | `kalyx checkpoint` | 创建或重用本地检查点 | | `kalyx checkpoint --format json` | 以 JSON 格式打印检查点操作 | | `kalyx anchor` | 将最新的本地检查点提交到锚点服务 | | `kalyx anchor-status` | 将本地检查点与最新的 Pi 锚点进行比较 | | `kalyx inspect` | 以可读形式打印账本条目 | | `kalyx export` | 导出账本记录和验证状态 | | `kalyx audit` 显示 `kalyx_ledger_watch` 的 auditd 账本访问事件 | | `kalyx detect` | 针对受信任的账本证据运行确定性检测 | | `kalyx alerts` | 打印已持久化的告警 | | `kalyx --help` | 显示命令帮助 | ## API 概览 KALYX 有两个 FastAPI 应用程序：主机 API 和锚点 API。 ### 主机 API 启动： ``` kalyx-api ``` 基础 URL： ``` http://127.0.0.1:8000 ``` | 方法 | 路由 | 保护 | 用途 | |---|---|---|---| | `GET` | `/` | 开放 | 极简的 API 运行页面 | | `GET` | `/status` | 开放 | 账本状态、信任状态、检查点元数据 | | `POST` | `/verify` | 配置时需要 API 密钥 | 验证账本并在安全时写入/重用检查点 | | `POST` | `/ingest` | 配置时需要 API 密钥 | 摄入原始行或结构化事件 | | `POST` | `/detect` | 配置时需要 API 密钥 | 运行验证门控的检测 | | `GET` | `/alerts` | 开放 | 返回已持久化的告警 | | `GET` | `/ledger` | 开放 | 返回最近解析的账本记录 | 可选的本地 API 密钥保护： ``` export KALYX_API_KEY=example-dev-key kalyx-api ``` 受保护的主机路由随后需要： ``` X-KALYX-API-Key: example-dev-key ``` 这是针对操作路由的轻量级本地保护。它不是用户身份验证、RBAC、OAuth、JWT 或来源证明。 ### 锚点 API 启动： ``` kalyx-anchor ``` 基础 URL： ``` http://127.0.0.1:8081 ``` | 方法 | 路由 | 用途 | |---|---|---| | `POST` | `/anchor` | 在 Pi 锚点链中存储检查点边界 | | `GET` | `/anchor/latest?ledger_id=...` | 返回为一个账本接受的最新锚点 | 详细的主机 API 文档位于 [docs/API_ENDPOINTS.md](docs/API_ENDPOINTS.md)。 ## 检测规则 检测是确定性的且基于规则的。它仅在账本成功验证后运行。 | 规则 | 严重性 | 触发条件 | |---|---|---| | `DELETE_CREATE` | 高 | 在 300 秒内对同一已知目标先执行 `DELETE` 后执行 `CREATE` | | `MODIFY_BURST` | 中 | 在短时间窗口内对同一已知目标重复执行 `MODIFY` 操作 | | `DESTRUCTIVE_BURST` | 高 | 同一用户/会话在 15 秒内执行多个破坏性操作 | | `SCRIPTED_DESTRUCTIVE_ACTION` | 高 | 在交互式会话之外由脚本父进程启动的 `DELETE` 或 `MODIFY` | 告警通过稳定的签名进行持久化，以避免在重复或并发的检测运行中产生重复写入。 ## 测试与验证 KALYX 测试侧重于支持其完整性声明的正确性属性。 运行： ``` python3 -m compileall kalyx python3 -m pytest -q ``` 前端构建检查： ``` cd frontend npm ci npm run build ``` | 领域 | 覆盖的行为 | |---|---| | 账本完整性 | 有效追加、确定性验证、哈希不匹配检测 | | 损坏处理 | 无效 JSON、无效记录类型、前一个哈希不匹配、Payload 哈希不匹配 | | 并发追加 | 并行写入下的文件锁保护序列和哈希连续性 | | 流水线验证 | 缺失字段、无效 PID/PPID、空命令拒绝 | | 摄入信任门控 | 在发生篡改或检查点不一致后阻止摄入 | | 检查点 | 创建、去重、自哈希验证、链验证、截断检测 | | 信任状态 | `VERIFIED`、`PARTIALLY_TRUSTED`、`UNTRUSTED`、`EMPTY`、`NO_LEDGER` 行为 | | 检测规则 | 删除/创建、修改突发、破坏性突发、脚本化破坏性操作 | | 告警持久化 | 去重和并发写入安全 | | 主机 API | 状态、摄入、验证、检测、告警、账本、API 密钥行为 | | 锚点服务 | 锚点创建、锚点链完整性、陈旧拒绝、最新查找 | | 锚点 CLI/客户端 | `kalyx anchor`、`kalyx anchor-status`、环境覆盖、比较状态 | | Angular 服务/状态 | API 密钥标头行为和信任状态显示映射 | GitHub Actions 会在向 `main` 分支推送和提交 Pull Request 时运行后端编译/测试以及 Angular 生产构建。 ## 项目结构 ``` kalyx/ anchor/ api.py storage.py api/ app.py dashboard.html main.py static/ style.css cli/ app.py core/ alerts.py chain.py detector.py normalize.py verify.py engine/ enrichment.py ingest_execsnoop.py ingest_execsnoop_live.py parser.py models/ schema.py services/ anchor_client.py detection.py ledger.py pipeline.py tests/ test_alert_persistence.py test_anchor_service.py test_anchor_status.py test_api_auth.py test_api_endpoints.py test_checkpoint_integrity.py test_cli_anchor.py test_detection_rules.py test_ingestion_trust_gate.py test_ledger_corruption.py test_ledger_integrity.py test_pipeline_validation.py docs/ API_ENDPOINTS.md ARCHITECTURE.md CONFIGURATION.md DETECTION_ENGINE.md TESTING_SUMMARY.md THREAT_MODEL.md frontend/ angular.json package.json proxy.conf.json src/ app/ core/ features/ layout/ shared/ environments/ pyproject.toml setup.py requirements.txt sample_exec.log ``` 运行时文件在本地创建并被 git 忽略： ``` logs/exec_chain.jsonl logs/checkpoints.jsonl logs/alerts.jsonl logs/.kalyx_status.json anchors/anchor_chain.jsonl reports/ledger_export.json ``` ## 配置 | 变量 | 必需 | 用途 | |---|---:|---| | `KALYX_API_KEY` | 否 | 配置后保护主机 API 操作路由 | | `KALYX_ANCHOR_URL` | 否 | `kalyx anchor` 和 `kalyx anchor-status` 的默认锚点 URL | | `KALYX_LEDGER_ID` | 否 | 用于锚点提交和比较的默认账本 ID | 示例： ``` export KALYX_API_KEY=example-dev-key export KALYX_ANCHOR_URL=http://127.0.0.1:8081 export KALYX_LEDGER_ID=kalyx-main-host ``` 前端 API 设置位于： ``` frontend/src/environments/environment.ts ``` 默认的前端 API 配置指向： ``` http://127.0.0.1:8000 ``` 前端配置在构建的 JavaScript 中可见。请勿将其视为机密存储。 ## 局限性 - KALYX 不能防止攻击或拦截进程。 - KALYX 不能证明摄入的事件来自真实的来源。 - 原始 execsnoop 行和结构化 API Payload 被视为输入，而非证据。 - 主机被完全攻陷可能会使仅限本地的证据失效。 - Raspberry Pi 锚定存储的是检查点边界，而不是完整的主机状态。 - 锚点比较依赖于 Pi 服务可达。 - 实时 eBPF 摄入需要具有 `execsnoop-bpfcc` 和适当权限的兼容 Linux 环境。 - 账本存储是本地 JSONL，而不是索引数据库。 - 验证的时间复杂度为 O(n)，因为每条账本记录都是按顺序重新计算的。 - 检测使用确定性规则，而不是 ML 或外部威胁情报。 ## 设计权衡 - **JSONL 账本**：简单、易于追加、可检查，且易于逐行验证。 - **规范化哈希**：确定性的序列化使得验证可重现。 - **本地检查点**：在外部锚定之前记录已验证的边界。 - **Raspberry Pi 锚点**：提供独立的检查点机构，而无需引入庞大的分布式系统。 - **基于规则的检测**：可解释、确定且可测试。 - **轻量级接口**：CLI、API 和 Angular 调用共享的后端服务，而不是重复信任逻辑。 - **无数据库**：保持原型可检查，并在需要索引存储之前避免操作复杂性。 ## 更多文档 | 文档 | 用途 | |---|---| | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 后端架构、服务层、请求流 | | [docs/API_ENDPOINTS.md](docs/API_ENDPOINTS.md) | 主机 API 路由详情 | | [docs/DETECTION_ENGINE.md](docs/DETECTION_ENGINE.md) | 检测规则、语义、限制 | | [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md) | 信任边界和超出范围的假设 | | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 环境和前端 API 配置 | | [docs/TESTING_SUMMARY.md](docs/TESTING_SUMMARY.md) | 测试覆盖率和验证方法 | ## 路线图 当前存储库中尚未实现的未来工作： - 主机和锚点之间的签名检查点交换 - 账本分段和增量验证 - 经过身份验证的事件源摄入 - 索引告警和重放存储 - 更强的 Raspberry Pi 锚点强化 - CI 中基于浏览器的 Angular 测试覆盖率
标签：Docker镜像, Python, Zenmap, 哈希链, 安全规则引擎, 执行证据, 数字取证, 数据完整性, 无后门, 时序数据库, 自动化脚本, 逆向工具, 防篡改