jusso-dev/Kelpie

# Kelpie 面向小型 SOC 团队的事件响应与案件管理工具。开源，支持自托管。 Kelpie 是一款作为单个 Next.js 应用程序构建的 SOC 案件管理工具，由 Postgres 提供支持。它专为在一台普通虚拟机上流畅运行而设计。 ## 此 MVP 中的功能 - 多租户组织，BetterAuth 邮箱和密码登录，管理员 / 分析师 / 只读角色。 - 入站告警 API (`POST /api/v1/alerts`)、分流队列、驳回或升级为案件。 - 具备完整事件生命周期的案件 (`open → in_progress → contained → eradicated → recovered → closed`)、严重程度、TLP、PAP、分类、MITRE ATT&CK 标签、每个组织独有的案件编号 (`KP-YYYY-NNNN`)。 - 具有节奏的任务：定义带有定时步骤的 playbook，应用 playbook 会生成带有截止时间的任务。 - 支持手动输入的 Observables、从已升级的告警中自动继承、跨案件查找，以及可插拔的富化接口（内置反向 DNS 和 URL 解析）。 - 仅追加的 timeline，记录每一次状态变更、评论、任务和 observable 事件。 - 支持 `@mention` 邮件通知的 Markdown 评论。 - 计算 SHA256 的本地文件附件。 - 仪表盘，展示按严重程度划分的待处理案件、MTTA / MTTC / MTTR、主要分类。 - 使用 Postgres 进行 Docker Compose 部署。 最初的路线图作为 GitHub issues 在 **roadmap** 标签下进行跟踪。第二阶段已发布，第三阶段的集成、SSO、threat-intel、response-action、自定义以及状态呈现功能现已构建完成；请参阅下方的[已发布的第三阶段功能](#shipped-phase-3-features)。移动端配套应用以及更广泛的协作字段编辑优化仍是后续工作。 ## 产品截图 以下截图均来自使用虚假用户、案件、告警、威胁情报、集成、SSO 和自定义字段数据播种的本地演示工作区。

运维工作区

### 仪表盘  ### 告警分流队列  ### 案件列表 

案件调查

### 案件详情  ### 案件 Observables  ### 案件评论 

威胁数据与响应内容

### Observable 搜索  ### 威胁情报  ### Playbooks 

管理

### 设置  ### 集成  ### 自定义字段  ### 单点登录 

## 技术栈 - Next.js 16, React 19, server components 和 server actions。 - TypeScript, 严格模式。 - 配合 PostgreSQL 的 Drizzle ORM。 - BetterAuth，支持 SAML 2.0 和 OIDC 单点登录（通过 `@node-saml/node-saml` 和手动实现的 OIDC 流程）。 - Tailwind v4 及定制组件（在 MVP 范围内无需安装 shadcn）。 - 后台工作通过由外部调度程序（在捆绑的技术栈中作为 Docker Compose sidecar）驱动的内部 `/api/cron/*` 端点运行。无需额外的队列或 worker 进程。 ## 已发布的第三阶段功能 这些已发布的功能将 Kelpie 从一个独立的案件管理器转变为可以接入 SOC 现有工具的平台。以下所有功能均支持多租户：配置按组织独立存放。 ### SIEM connectors (Splunk, Elastic, Sentinel) 单一的 connector 框架托管了所有供应商。每个 connector 都是 `src/lib/connectors/handlers/` 下的一个文件，实现了一个小型的 `poll()` 接口；该框架负责处理调度、游标、幂等告警生成和字段映射。 - 在 **Settings → Integrations → SIEM connectors** 下**配置**。选择一种类型（Splunk, Elastic, Sentinel），为其命名并填写凭据。该 connector 随即以活跃状态启动。 - **字段映射** 是一份单一的 JSON 文档，描述了如何将供应商记录转换为 Kelpie 告警（`title`、`description`、带 `severityMap` 的 `severity`、用于去重的 `externalRef` 以及 `observables`）。每个 connector 都提供了一套合理的默认映射。 - **幂等性**：告警基于 `externalRef` 进行去重，因此重新轮询永远不会产生重复项。 - **凭据错误会停止轮询**：轮询失败会在 connector 上记录 `last_error` 并停止后续轮询，直到管理员点击 **Clear error**。每个 connector 均可见状态（上次轮询、上次错误、生成的告警总数）。 - 轮询由 `POST /api/cron/connectors` 驱动（在捆绑的技术栈中每分钟一次）。**Poll now** 会按需运行 connector。 添加新的供应商只需一个实现 `Connector` 接口的文件，并在 `src/lib/connectors/registry.ts` 中添加一行即可。 ### SOAR 风格的 response actions (Cloudflare, Entra, CrowdStrike) Kelpie 是一个案件管理器，而不是 SOAR，但可以直接从案件中运行少数界限明确的操作： - **在 Cloudflare 上封锁 IP** — 在配置的区域中为 IP observable 创建 WAF 访问规则。 - **在 Microsoft Entra 中禁用用户** — 通过 Microsoft Graph 将用户名/邮箱 observable 的 `accountEnabled` 设置为 `false`；记录以前的状态以便手动回滚。 - **在 CrowdStrike 中隔离主机** — 将主机名 observable 解析为 Falcon agent id 并隔离该设备。 在 **Settings → Integrations → Response actions** 下配置凭据（仅限管理员，可针对每个操作启用/禁用）。在案件页面上，**Response actions** 面板仅提供其所需 observable 类型已存在的操作。运行操作需要管理员或分析师角色，会显示确认对话框，并写入一条包含操作者、目标和结果的 `response_action` timeline 事件。每次运行都会存储在 `response_action_runs` 中以供审计。回滚已有文档记录但并未自动化：请手动执行反向操作。 新的操作处理器在 `src/lib/response-actions/handlers/` 中实现 `ActionHandler`，并在 `registry.ts` 中注册。 ### 威胁情报存储和 feeds 一个小型的 TI 存储可以通过亚秒级的索引查询来回答“这个 IOC 是否已知是恶意的？”。 - **Feeds**（通用 CSV/TXT URL、通过 API 的 MISP、通过 API 的 OTX）在 **Threat intel** 页面（管理员）中进行配置。每个 feed 按自己的时间间隔轮询（由 `POST /api/cron/ti` 驱动），跟踪上次轮询状态和指标计数，并在遇到凭据错误时停止运行，直到被清除。 - **自动匹配**：创建 observable 时，Kelpie 会运行索引 TI 查询，并立即将匹配项附加到 observable 的 `enrichment.ti` 中。`ti` provider 也是 enrichment registry 的一部分，因此后续的处理会与反向 DNS、VirusTotal 等一起对其进行刷新。 - 从 **Threat intel** 页面**浏览/搜索**存储：按值、类型、feed 或标签进行过滤。每个指标的详情都会显示其来源 feed（包含置信度）以及出现的案件。 新的 feed 处理器在 `src/lib/ti/handlers/` 中实现 `TiFeedHandler`。 ### 自定义字段构建器 管理员无需代码即可在 **Settings → Custom fields** 下为每个案件添加字段。 - 字段类型：文本、数字、日期、下拉选择、多选、是/否。字段可以重新排序、停用并标记为必填。 - 自定义字段在案件详情页内联呈现，并可由分析师编辑；每次更改都会写入一个 `custom_field_changed` timeline 事件。 - **模板** 可以预先填充自定义字段的默认值，并在从模板创建案件时应用。 - **API**：`GET /api/v1/cases/{id}` 返回 `custom_fields: { key: value }`；`PATCH` 接受带有按类型验证和强制转换的 `custom_fields` 对象。案件列表支持对字段值的基本相等过滤。 ### 单点登录 (SAML 2.0 和 OIDC) 针对每个组织的 SSO 与邮箱/密码并存，在 **Settings → Single sign-on**（管理员）下配置。 - **OIDC**（Entra、Okta、Google Workspace 以及任何支持发现的服务）：设置 issuer、client id/secret、scopes 以及可选的 role claim 和 role map。该流程使用 OIDC 发现和 PKCE。登录 URL：`/api/sso/oidc/{org-slug}/start`。 - **SAML 2.0**：粘贴 IdP SSO URL 和签名证书；断言签名由 `@node-saml/node-saml` 验证。SP 元数据由 `/api/sso/saml/{org-slug}/metadata` 提供，ACS 位于 `/api/sso/saml/{org-slug}/acs`，而登录从 `/api/sso/saml/{org-slug}/start` 开始。 - **即时 (JIT) 配置**：首次成功登录会在组织内创建用户，其角色来源于您的 claim 映射（默认回退为 `analyst`）；后续登录会刷新姓名和角色。 - **强制 SSO**：针对每个组织的开关，拒绝该组织的邮箱/密码登录。 SSO 会话兼容 BetterAuth：回调会创建一个会话行并设置标准的已签名 BetterAuth 会话 cookie，因此应用程序的其余部分将 SSO 和密码会话同等对待。 ### 实时状态呈现与版本守卫的编辑 - **状态呈现**：打开案件时会显示正在查看该案件的其他分析师的头像，外加一个“正在输入评论”的指示器。传输方式是通过服务器发送事件在 `/api/cases/{id}/presence` 流式传输的基于 Postgres 的花名册，因此它无需 Redis 即可跨应用程序副本工作。数据行在不活动 30 秒后过期，并在 cron 触发时被清理。 - **版本守卫的字段保存**：受守卫的案件字段（severity、classification、TLP、PAP、assignee、tags）带有乐观版本戳。冲突的保存操作会被拒绝并返回当前值，以便分析师可以重新加载并选择保留哪一个。相同的版本守卫也在 `PATCH /api/v1/cases/{id}` 上强制执行（发送 `version`；过期的值将返回 `409 version_conflict`）。 移动端配套应用（issue #32）特意排除在本次构建范围之外。 ## 快速开始（本地开发） ``` # 1. 安装依赖 npm install # 2. 配置环境 cp .env.example .env # （默认设置适用于捆绑的 docker-compose db） # 3. 启动 Postgres（或运行你自己的；只需将 DATABASE_URL 指向它） docker compose up -d db # 4. 生成并应用 migrations，然后进行 seed npm run db:generate npm run db:migrate npm run db:seed # 5. 运行应用 npm run dev ``` 然后访问 http://localhost:3000 并以 `admin@acme.local` / `kelpieadmin` 的身份登录。 ## Docker Compose（自托管） ``` cp .env.example .env # 在公开暴露之前，将 BETTER_AUTH_SECRET 设置为一个长的随机字符串。 docker compose up -d --build # 仅首次运行：应用 migrations 并进行 seed docker compose exec app node -e "require('./src/db/migrate')" || npm run db:migrate ``` compose 技术栈会启动 Postgres、Kelpie 应用程序和一个小的 cron sidecar。上传的文件将存放在 `kelpie_uploads` 数据卷中。 ## 后台任务 后台工作通过经过身份验证的内部端点运行，由外部调度程序每分钟调用一次。捆绑的 `docker-compose.yml` 包含一个 sidecar，它会使用 `CRON_SECRET` 对其进行 curl 操作。这些端点是： | Endpoint | 任务 | | --- | --- | | `POST /api/cron/sla` | SLA 违规 + 预警检查和指派人邮件 | | `POST /api/cron/webhooks` | 具有重试/退避机制的出站 webhook 传递 | | `POST /api/cron/enrichment` | Observable 富化处理 + 缓存清理 | | `POST /api/cron/connectors` | 轮询活跃的 SIEM connectors | | `POST /api/cron/ti` | 轮询到期的 TI feeds + 清理过期的 presence 行 | 每个端点都需要 `Authorization: Bearer $CRON_SECRET`。如果您不使用捆绑的 sidecar，可以将任何调度程序（cron、k8s CronJob 或 GitHub Actions 定时任务）指向它们。 ## 冒烟测试 在播种并且开发服务器运行的情况下： ``` npm run smoke # Phase 1: alert round trip npm run smoke:phase2 # Phase 2: cases/tasks/observables API, webhooks, reports, cron npm run smoke:phase3 # Phase 3: connectors, response actions, TI, custom fields, presence, SSO ``` `smoke:phase3 直接针对数据库测试第三阶段的后端（TI 摄入 + 查找、自定义字段验证、带有审计跟踪的 response-action 运行、connector 凭据故障停止、presence 花名册以及 SSO 会话 cookie 签名）。 ## 从 SIEM 发送告警 ``` curl -X POST http://localhost:3000/api/v1/alerts \ -H "Authorization: Bearer klp_yourtoken" \ -H "Content-Type: application/json" \ -d '{ "title": "Suspicious login from new geo", "severity": "high", "source": "siem-splunk", "observables": [{"type": "ip", "value": "203.0.113.4"}] }' ``` 在 Settings → API tokens 下创建 token。 ## 约定 - 在代码、文案和文档中使用澳大利亚拼写。 - 不使用破折号。 - 时间以 UTC 格式存储。 - timeline 是仅追加的。绝不会被编辑或删除。 - 案件上的每一次状态变更操作都会写入一个 timeline 事件。 ## 许可证 此仓库默认不提供许可证文件。在发布之前，请添加一个与您的分发意图相符的许可证。

标签：Docker, MITM代理, Postgres, 安全运营, 安全防御评估, 工单管理, 扫描框架, 测试用例, 版权保护, 自动化攻击