ResearchForumOnline/ZSEC-Shield

# ZSEC Shield ZSEC Shield 是一款适用于 Python 3.11+ 的确定性、非 AI、按需文件扫描器。 它使用 SHA-256 对常规文件进行哈希处理，应用精确的字节和摘要规则，验证 仅包含数据的 Ed25519 签名规则源，生成结构化的 JSON，并可以 将明确选定的匹配项移动到可恢复的隔离区。 这是一个 MVP，而不是一个完整的防病毒产品。它没有内核驱动程序、 实时文件系统拦截、行为监控、内存扫描器、云 信誉服务、漏洞拦截器，也无法保证主机是干净的。 ## 安全边界 - 扫描是本地且按需进行的。不使用任何 AI 模型、API 密钥、遥测端点或 云上传。 - 不跟随 Symlinks 和 Windows reparse points。跳过特殊文件。 - 默认情况下，递归扫描会保持在初始文件系统内。 - 默认情况下跳过大于 64 MiB 的文件；该限制是明确的且 会被报告。 - 除非存在 `--quarantine`，否则禁用隔离。 - 恢复操作永远不会覆盖现有目标，并且已验证的恢复 对象在恢复后会被保留。 - 在使用规则源中的规则之前，会检查源签名、schema、时间戳、密钥状态、序列号和 payload 摘要。 - 源对象仅接受 SHA-256 和精确的字面字节规则。Command、script、 package、firewall、URL-action 和 configuration 字段将被拒绝。 - 如果源、trust store 或 rollback record 无效，则所有源规则都将被忽略 ，并且命令会报告结果未完成。内置规则仍然可用。 请参阅 [威胁模型](docs/THREAT_MODEL.md) 和 [Feed 格式](docs/FEED_FORMAT.md)。 ## 平台范围 扫描核心使用 Python 和标准文件系统调用，适用于： - Windows 10 和 11； - 当前受支持的 macOS 版本； - 主流 Linux 发行版。 清单适配器是只读的。它们识别基本的 OS 和 runtime 上下文，但不 断言补丁、Microsoft Defender、XProtect、包数据库或安全 控件是健康的。 ## 安装以进行评估 使用 Python 3.11 或更高版本创建一个隔离环境： ``` py -3.11 -m venv .venv .\.venv\Scripts\python.exe -m pip install --upgrade pip .\.venv\Scripts\python.exe -m pip install -e . .\.venv\Scripts\zsec-shield.exe --version ``` 在 macOS 或 Linux 上： ``` python3.11 -m venv .venv .venv/bin/python -m pip install --upgrade pip .venv/bin/python -m pip install -e . .venv/bin/zsec-shield --version ``` 运行时依赖项是 `cryptography`，仅用于 Ed25519 验证。 ## 快速开始 扫描单个文件或目录： ``` zsec-shield check ./downloads ``` 扫描多个根目录并保存机器可读的报告： ``` zsec-shield check ./downloads ./incoming --report ./reports/check.json --json ``` 检查状态和只读清单： ``` zsec-shield status --json zsec-shield inventory --json ``` `scan` 命令是 `check` 的别名。 ### EICAR 测试检测 内置规则集可以检测规范 EICAR 防病毒测试文件的精确字节和 SHA-256。EICAR 是一种无害的测试模式，而不是恶意软件。现有的 防病毒软件可能会在 ZSEC Shield 打开它之前阻止或删除它，因此 请仅在隔离的测试目录中使用官方的 EICAR 测试说明。测试 套件在内存中验证签名，并且不会将规范的 EICAR 内容写入磁盘。 ## 隔离与恢复 正常的检查不会更改扫描的内容： ``` zsec-shield check ./incoming ``` 隔离需要明确的标志： ``` zsec-shield check ./incoming --quarantine --report ./reports/quarantine.json ``` 对于每个匹配的文件，ZSEC Shield 首先创建一个私有的恢复副本并对其进行哈希处理。 只有当源仍然与扫描结果匹配时，它才会删除原始文件。如果源 删除失败，元数据会显示 `copy_only`，并且命令会返回一个未完成的退出 代码。这不会被报告为成功的隔离。 列出并恢复条目： ``` zsec-shield quarantine list --json zsec-shield quarantine restore 00000000-0000-0000-0000-000000000000 zsec-shield quarantine restore ENTRY-ID --destination ./recovered/sample.bin ``` 恢复需要一个现有的、非 reparse 的父目录，并拒绝覆盖。 在此 MVP 中故意没有提供 purge 命令。 ## 签名 Feed 更新 打包的 keyring 是故意留空的：这个 MVP 不会捏造一个生产环境的 trust anchor。在 keyring 中绑定一个由操作员控制的 Ed25519 公钥并显式传递， 设置 `ZSEC_SHIELD_KEYRING`，或者将其放置在 `STATE_DIR/trusted_keys.json`。 ``` zsec-shield --keyring ./trusted_keys.json update --file ./feed.json --json zsec-shield --keyring ./trusted_keys.json update --url https://security.example/feed.json --json zsec-shield --keyring ./trusted_keys.json check ./incoming ``` 远程 URL 必须使用无凭据的 HTTPS，并且最多通过三次 重定向后仍保持 HTTPS。Feed 大小被限制在 2 MiB 以内。在安装前会对更新进行验证； 旧序列以及使用不同签名内容的序列重用将被拒绝。 该 Feed 仅提供检测数据。它无法请求执行、删除、 隔离、安装包、网络访问或系统更改。 ## 状态目录 使用全局 `--state-dir` 或 `ZSEC_SHIELD_HOME` 覆盖状态根目录。 默认值如下： | 平台 | 默认值 | | --- | --- | | Windows | `%LOCALAPPDATA%\ZSEC\Shield` | | macOS | `~/Library/Application Support/ZSEC Shield` | | Linux | `$XDG_STATE_HOME/zsec-shield` 或 `~/.local/state/zsec-shield` | 当状态根目录位于请求的扫描根目录之下时，它会自动被排除。 ## 退出代码 | 代码 | 含义 | | --- | --- | | `0` | 扫描完成且没有配置的规则匹配，或者诊断/更新命令成功。 | | `1` | 匹配到一个或多个已配置的规则，且扫描以其他方式完成。 | | `2` | 操作未完成/失败：文件无法读取或正在更改、无效的 feed、不安全的恢复，或其他操作错误。 | | `130` | 被操作员中断。 | `0` 被刻意表述为“没有配置的规则匹配”，而不是“干净”。 ## 开发 ``` python -m pip install -e ".[dev]" python -m pytest ruff check src tests mypy src/zsec_shield python -m build ``` GitHub Actions 会在 Windows、macOS 和 Linux 上测试 Python 3.11 和 3.13，并带有一个 单独的 lint/build 作业。不包含发布工作流。 ## 许可证 Apache License 2.0。请参阅 [LICENSE](LICENSE)。

标签：Python, SHA-256, 云计算, 恶意软件扫描, 文件扫描, 无后门, 本地扫描, 规则引擎, 逆向工具