rmednitzer/core-graph
GitHub: rmednitzer/core-graph
core-graph是一款基于PostgreSQL的融合图向量知识平台，用于安全、威胁情报和AI记忆。
Stars: 1 | Forks: 0
# 核心图
基于 PostgreSQL 和 Apache AGE 以及 pgvector 构建的融合图向量知识平台。专为欧盟主权部署设计，以安全性、合规性和运营保证作为结构属性。
[](https://deepwiki.com/rmednitzer/core-graph)
## 功能
core-graph 是异构安全和基础设施数据的规范汇聚点。卫星系统通过 NATS JetStream 将结构化实体发布到一个 PostgreSQL 集中，在那里它们被存储为图（Apache AGE），并使用向量嵌入（pgvector）进行丰富，并通过多个接口进行暴露。
### 数据领域（八个本体层）
| 层级 | 描述 | 标准 |
|---|---|---|
| **威胁情报** | TTPs、指标、活动、威胁行为者、恶意软件、漏洞 | STIX 2.1、MITRE ATT&CK |
| **安全事件** | 来自 Wazuh、EDR、IDS/IPS 的标准化警报和检测 | OCSF 1.1 |
| **开源情报** | 信息源聚合、实体提取、去重 | STIX 2.1 |
| **审计和合规** | 证据链、控制映射（NIS2、BSI Grundschutz） | OSCAL |
| **AI 记忆** | 代理对话上下文、推理跟踪、语义嵌入 | MCP 对齐 |
| **法医时间线** | 双时间事实、保管链、不可变证据 | CASE/UCO、STIX 2.1 |
| **基础设施和资产** | CMDB、网络清单、监控警报 | Netbox/Prometheus 对齐 |
| **身份和访问管理** | IAM 顶点具有 TLP:AMBER 桥，Keycloak 同步 | Keycloak/Cerbos 对齐 |
### 接口
- **MCP 服务器** -- 主要 AI 代理接口（基于工具的图查询、语义搜索）
- **REST API** -- 基于 FastAPI 的 CRUD 和查询端点，供人类消费者使用
- **TAXII 2.1** -- 与合作伙伴组织的联合威胁情报共享
## 状态
**Alpha**：本地开发堆栈运行正常，模式稳定，摄取管道功能正常，Helm 图表和 ArgoCD 清单已准备就绪。
## 先决条件
- Python 3.13+
- Docker 和 Docker Compose（用于本地开发堆栈）
- PostgreSQL 18+，带有 [Apache AGE](https://age.apache.org/) 和 [pgvector](https://github.com/pgvector/pgvector)（由开发堆栈提供）
- NATS 服务器 2.10+（由开发堆栈提供）
## 快速入门
```
git clone https://github.com/rmednitzer/core-graph.git
cd core-graph
# 安装 Python 依赖
pip install -e ".[dev,test]"
# 启动完整开发栈（包括 API 在 :8000）
make up
# 运行迁移和加载参考数据
make migrate
make seed
```
开发堆栈（`make up`）在 `:8000` 上启动所有服务，包括 REST API。
要**本地运行服务**（例如，用于热重载开发），首先停止堆栈，然后仅启动基础设施，然后在 Docker 外运行 API：
```
make down
docker compose -f deploy/docker/docker-compose.yml up -d postgres nats valkey spicedb cerbos minio
make serve # REST API on :8000 (uvicorn --reload)
make mcp # MCP server
make graph-writer # Ingest graph writer
```
## 部署
### Docker Compose（开发）
```
make up # start
make down # stop
make reset # drop + recreate database, re-run migrations and seeds
```
### Helm 图表（Kubernetes）
`deploy/k8s/helm/` 中的 Helm 图表捆绑了 API、图写入器、PostgreSQL、NATS JetStream 和 Valkey。每个依赖项都可以禁用，以指向外部服务。
```
# 实验室（捆绑依赖，2 个 API 副本）
helm install cg deploy/k8s/helm/
# 生产（高可用副本，自动扩展，资源限制）
helm install cg deploy/k8s/helm/ -f deploy/k8s/helm/values-prod.yaml
# 外部 PostgreSQL
helm install cg deploy/k8s/helm/ \
--set postgres.enabled=false \
--set postgres.external.host=my-pg.example.com \
--set postgres.external.password=secret
```
有关完整配置参考，请参阅 `deploy/k8s/helm/values.yaml`。
### ArgoCD
为两个环境提供了预构建的应用程序清单：
```
# 实验室 -- 自动同步，自我修复，CreateNamespace=true
kubectl apply -f deploy/k8s/helm/argocd/application-lab.yaml
# 生产 -- 手动同步，符合变更控制
kubectl apply -f deploy/k8s/helm/argocd/application-prod.yaml
```
### 空中隔离安装（Zarf）
[Zarf](https://zarf.dev/) 将 Helm 图表和所有容器镜像打包成一个单独的签名 tarball，用于断开连接的集群。
```
# 构建（互联网连接的机器）
zarf package create --confirm
# 部署（断网集群）
zarf package deploy zarf-package-core-graph-amd64-0.1.0.tar.zst --confirm
# 使用生产配置部署
zarf package deploy zarf-package-core-graph-amd64-0.1.0.tar.zst \
--components="core-graph,prod-profile" --confirm
```
## 架构
```
Satellites NATS JetStream Ingest Pipeline
---------- -------------- ---------------
Wazuh (SIEM) ──┐
OpenCTI (TIP) ──┤ ┌─────────────────┐
MISP (IOC DB) ──┼──► NATS JetStream ──►│ NER + Entity │
OSINT Feeds ──┤ (at-least-once) │ Resolution + │
Netbox (CMDB) ──┤ │ Graph Writer │
Prometheus ──┤ └────────┬────────┘
Keycloak (IdP) ──┘ │
▼
┌────────────────────────┐
│ PostgreSQL 18+ │
│ ┌────────┐ ┌────────┐ │
│ │ AGE │ │pgvector│ │
│ │(graph) │ │(embed.)│ │
│ └────────┘ └────────┘ │
│ RLS · pgAudit · cron │
│ Bitemporal model │
└────────────┬───────────┘
│
┌──────────────────────────────────┼──────────┐
│ API Layer │ │
│ Cerbos (ABAC) + SpiceDB (ReBAC) │
├──────────┬───────────┬─────────────────────┤
│ MCP Server│ REST API │ TAXII 2.1 │
│(AI agents)│ (humans) │ (sharing) │
└──────────┴───────────┴─────────────────────┘
Evidence chain: audit_log ──► hash chain ──► MinIO WORM ──► cosign ──► Rekor
```
### 关键设计决策
- **PostgreSQL 是核心。** 没有Neo4j，没有ArangoDB。Apache AGE 用于图（openCypher），pgvector 用于嵌入（HNSW）。
- **NATS JetStream** 作为消息总线。至少一次交付，死信队列带有重试和存档。
- **三层授权**：Cerbos（ABAC）评估 TLP 清除和角色策略，SpiceDB（ReBAC）评估隔室成员资格，PostgreSQL RLS 在引擎级别强制执行。即使有缺陷的应用程序代码也无法泄露数据。
- **双时间模型**：每个事实有四个时间戳（`t_valid`、`t_invalid`、`t_recorded`、`t_superseded`）。事实被无效化，永远不会被删除。
- **证据完整性**：仅追加审计日志、SHA-256 哈希链、带有 RFC 3161 时间戳的 Merkle 根、MinIO WORM 存储、cosign 签名、Rekor 透明日志。
- **欧盟主权**：所有基础设施都在欧盟提供商（Hetzner、自托管注册表）上运行。生产环境中没有美国云依赖项。
## 开发
### Make 目标
| 目标 | 描述 |
|---|---|
| `make up` | 启动 Docker Compose 开发堆栈 |
| `make down` | 停止开发堆栈 |
| `make reset` | 删除、重新创建、迁移和初始化数据库 |
| `make migrate` | 运行编号的 SQL 迁移 |
| `make seed` | 加载参考数据（MITRE ATT&CK、STIX、角色） |
| `make serve` | 在 :8000 上运行 REST API（uvicorn --reload） |
| `make mcp` | 运行 MCP 服务器 |
| `make graph-writer` | 运行图写入器工作进程 |
| `make psql` | 交互式连接到开发数据库 |
| `make test` | 运行所有测试（pytest + RLS 强制执行） |
| `make integration-test` | 仅运行集成测试 |
| `make lint` | 检查 Python（ruff）和 YAML 策略 |
| `make bench` | 运行性能基准（NER、遍历、吞吐量） |
| `make verify-chain` | 验证审计日志哈希链 |
| `make verify-merkle` | 验证 Merkle 根链 |
| `make stamp-merkle` | 为 Merkle 根请求 RFC 3161 时间戳 |
| `make helm-validate` | 检查和模板化 Helm 图表 |
| `make deploy-lint` | 验证所有部署工件 |
### 运行测试
```
# 所有测试（单元 + RLS 执法）
make test
# 集成测试（需要运行 Docker 栈）
make integration-test
# 特定测试文件
pytest tests/skills/test_asset_skills.py -v
# 代码风格检查
make lint
```
## 仓库布局
```
core-graph/
├── api/ API layer
│ ├── rest/ FastAPI REST endpoints + middleware (OIDC, metrics, logging)
│ ├── mcp/ MCP server, skill registry, query templates
│ │ ├── skills/ Skill implementations (asset, compliance, identity, threat)
│ │ └── tools/ MCP tools (cypher query, entity resolve, vector search, ...)
│ ├── taxii/ TAXII 2.1 server for threat intel sharing
│ ├── authz/ SpiceDB (ReBAC) and Cerbos (ABAC) client modules
│ ├── utils/ AGE query guard, Cypher safety validation
│ └── db.py Shared connection pool (psycopg-pool)
├── ingest/ Ingest pipeline
│ ├── connectors/ Satellite adapters (Wazuh, OpenCTI, MISP, OSINT, Netbox,
│ │ Prometheus, Keycloak) -- all extend AdapterBase
│ ├── ner/ Named entity recognition (tier 1: regex + STIX patterns)
│ ├── resolver/ Entity resolution and deduplication
│ ├── dlq/ Dead-letter queue processor
│ ├── enrichment.py ingest.* → enriched.* normalisation (+ enrichment_worker.py)
│ └── graph_writer.py Batch graph writer with bitemporal versioning
├── schema/
│ ├── migrations/ Numbered SQL files (001_ through 027_), idempotent
│ └── seed/ Reference data (MITRE ATT&CK, STIX vocabularies, roles)
├── policies/ Cerbos YAML policies (threat entities, evidence, incidents, IAM)
├── evidence/ Evidence integrity
│ ├── chain/ Merkle root computation and hash chain verification
│ └── signing/ cosign signing, MinIO WORM storage, RFC 3161 timestamps
├── deploy/
│ ├── docker/ Docker Compose dev stack + hardened PostgreSQL config
│ ├── k8s/ Helm chart, ArgoCD manifests
│ ├── nats/ NATS server config (dev + prod)
│ └── grafana/ Dashboards and provisioning
├── tests/ Schema, RLS, ingest, integration, skills, TAXII tests
├── scripts/ Bootstrap, validation, benchmarks, MinIO init
├── docs/ Architecture, compliance, ontology, operations, runbooks
└── zarf.yaml Air-gapped deployment package definition
```
## 文档
详细文档位于 `docs/`：
| 区域 | 文档 |
|---|---|
| **架构** | [概述](docs/architecture/overview.md), [授权模型](docs/architecture/authorization-model.md), [RLS + AGE 集成](docs/architecture/rls-age-integration.md), [IAM 层](docs/architecture/iam-layer.md), [数据驻留](docs/architecture/data-residency.md) |
| **ADRs** | [0001 建立 ADR 实践](docs/architecture/adr/ADR-0001-establish-adr-practice.md), [0002 混合检索](docs/architecture/adr/ADR-0002-hybrid-retrieval.md), [0003 边缘 TLP 异常化](docs/architecture/adr/ADR-0003-edge-tlp-denormalization.md), [0004 显著性公式](docs/architecture/adr/ADR-0004-salience-formula.md), [0005 内存替代](docs/architecture/adr/ADR-0005-memory-supersession.md), [0006 代码库验证 2026-05](docs/architecture/adr/ADR-0006-codebase-validation-2026-05.md), [0007 现代化审计 2026-05](docs/architecture/adr/ADR-0007-modernization-audit-2026-05.md), [0008 授权分层](docs/architecture/adr/ADR-0008-authorization-layering.md) |
| **本体** | [模式设计](docs/ontology/schema-design.md), [STIX 映射](docs/ontology/stix-mapping.md), [OCSF 规范化](docs/ontology/ocsf-normalization.md) |
| **合规** | [NIS2 控制](docs/compliance/nis2-controls.md), [BSI IT-Grundschutz](docs/compliance/bsi-grundschutz-map.md) |
| **操作** | [备份和还原](docs/operations/backup-restore.md), [PostgreSQL 强化](docs/operations/postgresql-hardening.md), [破玻璃程序](docs/operations/break-glass.md), [PG 主要升级](docs/operations/pg-major-upgrade.md), [数据库迁移手册](docs/operations/database-migration-runbook.md) |
| **手册** | [审计链损坏](docs/operations/runbooks/audit-chain-broken.md), [摄取管道停滞](docs/operations/runbooks/ingest-pipeline-stalled.md), [DLQ 溢出](docs/operations/runbooks/dlq-overflow.md), [RLS 配置错误](docs/operations/runbooks/rls-misconfiguration.md) |
| **技能** | [MCP 技能注册](docs/skills/README.md) |
## 规范
- **提交**：[常规提交](https://www.conventionalcommits.org/)，范围：`feat:`、`fix:`、`docs:`、`schema:`、`policy:`、`deploy:`、`test:`、`skill:`
- **迁移**：编号的 SQL 文件（`001_`、`002_`、...）。没有 ORM。
- **安全**：参数化 SQL、AGE 查询模板（没有字符串连接）、RLS 强制执行、每个请求的 Cerbos/SpiceDB 授权。
- **格式**：SI 单位、ISO 8601 日期（YYYY-MM-DD）、24 小时时间、UTC 除非明确为本地时间。
## 贡献
有关开发工作流程、代码风格和 PR 指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
有关漏洞报告和安全设计概述，请参阅 [SECURITY.md](SECURITY.md)。
## 许可证
Apache-2.0。请参阅 [LICENSE](LICENSE）。
核心路径（PostgreSQL + AGE + pgvector + NATS + Cerbos + cosign）完全是 Apache 2.0 / MIT / BSD / PostgreSQL 许可证。卫星组件携带自己的许可证（GPL、AGPL）并作为外部服务运行，而不是嵌入在可分发代码中。
标签：AI 内存, Apache AGE, Cerbos, Cloudflare, EDR, ESC4, IDS/IPS, Keycloak, MCP, MITRE ATT&CK, Netbox, OCSF, OSINT, pgvector, PostgreSQL, REST API, STIX, TAXII, Wazuh, 向量知识库, 基础设施资产, 威胁情报, 子域名突变, 安全事件, 安全情报, 审计合规, 开发者工具, 法医时间线, 测试用例, 脆弱性评估, 请求拦截, 身份访问管理, 逆向工具