stariik/NetLens

# NetLens NetLens 是一个被动、离线的网络取证和威胁狩猎后端，适用于经过授权的 packet capture。它会验证上传的 PCAP/PCAPNG 文件，将 Zeek 和 Suricata 的 输出标准化为统一的事件模型，应用可解释的启发式规则，并通过 FastAPI API 公开调查、 发现、分析视图和报告。 ## 项目状态 本仓库是一个**开发中的后端**，而非生产就绪的端到端 应用程序。源代码目前包含大量的核心和 API 功能，但 尚未包含目标架构中所描述的完整产品。 | 领域 | 当前状态 | | --- | --- | | 共享核心 | 包含模型、配置、存储、PCAP 验证、解析器、查询、分析和报告渲染。 | | API | 包含用于身份验证、调查、证据、事件、发现、视图、报告、保存的过滤器和系统健康状态的 FastAPI 路由。 | | Worker | 包含沙盒工具运行器和批量摄取；但缺少队列消费者和端到端任务编排。 | | Web UI | 尚未实现；不存在任何前端文件。 | | 部署 | 此快照中不包含 Compose 文件、Dockerfile、数据库迁移和生产部署资产。 | | 测试 | 98 个核心测试在本地通过；API 和 worker 测试目录目前不包含测试用例。 | | 质量门禁 | 已配置 Ruff 和严格的 mypy，但当前源代码仍存在未解决的 lint 和类型检查问题。 | 由于缺少 worker 入口点，API 可以接受上传并将其排入队列，但仅凭 此仓库无法端到端地完成分析任务。 ## 已实现的功能 - 使用魔数而非文件扩展名对 PCAP/PCAPNG 进行流式验证 - 增量执行上传大小限制和单次扫描的 SHA-256 哈希校验 - 基于 UUID 的证据命名、路径包含检查、严格的文件权限，以及 对未完成上传的清理 - 异步 SQLAlchemy 模型，支持部署时使用 PostgreSQL，本地工作时使用 SQLite - Argon2 密码哈希、JWT bearer 身份验证、所有权检查、审计记录，以及 由 Redis 支持的速率限制（带有内存回退机制） - Zeek TSV/JSON 和 Suricata EVE 解析器，带有共享的标准化事件 schema - 用于时间线、主机、通信图、DNS、TLS 和概览数据的查询服务 - 十种可解释的启发式规则，涵盖信标活动、罕见目标、可疑的 DNS 形态、 大规模出站传输、连接失败、延迟目标、非常见端口和 证书有效性 - 独立的 Markdown 和 HTML 调查报告 - Docker 模式下的运行器参数：拒绝网络访问、丢弃 capabilities、使用只读 文件系统、以非 root 用户身份运行，以及应用 CPU、内存、PID 和挂钟时间限制 这些发现被有意设定为需要调查的证据，而非最终结论。每条启发式规则 都包含其基本原理、代入计算、可能的良性解释、验证 步骤以及所使用的阈值。 ## 处理模型 ``` flowchart LR A[Authorized PCAP/PCAPNG] --> B[Stream validation + SHA-256] B --> C[UUID evidence storage] C --> D[Isolated Zeek / Suricata run] D --> E[Defensive parsers] E --> F[(Normalized events)] F --> G[Explainable heuristics] F --> H[Analysis views] G --> I[Findings + evidence links] H --> J[FastAPI] I --> J J --> K[HTML / Markdown reports] ``` 上面展示的运行器、解析器、分析、查询和报告组件均已存在。但将 它们连接到完整的队列 worker 生命周期中仍有待实现。 ## 仓库布局 ``` NetLens/ ├── apps/ │ ├── api/ FastAPI application │ └── worker/ Tool runners and ingestion primitives ├── packages/ │ └── netlens-core/ Shared domain, data, parser, analytics, and reporting code ├── docs/ API, event-schema, and worker-isolation documentation ├── ARCHITECTURE.md Target system design and design decisions ├── THREAT_MODEL.md Trust boundaries, risks, and controls ├── TASKS.md Original target implementation plan ├── .env.example Configuration reference └── pyproject.toml Workspace lint, type-check, test, and coverage settings ``` ## 本地设置 以下设置针对 SQLite 运行已实现的 API。这对于 API 和核心 开发很有用；但它不提供缺失的后台 worker 编排。 ### 前置条件 - Python 3.11 或更新版本 - 进行本地 API 工作时，Redis 是可选的；如果没有它，就绪状态将报告为降级，并且 排队任务仅由进程本地的回退机制记录 - 只有在开发分析运行器时才需要 Docker 以及 Zeek/Suricata 镜像 ### 1. 创建环境并安装软件包 ``` python -m venv .venv ``` PowerShell: ``` .\.venv\Scripts\Activate.ps1 ``` macOS/Linux: ``` source .venv/bin/activate ``` 然后安装各个可编辑的工作区软件包： ``` python -m pip install --upgrade pip python -m pip install -e "./packages/netlens-core[dev]" python -m pip install -e "./apps/api[dev]" python -m pip install -e "./apps/worker[dev]" ``` ### 2. 配置本地开发环境 将 `.env.example` 复制到 `.env`，然后针对仅 API 的 SQLite 设置使用以下值： ``` NETLENS_ENV=development NETLENS_DATABASE_URL=sqlite+aiosqlite:///./data/netlens.db NETLENS_REDIS_URL=redis://localhost:6379/0 NETLENS_EVIDENCE_DIR=./data/evidence NETLENS_SCRATCH_DIR=./data/scratch NETLENS_ZEEK_EXECUTION_MODE=disabled NETLENS_SURICATA_ENABLED=false ``` `.env.example` 中的开发密钥是故意设计为不安全的，并且当配置为 `NETLENS_ENV=production` 时会被拒绝。 ### 3. 创建本地 schema 首先创建 `data` 目录： ``` New-Item -ItemType Directory -Force data | Out-Null ``` 在 macOS/Linux 上，使用 `mkdir -p data`。然后创建 schema： ``` python -c "import asyncio; from netlens_core.db import create_all; asyncio.run(create_all())" ``` `create_all()` 适用于测试和本地开发。生产环境的迁移尚未 添加到仓库中。 ### 4. 启动 API ``` python -m uvicorn netlens_api.main:app --reload ``` 常用 URL： - API 文档： - OpenAPI schema： - 存活状态： - 依赖就绪状态： 带有版本号的 API 根路径为 `/api/v1`。 ## 证据上传契约 已实现的上传端点将捕获文件作为原始请求体进行消费。这避免了 在应用程序执行其字节限制之前产生无限制的 multipart 缓存。 ``` curl -X POST "http://localhost:8000/api/v1/investigations/INVESTIGATION_ID/evidence" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/octet-stream" \ -H "X-Filename: capture.pcap" \ --data-binary "@capture.pcap" ``` 原始名称仅用于显示。它会被净化处理，绝不会被用作 文件系统路径或进程参数。响应为 `202 Accepted`；完成排队的分析 需要目前尚未提供的 worker 编排。 ## 开发检查 ``` python -m pytest python -m ruff format --check . python -m ruff check . python -m mypy ``` 在仓库创建时，`pytest` 报告 `98 passed, 1 skipped`。Ruff 和 mypy 作为 预期的质量门禁被包含在内，但目前报告的是预先存在的问题；请参阅 上面的项目状态表。 ## 安全模型 上传的捕获文件和工具输出是受攻击者影响的数据。因此，该设计 假设原生协议解析器可能会被攻破，并将重点放在隔离控制上： - 证据以只读方式作为单个文件挂载。 - 分析容器使用 `--network none`，并且不接收任何应用程序凭证。 - 容器以非 root 身份运行，丢弃所有 capabilities，并启用 `no-new-privileges`。 - Root 文件系统是只读的；可写的输出是临时的且仅限于任务范围。 - 工具进程受到资源上限和严格超时的限制。 - 工具输出经过防御性解析，并作为数据渲染，而非可执行的标记。 在扩展捕获流水线之前，请阅读完整的[威胁模型](./THREAT_MODEL.md)和 [Worker 隔离规则](./docs/WORKER_ISOLATION.md)。 ## 文档 - [架构](./ARCHITECTURE.md) — 目标架构和设计决策 - [威胁模型](./THREAT_MODEL.md) — 信任边界、STRIDE 分析和残余风险 - [API 契约](./docs/API_CONTRACT.md) — 端点约定和资源模型 - [标准化事件 schema](./docs/EVENT_SCHEMA.md) — 来源、字段、映射和严重性 - [Worker 隔离](./docs/WORKER_ISOLATION.md) — 进程隔离和文件生命周期 - [实施计划](./TASKS.md) — 最初的目标计划；并非当前的完成记录 部分设计文档描述了此快照中尚未提供的计划组件。 本 README 中的项目状态部分是当前实现的真实来源。 ## 负责任的使用 仅分析您有权拥有和检查的捕获文件。Packet capture 可能包含 凭证、个人数据、内部地址和其他敏感信息。将证据排除在 版本控制之外；默认情况下，仓库会忽略常见的捕获文件扩展名以及 `data/`、 `evidence/` 和 `scratch/` 目录。 ## 贡献 在提交更改之前，请保持被动/离线的范围边界完整，为新 行为添加测试，并运行上述开发检查。最高优先级的缺失部分是 worker 编排器、API 和 worker 的集成测试、迁移、部署资产以及 前端。 ## 许可证 尚未选择或包含任何许可证。在仓库所有者添加许可证之前，不得 分发或重复使用此代码。

标签：AV绕过, FastAPI, IP 地址批量处理, Metaprompt, PB级数据处理, 后端开发, 安全运维, 搜索引擎查询, 测试用例, 请求拦截, 逆向工具, 防御绕过