copyleftdev/parallax
GitHub: copyleftdev/parallax
一个 Rust 原生的网络资产情报图引擎，将基础设施建模为属性图，通过 PQL 查询语言支持安全团队进行资产关联分析、策略评估与合规态势监控。
Stars: 0 | Forks: 0
用于网络资产情报的 Rust 原生图引擎。
Parallax 将您的基础设施建模为属性图 —— 实体作为节点，
关系作为边 —— 并允许您使用 PQL（一种专用
图查询语言）进行查询。它以专注于库 crate 的 Cargo workspace 形式
和一个独立的 HTTP server 发布，无需外部存储引擎依赖。
```
FIND host THAT !PROTECTS edr_agent -- hosts without EDR coverage
FIND host WITH os = 'linux' THAT USES aws_iam_role WITH admin = true -- over-privileged EC2
FIND user WITH mfaActive = false THAT ASSIGNED role -- MFA gap
```
## 为什么选择 Parallax
安全团队管理着成千上万的资产，跨越数十种工具。
每种工具只能看到自己的一小部分。没有工具能看到各部分之间的联系。
图模型 —— 通过类型化、有向关系连接的实体 —— 是
正确的抽象。Parallax 将该模型作为**基础设施**提供：开放、
可嵌入、快速且正确，而不会将您锁定在 SaaS 平台或
外部图数据库中。
## 功能特性
- **自定义存储引擎** —— 仅追加 WAL、内存 MemTable、不可变
segments、MVCC 快照。无 RocksDB，无 SQLite，无外部依赖。
- **PQL 查询语言** —— `FIND`、`WITH`、`THAT`、`GROUP BY`、`SHORTEST PATH`、
`BLAST RADIUS`。手写的词法分析器和递归下降解析器。
- **Connector SDK** —— 实现 `Connector` trait；调度器负责
拓扑步骤排序、并行波执行 和 source-scoped diffing。
- **策略引擎** —— YAML 规则文件、PQL 支持的评估、通过
`std::thread::scope` 并行执行、每个框架的合规态势评分。
- **REST API** —— 基于 Axum 的 HTTP server，具有 token 认证、Prometheus 指标，
以及完整的摄取/查询/策略面。
- **CLI** —— `parallax serve`、`parallax query`、`parallax stats`、`parallax wal dump`。
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ parallax-cli parallax-server │
│ │ │ │
│ parallax-connect parallax-query parallax-policy │
│ │ │ │ │
│ └──────── parallax-ingest ───────────┘ │
│ │ │
│ parallax-graph │
│ │ │
│ parallax-store │
│ │ │
│ parallax-core │
└─────────────────────────────────────────────────────────┘
```
依赖流严格无环。每个 crate 都有单一的职责。
| Crate | 角色 |
|---|---|
| `parallax-core` | `EntityId`, `Entity`, `Relationship`, `Value`, `Timestamp` (HLC) |
| `parallax-store` | WAL, MemTable, Segment, Snapshot, `StorageEngine` |
| `parallax-graph` | `GraphReader`, 遍历, 最短路径, 爆炸半径 |
| `parallax-query` | PQL 词法分析器, 解析器, 规划器, 执行器 |
| `parallax-policy` | YAML 规则, `PolicyEvaluator`, 态势评分 |
| `parallax-ingest` | `SyncEngine`, source-scoped diffing |
| `parallax-connect` | `Connector` trait, 步骤调度器, `run_connector()` |
| `parallax-server` | Axum HTTP server, REST API |
| `parallax-cli` | 二进制入口点 |
## 快速开始
### 从源码构建
```
git clone https://github.com/copyleftdev/parallax
cd parallax
cargo build --release
```
### 运行服务器
```
cargo run --package parallax-cli -- serve --data-dir /tmp/parallax-data
```
### 查询
```
# 在另一个终端
parallax query "FIND host WITH os = 'linux'"
parallax query "FIND host THAT !PROTECTS edr_agent"
parallax stats
```
## PQL — Parallax 查询语言
PQL 是一种声明式图查询语言。每个查询都以 `FIND` 开头。
### 实体查找
```
FIND host
FIND host WITH os = 'linux'
FIND host WITH os = 'linux' OR os = 'windows'
FIND host WITH state = 'running' AND env = 'prod'
FIND * -- all entities
```
### 关系遍历
```
FIND host THAT USES aws_iam_role
FIND host THAT !PROTECTS edr_agent -- negated (missing relationship)
FIND user THAT ASSIGNED role WITH admin = true
```
### 路径查询
```
SHORTEST PATH FROM 'instance-001' TO 'prod-db-01'
BLAST RADIUS FROM 'compromised-host'
```
### 聚合
```
FIND host GROUP BY os -- group by property
FIND host RETURN COUNT -- scalar count
FIND host WITH os = 'linux' LIMIT 100
```
## Connector SDK
Connector 从外部来源拉取数据，并将实体和关系
发送到图中。实现 `Connector` trait：
```
use parallax_connect::{Connector, StepContext, StepDefinition, ConnectorError};
use parallax_connect::builder::{entity, relationship};
use async_trait::async_trait;
pub struct MyConnector;
#[async_trait]
impl Connector for MyConnector {
fn name(&self) -> &str { "my-source" }
fn steps(&self) -> Vec
{
vec![
step("hosts", "Emit host inventory").build(),
step("services", "Emit services")
.depends_on(&["hosts"])
.build(),
]
}
async fn execute_step(
&self,
step_id: &str,
ctx: &mut StepContext,
) -> Result<(), ConnectorError> {
match step_id {
"hosts" => {
ctx.emit_entity(
entity("host", "web-01")
.class("Host")
.display_name("web-01")
.property("os", "linux")
.property("active", true),
)?;
}
_ => {}
}
Ok(())
}
}
```
调度器自动根据步骤依赖关系计算波次顺序，
并通过 `tokio::task::JoinSet` 并发运行每个波次的步骤。
### 合成 Connector（用于测试）
```
use connector_aws_synthetic::AwsSyntheticConnector;
// 100 EC2 instances, 70% EDR coverage (30% gap for policy testing)
let connector = AwsSyntheticConnector::realistic(100);
// Clean baseline — all policies pass
let connector = AwsSyntheticConnector::clean(50);
// Worst case — maximum violations
let connector = AwsSyntheticConnector::worst_case(50);
```
GCP synthetic 可通过 `connector-gcp-synthetic` 获得，API 相同。
## 策略引擎
在 YAML 中定义安全规则。每个规则都是一个 PQL 查询 —— 查询返回的
实体即为违规。
```
rules:
- id: edr-coverage-001
name: Hosts without EDR
severity: high
query: "FIND host THAT !PROTECTS edr_agent"
enabled: true
schedule: "every:1h"
frameworks:
- framework: CIS-Controls-v8
control: "10.1"
remediation: Deploy an EDR agent to all active hosts.
- id: mfa-all-users
name: Users without MFA
severity: high
query: "FIND user WITH mfaActive = false"
enabled: true
frameworks:
- framework: CIS-Controls-v8
control: "6.5"
```
```
use parallax_policy::{PolicyEvaluator, load_rules_from_yaml};
let rules = load_rules_from_yaml(Path::new("rules/security.yaml"))?;
let evaluator = PolicyEvaluator::load(rules, &index_stats)?;
// Parallel evaluation — all rules run concurrently on separate OS threads
let results = evaluator.par_evaluate_all(&graph, QueryLimits::default());
// Compliance posture
let posture = compute_posture("CIS-Controls-v8", &rules, &results);
println!("Score: {:.0}%", posture.overall_score * 100.0);
```
## REST API
| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/health` | 健康检查 (无认证) |
| `GET` | `/v1/stats` | 实体和关系计数 |
| `POST` | `/v1/query` | 执行 PQL 查询 |
| `GET` | `/v1/entities/:id` | 通过 ID 获取实体 |
| `POST` | `/v1/ingest/sync` | 提交同步批次 |
| `GET` | `/v1/connectors` | 列出已注册的 Connector |
| `GET` | `/v1/policies` | 列出已加载的策略规则 |
| `POST` | `/v1/policies` | 替换规则集 |
| `POST` | `/v1/policies/evaluate` | 评估所有规则 |
| `GET` | `/v1/policies/posture` | 合规态势评分 |
| `GET` | `/v1/metrics` | Prometheus 指标 |
认证：`Authorization: Bearer ` header。通过
`PARALLAX_API_TOKEN` 环境变量或 `--token` 标志设置 token。
## 状态
当前版本：**v0.2**
| 领域 | 状态 |
|---|---|
| 存储引擎 (WAL + segments + MVCC) | Stable |
| PQL 解析器 + 执行器 | Stable |
| 图遍历 (BFS/DFS, 最短路径, 爆炸半径) | Stable |
| 策略引擎 (YAML 规则, 并行评估, 态势) | Stable |
| Connector SDK (并行波执行) | Stable |
| REST API | Stable |
| CLI | Stable |
| 字段投影 (`RETURN field1, field2`) | 延期至 v0.3 |
| 参数化查询 (`WITH state = $1`) | 延期至 v0.3 |
| gRPC | 延期至 v0.3 |
查看 [路线图](docs/src/reference/roadmap.md) 了解完整计划。
## 许可证
根据以下任一许可证授权：
- [Apache License, Version 2.0](LICENSE-APACHE)
- [MIT License](LICENSE-MIT)
由您选择。标签：CAASM, MVCC, PQL, Rust, 占用监测, 可视化界面, 图查询语言, 安全可视化, 嵌入式数据库, 无外部依赖, 网络安全, 网络流量审计, 网络空间资产测绘, 自定义请求头, 资产图谱, 资产管理, 通知系统, 隐私保护