Ovotron-net/vigilant-chainsaw
GitHub: Ovotron-net/vigilant-chainsaw
一个基于声明式 JSON 策略的 Linux 网络流量持续监控传感器，支持实时捕获与离线 PCAP 分析，可记录违规事件并选择性地生成 nftables 拦截规则。
Stars: 0 | Forks: 0
# ibn-monitor
**基于意图的持续流量监控器** — 一个 Linux 网络传感器，基于声明式 JSON 策略评估实时或离线 IP 流量，将违规行为记录为 JSONL，可选择通过 webhook 进行通知，暴露健康状态/指标和一个小型仪表板，并可将 `action=drop` 规则渲染到 `nftables` 转发表中。
## 功能
| 功能 | 详情 |
|---|---|
| **持续捕获 (v1)** | 通过 Scapy 获取 IPv4/IPv6 头部元数据（使用 `AsyncSniffer` 或 PCAP 重放） |
| **声明式策略** | V1：CIDRs、协议、端口、严重级别、`alert` / `drop`。V2：带有执行配置的明确禁止流声明 |
| **不捕获 payload** | 仅限 IP/传输层字段 — 绝不包含应用层 body 字节 |
| **结构化事件** | V1 轮转 JSONL + 可选 webhook；v2 schema-v2 事件证据封装 |
| **V2 经典 PCAP 重放** | 仅限头部流式传输、事件时间水印、违规片段（不支持 PCAPNG） |
| **热重载** | `SIGHUP` 可在不停止捕获的情况下切换 v1 规则 |
| **可观测性** | `/healthz`, `/readyz`, Prometheus `/metrics`, `/api/state`，以及位于 `/` 的 HTML 仪表板 |
| **执行（可选）** | 将 v1 `action=drop` 规则渲染到 `inet ibn_monitor`，用于网关 `nftables` |
## 快速开始
### 开发（任何操作系统）
```
python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1
source .venv/bin/activate
pip install -e ".[dev]"
ibn-monitor validate --config config/policy.json
```
### 实时捕获 (Linux)
需要 `libpcap` 和 `CAP_NET_RAW`（或 root 权限）：
```
sudo apt-get install -y libpcap0.8 nftables
ip -brief link # set sensor.interface in config/policy.json
sudo .venv/bin/ibn-monitor run --config config/policy.json
```
事件将输出到 `logging.file` 配置的路径中（示例策略：`/var/log/ibn-monitor/events.jsonl`）。
### 无需 root 权限
```
# Synthetic policy check (v1 exit 2 = match; v2 exit 1 = match, 2 = error)
ibn-monitor check --config config/policy.json \
--source 10.20.5.14 --destination 10.50.10.8 \
--protocol tcp --destination-port 5432
ibn-monitor check --config config/policy.v2.example.json \
--source 10.20.5.14 --destination 10.50.10.8 \
--protocol tcp --destination-port 5432 --format json
# V1 离线 PCAP 通过 Scapy 路径
python scripts/generate_test_pcap.py
ibn-monitor run --config config/policy.json --pcap test-traffic.pcap
# V2 经典 PCAP 事件时间重放（无 Scapy）
ibn-monitor validate --config config/policy.v2.example.json --strict
ibn-monitor replay --config config/policy.v2.example.json \
--pcap test-traffic.pcap --output build/replay-v2.jsonl --summary-output -
# 将明确的 v1 policy 迁移到 v2 候选（拒绝覆盖）
ibn-monitor migrate-policy --config config/policy.json --output build/policy.v2.json \
--sensor-id edge-gw-01 --topology gateway --capture-point wan=eth0
```
## 架构
实时路径仅限 Linux 且使用策略 **版本 2**。离线分析使用经典 PCAP 重放（任何操作系统，无需 root）。执行始终是一个独立的渲染/应用步骤 — 传感器绝不会丢弃数据包。
```
flowchart TD
subgraph inputs [Inputs]
NIC[Network interface]
PCAP[Classic PCAP file]
POLCFG[policy v2 JSON]
end
subgraph capture [Capture and decode]
AFP[AF_PACKET + cBPF
capture_afpacket.py] STG[Staged MSG_PEEK reader
staged_reader.py] DEC[Header-only decode
decode.py] PCP[Streaming PCAP reader
pcap.py] end subgraph pipeline [Ordered pipeline] OQ[Observation queue
drop-oldest] CTL[Control lane
reload / stats / shutdown] WORK[PipelineWorker
pipeline.py] MATCH[evaluate_policy
policy.py] EP[EpisodeTracker
episodes.py] SEQ[EvidenceSequencer
events.py] end subgraph outputs [Evidence and surfaces] JRN[JournalWriter JSONL
journal.py] WH[WebhookV2Notifier
notifications_v2.py] RM[Atomic read model
read_model.py] PROBE[Probe HTTP
/healthz /readyz /metrics] OPS[Ops HTTP + dashboard
/ /api/state] end subgraph offline [Offline] RPL[ibn-monitor replay
replay.py] end subgraph enforce [Enforcement separate step] RNF[render-nftables
enforcement.py] NFT[nftables table] end NIC --> AFP --> STG --> DEC --> OQ PCAP --> PCP --> RPL RPL --> MATCH POLCFG --> MATCH POLCFG --> RNF OQ --> WORK CTL --> WORK WORK --> MATCH --> EP --> SEQ SEQ --> JRN JRN --> WH JRN --> RM RM --> PROBE RM --> OPS RNF --> NFT RPL --> SEQ ``` **实时数据流 (v2)：** AF_PACKET → 解码 → Observation 队列 → `PipelineWorker` → `evaluate_policy` → `EpisodeTracker` → `EvidenceSequencer` → `JournalWriter` → webhook / 运维快照 / 探针。 **离线：** `ibn-monitor replay` 将经典 PCAP 流式传输并经过相同的策略和事件路径（无需 root）。**实时：** 仅限 Linux + 策略版本 2。 `src/ibn_monitor/` 下的模块 — 无 Web 框架，无 ORM： | 模块 | 作用 | |---|---| | `models.py` | 冻结的领域类型：v2 `Observation`/`PolicyRule`/episodes/evidence；用于渲染/检查的过渡期 v1 `Rule`/`Event` | | `config.py` | V1 `load_config`（渲染/迁移源）；v2 `validate_v2_config`/`load_v2_config` + `runtime_identity_hash` | | `capture.py` | `ObservationSource` + `MemoryObservationSource`（不依赖 Scapy） | | `capture_afpacket.py` | Linux `AfPacketSource` (AF_PACKET / cBPF) | | `cbpf.py` / `linux_packet.py` / `staged_reader.py` | 专属 BPF 模板、socket 辅助工具、MSG_PEEK 读取器 | | `decode.py` / `pcap.py` / `policy.py` / `episodes.py` / `replay.py` | 纯 v2 解码、PCAP、匹配、事件片段、离线重放 | | `pipeline.py` / `ops_state.py` / `read_model.py` | 有序 worker、运维状态、原子操作投影 | | `probe.py` / `operations.py` / `dashboard.py` | 探针 `/healthz` `/readyz` `/metrics`；运维 `/` + `/api/state`；内嵌 SPA | | `journal.py` / `notifications_v2.py` / `evidence_stub.py` | 持久化日志、v2 webhook、证据写入接口 | | `monitor.py` | `LiveMonitor` 组合根 | | `migration.py` / `cli.py` | v1→v2 迁移；验证/检查/重放/运行/渲染 nftables | | `enforcement.py` | V1 `render_nftables` + v2 感知拓扑的 `render_nftables_v2`（网关/主机；不支持镜像） | | `engine.py` / `events.py` / `health.py` | V1 检查/渲染辅助工具 + 遗留指标 | 有关运维操作，请参阅 [docs/operator/runbook.md](docs/operator/runbook.md)。领域词汇表：[CONTEXT.md](CONTEXT.md)。贡献者规范：[AGENTS.md](AGENTS.md)。 ## 环境要求 | | | |---|---| | **Python** | 3.11+ | | **实时捕获 / nftables** | Linux + `libpcap` + 相应的 capabilities | | **开发 / 测试 / PCAP** | Windows、macOS 或 Linux | | **运行时依赖** | `scapy`, `jsonschema` | Capabilities：捕获需要 `CAP_NET_RAW`；仅在应用防火墙规则时需要 `CAP_NET_ADMIN`。 ## 策略模型 **V1** `config/policy.json` 会根据内置的 `ibn_monitor/policy.schema.json` 进行验证。schema 负责控制结构（枚举、范围、端口仅限 tcp/udp）。`config.py` 负责控制语义（唯一规则 ID、CIDR 解析、冻结的 dataclasses）。 **V2** 示例：`config/policy.v2.example.json`，schema 为 `ibn_monitor/policy-v2.schema.json`。所有的匹配选择器都必须明确指定；省略 CIDRs/端口是无效的。规范的策略/配置修订版本通过内容哈希确定。 ``` { "version": 1, "sensor": { "interface": "eth0", "bpf_filter": "ip or ip6", "promiscuous": false }, "logging": { "file": "/var/log/ibn-monitor/events.jsonl", "max_bytes": 10485760, "backup_count": 5 }, "health": { "enabled": true, "bind": "127.0.0.1", "port": 9108 }, "notifications": { "webhook_url_env": "IBN_WEBHOOK_URL", "timeout_seconds": 3, "minimum_severity": "high", "deduplication_seconds": 60 }, "rules": [ { "id": "DEV-TO-PROD-DB", "description": "Development systems must not connect directly to PostgreSQL in production", "enabled": true, "source_cidrs": ["10.20.0.0/16"], "destination_cidrs": ["10.50.10.8/32"], "protocol": "tcp", "destination_ports": [5432], "severity": "critical", "action": "drop" } ] } ``` ### 动作 | 动作 | 行为 | |---|---| | `alert` | 仅检测并记录 | | `drop` | 检测、记录，**并且**有资格进行 nftables 渲染 | 实时传感器**绝不**丢弃数据包。执行是一个独立的 `render-nftables`（或应用脚本）步骤。 ### 约束条件 - 规则 ID 必须唯一。 - 非空的 `destination_ports` 要求 `protocol` 为 `tcp` 或 `udp`。 - `notifications.webhook_url_env` 是一个**环境变量名称**，绝不是 URL 本身。 - `SIGHUP` 仅重载**规则**。对 `sensor`、`logging` 或 `health` 的修改需要重启。 ## CLI ``` ibn-monitor validate --config config/policy.json ibn-monitor check --config config/policy.json \ --source 10.20.5.14 --destination 10.50.10.8 \ --protocol tcp --destination-port 5432 # exit 0 = no match, exit 2 = match ibn-monitor run --config config/policy.json ibn-monitor run --config config/policy.json --pcap traffic.pcap ibn-monitor run --config config/policy.json --interface eth1 ibn-monitor render-nftables --config config/policy.json --output build/ibn-monitor.nft ``` | Make 目标 | 命令 | |---|---| | `make test` | pytest + coverage | | `make lint` | ruff check . | | `make validate` | policy validate | | `make check` | sample flow check | | `make pcap` | generate + replay test PCAP | | `make docker` | compose up --build -d | | `make nftables` | render + `nft --check` | ## Webhook 通知 ``` export IBN_WEBHOOK_URL='https://your-authorized-endpoint.example/events' # Linux + sudo: 保留 secret sudo --preserve-env=IBN_WEBHOOK_URL .venv/bin/ibn-monitor run --config config/policy.json ``` PowerShell： ``` $env:IBN_WEBHOOK_URL = 'https://your-authorized-endpoint.example/events' ibn-monitor run --config config/policy.json ``` - POST body 是与 JSONL 日志行相同的 JSON 对象。 - 交付是异步的（daemon worker，队列最大 1000）。 - 低于 `minimum_severity` 的事件不会被发送；在 `deduplication_seconds` 内的重复项（相同规则 + flow key）会被抑制。**所有**匹配项仍会写入本地日志。 - 切勿提交 webhook URL。 ## 健康、指标和仪表板 默认绑定：`127.0.0.1:9108`。 | 路径 | 用途 | |---|---| | `/` | 内嵌仪表板（指标、规则、近期违规；3秒刷新） | | `/api/state` | JSON：指标 + 规则 + 近期事件 | | `/healthz` | 存活状态 | | `/readyz` | 一旦建立捕获即就绪（在此之前为 `503`） | | `/metrics` | Prometheus 文本格式 | ``` curl http://127.0.0.1:9108/healthz curl http://127.0.0.1:9108/readyz curl http://127.0.0.1:9108/metrics curl http://127.0.0.1:9108/api/state ``` 在没有访问控制的情况下，请勿将健康状态监听器暴露在不受信任的网络中。 ## 事件格式 每行一个 JSON 对象： ``` { "schema_version": 1, "event_id": "9a790d64-b9d4-47e1-89bc-b469b72a3063", "event_type": "network_policy_violation", "observed_at": "2026-07-17T18:21:44.842911+00:00", "rule": { "id": "DEV-TO-PROD-DB", "description": "Development systems must not connect directly to PostgreSQL in production", "severity": "critical", "action": "drop" }, "network": { "timestamp": "2026-07-17T18:21:44.842911+00:00", "interface": "eth0", "source": "10.20.5.14", "destination": "10.50.10.8", "protocol": "tcp", "source_port": 50000, "destination_port": 5432, "packet_length": 40, "tcp_flags": "S" } } ``` ## Docker 实时捕获需要主机网络和 Linux capabilities： ``` mkdir -p data/logs docker compose up --build -d docker compose logs -f ``` Compose 会将 `config/policy.json` 以只读方式挂载，并将日志写入 `./data/logs`。如果设置了主机环境中的 `IBN_WEBHOOK_URL`，它将被转发。 ## systemd (Linux) ``` sudo ./scripts/install-systemd.sh sudo systemctl status ibn-monitor sudo journalctl -u ibn-monitor -f # 仅在编辑 policy 规则后： sudo systemctl reload ibn-monitor # SIGHUP ``` 修改接口、BPF 过滤器、日志路径或健康状态绑定需要完全重启。 ## nftables 执行 (Linux) 生成、验证，然后应用： ``` ibn-monitor render-nftables \ --config config/policy.json \ --output build/ibn-monitor.nft sudo nft --check --file build/ibn-monitor.nft sudo nft --file build/ibn-monitor.nft sudo nft list table inet ibn_monitor # or sudo ./scripts/apply-nftables.sh config/policy.json ``` 渲染可在任何操作系统上运行；应用需要 Linux 和 `nft`。 **操作说明** - 生成的链挂在 **forward** — 部署在能看到相应流量的网关上。 - 仅管理 `inet ibn_monitor` 表；其他的宿主机防火墙状态保持不变。 - 首先在非生产环境中进行验证；在进行远程防火墙更改之前，请保持控制台/带外访问可用。 - 持久化配置因发行版而异 — 请将生成的文件接入到您平台的 nftables 服务中。 ## 测试 ``` make test # or: pytest make lint # or: ruff check . ``` - 共享的 fixtures：`tests/factories.py` (`rule`, `metadata`, `app_config`)。 - `PacketSource` 是可注入的 — `MonitorService` 测试使用内存源（无需 mock Scapy）。 - 在 `tests/conftest.py` 中禁用了 Scapy 路由自动加载，以实现 CI 隔离。 ## 安全性 有关报告和操作指南，请参阅 [SECURITY.md](SECURITY.md)。简而言之： - 仅限元数据 — 设计上不存储 payload。 - 主机传感器只能看到交付给该主机或镜像到该主机的流量（如需更广泛的可见性，请使用 TAP/SPAN/云镜像）。 - 检测 ≠ 执行；请在受控验证后应用防火墙规则。 - 保护策略、日志、健康状态绑定和 webhook 密钥。 ## 许可证 [GPL-2.0-only](LICENSE)。
capture_afpacket.py] STG[Staged MSG_PEEK reader
staged_reader.py] DEC[Header-only decode
decode.py] PCP[Streaming PCAP reader
pcap.py] end subgraph pipeline [Ordered pipeline] OQ[Observation queue
drop-oldest] CTL[Control lane
reload / stats / shutdown] WORK[PipelineWorker
pipeline.py] MATCH[evaluate_policy
policy.py] EP[EpisodeTracker
episodes.py] SEQ[EvidenceSequencer
events.py] end subgraph outputs [Evidence and surfaces] JRN[JournalWriter JSONL
journal.py] WH[WebhookV2Notifier
notifications_v2.py] RM[Atomic read model
read_model.py] PROBE[Probe HTTP
/healthz /readyz /metrics] OPS[Ops HTTP + dashboard
/ /api/state] end subgraph offline [Offline] RPL[ibn-monitor replay
replay.py] end subgraph enforce [Enforcement separate step] RNF[render-nftables
enforcement.py] NFT[nftables table] end NIC --> AFP --> STG --> DEC --> OQ PCAP --> PCP --> RPL RPL --> MATCH POLCFG --> MATCH POLCFG --> RNF OQ --> WORK CTL --> WORK WORK --> MATCH --> EP --> SEQ SEQ --> JRN JRN --> WH JRN --> RM RM --> PROBE RM --> OPS RNF --> NFT RPL --> SEQ ``` **实时数据流 (v2)：** AF_PACKET → 解码 → Observation 队列 → `PipelineWorker` → `evaluate_policy` → `EpisodeTracker` → `EvidenceSequencer` → `JournalWriter` → webhook / 运维快照 / 探针。 **离线：** `ibn-monitor replay` 将经典 PCAP 流式传输并经过相同的策略和事件路径（无需 root）。**实时：** 仅限 Linux + 策略版本 2。 `src/ibn_monitor/` 下的模块 — 无 Web 框架，无 ORM： | 模块 | 作用 | |---|---| | `models.py` | 冻结的领域类型：v2 `Observation`/`PolicyRule`/episodes/evidence；用于渲染/检查的过渡期 v1 `Rule`/`Event` | | `config.py` | V1 `load_config`（渲染/迁移源）；v2 `validate_v2_config`/`load_v2_config` + `runtime_identity_hash` | | `capture.py` | `ObservationSource` + `MemoryObservationSource`（不依赖 Scapy） | | `capture_afpacket.py` | Linux `AfPacketSource` (AF_PACKET / cBPF) | | `cbpf.py` / `linux_packet.py` / `staged_reader.py` | 专属 BPF 模板、socket 辅助工具、MSG_PEEK 读取器 | | `decode.py` / `pcap.py` / `policy.py` / `episodes.py` / `replay.py` | 纯 v2 解码、PCAP、匹配、事件片段、离线重放 | | `pipeline.py` / `ops_state.py` / `read_model.py` | 有序 worker、运维状态、原子操作投影 | | `probe.py` / `operations.py` / `dashboard.py` | 探针 `/healthz` `/readyz` `/metrics`；运维 `/` + `/api/state`；内嵌 SPA | | `journal.py` / `notifications_v2.py` / `evidence_stub.py` | 持久化日志、v2 webhook、证据写入接口 | | `monitor.py` | `LiveMonitor` 组合根 | | `migration.py` / `cli.py` | v1→v2 迁移；验证/检查/重放/运行/渲染 nftables | | `enforcement.py` | V1 `render_nftables` + v2 感知拓扑的 `render_nftables_v2`（网关/主机；不支持镜像） | | `engine.py` / `events.py` / `health.py` | V1 检查/渲染辅助工具 + 遗留指标 | 有关运维操作，请参阅 [docs/operator/runbook.md](docs/operator/runbook.md)。领域词汇表：[CONTEXT.md](CONTEXT.md)。贡献者规范：[AGENTS.md](AGENTS.md)。 ## 环境要求 | | | |---|---| | **Python** | 3.11+ | | **实时捕获 / nftables** | Linux + `libpcap` + 相应的 capabilities | | **开发 / 测试 / PCAP** | Windows、macOS 或 Linux | | **运行时依赖** | `scapy`, `jsonschema` | Capabilities：捕获需要 `CAP_NET_RAW`；仅在应用防火墙规则时需要 `CAP_NET_ADMIN`。 ## 策略模型 **V1** `config/policy.json` 会根据内置的 `ibn_monitor/policy.schema.json` 进行验证。schema 负责控制结构（枚举、范围、端口仅限 tcp/udp）。`config.py` 负责控制语义（唯一规则 ID、CIDR 解析、冻结的 dataclasses）。 **V2** 示例：`config/policy.v2.example.json`，schema 为 `ibn_monitor/policy-v2.schema.json`。所有的匹配选择器都必须明确指定；省略 CIDRs/端口是无效的。规范的策略/配置修订版本通过内容哈希确定。 ``` { "version": 1, "sensor": { "interface": "eth0", "bpf_filter": "ip or ip6", "promiscuous": false }, "logging": { "file": "/var/log/ibn-monitor/events.jsonl", "max_bytes": 10485760, "backup_count": 5 }, "health": { "enabled": true, "bind": "127.0.0.1", "port": 9108 }, "notifications": { "webhook_url_env": "IBN_WEBHOOK_URL", "timeout_seconds": 3, "minimum_severity": "high", "deduplication_seconds": 60 }, "rules": [ { "id": "DEV-TO-PROD-DB", "description": "Development systems must not connect directly to PostgreSQL in production", "enabled": true, "source_cidrs": ["10.20.0.0/16"], "destination_cidrs": ["10.50.10.8/32"], "protocol": "tcp", "destination_ports": [5432], "severity": "critical", "action": "drop" } ] } ``` ### 动作 | 动作 | 行为 | |---|---| | `alert` | 仅检测并记录 | | `drop` | 检测、记录，**并且**有资格进行 nftables 渲染 | 实时传感器**绝不**丢弃数据包。执行是一个独立的 `render-nftables`（或应用脚本）步骤。 ### 约束条件 - 规则 ID 必须唯一。 - 非空的 `destination_ports` 要求 `protocol` 为 `tcp` 或 `udp`。 - `notifications.webhook_url_env` 是一个**环境变量名称**，绝不是 URL 本身。 - `SIGHUP` 仅重载**规则**。对 `sensor`、`logging` 或 `health` 的修改需要重启。 ## CLI ``` ibn-monitor validate --config config/policy.json ibn-monitor check --config config/policy.json \ --source 10.20.5.14 --destination 10.50.10.8 \ --protocol tcp --destination-port 5432 # exit 0 = no match, exit 2 = match ibn-monitor run --config config/policy.json ibn-monitor run --config config/policy.json --pcap traffic.pcap ibn-monitor run --config config/policy.json --interface eth1 ibn-monitor render-nftables --config config/policy.json --output build/ibn-monitor.nft ``` | Make 目标 | 命令 | |---|---| | `make test` | pytest + coverage | | `make lint` | ruff check . | | `make validate` | policy validate | | `make check` | sample flow check | | `make pcap` | generate + replay test PCAP | | `make docker` | compose up --build -d | | `make nftables` | render + `nft --check` | ## Webhook 通知 ``` export IBN_WEBHOOK_URL='https://your-authorized-endpoint.example/events' # Linux + sudo: 保留 secret sudo --preserve-env=IBN_WEBHOOK_URL .venv/bin/ibn-monitor run --config config/policy.json ``` PowerShell： ``` $env:IBN_WEBHOOK_URL = 'https://your-authorized-endpoint.example/events' ibn-monitor run --config config/policy.json ``` - POST body 是与 JSONL 日志行相同的 JSON 对象。 - 交付是异步的（daemon worker，队列最大 1000）。 - 低于 `minimum_severity` 的事件不会被发送；在 `deduplication_seconds` 内的重复项（相同规则 + flow key）会被抑制。**所有**匹配项仍会写入本地日志。 - 切勿提交 webhook URL。 ## 健康、指标和仪表板 默认绑定：`127.0.0.1:9108`。 | 路径 | 用途 | |---|---| | `/` | 内嵌仪表板（指标、规则、近期违规；3秒刷新） | | `/api/state` | JSON：指标 + 规则 + 近期事件 | | `/healthz` | 存活状态 | | `/readyz` | 一旦建立捕获即就绪（在此之前为 `503`） | | `/metrics` | Prometheus 文本格式 | ``` curl http://127.0.0.1:9108/healthz curl http://127.0.0.1:9108/readyz curl http://127.0.0.1:9108/metrics curl http://127.0.0.1:9108/api/state ``` 在没有访问控制的情况下，请勿将健康状态监听器暴露在不受信任的网络中。 ## 事件格式 每行一个 JSON 对象： ``` { "schema_version": 1, "event_id": "9a790d64-b9d4-47e1-89bc-b469b72a3063", "event_type": "network_policy_violation", "observed_at": "2026-07-17T18:21:44.842911+00:00", "rule": { "id": "DEV-TO-PROD-DB", "description": "Development systems must not connect directly to PostgreSQL in production", "severity": "critical", "action": "drop" }, "network": { "timestamp": "2026-07-17T18:21:44.842911+00:00", "interface": "eth0", "source": "10.20.5.14", "destination": "10.50.10.8", "protocol": "tcp", "source_port": 50000, "destination_port": 5432, "packet_length": 40, "tcp_flags": "S" } } ``` ## Docker 实时捕获需要主机网络和 Linux capabilities： ``` mkdir -p data/logs docker compose up --build -d docker compose logs -f ``` Compose 会将 `config/policy.json` 以只读方式挂载，并将日志写入 `./data/logs`。如果设置了主机环境中的 `IBN_WEBHOOK_URL`，它将被转发。 ## systemd (Linux) ``` sudo ./scripts/install-systemd.sh sudo systemctl status ibn-monitor sudo journalctl -u ibn-monitor -f # 仅在编辑 policy 规则后： sudo systemctl reload ibn-monitor # SIGHUP ``` 修改接口、BPF 过滤器、日志路径或健康状态绑定需要完全重启。 ## nftables 执行 (Linux) 生成、验证，然后应用： ``` ibn-monitor render-nftables \ --config config/policy.json \ --output build/ibn-monitor.nft sudo nft --check --file build/ibn-monitor.nft sudo nft --file build/ibn-monitor.nft sudo nft list table inet ibn_monitor # or sudo ./scripts/apply-nftables.sh config/policy.json ``` 渲染可在任何操作系统上运行；应用需要 Linux 和 `nft`。 **操作说明** - 生成的链挂在 **forward** — 部署在能看到相应流量的网关上。 - 仅管理 `inet ibn_monitor` 表；其他的宿主机防火墙状态保持不变。 - 首先在非生产环境中进行验证；在进行远程防火墙更改之前，请保持控制台/带外访问可用。 - 持久化配置因发行版而异 — 请将生成的文件接入到您平台的 nftables 服务中。 ## 测试 ``` make test # or: pytest make lint # or: ruff check . ``` - 共享的 fixtures：`tests/factories.py` (`rule`, `metadata`, `app_config`)。 - `PacketSource` 是可注入的 — `MonitorService` 测试使用内存源（无需 mock Scapy）。 - 在 `tests/conftest.py` 中禁用了 Scapy 路由自动加载，以实现 CI 隔离。 ## 安全性 有关报告和操作指南，请参阅 [SECURITY.md](SECURITY.md)。简而言之： - 仅限元数据 — 设计上不存储 payload。 - 主机传感器只能看到交付给该主机或镜像到该主机的流量（如需更广泛的可见性，请使用 TAP/SPAN/云镜像）。 - 检测 ≠ 执行；请在受控验证后应用防火墙规则。 - 保护策略、日志、健康状态绑定和 webhook 密钥。 ## 许可证 [GPL-2.0-only](LICENSE)。
标签：nftables, Python, Scapy, 入侵防御, 无后门, 网络传感器, 自定义请求头, 请求拦截, 逆向工具, 防御绕过