king-tero/VT-sentinel

# VT Sentinel — VirusTotal 安全插件（OpenClaw） 为 OpenClaw 代理提供自动恶意软件检测与 AI 驱动的代码分析。 零配置 — 无需 API 密钥。自动注册到 VirusTotal 的 AI API。 ## 安装 ``` openclaw plugins install clawhub:openclaw-plugin-vt-sentinel ``` 旧版 / 向后兼容的 npm 安装： ``` openclaw plugins install openclaw-plugin-vt-sentinel ``` 然后重启网关： ``` openclaw gateway restart ``` ## 验证 ``` openclaw plugins list | grep vt-sentinel ``` 应显示 9 个已注册工具。 ## 工具 | 工具 | 用途 | |------|---------| | `vt_scan_file` | 全文件扫描（AV 引擎 + AI 代码洞察） | | `vt_check_hash` | 快速哈希查询（不上传文件） | | `vt_upload_consent` | 管理敏感文件上传的同意 | | `vt_sentinel_status` | 查看配置、监控目录与保护状态 | | `vt_sentinel_configure` | 运行时更改设置（预设、通知级别、阻塞模式） | | `vt_sentinel_reset_policy` | 将所有设置重置为默认值 | | `vt_sentinel_help` | 快速入门指南与隐私信息 | | `vt_sentinel_update` | 检查更新并获取升级说明 | | `vt_sentinel_re_register` | 重新注册代理身份到 VTAI | ## 功能 - 自动扫描下载与创建的文件（AV + AI 代码洞察） - 保护指令文件（SKILL.md、TOOLS.md 等）在未获同意时不上传 - 阻止执行恶意文件与危险命令模式 - 实时监控目录（Downloads、/tmp、工作区） - 以轮换审计日志隔离威胁 - 检测 TOCTOU 攻击、LOLBins 与持久化模式 ## 更新 如果 VT Sentinel 已安装，请使用内置更新工具： ``` Ask your agent: "check for VT Sentinel updates" ``` 或手动操作： ``` openclaw gateway stop openclaw plugins update openclaw-plugin-vt-sentinel openclaw gateway start ``` ## 配置 ### 可选：添加你自己的 VirusTotal API 密钥（更高速率限制） 没有密钥时，VT Sentinel 会自动注册到 VTAI 并开箱即用。 如果你拥有 VirusTotal API 密钥（v3），在插件配置中设置： ``` openclaw config set plugins.entries.openclaw-plugin-vt-sentinel.config.apiKey "vt_xxxxxxxxxxxx" ``` ### 预设 | 预设 | 描述 | |--------|-------------| | `balanced` | 默认 — 扫描所有内容并隔离威胁 | | `privacy_first` | 仅哈希查询，不上传文件 | | `strict_security` | 最大保护，怀疑即拦截 | ### 设置 | 设置 | 可选值 | 默认 | |---------|--------|---------| | `notifyLevel` | all, threats_only, silent | all | | `blockMode` | quarantine, block_only, log_only | quarantine | | `sensitiveFilePolicy` | ask, ask_once, always_upload, hash_only | ask | | `semanticFilePolicy` | ask, ask_once, always_upload, hash_only | hash_only | | `maxFileSizeMb` | 1-32 | 32 | | `autoScan` | true, false | true | ## 工作原理 VT Sentinel 连接至 [VTAI](https://ai.virustotal.com) —— VirusTotal 的 LLM 优化代理层。首次运行时自动注册代理身份并获得永久 API 令牌。所有扫描均通过 VTAI 的精简响应格式进行，以优化大语言模型的上下文窗口。 文件分析包括： - **AV 检测结果**（来自 60+ 款杀毒引擎） - **AI 代码洞察**（VirusTotal AI 驱动的语义分析） - **社区贡献的 AI 结果**（来自 VirusTotal 社区） ## 隐私与合规 VT Sentinel 是一个安全插件，因此对其读取、写入与发送内容的透明性是威胁模型的一部分。 `vt_sentinel_status`（合规 / 数据流区块）以及 `openclaw security audit --deep`（通过插件的 `securityAuditCollector` —— 自 v0.12.1 起的 CLI 审计支持）会输出相同的结构化视图，因此你可以在不阅读源码的情况下验证其行为。 ### 数据流 | 类别 | 详情 | |---|---| | **读取的文件** | 配置监控目录下的候选文件（用于哈希与分类）。仅当上传策略允许且（对 `ask`/`ask_once`）用户同意时，完整内容才会上传至 VirusTotal/VTAI。指令文件（SKILL.md、HOOK.md、AGENTS.md 等）默认为 `hash_only`，永不上传。 | | **上传的文件** | 哈希查询免费（不发送内容）。内容上传仅按配置的 `sensitiveFilePolicy` / `semanticFilePolicy` 进行。 | | **网络端点** | 用户密钥模式：`www.virustotal.com`。VTAI 模式：`ai.virustotal.com`。仅在用户显式调用 `vt_sentinel_update` 时才联系 `registry.npmjs.org` 与 `clawhub.ai` —— 插件加载时从不联系。 | | **存储的凭证** | `/vt-sentinel-agent.json`（权限 `0o600`，仅所有者）。v0.12.0+ 同时对审计日志强制 `0o600`、审计目录强制 `0o700`。 | | **审计日志** | `/vt-sentinel-audit/uploads.log` 与 `detections.log`。轮换记录插件上传文件的时间与检测触发时间。 | | **运行时状态** | `/vt-sentinel-state.json` —— 首次运行标志、持久化策略覆盖、自动生成的代理名称。不包含样本文件内容。 | | **退出选项** | `vt_sentinel_configure` → 切换至 `configPreset: privacy_first`、设置 `autoScan: false` 或将各类策略改为 `hash_only`。 | ### `VIRUSTOTAL_API_KEY` 环境变量已弃用 早期版本会回退读取 shell 环境中的 `VIRUSTOTAL_API_KEY`。 **该回退在 0.11.0 中已移除。** 如果你之前导出了该变量，请一次性将值移至插件配置： ``` openclaw config set plugins.entries.openclaw-plugin-vt-sentinel.config.apiKey "vt_xxxxxxxx" ``` 或什么都不做，让 VTAI 在首次扫描时自动注册。两者均完全支持；环境变量不再生效。 ### 保留的 v0.11.0 特性 - **网络端点**：仅 `www.virustotal.com`（VT API）与 `ai.virustotal.com`（VTAI）。`registry.npmjs.org` / `clawhub.ai` 仅在显式调用 `vt_sentinel_update` 时联系 —— 插件加载时不联系。 - **不修改环境**：插件从不写入 `process.env`。 - **状态目录**：`/vt-sentinel-agent.json`（凭证，权限 `0o600`）、`vt-sentinel-state.json`（运行时覆盖）、`vt-sentinel-audit/`（轮换上传与检测日志）。 - **上传同意**：`SEMANTIC_RISK` 文件（SKILL.md、HOOK.md、AGENTS.md 等）默认为 `hash_only` —— 永不上传。`SENSITIVE` 文件（PDF、Office 文档、未知归档）默认为 `ask`，需每次运行显式同意。 - **安装通过安全扫描**：在 OpenClaw 2026.4.5 及更高版本上可干净安装，无需 `--dangerously-force-unsafe-install`。 随时可通过 `vt_sentinel_status` 检查当前配置。 ## 许可证 MIT

标签：AI代码分析, API密钥, Ask搜索, LOLBins, MITM代理, OpenClaw插件, SEO, TOCTOU攻击, VirusTotal, 主动防护, 云端安全, 哈希查询, 威胁隔离, 审计日志, 技术栈, 持久化攻击, 数据可视化, 文件扫描, 目录监控, 自动化攻击, 自动注册, 行为检测, 零配置