SeifMoussa/offline-network-packet-analyzer-lab

# 离线网络数据包分析器实验室 [](https://github.com/SeifMoussa/offline-network-packet-analyzer-lab/actions/workflows/ci.yml) [](https://github.com/SeifMoussa/offline-network-packet-analyzer-lab/actions/workflows/codeql.yml) [](https://github.com/SeifMoussa/offline-network-packet-analyzer-lab/blob/main/LICENSE) 离线网络数据包分析器实验室是一个防御性的、仅限离线的网络安全作品集项目。它分析本地合成数据包/事件日志、测试中手工制作的合成字节夹具、流摘要、检测规则、风险评分、脱敏证据以及 Markdown/JSON 报告。 这不是一个实时的嗅探器。它不捕获数据包，不检查网络接口，不解析 PCAP 文件，不需要 sudo/root 权限，不使用原始套接字或 AF_PACKET，不使用 Scapy，也不提取凭证。它不能替代生产环境的 IDS 或 NDR。 CI/CodeQL 已在本地配置，但尚未通过 GitHub 验证。该仓库尚未发布，也没有创建任何标签或发布版本。 ## 目标岗位 本项目旨在方便以下岗位人员进行代码审查： - SOC Analyst - Network Security Analyst - Detection Engineer - Security Engineer - Incident Response 实习生 ## 展示内容 - 无需实时流量采集的防御性数据包分析思维 - 协议头解析基础知识 - 严格的本地文件加载和样本验证 - 基于归一化事件的流和协议摘要 - 基于 YAML 的检测规则和警报分诊 - 确定性的风险评分 - 仅使用安全合成标记的敏感标记脱敏 - 适合作品集审查的 Markdown 和 JSON 报告 - Pytest、Ruff、本地文档检查、GitHub Actions、CodeQL 和 Dependabot 配置 ## 功能 - 本地 JSON、CSV 和文本合成样本加载器 - 验证允许的 IP 范围、域名、文件类型和样本大小 - Ethernet、IPv4、TCP 元数据和 UDP 元数据解析器 - 对畸形记录和畸形字节夹具的受控处理 - 流摘要、协议计数、主要来源、主要目标和主要通信方 - 基于 YAML 的合成检测规则 - 包含严重性、置信度、得分、风险级别、证据和指导的结构化警报 - 使用 `[REDACTED]` 脱敏的敏感标记证据 - JSON 和 Markdown 报告生成 - 针对显式本地输入、严重性过滤和失败阈值 (`fail-on`) 的 CLI 强化 - 文档安全检查和工作流配置测试 ## 技术栈 - Python 3.12 - `argparse` - `dataclasses` - `struct` - PyYAML - pytest - pytest-cov - Ruff - GitHub Actions - CodeQL - Dependabot ## 支持的合成样本 该项目仅支持安全的本地合成数据： - 合成 JSON 数据包/事件日志 - 合成 CSV DNS 类日志 - 合成文本 HTTP 类日志 - 仅在测试中手工制作的合成字节夹具 允许的值仅限于私人实验室范围、保留的文档 IP 范围、`example.com`、`example.org`、`example.net`、`.test` 域以及合成的 hostname。 ## 安全边界 - 仅用于防御 - 仅限离线/本地文件 - 仅限合成样本 - 无实时网络嗅探 - 无实时数据包捕获 - 无 raw sockets - 无 AF_PACKET - 无 sudo/root/CAP_NET_RAW 权限要求 - 无混杂模式 - 无数据包注入 - 无 ARP 欺骗 - 无 MITM 逻辑 - 无 PCAP 解析 - 无 Scapy - 无真实流量 - 无真实数据包捕获 - 无凭证提取 - 无 payload 转储 - 不能替代生产环境的 IDS/NDR ## 解析器概述 解析器模块仅对传入解析器函数的 `bytes` 进行操作。 - Ethernet：目的 MAC、源 MAC、EtherType、payload 提取 - IPv4：版本、IHL、TTL、协议、源 IP、目的 IP、payload 提取 - TCP 元数据：端口、序列号、确认号、数据偏移量、标志 - UDP 元数据：端口、长度、校验和、payload 提取 解析器测试仅使用手工制作的字节数组。不包含任何二进制样本文件、PCAP 文件或复制的真实数据包字节。 ## 流和协议摘要 流摘要是由从本地合成样本加载的归一化 `PacketEvent` 记录构建而成的。摘要包括： - 按来源、目的、协议和端口划分的流密钥 - 事件计数和字节总数 - 协议计数 - 目标端口计数 - 主要来源 - 主要目标 - 主要通信方 - 畸形记录计数 ## 检测类别 默认的合成检测包括： - 重复的连接尝试 - 来自单一源的多个目标端口 - 对可疑 `.test` 域的 DNS 查询 - 大容量合成出站流 - 异常目标端口 - 意外的协议和端口配对 - 重复的连接失败标记 - 可疑的合成 HTTP user-agent 标记 - 内部到文档范围的目标模式 - 带有脱敏证据的合成敏感标记检测 规则位于 [rules/signatures.yaml](rules/signatures.yaml)。 ## 评分和脱敏 警报会获得 0 到 100 之间的确定性实验室得分，以及信息、低、中、高或危急的风险等级。评分是透明的，旨在用于实验室分诊，而非生产风险评级。 敏感标记处理仅识别已批准的合成标记常量，并在 CLI 输出、警报证据、JSON 报告和 Markdown 报告中将它们呈现为 `[REDACTED]`。本项目不解析或提取真实的机密信息。 ## 报告 报告由本地合成样本生成，包括： - 安全范围 - 输入和文件摘要 - 流和协议摘要 - 检测摘要 - 带有得分的警报 - 脱敏证据 - 分诊指导 - 限制说明 示例报告： - [JSON 报告](reports/examples/offline_packet_analysis_report.json) - [Markdown 报告](reports/examples/offline_packet_analysis_report.md) ## CLI 示例 安装开发依赖： ``` python -m pip install -e ".[dev]" ``` 显示帮助： ``` python -m offline_packet_analyzer --help ``` 清点本地合成样本： ``` python -m offline_packet_analyzer inventory --input samples --format json ``` 验证本地合成样本： ``` python -m offline_packet_analyzer validate-samples --input samples ``` 摘要已加载的合成事件： ``` python -m offline_packet_analyzer summarize --input samples --format json python -m offline_packet_analyzer summarize --input samples --format text ``` 运行安全的合成检测： ``` python -m offline_packet_analyzer detect --input samples --format json python -m offline_packet_analyzer detect --input samples --format text python -m offline_packet_analyzer detect --input samples --format json --min-severity high python -m offline_packet_analyzer detect --input samples --format json --fail-on high ``` `--fail-on` 仅在存在达到或超过所选严重级别的警报时返回非零退出代码。 生成脱敏报告： ``` python -m offline_packet_analyzer report --input samples --output reports/examples/offline_packet_analysis_report.json --format json python -m offline_packet_analyzer report --input samples --output reports/examples/offline_packet_analysis_report.md --format markdown ``` 目录输入默认是递归的。在清点、验证、摘要、检测或报告命令上使用 `--no-recursive` 可以仅检查本地目录的直接子文件。 ## 测试和质量状态 最新的本地验证： - `164 passed` - `92.50%` 覆盖率 - `90%` 覆盖率门禁 - Ruff 检查通过 - Ruff 格式检查通过 - 文档安全检查通过 - CLI 冒烟测试通过 - 成功生成稳定的示例报告 - CLI/报告输出中不存在原始的已批准敏感标记常量 运行本地质量检查： ``` python -m pytest python -m pytest --cov=offline_packet_analyzer --cov-report=term-missing --cov-fail-under=90 python -m ruff check . python -m ruff format --check . python scripts/check-docs.py ``` ## CI 和 CodeQL 状态 GitHub Actions CI、CodeQL 和 Dependabot 已在本地配置。由于该代码库尚未发布，它们尚未通过 GitHub 验证。 已配置的工作流： - CI：测试、Ruff、覆盖率门禁、文档安全检查、CLI 冒烟测试 - CodeQL：使用 security-and-quality 查询进行 Python 分析 - Dependabot：每周更新 pip 和 GitHub Actions ## 项目结构 ``` .github/ GitHub templates, CI, CodeQL, Dependabot docs/ Safety, schema, detection, testing, release, portfolio docs reports/examples/ Stable redacted JSON and Markdown example reports rules/ Safe synthetic detection rules samples/logs/ Synthetic JSON, CSV, and text sample logs samples/raw/ Raw fixture policy documentation scripts/ Documentation safety checks src/offline_packet_analyzer/ detections/ Rule loading and detection engine flows/ Flow and protocol summaries guidance/ Defensive triage guidance loaders/ Local JSON, CSV, and text loaders models/ Event, flow, alert, packet, load models parsers/ Ethernet, IPv4, TCP, UDP metadata parsers redaction/ Synthetic marker redaction reporting/ JSON and Markdown report generation scoring/ Deterministic risk scoring tests/ Unit, CLI, safety, workflow, documentation tests ``` ## 已知限制 - 仅使用合成的本地样本 - 不处理真实的数据包捕获 - 不检查实时网络接口 - 不解码来自真实流量的应用层 payload - 不执行凭证提取 - 不能替代 IDS、NDR、SIEM 或数据包捕获平台 - CI/CodeQL 尚未在 GitHub 上运行 ## 许可证 MIT 许可证。请参阅 [LICENSE](LICENSE)。

标签：Beacon Object File, DNS 反向解析, IP 地址批量处理, Python, 安全规则引擎, 恶意代码分类, 数据脱敏, 无后门, 网络流量分析, 风险评分