ecoPrimals/skunkBat
GitHub: ecoPrimals/skunkBat
纯 Rust 网络防御安全原语库，通过仅依赖元数据的侦察方式在主权计算环境中实现多类型威胁检测与分级响应。
Stars: 0 | Forks: 0
# skunkBat
**外部成熟度**：可部署状态
**版本**：0.2.18 | **测试**：586 | **最大生产文件**：700L
**许可证**：AGPL-3.0-or-later (scyBorg 三重 Copyleft)
用于主权计算环境的防御性网络安全原语。
## 什么是 skunkBat？
skunkBat 通过仅基于元数据的防御性侦察来保护主权计算环境。它能够检测威胁、协调分级响应，并在受信任的节点之间联合威胁情报 —— 所有这些都不会检查数据包内容或跟踪用户行为。
- **7 种威胁类型**：基因（谱系）、拓扑（跨层）、行为（统计异常）、入侵（特征）、资源（DoS/耗尽）、配置漂移、进程生成异常（崩溃循环检测）
- **可组合原语**：`baseline`、`metadata`、`response`、`lineage`、`health` —— 每个都可以作为独立功能单独使用
- **胸腺选择模型**：通过 BearDog 谱系进行自我/非我识别（设计阶段）
- **分级防御**：监控、隔离、阻断 —— 保留用户授权
- **统计基线**：学习您网络的正常状态，而非通用启发式规则
- **JSON-RPC 2.0**：完整规范 —— 支持单次请求、批量请求和通知
- **BTSP 阶段 1/2/3**：Socket 命名，TCP + UDS 上 BearDog 委托握手，用于 biomeOS 组合绕过的首字节窥探，带有自动升级至 `ChaCha20-Poly1305` 加密帧的 `btsp.negotiate` 密码协商，键型密码强制执行（共价键/金属键/离子键），服务端密码底线策略（`SKUNKBAT_CIPHER_FLOOR`），协议版本 `1.0`
- **Wire 标准 L2/L3**：兼容 `capabilities.list` 和 `identity.get`
- **架构级隐私**：内容检查在结构上是不可能的
### 理念
**防御，而非攻击** —— 保护网络，永不发起攻击。
**侦察，而非监控** —— 监控模式，而非用户行为。
**用户授权** —— 所有者批准重大操作。
**主权优先** —— 默认本地化，数据由用户控制。
有关完整的伦理框架，请参阅 `RECONNAISSANCE_NOT_SURVEILLANCE.md`。
## 工作区
```
skunkBat/
├── crates/
│ ├── skunk-bat-core/ # Threat detection, defense, observability
│ ├── skunk-bat-integrations/ # JSON-RPC client, discovery, federation
│ ├── skunk-bat-server/ # UniBin server (TCP + UDS + BTSP)
│ └── skunky-ingest/ # Live Caddy log tailer → baseline.observe
├── examples/ # 12 narrative demos
├── tests/ # Integration, e2e, chaos tests
└── specs/ # Technical specifications
```
| Crate | 职责 | 类型 |
|-------|------|------|
| `skunk-bat-core` | 威胁检测（7 种类型）、防御编排、可观测性、通用适配器 | 库 |
| `skunk-bat-integrations` | JSON-RPC 2.0 客户端、BearDog 谱系、ToadStool 发现、Songbird 联邦 | 库 |
| `skunk-bat-server` | 包含 `server`、`health`、`scan`、`detect` 子命令的 UniBin CLI | 二进制 |
| `skunky-ingest` | 实时 Caddy 日志跟踪器，将流量观察结果输入行为分析器 | 二进制 |
## 快速开始
### 运行服务器
```
# 启动 JSON-RPC server (TCP + UDS，默认端口 9750)
cargo run -p skunk-bat-server -- server
# 覆盖 bind/port/socket
cargo run -p skunk-bat-server -- server --bind 0.0.0.0 --port 9750 --socket /tmp/skunkbat.sock
# 健康检查
cargo run -p skunk-bat-server -- health
# 运行扫描
cargo run -p skunk-bat-server -- scan
# 检测威胁
cargo run -p skunk-bat-server -- detect
```
### 库用法
```
use skunk_bat_core::{SkunkBat, SkunkBatConfig};
use skunk_bat_core::PrimalLifecycle;
#[tokio::main]
async fn main() -> Result<(), Box> {
let config = SkunkBatConfig::default();
let mut skunkbat = SkunkBat::new(config);
skunkbat.start().await?;
skunkbat.scan_network().await?;
let threats = skunkbat.detect_threats().await?;
for threat in threats {
skunkbat.respond_to_threat(&threat)?;
}
let metrics = skunkbat.get_security_metrics();
Ok(())
}
```
### 示例
`examples/` 目录包含 12 个叙事演示，说明了核心 API 用法、威胁响应模式和集成架构。有关扫描 → 检测 → 响应的演练，请参阅 `examples/basic_usage.rs`。
## 构建和测试
```
cargo build --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check
cargo doc --no-deps
cargo deny check
# 跨架构（通过 .cargo/config.toml 实现 musl static binaries）
cargo build-x64 # x86_64-unknown-linux-musl
cargo build-arm64 # aarch64-unknown-linux-musl
# Windows 交叉检查
cargo check --target x86_64-pc-windows-gnu
```
## 配置
### 环境变量
```
# Server bind address + port
export SKUNKBAT_LISTEN_ADDR=127.0.0.1 # Default: localhost-only (secure-by-default)
export SKUNKBAT_PORT=9750 # Default: 9750
# Auth mode (MethodGate)
export SKUNKBAT_AUTH_MODE=enforced # Default: permissive (log + allow)
# BTSP Phase 1
export FAMILY_ID=your-family-id
export BIOMEOS_SOCKET_DIR=/run/biomeos
export BIOMEOS_INSECURE=1 # Required when FAMILY_ID is unset
# 基于 Capability 的 discovery（运行时，非 hardcoded）
export LINEAGE_ENDPOINT=127.0.0.1:9300
export DISCOVERY_ENDPOINT=127.0.0.1:3000
export FEDERATION_ENDPOINT=127.0.0.1:8080
# 审计 forwarding targets
export RHIZOCRYPT_ENDPOINT=127.0.0.1:9400
export SWEETGRASS_ENDPOINT=127.0.0.1:9500
# Server operational tuning（均有合理的默认值）
export SKUNKBAT_SESSION_TTL=3600 # Session eviction after N seconds
export SKUNKBAT_SESSION_SWEEP=300 # Sweep interval (seconds)
export SKUNKBAT_FORWARD_INTERVAL=10 # Audit forwarding poll interval
export SKUNKBAT_FORWARD_TIMEOUT=5 # Forwarding RPC timeout
export SKUNKBAT_FORWARD_MIN_SEVERITY=warn # info|warn|error
export SKUNKBAT_REGISTRATION_TIMEOUT=3 # Discovery registration timeout
export SKUNKBAT_LINEAGE_ID=my-family # Genetic verification (enables BearDog)
export SKUNKBAT_TOPOLOGY_PATH=1,2,3 # Expected layer traversal path
export SKUNKBAT_INTEGRATION_TIMEOUT_MS=3000 # Integration RPC timeout (ms)
export SKUNKBAT_DATA_DIR=./data # Quarantine persistence directory
export SKUNKBAT_FEDERATION_POLL_SECS=10 # Federation broadcast poll interval
export SKUNKBAT_FEDERATION_BATCH_SIZE=50 # Federation max events per poll
export SKUNKBAT_CONTENT_TIMEOUT=5 # NestGate content RPC timeout (secs)
export SKUNKBAT_HANDSHAKE_DEADLINE=30 # BTSP handshake deadline (secs)
export SKUNKBAT_SKIP_SYNTHETIC_BASELINE=false # Skip synthetic baseline seeding
```
### 威胁阈值
所有检测参数均可通过 `SkunkBatConfig.thresholds`（`ThreatThresholds` 结构体）进行配置。默认值针对典型的局域网环境进行了调优：
| 字段 | 默认值 | 描述 |
|-------|---------|-------------|
| `sigma_threshold` | 2.5 | 触发异常报告的 Sigma 偏差 |
| `dos_load_threshold` | 0.9 | 触发 DoS 警报的系统负载（0–1） |
| `spawn_rate_threshold` | 50.0 | 触发崩溃循环警报的进程派生数/秒 |
| `intrusion_sensitive_ports` | 22, 23, 3389, 445, 135 | 触发端口扫描检测的端口 |
| `intrusion_exfil_volume` | 100,000 | 触发数据外泄启发式规则的最小字节数 |
| `intrusion_exfil_ratio` | 10,000 | 流量/连接比率阈值 |
| `quarantine_critical_confidence` | 0.9 | 立即隔离的置信度 |
| `quarantine_high_confidence` | 0.7 | 隔离并发送警报的置信度 |
阈值也可以通过环境变量设置：`SKUNKBAT_SIGMA_THRESHOLD`、
`SKUNKBAT_DOS_LOAD_THRESHOLD`、`SKUNKBAT_SPAWN_RATE_THRESHOLD`、`SKUNKBAT_GENETIC_CONFIDENCE`、
`SKUNKBAT_BEHAVIORAL_WINDOW`、`SKUNKBAT_BEHAVIORAL_MIN_OBS`、`SKUNKBAT_AUDIT_LOG_CAPACITY`。
## 生态系统集成
skunkBat 在运行时通过基于能力的 JSON-RPC 发现其他原语。生产代码中没有硬编码任何原语名称。
- **BearDog**：基因谱系验证（WHO）—— 通过 `lineage-verification.sock` 或 `LINEAGE_ENDPOINT` 进行 `lineage.verify` + `lineage.list`
- **ToadStool**：基于能力的原语发现（WHERE）—— 通过 `discovery.sock` 或 `DISCOVERY_ENDPOINT`
- **Songbird**：联合威胁情报（COORDINATION）—— 通过 `federation.sock` 或 `FEDERATION_ENDPOINT`
- **NestGate**：受保护的应用平台（HOME）
### 消费的能力
`btsp.server.verify`、`btsp.negotiate`（对外提供）、`lineage.verify`、`lineage.list`、
`capabilities.list`、`federation.broadcast`、`discovery.find_by_capability`
## 质量
- Edition 2024，全工作区实施 `forbid(unsafe_code)`
- Clippy pedantic + nursery，零警告（`-D warnings`）
- `#[expect(reason)]` 为标准的 lint 抑制方式 —— 生产代码中零 `#[allow]`
- `cargo deny` 的 advisory/ban/license/source 检查均通过；明确禁止使用 `ring`
- 所有源文件均不到 800 行（生产代码最大：700 行；测试文件豁免）
- 所有源文件均带有 SPDX `AGPL-3.0-or-later` 头
- 生产代码中零 `TODO`/`FIXME`/`HACK`；生产代码中零 `unwrap()`/`expect()`
- 生产代码中零 `unreachable!()` —— 全部演进为正确的错误返回
- `ThreatThresholds` 结构体 —— 所有检测常量均可配置，无魔术数字
- 纯 Rust —— 零跨仓库路径依赖，无 C 依赖，移除了 `rand`（通过 RustCrypto 使用 OsRng）
- 586 个测试通过（库测试 + 集成测试 + 混沌测试），覆盖整个工作区
- 所有 30 个 IPC 方法均已划分稳定性等级（28 个应用层 + 2 个传输层；稳定；`auth.*` 处于测试阶段）
- 跨架构：`cargo check --target x86_64-pc-windows-gnu` 顺利通过；
通过 `.cargo/config.toml` 别名（`build-x64`、`build-arm64`）进行 musl 静态构建
- CI：GitHub Actions 包含 fmt/clippy/doc/deny/test 门控（`actions/checkout@v5`）
- 移除并禁止了 `async-trait` —— 全面采用原生 RPITIT
- 向发现服务自注册（`ipc.register`）+ Neural API `primal.announce`
- 支持发现升级层次结构：第 1 层（Songbird `ipc.resolve`），第 3 层（UDS 文件系统），第 5 层（端口 9750 上的 TCP 探测）
- 支持 SIGTERM 优雅关闭，提供 `lifecycle.status` 健康端点
## 规范文档
- `specs/00_SPECIFICATIONS_INDEX.md` —— 所有规范的索引
- `specs/RECONNAISSANCE_SPEC.md` —— 网络情报
- `specs/THREAT_DETECTION_SPEC.md` —— 威胁识别（包括胸腺模型、键型映射）
- `specs/AUTO_DEFENSE_SPEC.md` —— 防御机制
- `specs/OBSERVABILITY_SPEC.md` —— 指标和监控
- `specs/THYMIC_SELECTION_SPEC.md` —— 自我/非我识别模型（设计阶段）
- `specs/COMPOSABLE_PRIMITIVES_SPEC.md` —— 原语分解与组合模式
## 许可证
scyBorg 三重 Copyleft：软件遵循 AGPL-3.0-or-later，游戏机制遵循 ORC，创意内容遵循 CC BY-SA 4.0。详情请参阅 `LICENSE`。
标签：Rust, 可视化界面, 威胁情报, 开发者工具, 异常检测, 网络安全, 网络流量审计, 通知系统, 隐私保护