miltech0/VigilScope

# VigilScope 这是一款基于 Python 构建的、隐私优先的本地 Windows endpoint 可见性、检测和事件调查工作台。 [](https://github.com/miltech0/VigilScope/actions/workflows/ci.yml) [](https://github.com/miltech0/VigilScope/actions/workflows/codeql.yml) [](https://github.com/miltech0/VigilScope/releases/latest) VigilScope 是一款受 EDR 启发的被动桌面应用程序，用于了解一台本地 Windows 计算机上正在发生的事情。它结合了系统指标、进程可见性、网络观测、可解释的检测规则、警报以及面向案例的调查，但并不自诩为商业 EDR。 ## 下载 Windows x64 构建版本发布在 [GitHub Releases 页面](https://github.com/miltech0/VigilScope/releases)。每个 版本包含： - `VigilScope.exe`； - `VigilScope.exe.sha256`； - 一个包含可执行文件、校验和、README 和安全策略的 ZIP 归档文件。 在运行可执行文件之前，请先进行验证： ``` .\scripts\verify_release.ps1 ` -ExePath .\VigilScope.exe ` -ChecksumPath .\VigilScope.exe.sha256 ``` 发布二进制文件是由 GitHub 托管的 Windows runner 上标记的源代码构建的。它们目前是**未签名**的，因此 Windows SmartScreen 或杀毒软件可能会显示信誉警告。请查阅源代码、验证校验和，并仅从本仓库的 Releases 页面下载。 ## 概述 VigilScope 通过 `psutil` 收集操作系统信息，将历史记录存储在本地 SQLite 数据库中，并在深色的 Tkinter 界面中呈现数据。该应用程序专为教育、个人和防御性安全用途而设计。 在运行时可以使用英文和土耳其语。应用程序头部的标志按钮可切换所有重新构建的主视图，而无需重启应用程序。所选语言将被保存以供下次启动时使用。 ## 主要功能 - 用于 CPU、内存、磁盘和活动连接的概览卡片。 - 带有进程查找功能的、可排序的活动 TCP 和 UDP 连接表。 - 详细的进程列表、过滤器、进程树和只读进程详细信息。 - 被动监听端口和远程 endpoint 基线。 - 带有预期基线说明的可解释网络发现。 - 系统、连接、进程和网络事件历史记录。 - 纯数据内置和用户自定义检测规则。 - 警报证据、分析师注释、抑制、MITRE ATT&CK 映射和案例。 - UTF-8 CSV 和规范 JSON 导出，并带有敏感命令行掩码。 - 运行时土耳其语/英语语言切换，带有本地化的日期和枚举。 ## 截图 尚未捆绑真实的项目截图。请参阅 [`docs/screenshots/README.md`](docs/screenshots/README.md) 了解捕获 清单和命名指南。未使用任何模拟或伪造的产品截图。 ## 语言支持 支持的语言代码有： - `tr` — Türkçe - `en` — English 翻译文件位于 `locales/tr.json`、`locales/en.json` 以及 `locales/rules/` 下匹配的规则翻译文件中。两个 locale 目录使用相同的键和参数名称。缺失的翻译会回退到英语；缺失的英语键会产生可见的开发警告，而不会导致 UI 崩溃。 首次启动时，土耳其语 Windows 显示语言将选择土耳其语。其他显示语言将选择英语。随后的启动将使用 `settings.json` 中保存的首选项。 ## 架构 该应用程序将收集、持久化、分析、呈现和本地化分离开来： - `system_info/product.py` 包含规范的产品元数据和文件名。 - `system_info/settings.py` 加载并原子保存用户首选项。 - `system_info/i18n.py` 提供线程安全的、基于键的翻译、枚举 呈现、回调以及日期/数字格式化。 - `system_info/data_migration.py` 执行一次性的旧版数据库备份。 - `system_info/database.py` 拥有可重复的 SQLite schema 升级。 - `system_info/app.py` 协调 Tkinter 生命周期和后台任务。 - `system_info/process_*` 模块收集、过滤、比较并呈现进程 数据。 - `system_info/network_*` 模块构建一个共享的被动网络快照， 维护基线，并创建可解释的发现。 - `system_info/detection_*`、`rule_*` 和 `correlation_engine.py` 实现纯数据 检测和调查工作流。 - `system_info/exporting.py` 和 `detection_exporting.py` 创建掩码导出。 后台 worker 绝不直接更新 Tkinter widget。结果通过队列返回，并在 UI 线程上应用。重复的进程和网络扫描将被抑制，而不是无限排队。 ## 检测引擎 内置规则是 [`rules/builtin_rules.json`](rules/builtin_rules.json) 中的规范英语 JSON 记录。匹配使用稳定的事件、严重性、状态和地址范围代码，而不是翻译后的标签。 土耳其语内置规则标题、描述和类别通过 locale 目录中的规则 ID 进行解析。 规则比较规范化的字段，并支持有界序列、计数和去重计数关联。它们不执行 Python、PowerShell、shell 命令或嵌入在 JSON 中的代码。用户规则保留用户编写时使用的语言，绝不进行机器翻译。 警报是调查信号，不是恶意软件的证据。预期的基线可以降低发现或警报的有效严重性，但 VigilScope 绝不会自动将 endpoint 标记为可信。 ## 网络分析 网络分析将一个本地 `psutil.net_connections` 快照重用于活动连接、监听器、endpoint 基线、网络事件和发现。 监听端口是等待流量的本地 socket。地址范围很重要： - **Loopback**（`127.0.0.1`、`::1`）只能从同一台计算机访问。 - **Private network** 地址用于本地网络范围。 - **All interfaces**（`0.0.0.0`、`::`）将监听器绑定到每个匹配的 本地接口，值得进一步审查。 - **Public** 标识全局可路由的远程地址。 第一个网络快照是基线，不会产生大量“已启动”或“新 endpoint”事件。随后的更改会创建规范的网络事件。远程 endpoint 由协议、IP 和端口标识；进程使用情况被单独跟踪。 可选的反向 DNS 仅使用操作系统解析器，在有界后台工作中运行，并缓存结果。VigilScope 不使用 WHOIS、地理定位、ASN、信誉或威胁情报 API。 ## 进程监控 “进程”选项卡默认每两秒刷新一次，并支持： - 文本、状态、最低 CPU、最低 RAM 和网络活动过滤器； - 稳定的数字和文本排序； - 具有孤儿和循环保护的父子进程树； - 只读进程详细信息、命令行、路径、工作目录（如果可用）的打开文件 计数、相关连接、子进程和父进程链。 仅凭 PID 并不是持久的身份标识，因为 Windows 可以重用它。VigilScope 尽可能使用 PID 加上进程创建时间。第一个进程快照被视为正常基线；启动和停止事件从随后的更改开始。 `Access Denied`、`Terminated` 和 `Unknown` 是安全的显示状态。一个无法访问或消失的进程不会中止整个快照。 收集命令行时不会阻塞每个进程的 CPU 调用。 VigilScope 故意没有进程终止、挂起、删除或其他干预控制。 ## 历史记录和 SQLite 存储 活动数据库为： ``` %LOCALAPPDATA%\VigilScope\vigilscope.db ``` 在非 Windows 开发系统上，使用等效的 XDG 数据目录。 SQLite 使用 WAL 模式、外键、忙碌超时、短期连接和可重复的 schema 迁移。规范时间戳保留在数据库中；显示格式化仅在 UI 中应用。 默认保留期限： - 系统测量：7 天； - 连接事件：14 天； - 进程事件：14 天； - 监听端口和网络事件：30 天； - endpoint 每小时观测：8 天； - DNS 缓存：7 天； - 远程 endpoint 基线：不自动删除； - 发现、警报、案例、注释和检测检查点：不通过 例行保留清理移除。 保留值集中在 `system_info/config.py` 中。 ### 旧版数据迁移 如果新数据库不存在，且存在此旧版数据库： ``` %LOCALAPPDATA%\SistemBilgisi\system_history.db ``` VigilScope 将使用 SQLite 的备份 API 创建新数据库，验证其 完整性，写入迁移标记，并保持原始文件夹不变。 它从不覆盖现有的 `vigilscope.db`，也绝不将活动的 WAL 数据库作为不受控制的原始文件操作进行复制。 Schema 版本 5 将旧版的土耳其语或英语枚举标签规范化为稳定 代码，同时保留警报、证据、案例、注释、基线、自由格式的 规则文本和用户编写的注释。 ## 警报和案例 警报保留其证据、首次和最后一次观测、重复计数、 状态历史记录和分析师注释。案例将选定的警报关联到 调查时间线中，而不会删除源记录。“案例”表示一个 调查文件；“事件”表示原始的系统或网络观测。 警报状态代码为 `new`、`investigating`、`confirmed`、 `false_positive`、`ignored` 和 `closed`。本地化的标签仅用于 呈现。 ## MITRE ATT&CK 映射 内置规则可能包含官方的 MITRE ATT&CK 战术和技巧 ID 以及 英文技巧名称。覆盖视图总结了已启用 规则和观察到的警报的映射。这是一种行为分类，而不是对 完整企业 ATT&CK 覆盖范围的声明。 ## 隐私 VigilScope 是本地优先的。它不上传遥测数据，也不发送 IP 地址、进程名、用户名、路径、命令行、事件、发现、 警报或案例到外部服务。常见的密码、token、API-key 和 Bearer 模式在命令行呈现和导出之前会被掩码处理。 本地数据库和导出文件仍可能包含敏感的 endpoint 元数据， 包括用户名、进程路径、IP 地址、端口、时间戳和 分析师注释。请保护 `%LOCALAPPDATA%\VigilScope`，将导出文件视为 敏感文件，并在将截图或报告附加到 公共 issue 之前移除私有数据。该数据库未进行应用层加密；它依赖于 操作系统用户配置文件权限。可选的反向 DNS 使用 计算机配置的 DNS 解析器，并且默认禁用。 ## 安全模型 该应用程序是被动的和只读的。 - 它不主动扫描端口或远程计算机。 - 它不发送或注入数据包。 - 它不终止或挂起进程。 - 它不阻止或终止网络连接。 - 它不修改 Windows 防火墙。 - 它不在远程系统上执行命令。 - 它不自动阻止 IP 地址。 - 它不上传遥测数据。 - 它不联系外部威胁情报服务。 ## 要求 - Windows 10 或更高版本是主要目标。 - Python 3.11 或更高版本。 - Tkinter，包含在标准的 Windows Python 发行版中。 - 运行时依赖项固定在 `requirements.txt` 中（`psutil==7.2.2` 和 `regex==2026.7.10`）。 某些进程和 socket 字段需要提升的 Windows 权限。该 应用程序在没有提权的情况下仍然可用，并安全地报告无法访问的字段。 ## 从源代码安装 PowerShell： ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install -r requirements-dev.txt ``` 不需要庞大的绘图库或网络服务 SDK。 ## 运行应用程序 ``` .\.venv\Scripts\python.exe main.py ``` 运行非 GUI 健康检查： ``` .\.venv\Scripts\python.exe main.py --check ``` ## 运行测试 ``` .\.venv\Scripts\python.exe -m pytest -q .\.venv\Scripts\python.exe -m compileall -q main.py system_info tests tools .\.venv\Scripts\python.exe -m ruff check . .\.venv\Scripts\python.exe -m bandit -r system_info main.py -q .\.venv\Scripts\python.exe -m pip_audit -r requirements.txt --strict .\.venv\Scripts\python.exe -m pip check ``` ## 构建 Windows 可执行文件 在 Windows 上，安装构建依赖项并运行： ``` .\scripts\build_windows.ps1 ``` 构建使用 `VigilScope.spec`，捆绑 locale 目录、内置规则、 标志和应用程序图标，然后运行打包后的 `--check` 健康测试并 创建 SHA-256 校验和。PyInstaller 为其运行的 操作系统进行构建；因此官方的 Windows 可执行文件是在 Windows runner 上生成的。 推送版本标签将启动发布工作流： ``` git tag v0.1.0 git push origin v0.1.0 ``` 手动运行工作流会构建工件，但不会创建 GitHub Release。 ## 数据存储 应用程序目录为： ``` %LOCALAPPDATA%\VigilScope ``` 它包含： - 活动状态下的 `vigilscope.db` 和由 SQLite 管理的 WAL/SHM 文件； - `settings.json`，以 UTF-8 原子写入； - 旧版迁移成功后的 `.legacy-data-migrated.json`。 源文件夹不用于运行时数据库或瞬态用户数据。 ## 内置规则 内置规则是版本化的、规范的英语、纯数据记录。它们的 ID、 匹配字段、MITRE ID、协议值、路径和其他技术值 从不被翻译。支持禁用内置规则；故意限制在 UI 中删除或编辑其规范定义。 ## 创建用户规则 规则编辑器接受 JSON 条件和有界关联设置。 在保存之前，针对本地历史记录验证并预览规则。用户标题、 描述、类别、误报说明和调查步骤 完全保留编写时的原样。 ## 导出数据 历史记录、、发现、警报和案例在适用的地方支持 UTF-8 CSV 或 JSON 导出。 - CSV 标题遵循活动的显示语言。 - JSON 字段名保持规范英语，以实现机器兼容性。 - JSON 捆绑包包含 `product`、`display_language` 和 ISO `exported_at` 元数据。 - 默认文件名使用安全的英文名称，例如 `vigilscope_history_2026-07-19.json`。 - 常见的命令行密钥保持掩码状态。 ## 安全验证 该仓库在 Windows 和 Linux 上运行测试，使用 Ruff、Bandit、依赖项 审计、已提交密钥检测和 CodeQL。发布工作流在打包前重新运行 源验证。请参阅 [`SECURITY_AUDIT.md`](SECURITY_AUDIT.md) 了解已审查的攻击面、已修复的发现、验证证据和 残余风险。自动化工具可降低风险，但不能证明该 软件没有漏洞。 安全漏洞应通过 [GitHub Security Advisories](https://github.com/miltech0/VigilScope/security/advisories/new) 私下报告， 而不是通过公开的 issue。 ## 已知限制 - `psutil` 暴露的是操作系统 socket 表，而不是数据包 payload。 - 短暂的连接和进程可能在 快照之间出现和消失。 - 访问权限可能会隐藏进程所有者、路径、命令行或 socket PID。 - 反向 DNS 可能会超时或不返回 hostname。 - 基线和可解释的规则可能会产生误报，特别是对于 浏览器、开发工具、安装程序和更新程序。 - 运行时语言切换会重建主界面并关闭打开的详情 窗口；重新打开详细记录以新语言查看。 - 本地遥测数据库未由应用程序加密。 - 官方二进制文件未进行代码签名，可能会触发信誉警告。 - 静态分析和自动化测试无法保证没有漏洞。 - 本项目不能替代商业 endpoint 保护。 ## 项目结构 ``` assets/flags/ Bundled TR and GB flag PNGs docs/screenshots/ Screenshot contribution guidance packaging/ Windows executable metadata scripts/ Build and checksum verification scripts .github/workflows/ CI, CodeQL, and Windows release automation locales/ English and Turkish UI/rule catalogs rules/ Canonical built-in JSON detection rules system_info/ Application, services, repositories, and UI modules tests/ Isolated automated tests tools/ Reproducible asset and rule maintenance scripts main.py Application entry point requirements.txt Runtime dependency pin requirements-dev.txt Test and security-tool dependency pins requirements-build.txt PyInstaller build dependency pin VigilScope.spec Reproducible executable bundle configuration SECURITY_AUDIT.md Security review scope, fixes, and residual risks ``` ## 路线图 潜在的未来工作包括更完整的键盘导航、更丰富的 本地化分析师指导、针对超大案例历史记录的分页、签名 发布打包，以及额外的可解释被动规则。路线图项目 不是承诺，也不表示为实现的功能。 ## 免责声明 VigilScope 是一个教育和个人防御性安全项目。警报 和发现是调查信号，不是恶意软件的证据。它不是 功能齐全的商业 EDR，也不能替代商业 endpoint 保护、组织监控、事件响应程序或 专业安全建议。

标签：AMSI绕过, DFIR, IPv6支持, Mr. Robot, Python, Tkinter, Windows 调试器, 威胁检测, 安全调查, 无后门, 无线安全, 终端可见性, 终端安全, 逆向工具