cac0ns3c/Lyrebird

# Lyrebird **专为恶意软件分析实验室设计的现代互联网服务模拟套件。** [](https://github.com/cac0ns3c/Lyrebird/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](https://pypi.org/project/lyrebird-emulator/) Lyrebird 能够搭建起逼真的伪造网络服务 —— HTTP/HTTPS, DNS (UDP + TCP), SMTP, POP3/IMAP, FTP, TFTP, SSH, Telnet, IRC, NTP, TLS, QUIC/HTTP-3, 以及一个通用的 TCP sink —— 使得运行在**隔离沙箱**中的恶意软件样本 表现得就像连接到了真实的互联网一样。每一次交互都会被记录为结构化的 JSON 事件，并且样本发送的每一个 payload 都会被捕获到磁盘中。 它是 [INetSim](https://www.inetsim.org/) 的精神续作（其最后一个版本为 1.3.2，发布于 2020 年），使用 Python 以 async 为核心进行了重构，并将检测遥测数据作为 一等输出。 ## 演示 启动一个实验室环境，一个替代样本与模拟服务进行通信，每一次 交互都会生成结构化的 JSONL，并随着检测触发生成相应的标签：  ### 凭证捕获蜜罐 SSH 和 Telnet 蜜罐会捕获暴力破解的凭证，然后向 “样本”提供一个伪造的 shell 来记录其执行的命令 —— 包括获取第二阶段 payload 的 URL —— 同时不会真正执行或拉取任何内容：  ### 结合 AI 模型层 作为可选功能，Lyrebird 可以调用模型来 (1) 为没有预置静态规则的 endpoint 即兴生成一个合理且**无害的** 回复 —— 让未知的样本继续 通信 —— 并且 (2) 将捕获的会话进行分类，得出结论并生成相应的 Sigma 检测建议：  ## 为什么需要它 INetSim 依然是该领域的参考工具，但它是基于 Perl 的、同步运行的，配置使用的是 自定义格式，而且其日志设计初衷是为了生成人类可读的报告，而不是为了方便 SIEM 摄取。Lyrebird 保留了经过验证的模型并对其进行了现代化改造： - **异步核心** (asyncio / FastAPI / aiosmtpd / dnslib) - **YAML 配置** 具有合理的默认值 —— 即使是一个空文件也能提供一个可用的实验室环境 - **结构化的 JSONL 事件** —— 每次交互生成一个规范化的对象，可直接 传输至 SIEM（这是所有数据流转的骨干基础） - **Artifact 捕获** —— 存储并哈希上传的文件、邮件正文以及原始 socket 数据 - **自动实验室 CA** —— TLS 握手直接可用；在首次运行时生成证书 - **容器原生** —— 在内部（无出站）网络中直接运行 `docker compose up` - **配套的 Sigma 检测** —— 每个服务都附带检测内容 ## 快速开始 从 PyPI 安装并使用内置默认配置运行： ``` pip install lyrebird-emulator lyrebird # binds the standard service ports (run as root on the lab host) ``` 或者从源码运行，并使用示例配置： ``` pip install -r requirements.txt python -m lyrebird --config config/lyrebird.yaml ``` 或者使用容器化部署（推荐 —— compose 网络设置为 `internal: true`，因此 该实验室环境默认没有外部路由）： ``` cd docker && docker compose up --build ``` 将你的恶意软件分析虚拟机的默认网关 / DNS 指向 Lyrebird 主机，然后 引爆发样本并观察涌入的事件流。 ## 输出内容 每一次交互都会输出为一行 JSON： ``` {"schema":"1.0","ts":"2026-06-29T12:00:00.000+00:00","session":"...", "service":"dns","transport":"udp","src_ip":"10.13.37.66","src_port":51000, "dst_port":53,"event_type":"request","summary":"A evil.example", "request":{"qname":"evil.example.","qtype":"A"}, "response":{"rcode":0,"answer":"10.13.37.1"},"artifacts":[],"tags":[]} ``` 事件日志保存在 `labdata/events/.jsonl` 中；捕获的 payload 存放在 `labdata/artifacts//` 目录下。 完整的事件字段 schema 以及完整的检测目录详见 [`REFERENCE.md`](REFERENCE.md) —— 该文件是根据 `events.py` 和 Sigma 规则生成的， 因此永远不会产生偏移。可以通过 `python scripts/gen_reference.py` 重新生成。 ## 服务 | Service | Transport | Status | Notes | |---|---|---|---| | HTTP / HTTPS | TCP | ✅ 已实现 | 捕获任意方法/路径；自动 TLS；捕获请求体 | | DNS | UDP | ✅ 已实现 | sinkhole 响应器；记录每一次查询；可选的真实 NXDOMAIN 模式（默认关闭） | | SMTP | TCP | ✅ 已实现 | 接收并捕获邮件；记录信封 | | POP3 | TCP | ✅ 已实现 | 伪造邮箱；记录凭证/命令 | | FTP | TCP | ✅ 已实现 | 被动 + 主动 (PORT) 模式；捕获 STOR 上传 | | TFTP | UDP | ✅ 已实现 | 捕获 WRQ 上传；基于单次传输的 TID | | IRC | TCP | ✅ 已实现 | 观察僵尸网络 C2 — 昵称、频道、PRIVMSG 任务指令 | | NTP | UDP | ✅ 已实现 | 响应时间查询；可配置时间偏移量 | | TCP sink | TCP | ✅ 已实现 | 将所有数据记录到额外端口（相当于 INetSim 的 "Dummy"） | | IMAP | TCP | ✅ 已实现 | 伪造邮箱；记录 LOGIN 凭证；IDLE 推送（邮箱-C2 长轮询） → imap-idle | | DNS over TCP | TCP | ✅ 已实现 | 基于 TCP 传输的 sinkhole | | TLS (指纹识别及响应) | TCP | ✅ 已实现 | JA3/JA4 + SNI，终结连接并响应，同连接下的 SNI-vs-Host 检测（默认关闭） | | TLS 指纹监听 | TCP | ✅ 已实现 | 捕获 JA3/JA4 + SNI 然后关闭连接（默认关闭） | | SSH | TCP | ✅ 已实现 | asyncssh 蜜罐；捕获暴力破解凭证，随后通过伪造的 shell 记录命令 (ssh-bruteforce, ssh-payload-pull) | | Telnet | TCP | ✅ 已实现 | 明文 IoT/Mirai 蜜罐；暴力破解凭证 → 伪造 shell 记录命令 (telnet-bruteforce, telnet-payload-pull) | | QUIC / HTTP-3 | UDP | ✅ 已实现 | aioquic h3 服务器；捕获每一个 HTTP/3 请求并进行良性响应 (http3-transport) | ## 自定义响应 无需修改代码，即可通过为每个服务配置 `responses` 块来定制其返回内容（这是对 INetSim fakefiles 功能的现代化改进）。解析优先顺序为 **操作员规则 → fakefile → 模型响应器 (如果启用) → 内置默认值**， 并且选定的来源会记录在每一个事件中 (`response.source`)。 ``` services: http: responses: http: - path: "/gate.php" # glob over the URL path method: "POST" status: 200 content_type: "application/json" body: '{"status":"ok","task":"none"}' - path: "/*.exe" body_file: "fakefiles/stub.bin" # relative to data_dir fakefiles_dir: "fakefiles" # also serve real files by URL path dns: responses: dns: - qname: "*.evil-c2.com" # point a family at a specific sink host qtype: "A" answer: "10.13.37.66" ``` Fakefile 服务受到路径遍历保护 —— 路径被限制在配置的目录范围内。 ## 启用 / 禁用服务 在配置文件中为每个服务设置 `enabled: true|false`，或者在启动时进行覆盖： ``` python -m lyrebird --disable smtp,ntp python -m lyrebird --enable http,dns --no-banner ``` ## 模型层 (前沿大模型 + 本地模型) Lyrebird 通过一个与供应商无关的统一接口与模型进行交互，因此你可以自由切换使用前沿大模型 API 或是完全本地化的模型。选择 `local` 可将所有数据保留在本机，以用于气隙隔离环境下的分析。 | provider | backend | |---|---| | `anthropic` | Claude (`ANTHROPIC_API_KEY`) | | `openai` | OpenAI (`OPENAI_API_KEY`) | | `gemini` | Google Gemini (`GEMINI_API_KEY`) | | `local` | 任何兼容 OpenAI 接口的本地服务器 — Ollama, LM Studio, llama.cpp, vLLM | | `mock` | 离线确定性存根 (用于测试 / 演练) | **主要用途 — 将会话分类并生成检测。** 将其指向已捕获的 会话，即可获得结构化的检测结论 + 候选的 Sigma 规则建议： ``` python -m lyrebird.analyze --session labdata/events/.jsonl --provider local python -m lyrebird.analyze --session --provider anthropic --model claude-sonnet-4-6 ``` **可选用途 — 响应生成。** 当 `models.respond.enabled: true` 时，如果遇到没有 匹配规则的 HTTP 请求，模型会生成一个**良性的占位符** 响应体，从而让未知样本继续通信。该功能**默认关闭**（系统优先使用 静态模板），并且受到了刻意的限制：捕获的输入会先进行净化处理，模型被限制为只能生成通用的无危害内容（绝对不包含 payload、脚本 或命令），并且输出会经过金丝雀检测和长度限制 —— 出现任何错误都会回退到 静态默认响应。 ### 不受信任的输入会被严格对待 由于捕获的流量是由攻击者（恶意软件）控制的，因此任何到达模型的数据都可能成为 prompt 注入的攻击面。`models/sanitize.py` 会中和注入标记，将 捕获的数据作为金丝雀隔离防护后的惰性观测数据进行处理，并根据 schema 验证模型输出。捕获的内容绝对不会被执行 —— 服务仅用于提供响应或记录 字节流。 ## 添加服务 继承 `BaseService` 类，实现 `start()` / `stop()` 方法，使用 `self.emit(...)` 发送事件，并在 `orchestrator.REGISTRY` 中注册该类。这就是 全部的接口约定 —— 详见 `services/dns.py` 提供的简洁示例。 ## 检测 `detections/sigma/` 目录下存放了基于 JSONL schema 的 Sigma 规则 (`logsource.product: lyrebird`)。目前已包含：DNS 长标签/DGA 检测、HTTP 缺失 User-Agent 信标检测、SMTP 群发收件人检测。其核心原则是，每一种 模拟的技术都会附带与之配对的检测规则。 ### 检测分析 除了基于单一事件的 Sigma 规则外，系统还会对捕获的会话执行三种分析，以应对基于统计 / 行为模式的场景： - `python -m lyrebird.beacons --session ` — 信标、抖动 (通过 到达时间间隔的 CV 计算) 以及信道轮换。这是针对第二阶段 (Phase 2) 行为的防御性配对分析。 - `python -m lyrebird.mimicry --session [--data-dir labdata]` — 流量伪装与加密特征检测：协议在异常端口上通信、域前端 启发式分析、使用浏览器 UA 的机器人、以及高熵（加密）数据体。 这是针对第三阶段 (Phase 3) 行为的防御性配对分析。 - `python -m lyrebird.dns_tunnel --session ` — DNS 隧道 / 数据外发 信道：在同一个父域名下传输的高熵、几乎全是唯一值的子域名， 这与单次查询的长标签 DGA 规则截然不同。 ## 目录结构 ``` src/lyrebird/ events.py # structured event model + JSONL sink (the backbone) config.py # YAML loading + defaults base.py # BaseService plugin contract certs.py # lab CA / leaf certs tls.py # ClientHello parsing + JA3 / JA4 profiles.py # operator response templates orchestrator.py # loads config, runs enabled services cli.py # `python -m lyrebird` analyze.py # model-assisted session triage beacons.py # beacon / jitter / channel-rotation analytic mimicry.py # traffic-mimicry / encryption-tell analytic dns_tunnel.py # DNS tunneling / exfil analytic services/ # http, dns, dns_tcp, smtp, pop3, imap, ftp, tftp, # irc, ntp, tls_capture, tcp_sink models/ # anthropic, openai, gemini, local, mock + sanitize config/lyrebird.yaml detections/sigma/ scripts/lint_sigma.py docker/ tests/ ``` ## 状态 所有十六个服务和所有三个会话分析功能均已实现，并通过了测试 （113 个测试，在 Python 3.10–3.12 上全部通过），均可正常运行；整个套件能够实现端到端 启动，并且每个服务都能输出遥测数据。近期增加的功能 —— SSH 和 Telnet 凭证捕获蜜罐、IMAP IDLE 模拟、FTP 主动模式 (FTP-bounce) 安全加固、TLS JA3/JA4 指纹识别、NTP mode-6/7 MONLIST 检测，以及 DNS 隧道/数据外发分析功能 —— 每一项都提供了与之配套的检测规则。插件 接口约定已趋于稳定；后续的工作都是在此基础上进行扩展。有关项目定位和路线图，请参阅 `SCOPE.md`。 ## 贡献 欢迎提交 PR —— 关于环境设置、代码变更标准以及添加新服务的 详细步骤指南，请参阅 `CONTRIBUTING.md`。CI (GitHub Actions) 会在 每次推送和提交 PR 时，在 Python 3.10–3.12 环境下运行测试套件、对 Sigma 规则进行 lint 检查，并对 CLI 进行冒烟测试。 ``` PYTHONPATH=src python -m pytest tests/ -q PYTHONPATH=src python scripts/lint_sigma.py ``` ## 许可证 GPL-3.0-or-later (详见 `LICENSE`)。选择此许可证是为了确保 Lyrebird 保持为一款著作权类型的（Copyleft）、对分支友好的社区工具，秉承与 INetSim (GPLv2) 相同的精神。每个源文件都包含 SPDX 标识头。

标签：DAST, Python, 异步编程, 恶意软件分析, 无后门, 沙箱环境, 网络仿真, 蜜罐技术, 计算机取证, 请求拦截, 逆向工具