arn-c0de/GDEF-L1NK

# GDEF-L1NK      

GDEF-L1NK 是 **GDEF 套件** 的一个模块化网络智能组件。它捕获授权的网络流量，丰富观察到的端点，并在交互式 3D 地球上可视化实时连接，用于防御分析、实验室工作和内部安全操作。 它设计为一个独立的模块，现在可以独立运行，并随着时间的推移集成到更大的 GDEF 套件工作流程中。 ## 导航 - [功能](#features) - [要求](#requirements) - [快速入门](#quick-start) - [Docker (Linux)](#docker-linux--the-standard-way-to-run-it) - [Windows](#windows-recommended) - [服务命令](#service-commands-linux--docker) - [开发（实时代码重新加载）](#development-live-code-reload) - [数据库（PostgreSQL）](#database-postgresql) - [多设备监控（传感器）](#multi-device-monitoring-sensors) - [仪表板覆盖选项卡](#dashboard-overlay-tabs) - [FritzDump 模块](#fritzdump-module-capture-from-pcap-files) - [安全与隐私](#security--privacy) - [安全环境变量](#security-environment-variables) - [Python 工作流程](#python-workflow) - [配置](#configuration) - [项目结构](#project-structure) - [安全通知](#security-notice) - [故障排除](#troubleshooting) - [已知问题](#known-issues) - [许可证](#license) - [作者](#author) ## 功能 - **实时数据包可见性**：使用 Scapy 捕获 TCP、UDP 和 ICMP 流量。 - **3D 地理可视化**：在交互式地球仪上显示外部连接。 - **本地网络发现**：检测本地设备和 mDNS 活动。 - **威胁丰富**：使用 FireHOL 风格的阻止列表数据提供基本声誉上下文。 - **多设备聚合**：作为远程传感器的中心枢纽——每个传感器都是一个有名称、有颜色的来源——具有加密的推送摄取和每个设备的统计信息。 - **操作控制**：支持 TCP/UDP 过滤器、本地/外部切换、固定 IP 和实时统计信息。 - **统一仪表板面板**：一个单选项卡覆盖（**统计信息 · 连接 · 设备 · 设置**）用于所有图表、连接表、设备管理和配置——通过 ⚙（设置）或 📊（统计信息）按钮打开。 - **套件就绪结构**：将运行时配置、数据集、脚本和 Web 资产分离，以便模块化 GDEF 套件集成。 ## 要求 - Python 3.11+ - `uv` 推荐用于 Python 依赖项管理 - 管理员/根权限用于数据包捕获 - Linux/macOS：根据平台要求安装 `libpcap`/`tcpdump` 软件包 - Windows：Npcap 或 WinPcap ## 快速入门 GDEF-L1NK 由基于令牌的登录保护。访问令牌在首次启动时生成，并安全地存储在 `database/access_token.txt` 中。 ### Docker (Linux — 标准运行方式) `run.sh` 是 Docker Compose 的一个薄包装器：嗅探器/网络应用程序和 PostgreSQL 数据库作为容器运行。应用程序容器使用 **主机网络** 加上 `NET_RAW`/`NET_ADMIN` 功能，因此 Scapy 可以从物理接口捕获——不需要主机级别的 `setcap`。需要 [Docker Engine + Compose 插件](https://docs.docker.com/engine/install/). ``` cp .env.example .env # 编辑 .env：设置 NETWORK_INTERFACE（例如 eth0/enp3s0）和强大的 POSTGRES_PASSWORD ./run.sh start # build (if needed) + start the stack ``` - **仪表板**：`http://localhost:8000` - **令牌**：`./run.sh token`（应用程序将其写入挂载的 `database/` 文件夹；`cat database/access_token.txt` 也行）。在 `.env` 中设置固定的 `ACCESS_TOKEN` 以保持其在重启之间稳定。 - **数据**：PostgreSQL 数据持久化在 `pgdata` 命名卷中；GeoIP `.mmdb` 数据集和生成的密钥保留在挂载的 `database/` 文件夹中。 ### Windows（推荐） 1. **安装 Npcap**：从 [npcap.com](https://npcap.com/）下载并安装。选择“安装 Npcap 与 WinPcap API 兼容模式”。 2. **运行启动器**：右键单击 `start.bat` 并选择**“以管理员身份运行”**。 * 脚本将自动强化 `database/` 文件夹的权限（只有你和管理员才能访问）。 * 它将使用 `uv`（或 `pip` 降级）同步依赖项。 3. **访问仪表板**：打开 `http://localhost:8000`。 4. **登录**：在 `database/access_token.txt` 中找到您的访问令牌。 ## 服务命令（Linux — Docker） `run.sh` 驱动 Docker Compose 栈： ``` ./run.sh start # build (if needed) + start app + PostgreSQL (baked image) ./run.sh dev # start with source bind-mounted (live frontend, fast backend reload) ./run.sh stop # stop and remove the containers ./run.sh restart # rebuild changed parts (frontend/backend) + restart — picks up code edits ./run.sh status # container status (docker compose ps) ./run.sh logs # follow the app logs ./run.sh build # (re)build the app image ./run.sh rebuild # rebuild from scratch and start ./run.sh token # print the dashboard access token ``` ### 开发（实时代码重新加载） `./run.sh dev` 启动相同的堆栈，但通过 `docker-compose.dev.yml` 将源（`app.py`、`db.py`、`static/`、`templates/`）绑定到应用程序容器中，因此编辑不需要重新构建镜像： - **前端**（`static/`、`templates/`）：在浏览器刷新时立即可见——无需重启。 - **后端**（`app.py`、`db.py`）：运行 `./run.sh restart` 以快速重启进程（无需构建镜像）。 Dev 模式通过 `.dev-mode` 标记文件记住，因此 `restart`/`logs`/`status` 保持挂载。使用 `./run.sh start`（或使用 `./run.sh stop` 完全退出 dev 模式）切换回类似生产的烘焙镜像。 如果您的用户不在 `docker` 组中，请使用 `sudo`。捕获通过容器的 `NET_RAW`/`NET_ADMIN` 功能进行，因此不需要主机 `setcap`（并且 `setcap` 在 `nosuid`/`ecryptfs` 挂载上始终被忽略）。 ## 数据库（PostgreSQL） GDEF-L1NK 将其实时 IP 表、固定 IP、MAC-供应商缓存、设置和威胁列表存储在 **PostgreSQL** 中（替换了以前的嵌入式 SQLite 数据库）。`database/datasets/` 中的 GeoIP `.mmdb` 数据集保持基于文件的格式，不受影响。 使用 Docker 堆栈，`db` 服务自动提供 PostgreSQL——无需安装。它默认在 `127.0.0.1` 上发布到端口 **55432**（通过 `.env` 中的 `POSTGRES_PORT` 设置），以避免与系统 PostgreSQL 在 5432 上的冲突。 要在外部 Docker 之外针对您自己的 PostgreSQL 运行应用程序，请通过以下环境变量配置连接： | 变量 | 默认 | 目的 | | --- | --- | --- | | `DATABASE_URL` | *(未设置)* | 完整的 libpq URL，例如 `postgresql://user:pass@127.0.0.1:5432/gdef_l1nk`。覆盖下面的 `PG*` 变量。 | | `PGHOST` | `127.0.0.1` | 数据库主机 | | `PGPORT` | `5432` | 数据库端口 | | `PGDATABASE` | `gdef_l1nk` | 数据库名 | | `PGUSER` | `gdef_l1nk` | 数据库用户 | | `PGPASSWORD` | *(必需)* | 数据库密码——**没有内置默认值**。应用程序拒绝启动，除非设置了此变量或 `DATABASE_URL`；仅将此变量设置为空值（`PGPASSWORD=`）以选择本地 `trust`/`peer` 认证，其中 PostgreSQL 本身不需要密码。 | | `DB_POOL_SIZE` | `10` | 每个进程的最大连接池大小 | | `DB_CONNECT_TIMEOUT` | `15` | 等待连接的秒数 | | `NETWORK_INTERFACE` | *(从配置)* | 捕获接口；覆盖 `database/backend_conf.json`（在容器中很有用） | 应用程序在启动时等待 PostgreSQL 接受连接，并自动创建其模式（`init_db`）。 ## 多设备监控（传感器） GDEF-L1NK 可以作为一个 **中心枢纽**，同时聚合来自多个捕获 **设备** 的流量——您的本地主机以及任何数量的远程 **传感器**。每个设备都是地球仪上自己的有名称、有颜色的来源，因此您可以一目了然地看到哪些连接属于哪个机器。 - **注册设备**：在仪表板侧边栏中，**设备 → + 添加设备**。 枢纽发出 `DEVICE_ID` 和一个一次性 `DEVICE_KEY`（仅显示一次）。 - **在目标服务器上安装传感器**：请参阅 [`sensor/README.md`](sensor/README.md）。 传感器在本地捕获并将连接推送到枢纽，**使用设备密钥进行 gzip 压缩和 Fernet 加密**，即使在 LAN 上的纯 HTTP 上也是机密和重放保护的。 - **颜色和过滤**：在威胁和设备之间切换地球仪颜色，显示/隐藏单个设备，并将统计信息面板的范围缩小到单个设备或所有设备。 过滤器和设备设置在页面重新加载之间持久化。 - **启动/停止（每个设备）**：每个设备行都有一个 **▶ 启动 / ■ 停止** 按钮（其 `enabled` 标志）。在设备停止时，**其所有流量都不会被处理**——甚至不在后台——并且它将从地球仪和所有列表中消失。再次启动它将立即重新获取和重新绘制其数据。即使是内置的 `local` 捕获也可以停止。 设备通过其 `DEVICE_ID` 进行识别，**而不是通过 IP**——因此位于同一家庭路由器后面（一个共享的公共 IP）的多个传感器保持不同。枢纽自己的捕获是内置的 `local` 设备；其显示名称来自 `HUB_DEVICE_NAME`（默认为主机名）。 枢纽公开 `POST /api/ingest` 用于传感器（按设备密钥身份验证，速率限制，大小限制）和会话身份验证的设备 API (`/api/devices...`)。摄取限制可以通过 `INGEST_MAX_AGE`、`INGEST_MAX_EVENTS`、`INGEST_MAX_BODY` 和 `INGEST_RATE_LIMIT` 进行调整。 ### 仪表板覆盖选项卡 通过 **⚙ 设置** 按钮或 **📊 统计信息** 按钮打开仪表板覆盖。它有四个选项卡： - **统计信息**：实时计数器、协议/威胁图表、顶级说话者、最新连接、未知 IP 和可疑目标。使用页眉中的 **设备** 选择器查看所有流量或仅查看一个设备。 - **连接**：可排序的连接表，包括 IP、LAN 设备、国家/地区、组织、协议、数据包计数、威胁级别和最后看到的时间。相同的 **设备** 选择器将范围缩小到表。 - **设备**：启用、停止、重命名、着色、过滤、添加、旋转或删除捕获设备。 - **设置**：显示选项、组织列表、IP 标签、CSV 导出和注销。 在 **设备** 选项卡中，每行有两个不同的控件： - 左侧的复选框仅显示/隐藏该设备在地球仪和列表中的内容。它是一个显示过滤器。 - **▶ 启动 / ■ 停止** 控制枢纽是否处理该设备的流量。停止的设备不会在后台处理，并且会从实时视图中消失。 常见的设备行： - **local** / 您的枢纽设备：这是枢纽自己的网络适配器捕获。适配器使用 `NETWORK_INTERFACE` 在根 `.env` 或 `database/backend_conf.json` 中选择。启动它以从该适配器捕获；如果您只想使用传感器/FritzDump 流量，请停止它。 - **FritzBox** / `module`：这是 FritzDump pcap 源。它仅在模块启用后出现。配置 `modules/FritzDump/.env`，然后在 **设备** 中按下 **▶ Start** 在 FritzBox 行上。启动将启动 FritzDump 工作进程，并开始跟踪 `modules/FritzDump/dumps/`；停止将终止工作进程并清除其当前数据。 - **sensor** 设备：使用 **+ 添加设备** 注册的远程主机。启动/停止接受或拒绝其加密的摄取批次。 ### FritzDump 模块（从 pcap 文件捕获） 除了从 NIC 进行实时捕获之外，枢纽还可以使用 **FritzDump** 模块作为捕获 *源*：而不是嗅探接口，它从您的 **FRITZ!Box** 捕获流量，并将其馈送到与所有其他内容相同的地球仪/统计信息中。 这使得没有可用的捕获接口（或没有 `CAP_NET_RAW`）的枢纽仍然可以看到真实流量——并且可以路由器后面的每个设备，而不仅仅是运行枢纽的主机。 **工作原理**： ``` FRITZ!Box ──(login + capture)──> modules/FritzDump/run.sh ──> dumps/*.pcap │ tail dashboard <── globe/stats <── process_packets <── hub reader ──┘ ``` 1. 您在仪表板中按下 **▶ Start** 在 FritzBox 设备上。 2. 枢纽启动 FritzDump 工作进程（`modules/FritzDump/run.sh`），它登录到盒子上，并将捕获流式传输到 `modules/FritzDump/dumps/` 下的 pcap 文件中。 3. 枢纽 **跟踪这些 pcap** 并解析每个数据包（它理解标准 libpcap 和 FRITZ!Box “修改”的 pcap 变体，魔法 `0xa1b2cd34`），将每个连接标记为 FritzBox 设备。 4. 地理/威胁/供应商丰富在中心发生，就像实时捕获一样，并且连接出现在地球仪和统计信息中。 因为 FRITZ!Box 看到整个 LAN，每个外部连接还记录其 **本地对等方**——*您的网络中的哪些设备在与该外部 IP 交谈*。单个外部服务器通常由多个本地主机同时访问（例如，`192.168.178.100`、`.90`、`.44`），因此仪表板收集 **所有** 这些。LAN 设备（以下称为“LAN 设备”）显示： - 在实时 **连接列表** 中内联（`→ 192.168.178.100, …`）， - 在点的详细面板中作为 **“LAN 设备”**，以及 - 在连接选项卡中作为可排序的 **“LAN 设备”** 列。 您可以在 **设置 → IP 标签** 下为您的自己的主机分配友好的名称（每行一个 `IP Name`，例如 `192.168.178.100 PC-E1`）。名称存储为简单的 JSON 映射（`database/ip_labels.json`），并在 LAN 设备列出的任何地方显示为 `PC-E1 (192.168.178.100)`。 **停止** 终止工作进程并清除其数据。该模块只是另一个设备，因此它遵守与任何传感器相同的颜色、可见性和启动/停止。 **该模块默认关闭**——如果您不使用它，您永远不会看到该设备，并且不会运行任何额外的内容。通过 Docker 打开它： ``` ./run.sh fritzdump on # bind-mounts the module, enables it, and recreates the app container ./run.sh fritzdump off # turn it back off any time (also applies immediately) ``` `fritzdump on/off` **重新创建应用程序容器本身**（一个普通的 `restart` 不会选择新的挂载/环境）。在外部 Docker 之外，只需设置 `FRITZDUMP_ENABLED=1`。 在按下 Start 之前，将 FRITZ!Box 登录数据放入模块自己的 env 文件中。这不是 **根项目 .env**；FritzDump 读取： ``` modules/FritzDump/.env ``` 该模块有自己的详细 README 在这里： [`modules/FritzDump/README.md`](modules/FritzDump/README.md）。 从模板创建它并限制权限： ``` cd modules/FritzDump cp .env.example .env chmod 600 .env ``` 然后编辑 `modules/FritzDump/.env`： ``` FRITZ_HOST=192.168.178.1 FRITZ_USER=fritz-capture-user FRITZ_PW=your-fritzbox-password FRITZ_HTTPS=true # 当 FRITZ_HTTPS=true 时推荐：固定 FRITZ!Box 证书。 # FRITZ_CACERT=fritzbox.pem ``` 如果可能，请使用专用 FRITZ!Box 用户。它只需要 **“FRITZ!Box 设置”** 权限。如果您的盒子上使用仅密码登录而没有用户名，请设置 `

标签：3D 地图, Docker, Flask, FritzDump, GDEF 套件, PostgreSQL, Python, Python 工作流, 仪表盘, 传感器监控, 内部安全, 威胁分析, 安全操作, 安全警告, 安全防御评估, 安全隐私, 开发环境, 故障排除, 无后门, 服务命令, 模块化, 环境变量, 端点检测, 系统分析, 网络分析, 网络安全, 网络流量可视化, 网络监控工具, 自动化侦查工具, 请求拦截, 逆向工具, 配置, 隐私保护, 项目结构