tue3306/TrellixEDR

## 💾 下载并运行 ### 🚀 4 个步骤

1	**前往 [**Releases**](https://github.com/tue3306/TrellixEDR/releases/latest) 下载** —— 从以下两个选项中选择一个： | 文件 | 说明 | |---------|---------| | `TrellixEDR-1.0.1-setup.exe` | **安装版** —— 创建快捷方式，并出现在“已安装的应用”中 | | `TrellixEDR-1.0.1-windows-x64.zip` | **便携版** —— 解压即可运行，无需安装任何内容 |
2	**运行。** 如果是安装版，双击并点击下一步。 如果是便携版，解压文件夹并双击 **`TrellixEDR.exe`**。
3	**安装扫描引擎** —— 从 Trellix 下载两个免费文件，大约需要 5 分钟。 👉 [**点击此处查看详细步骤**](docs/CONFIGURAR_SCANNER.md)
4	**打开控制台**并点击*快速扫描*。

## 📸 效果展示

查看所有界面

### 威胁中心 ### 扫描历史 ### 统计数据 ### 快速扫描 ### 自定义扫描 ### 报告 ### 磁盘清理 ### 日志 ### 设置 ### 关于

## 🙏 Trellix 致谢 本项目**本身不实现恶意软件检测功能**。它只是一个界面。 所有的分析工作均由 **[Trellix Command Line Scanner](https://www.trellix.com/downloads/)** 完成， 该工具由 **Musarubra US LLC** 发行 —— 它与 Trellix 企业级产品中使用的反恶意软件引擎相同，并作为免费的命令行工具提供。 | | Trellix Command Line Scanner | 本项目 | |---|---|---| | 恶意软件检测 | ✅ 引擎 + DATs | ❌ 无 | | 界面 | 命令行 | 图形化仪表盘 | | 历史记录 | 无 | 包含所有扫描记录的 SQLite 数据库 | | 图表和报告 | 无 | 十种图表，支持 PDF、HTML、CSV 和 JSON | | 威胁中心 | 无 | 隔离、删除、哈希值、VirusTotal | 这个控制台所增加的，都是围绕扫描*外围*的功能：为每种情况构建正确的命令行、跟踪进度、解读报告、保存结果，并以易读的方式呈现。 **检测威胁的能力完全归功于 Trellix。** 该扫描器是免费的，按照包内附带的相关条款分发，并且需要直接从他们那里下载——本仓库不会对其进行再分发。 ## ✨ 功能介绍 ### 扫描 七种预设配置文件，每种都会转换为对应的 `scan.exe` 标志（flags）集合： | 配置文件 | 目标 | |--------|------| | **快速** | Temp、下载、桌面、启动项及内存 | | **完整** | 所有本地驱动器，包含启发式扫描和压缩文件 | | **自定义** | 任意文件夹，显示所有选项 | | **下载** | 下载文件夹，进行深度分析 | | **桌面** | 桌面 | | **文档** | 文档，包含 OLE 宏分析 | | **内存** | 正在运行的进程 | 在扫描过程中，您可以查看已分析的文件、速度、百分比、预计剩余时间、当前文件以及出现的检测结果。**界面绝不会卡死** —— 扫描器在独立的线程中运行，取消操作会终止整个进程树。 百分比来自于对目标的并行预计数。对于那些实际工作量与磁盘文件不匹配的配置文件——例如内存扫描和全盘扫描——**不会显示预估值**，而不是显示一个具有误导性的数字。 ### 威胁中心 每个检测结果都包含名称、路径、MD5、SHA1、SHA256、严重程度、引擎和建议的操作。您可以对其进行隔离、删除、忽略、恢复、打开所在文件夹、复制哈希值或在 VirusTotal 中进行搜索——这仅会在浏览器中打开公共搜索页面：**绝对不会上传任何文件**。 ### 仪表盘、图表和报告 综合信息卡片和十个自动更新的图表：时间轴、每日/每种类型的检测、已分析文件、速度、按类型划分的平均时间、主要目录和扩展名、严重程度分布以及月度历史记录。 支持导出为 **PDF、HTML、CSV 和 JSON** 格式的报告，可以针对单次扫描或整合多次扫描，包含执行摘要、最终结论、图表以及完整的文件和哈希值列表。 ### 磁盘清理 通过删除 Windows 临时文件、浏览器缓存、崩溃报告、缩略图缓存和回收站来释放空间。这是程序中唯一会删除文件的部分，其设计完全围绕这一点展开： - 如果事先没有显示**多少个文件和占用多少空间**的分析，则不会删除任何内容； - 确认时会逐一列出各个类别的名称； - 文档、下载、桌面、图片、视频和音乐被置于受保护列表中，在构建目录和执行删除时都会进行**双重核对**； - 绝不跟随链接和联接点，以防止清理缓存时波及真实文件夹； - 最近使用的文件会被视为正在使用而加以保留。 ### 环境与诊断 应用程序会自动检测当前存在哪些扫描器组件、安装了哪套 DATs，以及执行文件的架构是否与计算机相匹配——如果不匹配，它会准确提示需要下载哪个包。 它还会以**只读**方式查询 Microsoft Defender 的状态，以解释为什么在开启实时保护时检测测试会失败。应用程序绝不会更改系统的安全配置。 ## 📥 安装说明 ### 使用程序（推荐） 请参阅顶部的 [**下载并运行**](#-baixar-e-rodar)。简而言之：前往 [Releases](https://github.com/tue3306/TrellixEDR/releases/latest) 下载安装版或便携版 `.zip`，运行并按照 [扫描器配置指南](docs/CONFIGURAR_SCANNER.md) 进行操作。 如果您从未安装过此类软件， [**完整的 Windows 指南**](docs/INSTALACAO_WINDOWS.md) 详细解释了每一个步骤，包括如何应对 SmartScreen 警告。 ### 从源码运行 如果您从未使用过 Python 或 Git， [**完整的 Windows 安装指南**](docs/INSTALACAO_WINDOWS.md) 将从零开始解释每一个步骤，无需任何预备知识。 对于已经安装好所有依赖的用户： ``` git clone https://github.com/tue3306/TrellixEDR.git ``` ``` cd TrellixEDR && python -m venv .venv && .venv\Scripts\activate && pip install -r requirements.txt ``` ``` python main.py ``` 或者只需**双击 `Start Dashboard.bat`** —— 它会自动创建虚拟环境、安装依赖并启动程序。 ## 💻 系统要求 ### 支持的系统 | 系统 | 状态 | |---------|----------| | **Windows 11**（所有版本，64 位） | ✅ 支持 —— 已在 build 26200 上测试 | | **Windows 10** 64 位，1809 或更高版本 | ✅ 支持 —— 已在 22H2 上测试 | | **32 位**的 Windows 10 或 11 | ❌ 发布的安装包是 x64 架构的 | | Windows 8.1、8、7 或更低版本 | ❌ PySide6 不再提供支持 | | **ARM64** 架构的 Windows（Surface Pro X 等） | ⚠️ 需配合 Trellix 的 ARM64 包从源码运行 | | macOS、Linux | ❌ 本应用依赖于 Windows API | ### 硬件 | | 最低要求 | 推荐 | |---|---|---| | 处理器 | 双核 | 四核或以上 | | 内存 | 4 GB | 8 GB | | 磁盘空间 | 500 MB + 150 MB DATs | 2 GB | | 屏幕分辨率 | 1280 × 720 | 1600 × 900 | ### 软件 **如果要运行 `.exe`：无需任何依赖。** 不需要 Python、Git 或其他库。 仅需 [Trellix 扫描器](docs/CONFIGURAR_SCANNER.md)，而且是免费的。 如果从源码运行：**Python 3.11 或更高版本**（持续集成会在 3.11、3.12 和 3.13 上进行测试）。 ## 🏗️ 架构 ``` flowchart TD UI["ui/ — janela, páginas, widgets
PySide6"] CORE["core/ — casos de uso
orquestrador, serviços"] SCANNER["scanner/ — adaptador do scan.exe
comando, parsers, exit codes"] DB["database/ — SQLite
um repositório por tabela"] MODELS["models/ — dataclasses puras
sem Qt, sem I/O"] EXE["scan.exe
Trellix Command Line Scanner"] REPORTS["reports/ + charts/
PDF, HTML, CSV, JSON"] UI --> CORE CORE --> SCANNER CORE --> DB CORE --> REPORTS SCANNER -->|subprocess| EXE EXE -->|"/LOUD no stdout"| SCANNER EXE -->|"relatório XML + JSON"| SCANNER SCANNER --> MODELS DB --> MODELS REPORTS --> MODELS ``` 界面**仅**与 `core/` 通信。模型是纯粹的：它们既不了解 Qt 也不了解数据库。并且系统的任何部分都不会在 `scanner/trellix_scanner.py` 之外执行 `scan.exe`。 ### 结果获取方式 ``` sequenceDiagram participant U as Usuário participant P as Página de varredura participant W as ScanWorker (QThread) participant S as scan.exe participant B as SQLite U->>P: inicia a varredura P->>W: cria e conecta os sinais W->>S: subprocess com /LOUD /XMLPATH /JSONPATH loop enquanto varre S-->>W: linhas do /LOUD W-->>P: progresso (arquivos, velocidade, ETA) end S-->>W: código de saída W->>W: lê o XML (JSON como plano B) W->>W: calcula MD5, SHA1 e SHA256 W->>B: grava tudo em uma transação W-->>P: finished_scan(scan_id) P->>B: reconsulta somente leitura ``` 有两个数据源，各自扮演着不同且明确设定的角色： - **stdout 中的 `/LOUD`** **仅**用于提供进度指示。其格式并未被制造商记录在文档中，因此解析器具有容错性：无法识别的行会被记录到日志中并忽略——它们绝不会导致扫描崩溃，也绝不会进入数据库。 - **XML 报告**（`/XMLPATH` + `/RPTALL`）是**唯一事实来源**。它遵循产品指南中发布的正式 schema，并为数据库、图表和报告提供数据。 - **JSON 报告**是**备用方案**：如果 XML 被截断或格式错误，扫描结果将通过 JSON 恢复，而不是被直接丢弃。 ### 项目结构 ``` TrellixEDR/ ├── main.py Ponto de entrada ├── models/ Dataclasses e enums do domínio (sem Qt, sem I/O) ├── config/ Caminhos, constantes, tema e perfis de varredura ├── database/ Conexão SQLite, schema e um repositório por tabela ├── scanner/ Adaptador do scan.exe: localizador, comando, │ parsers, códigos de saída e worker em QThread ├── core/ Casos de uso consumidos pela interface ├── ui/ Janela, sidebar, páginas, widgets e modelos de tabela ├── charts/ Funções puras de desenho + telas matplotlib ├── reports/ Construtores de PDF, HTML, CSV e JSON ├── utils/ Logging, hashes, formatação, validação e processos ├── resources/styles/ Folha de estilo do tema escuro ├── assets/ Ícone e capturas de tela ├── docs/ Documentação completa ├── examples/ Relatórios de exemplo gerados pela aplicação ├── installer/ Inno Setup, NSIS e scripts de geração ├── scripts/ Build, release, ícone, capturas e dados de demonstração ├── tests/ Suíte de verificação (19 scripts) ├── vendor/ Componentes do Trellix (você baixa; não versionado) └── .github/ CI/CD, templates de issue e de PR ``` 包含约 **16,600 行 Python 代码**，分布在 127 个文件中，其中 2,700 行为测试代码。 ## 🧪 测试 ``` python tests/run_all.py ``` 共有 **19 个脚本**，旨在针对真实行为（而非 mock）测试应用程序：数据库和存储库、七种配置文件的标志构建、针对**真实二进制文件输出**的 XML 和 JSON 解析器、完整的 worker 流水线、XML 损坏时的恢复、进度和剩余时间、文档记录的十一种退出代码、报告的保留和截断、四种格式的生成、表格排序、磁盘清理的安全限制、菜单与页面的绑定、整个界面、**使用已安装的 `scan.exe` 进行真实扫描**、**实际应用到扫描器的排除项**以及**使用 EICAR 进行的真实检测**。 依赖于二进制文件的测试在未检测到该文件时会自动跳过，并显示清晰的消息——持续集成正是以此方式运行的。 ``` python -m ruff check . && python -m mypy charts config core database models reports scanner ui utils main.py ``` ## 🔬 真实二进制文件揭示的信息 解析器是针对 Trellix 7.0.6.1105（引擎 6900.11121，DAT 11856）的执行进行验证的。**产品文档在五点上与实际二进制文件存在分歧**，这些都是通过实践发现的，并已通过测试锁定： | 指南说明 | 二进制文件的实际行为 | |---|---| | `/ALLDRIVES` 扫描所有驱动器 | 二进制文件不识别这个名称。`scan.exe /?` 仅列出 `/AD`、`/ADL` 和 `/ADN` | | 表 10 列出了文件状态 | 存在一个额外的状态：`error not supported file.` —— 尽管有这个前缀，但它**并不是错误** | | `Total-files` 是文件计数 | 它可能**大于** `` 元素：扫描器无法打开的内容会被计入统计，但不会生成对应的元素 | | `/EXCLUDE ` 排除列表中的内容 | 只有当文件是 **不带 BOM 的 UTF-8** 编码时才有效。如果带有 BOM，扫描器会接受该参数，以代码 0 退出，并**默默忽略整个列表** | | — | 排除路径末尾的反斜杠会**使该条目失效**，同样没有任何警告 | 关于 `error not supported file.` 的情况值得强调：如果将其归类为失败，将会导致任何不带 `/ALL` 参数的扫描报告出几十个不存在的错误——在发现该问题的测试中，56 个 `.py` 文件全部报错。 真实的样本位于 [`tests/fixtures/`](tests/fixtures/)，具体的每种情况详见 [`docs/PARSER.md`](docs/PARSER.md)。 ## 📚 文档 | 文档 | 用途 | |-----------|----------| | [Windows 上的安装](docs/INSTALACAO_WINDOWS.md) | 从零开始的详细步骤，无需预备知识 | | [配置扫描器](docs/CONFIGURAR_SCANNER.md) | 下载 Trellix 及其 DATs | | [使用指南](docs/GUIA_DE_USO.md) | 详解每个界面和按钮 | | [架构](docs/ARQUITETURA.md) | 分层、依赖项和设计决策 | | [扫描器](docs/SCANNER.md) | flags、退出代码、许可证 | | [解析器](docs/PARSER.md) | XML、JSON、`/LOUD` 以及与文档的分歧 | | [数据库](docs/BANCO_DE_DADOS.md) | Schema、迁移、事务 | | [线程](docs/THREADS.md) | 如何确保界面不被阻塞 | | [报告和图表](docs/RELATORIOS.md) | 格式、截断、生成方式 | | [磁盘清理](docs/LIMPEZA.md) | 分类和安全限制 | | [设置和日志](docs/CONFIGURACOES.md) | 每个选项的实际作用 | | [构建和打包](docs/BUILD.md) | 生成 `.exe`、安装程序和发布版 | | [故障排除](docs/TROUBLESHOOTING.md) | 最常见的错误 | | [常见问题](docs/FAQ.md) | 快速答疑 | ## 🗺️ 路线图 以下内容均未承诺具体的发布日期。此列表仅用于展示发展方向并接受建议——如果这里的某些内容对您很重要，请提交一个[想法](https://github.com/tue3306/TrellixEDR/issues/new/choose)。 **研究阶段** - [ ] 通过 Windows 任务计划程序安排扫描 - [ ] DAT 更新的检查和辅助下载 - [ ] 并排比较两次扫描结果 - [ ] 将完整历史记录导出为单个文件 **已考虑，但存在保留意见** - [ ] 浅色主题 —— 目前样式表完全是深色的 - [ ] 英文翻译 —— 需要将所有界面文本分离出来 - [ ] 长时间扫描完成时的 Windows 通知 **无法实现的范围** 实时保护、拦截文件或对检测方式进行任何更改。这属于 Trellix 引擎的范畴，本项目不会对其进行修改。 ## 🤝 贡献 欢迎提交贡献。[贡献指南](CONTRIBUTING.md) 说明了如何准备环境、项目对代码的期望，以及在使用解析器和磁盘清理时的具体注意事项。 在提交 Pull Request 之前，请运行 `ruff`、`mypy` 和完整的测试套件。 本项目采用[行为准则](CODE_OF_CONDUCT.md)。 ## 🔒 安全 **任何数据都不会离开您的电脑。** 没有遥测，没有服务器，不上传任何文件。数据库、日志、报告和隔离区全部保留在本地磁盘上。 要报告漏洞，请使用[私密渠道](https://github.com/tue3306/TrellixEDR/security/advisories/new)—— 切勿使用公开的 issue。详情请见 [SECURITY.md](SECURITY.md)。 **此控制台不能替代常驻防病毒软件。** Trellix Command Line Scanner 仅执行按需分析；它不会持续监控系统。请保持 Microsoft Defender 处于开启状态——两者可以无冲突共存。 ## 📄 许可证 本仓库中的代码基于 [MIT 许可证](LICENSE)。 **Trellix Command Line Scanner** 和 **DAT 文件**归 **Musarubra US LLC** 所有，遵循原包附带的相关条款，且**不在此处进行再分发**——必须直接从 Trellix 获取。 [NOTICE.md](NOTICE.md) 详细说明了所有第三方组件、其许可证以及提及的商标。

**[⬆ 返回顶部](#trellix-edr-console)** 使用 Python、PySide6 和 Trellix 扫描引擎构建。

标签：PySide6, 图形界面, 系统运维, 逆向工具, 防病毒软件