01rabbit/Azazel-Edge

# Azazel-Edge  [](https://github.com/01rabbit/Azazel-Edge/actions/workflows/ci.yml) [](LICENSE)     Azazel-Edge 是一个面向 Raspberry Pi 的边缘运维技术栈，它结合了： - 内部网络/网关设置 - 确定性 NOC/SOC 评估与动作选择 - 面向操作员的 Web UI + API + Runbook 工作流 - 可选的本地 AI 辅助（Ollama + Mattermost 集成） 本 README 基于截至 **2026-05-11** 已验证的代码库内容（代码、脚本、测试、Git 历史记录、GitHub Issue/PR 元数据）。 ## Azazel-Edge 是什么？ Azazel-Edge 是一款**用于应急操作的轻量级 SOC/NOC 网关**，专为在 Raspberry Pi 上运行而设计。 **适用人群** - 运行临时网段（活动场所、野外办事处、培训演练）的安全人员 - 需要在没有完整 SIEM 的情况下进行首次响应分流的操作员 - 使用本地、离线可用技术栈进行事件响应演练的团队 **适用场景** - 需要在不到一小时内部署好可用的网关 + 告警分流界面 - 没有云连接能力，或者希望将流量完全保持在本地 - 需要带有可选本地 AI 辅助（Ollama）的确定性决策引擎，而不是一个黑盒 **不适用场景** - 替代生产环境的 SIEM 或全职 SOC 平台 - 无需操作员确认即可做出决策的自主 AI - 依赖云：所有核心功能均可离线工作 ## 已验证用途 本代码库中实现的用途为： 1. 运行内部边缘网段（`br0`、DHCP、NAT/转发）并暴露操作界面。 2. 消费标准化遥测数据，并确定性评估 NOC/SOC 状态。 3. 生成带有解释/审计 payload 的显式动作（`observe`、`notify`、`throttle`、`redirect`、`isolate`）。 4. 提供操作员工作流（仪表盘、分流、Runbook、Mattermost 桥接、确定性演示）。 5. 可选通过 Ollama 提供本地 LLM 推理辅助（受限辅助路径，对于确定性演示路径不是必需的）。 凭证： - 网关/网络基线：`installer/internal/install_internal_network.sh` - 确定性动作模型：`py/azazel_edge/arbiter/action.py` - Web/API 界面：`azazel_edge_web/app.py` - 确定性演示重放：`bin/azazel-edge-demo`、`py/azazel_edge/demo/scenarios.py` - AI 代理运行时：`py/azazel_edge_ai/agent.py`、`systemd/azazel-edge-ai-agent.service` ## 核心架构 ``` flowchart LR subgraph ingestion["Event Ingestion"] SUP[Suricata EVE] --> RC[Rust Core] RC --> EP[Evidence Plane] end subgraph evaluation["Deterministic Evaluation"] EP --> NOC[NOC Evaluator] EP --> SOC[SOC Evaluator] NOC --> ARB[Action Arbiter] SOC --> ARB end subgraph action["Operator Plane"] ARB --> EXP[Decision Explanation] EXP --> WEB[Web UI / API] EXP --> NOTIF[Notification] end subgraph ai["AI Assist\n(optional)"] EXP --> GOV[AI Governance] GOV --> LLM[Ollama] LLM --> GOV end WEB --> OPR([Operator]) NOTIF --> MM[Mattermost] ARB --> AUD[Audit Logger] ``` 1. **事件摄取 + 标准化** - Rust 核心持续追踪 Suricata EVE (`AZAZEL_EVE_PATH`，默认 `/var/log/suricata/eve.json`) 并发出标准化告警事件。 - Rust 核心转发至 Unix socket (`/run/azazel-edge/ai-bridge.sock`) 和/或 JSONL 日志。 2. **确定性评估** - NOC 评估器和 SOC 评估器在 `py/azazel_edge/evaluators/` 下实现。 - 动作仲裁器根据被否决的备选方案和决策追踪决定明确的动作。 3. **操作平面** - Flask 应用提供仪表盘 (`/`)、演示 (`/demo`)、运维工作区 (`/ops-comm`) 和 `/api/*`。 - 控制守护进程在 `/run/azazel-edge/control.sock` 暴露 Unix socket 控制平面。 4. **可选 AI 辅助平面** - AI 代理消费标准化事件/手动查询，并写入咨询/指标/审计 JSONL。 - Ollama 和 Mattermost 由可选的基于 compose 的运行时脚本进行配置。 ## 入口点与接口 ### 服务入口点 - Web 应用：`azazel_edge_web/app.py`（通过 `systemd/azazel-edge-web.service` 运行 gunicorn） - 控制守护进程：`py/azazel_edge_control/daemon.py`（`systemd/azazel-edge-control-daemon.service`） - AI 代理：`py/azazel_edge_ai/agent.py`（`systemd/azazel-edge-ai-agent.service`） - Rust 核心：`rust/azazel-edge-core/src/main.rs`（`systemd/azazel-edge-core.service`） - EPD 刷新计时器：`systemd/azazel-edge-epd-refresh.timer` ### Web 路由 - UI：`/`、`/demo`、`/ops-comm` - 健康检查：`/health`（无需 token） - CA 元数据/下载：`/api/certs/azazel-webui-local-ca/meta`、`/api/certs/azazel-webui-local-ca.crt` ### 主要 API 组 | 组 | 端点 | 需要认证 | |-------|-----------|---------------| | State | `GET /api/state`、`GET /api/state/stream` | 是 | | Control | `POST /api/mode`、`POST /api/action`、`/api/wifi/*`、`/api/portal-viewer*` | 是 | | SoT | `POST /api/clients/trust`、`PUT/PATCH /api/sot/devices` | 是 | | Dashboard | `GET /api/dashboard/*` | 是 | | Triage | `/api/triage/*` | 是 | | Runbooks | `GET /api/runbooks`、`POST /api/runbooks/propose`、`POST /api/runbooks/act` | 是 | | Demo | `/api/demo/*` | 是 | | AI | `POST /api/ai/ask`、`GET /api/ai/capabilities` | 是 | | Mattermost | `POST /api/mattermost/command`、`POST /api/mattermost/message` | Token | | Health | `GET /health` | 否 | | CA cert | `GET /api/certs/*` | 否 | ### Socket 接口 - 控制 socket：`/run/azazel-edge/control.sock` - AI 桥接 socket：`/run/azazel-edge/ai-bridge.sock` ### 认证行为 - 大多数 `/api/*` 端点都受 token 保护。 - 安装程序管理的运行时默认设置为失败关闭 (`AZAZEL_AUTH_FAIL_OPEN=0`)。 - 当 token 文件不存在时，由 `AZAZEL_AUTH_FAIL_OPEN` 控制传统的失败打开兼容性。 - 通过 `AZAZEL_WEB_TOKEN_FILE` 管理的默认 token 文件是 `/etc/azazel-edge/web_token.txt`。 ## 更新日志 查看 [`docs/CHANGELOG.md`](docs/CHANGELOG.md) 获取完整的实现历史和 PR 追溯信息。 ## 系统要求 ### 运行时包（由脚本安装） - Core/app 堆栈：`python3`、`python3-venv`、`network-manager`、`iw`、`dnsmasq`、`nginx`、`openssl`、`rustc`、`cargo` 及相关 Python 系统包 - Security 堆栈选项：`docker.io`、`suricata` - AI 运行时选项：`docker.io`、`qemu-user-static`、`binfmt-support`、`jq` ### Python 运行时依赖 来自 `requirements/runtime.txt`： - `Flask` - `gunicorn` - `rich` - `textual` - `Pillow` - `requests` - `PyYAML` ### 可选外部服务 - Ollama 容器 (`security/docker-compose.ollama.yml`) - Mattermost + PostgreSQL (`security/docker-compose.mattermost.yml`) - OpenCanary (`security/docker-compose.yml`) ## 安装与复现 ### 统一安装程序 ``` cd /home/azazel/Azazel-Edge sudo ENABLE_INTERNAL_NETWORK=1 \ ENABLE_APP_STACK=1 \ ENABLE_AI_RUNTIME=1 \ ENABLE_DEV_REMOTE_ACCESS=0 \ bash installer/internal/install_all.sh ``` 有关所有安装程序开关和运行时变量，请参见[配置](#configuration)。 ### 仅 App 堆栈 ``` sudo ENABLE_SERVICES=1 bash installer/internal/install_migrated_tools.sh ``` ### 仅 AI 运行时 ``` sudo ENABLE_OLLAMA=1 ENABLE_MATTERMOST=1 bash installer/internal/install_ai_runtime.sh ``` 安装结果（默认脚本）： - 运行时文件位于 `/opt/azazel-edge` - 启动器位于 `/usr/local/bin` - Systemd 单元已安装并可选择启用 ## 配置 ### 安装程序开关 - `ENABLE_INTERNAL_NETWORK=1|0` - `ENABLE_APP_STACK=1|0` - `ENABLE_AI_RUNTIME=1|0` - `ENABLE_DEV_REMOTE_ACCESS=1|0` - `ENABLE_RUST_CORE=1|0` ### 主要运行时配置文件 - `/etc/default/azazel-edge-web`（Web/Mattermost 相关环境变量） - `/etc/default/azazel-edge-security`（安全堆栈选项，如 `SURICATA_IFACE`） - `/etc/azazel-edge/first_minute.yaml`（控制标志，如 `suppress_auto_wifi`） ### 重要环境变量（部分） - Web 绑定：`AZAZEL_WEB_HOST`、`AZAZEL_WEB_PORT` - Rust 核心：`AZAZEL_EVE_PATH`、`AZAZEL_AI_SOCKET`、`AZAZEL_NORMALIZED_EVENT_LOG`、`AZAZEL_DEFENSE_ENFORCE` - AI 代理：`AZAZEL_OLLAMA_ENDPOINT`、`AZAZEL_LLM_MODEL_PRIMARY`、`AZAZEL_LLM_MODEL_DEGRADED` - Mattermost 命令触发器/token：`AZAZEL_MATTERMOST_COMMAND_TRIGGER`、`AZAZEL_MATTERMOST_COMMAND_TOKEN_FILE` - Runbook 受控执行门：`AZAZEL_RUNBOOK_ENABLE_CONTROLLED_EXEC` - Topo-Lite/NOC 监控范围： - `AZAZEL_NOC_MONITOR_SCOPE`（默认为 `internal` 或 `external`） - `AZAZEL_INTERNAL_BRIDGE_IF`（默认为 `br0`） - `AZAZEL_MANAGED_CLIENT_CIDRS`（默认为 `172.16.0.0/24`） - `AZAZEL_INTERNAL_MONITOR_TARGET`（默认为 `172.16.0.254`） - `AZAZEL_NOC_EXTRA_INTERFACES`（用于多网段探测的可选 CSV） - Topo-Lite 合成种子模式： - `AZAZEL_TOPOLITE_SEED_MODE_PATH`（模式状态文件，默认 `/run/azazel-edge/topolite_seed_mode.json`） - API：带有 `mode=live|synthetic` 和可选 `seed_id` 的 `POST /api/topolite/seed-mode` ### Token 认证 - API token 可以通过请求头 `X-AZAZEL-TOKEN`（或 `X-Auth-Token`）或 `?token=` 提供。 - 如果不存在 token 文件，受保护的端点将实际上处于开放状态。 ## 用法 ### 服务状态 ``` sudo systemctl status \ azazel-edge-control-daemon \ azazel-edge-web \ azazel-edge-ai-agent \ azazel-edge-core ``` ### 访问端点（默认安装程序假设） - Web 后端：`http://127.0.0.1:8084/` - 如果已安装内部网络 + HTTPS 代理：`https://172.16.0.254/` - Mattermost（如果已启用）：`http://172.16.0.254:8065/` ### API 调用示例 ``` TOKEN="$(cat ~/.azazel-edge/web_token.txt)" curl -sS -H "X-AZAZEL-TOKEN: ${TOKEN}" http://127.0.0.1:8084/api/state | jq . ``` ### SoT 设备 API 契约 - `PUT /api/sot/devices` - 替换 SoT 中的整个 `devices` 数组。 - 请求体：`{"devices": []}`。 - `PATCH /api/sot/devices` - 仅通过 `id` 进行合并/upsert 语义（无删除行为）。 - 现有的设备字段将被保留，除非被 payload 中的字段覆盖。 - 请求体：`{"devices": []}`。 - 以上两个端点： - 都需要 token 认证（`@require_token()`）。 - 通过 `SoTConfig.from_dict` 验证生成的完整 SoT。 - 向 `AZAZEL_SOT_AUDIT_LOG` 追加审计记录，包括 `actor`（首选 `X-AZAZEL-ACTOR`，其次是调用者地址）。 - 成功更新后通过 `refresh` 触发重新评估。 ### 确定性演示放 ``` bin/azazel-edge-demo list bin/azazel-edge-demo run mixed_correlation_demo ``` ### Runbook 代理 CLI ``` python3 py/azazel_edge_runbook_broker.py list python3 py/azazel_edge_runbook_broker.py show rb.noc.service.status.check python3 py/azazel_edge_runbook_broker.py propose --question "Wi-Fi intermittent disconnects" ``` ## 开发 ### 本地设置 ``` python3 -m venv .venv . .venv/bin/activate pip install -U pip wheel setuptools pip install -r requirements/runtime.txt ``` ### 本地运行（不带 systemd） ``` PYTHONPATH=. python3 azazel_edge_web/app.py PYTHONPATH=. python3 py/azazel_edge_control/daemon.py PYTHONPATH=. python3 py/azazel_edge_ai/agent.py ``` 注意： - 多项测试将 `azazel_edge_web` 作为顶级包导入，因此在代码库布局中需要使用 `PYTHONPATH=.`。 - `py/azazel_edge_status.py` 是一个持续渲染器（按 Ctrl-C 停止），而不是典型的 `--help` CLI。 ## 测试 运行： ``` PYTHONPATH=. .venv/bin/pytest -q ``` 最新验证结果（2026-05-11）：**224 项通过，16 项子测试通过** ## 代码库布局 | 路径 | 职责 | |---|---| | `py/azazel_edge/` | Evidence Plane、评估器、仲裁器、审计、SoT、分流、演示以及研究/运行时扩展 | | `py/azazel_edge_control/` | 控制守护进程和动作处理器 | | `py/azazel_edge_ai/` | AI 代理集成和 M.I.O. 辅助路径 | | `azazel_edge_web/` | Flask 后端、仪表盘、ops-comm UI | | `rust/azazel-edge-core/` | Rust 防御核心 | | `runbooks/` | Runbook 注册表 | | `systemd/` | 服务和计时器 | | `security/` | Compose 堆栈和安全侧资产 | | `installer/` | 统一安装程序和分阶段安装脚本 | | `docs/` | 公共架构、AI 操作、角色和演示文档 | | `tests/` | 单元和回归测试覆盖 | ## 部署 ### 包含的 Systemd 单元 - `azazel-edge-control-daemon.service` - `azazel-edge-web.service` - `azazel-edge-ai-agent.service` - `azazel-edge-core.service` - `azazel-edge-epd-refresh.service` - `azazel-edge-epd-refresh.timer` - `azazel-edge-opencanary.service` - `azazel-edge-suricata.service` ### Security/AI 堆栈部署 - Security 堆栈安装：`installer/internal/install_security_stack.sh` - AI 运行时安装：`installer/internal/install_ai_runtime.sh` - 位于 `security/` 下的 compose 资产 ### 运行时日志/产物（部分） - `/var/log/azazel-edge/normalized-events.jsonl` - `/var/log/azazel-edge/ai-events.jsonl` - `/var/log/azazel-edge/ai-llm.jsonl` - `/var/log/azazel-edge/triage-audit.jsonl` - `/run/azazel-edge/ui_snapshot.json` ## 文档 ### 面向操作员 | 文档 | 描述 | |----------|-------------| | [AI 操作指南](docs/AI_OPERATION_GUIDE.md) | LLM 阈值、日常检查、事件响应 | | [演示指南](docs/DEMO_GUIDE.md) | 确定性演示重放演练 | ### 面向开发者 | 文档 | 描述 | |----------|-------------| | [P0 运行时架构](docs/P0_RUNTIME_ARCHITECTURE.md) | Pipeline、模块和约束 | | [AI 代理构建与操作细节](docs/AI_AGENT_BUILD_AND_OPERATION_DETAIL.md) | AI 代理内部机制 | | [M.I.O. 角色设定](docs/MIO_PERSONA_PROFILE.md) | 操作员角色设计规范 | | [演示后主线集成边界 (#104)](docs/POST_DEMO_MAIN_INTEGRATION_104.md) | 何为主线，何为仅展示功能 | | [演示后 Socket 权限模型 (#105)](docs/POST_DEMO_SOCKET_PERMISSION_MODEL_105.md) | Unix socket 权限决策 | | [下一阶段开发执行索引 2026Q2](docs/NEXT_DEVELOPMENT_EXECUTION_INDEX_2026Q2.md) | 路线图和执行计划 | ### 面向贡献者（AI 代理和人类） | 文档 | 描述 | |----------|-------------| | [AGENTS.md](AGENTS.md) | AI 代理工作章程 — 在进行任何更改之前必读 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 人类贡献者指南（分支、PR、测试规则） | | [更新日志](docs/CHANGELOG.md) | PR 和功能追溯历史 | ## 限制与已知问题 ### 设计约束（有意为之） - Rust 执行路径默认处于非活动状态： - `systemd/azazel-edge-core.service` 中的 `AZAZEL_DEFENSE_ENFORCE=false` - Rust 核心中的 `maybe_enforce()` 是一个占位符，等待空运行验证 - AI 辅助是可选且受限的 — 确定性路径无需 Ollama 即可工作 - 不建议在共存部署中使用 2b 参数以上的 Ollama 模型 - 测试数量和 runbook 数量在每次发布时都会进行验证；有关当前状态，请参见 CI 结果。 ### 已知缺陷 - `python3 py/azazel_edge_epd.py --help` 会因 `ValueError: incomplete format` 而失败 ### 待办工作项 有关当前列表，请参见 [GitHub Issues](https://github.com/01rabbit/Azazel-Edge/issues)。 截至 2026-05-11 的优先事项： - #140 Epic：Azazel-Topo-Lite MVP *(P0)* - #173 [Topo-Lite] 默认监控范围限定为内部网络 (br0/172.16.0.0/24) *(P0)* - #172 [Topo-Lite] 具有严格实时证据分离的合成种子模式 *(P0)* - #174 [Topo-Lite] 左侧边栏集成和单屏可视化分流 UI *(P0)* ## 当前状态 - 最近合并的 PR 包括 #95、#94、#88、#87、#86（UI、NOC 运行时集成、auth/i18n、SOC 成熟度）。 - 该代码库目前包含 **48** 个 Python 测试模块和 **15** 个 runbook YAML 定义。 - 可用的确定性演示场景：`mixed_correlation_demo`、`noc_degraded_demo`、`soc_redirect_demo`。 ## 许可证 本代码库基于 MIT 许可证授权。详情请参见 [LICENSE](LICENSE)。

标签：AI风险缓解, API, DLL 劫持, Flask, Google搜索, HTTP/HTTPS抓包, IP 地址批量处理, LLM评估, Mattermost, Metaprompt, NOC, Ollama, PB级数据处理, Python, Raspberry Pi, Runbook, Rust, TCP SYN 扫描, Web UI, 内存执行, 可视化界面, 大语言模型, 安全事件分诊, 安全运维, 库, 应急响应, 开源, 态势感知, 无后门, 无网络环境, 本地AI, 现场安全, 确定性分析, 离线部署, 网关, 网络安全, 网络流量审计, 请求拦截, 轻量级网关, 边缘计算, 逆向工具, 隐私保护