97 lines
9.7 KiB
Markdown
97 lines
9.7 KiB
Markdown
> Rust 3 测试市场版本 `0.5.0+artemis.7`；独立 Python/MCP/dotenv 与外部工具由使用者准备。验证边界见 [RUST3-VERIFICATION.md](RUST3-VERIFICATION.md)。下文保留原 2.x 版本的历史范围。
|
||
|
||
# 内部团队首次部署（Windows x64）
|
||
|
||
接收方先准备当前用例需要的工具，随后插件自动发现和检查。无需逐项填写程序路径。插件 ZIP 包含适配代码、原 Skill、通用样例和说明，不携带第三方程序、驱动、本机 profile、账号或测试数据。
|
||
|
||
## 1. 准备 Artemis 和 Python
|
||
|
||
使用已正常安装的 Artemis 2.x。在插件设置中把 `python` 指向当前 Artemis 环境的 **64 位 Python**，通常是该项目 `.venv\Scripts\python.exe`。独立 Python 需要具备 [requirements.txt](requirements.txt) 中的 MCP 和 dotenv；Artemis 插件安装器只解压、校验及登记插件，不自动执行 pip。
|
||
|
||
如果 MCP 服务无法启动，先在该解释器中检查导入：
|
||
|
||
```powershell
|
||
& '<Artemis Python 的绝对路径>' -I -c 'import mcp, dotenv; print("imports OK")'
|
||
```
|
||
|
||
依赖不齐时由维护该 Python 环境的人按它的依赖管理方式安装 requirements，然后重新诊断。不要切换 Artemis 全局 Python 来兼容旧 Binwalk。
|
||
|
||
## 2. 选择一种工具摆放方式
|
||
|
||
**方式 A：把程序所在目录加入 Windows PATH。** 加目录，不能把单个 EXE 或 DLL 文件加入 PATH。例如 FFmpeg 包的 `bin` 目录、Wireshark 完整安装目录、Nmap 安装目录和 MediaInfo DLL 目录。保留各软件需要的相邻 DLL、数据文件和配置资源；不要只复制一个 EXE。PATH 中的 MediaInfo 目录直接包含 `MediaInfo.dll`，不会递归搜索 PATH 下的全部文件夹。
|
||
|
||
**方式 B：集中到已解压目录，在插件中只设置一次 `tool_root`。** 示例目录结构：
|
||
|
||
```text
|
||
D:\ArtemisTools\
|
||
ffmpeg\bin\ffprobe.exe
|
||
ffmpeg\bin\ffmpeg.exe
|
||
wireshark\tshark.exe
|
||
wireshark\dumpcap.exe
|
||
nmap\nmap.exe
|
||
mediainfo\x64\MediaInfo.dll
|
||
binwalk-python\Scripts\python.exe （选择 Python 模块方式时）
|
||
```
|
||
|
||
这些行只显示入口；各软件的其他必需文件也要完整保留。统一目录最多枚举四层子目录、每个根目录最多 20000 个文件；使用专用小目录，不填整个磁盘。压缩包或安装包不能直接执行，插件不会解压或安装它们。
|
||
|
||
可混合使用：显式 `profile` 配置优先，其次 `tool_root`，最后 PATH。profile 可留空；仅在固定版本、特殊安装或排查时使用 [原通用样例](skill/assets/profile.example.json)。其中相对路径以 profile 文件所在目录为基准。显式路径不存在、文件名错误或 DLL 位数错误会报错，**不会静默改用其他版本**。因此跨电脑分发时不要携带自己的 profile。
|
||
|
||
Binwalk 的单独优先级为：`profile.runtimes.binwalk_python` → `profile.tools.binwalk` → `tool_root\binwalk-python\Scripts\python.exe` → 统一目录中的原生 Binwalk → PATH 原生 Binwalk。自动发现的模块运行时固定执行 `python.exe -I -m binwalk`，不会猜测 PATH 中哪个 Python 安装了该模块。按软件要求在接收方重新创建和准备虚拟环境；Python 虚拟环境不能靠复制另一台电脑上的目录保证可移植。
|
||
|
||
## 3. 按能力准备依赖
|
||
|
||
| 需要的功能 | 首次准备 | 插件自检覆盖与现场条件 |
|
||
| --- | --- | --- |
|
||
| `probe_media` 媒体元数据 | 完整 FFmpeg 发行包里的 **ffprobe** | 固定本地 AVI 视频读出尺寸。RTSP 地址、连接和业务预期在任务里验证 |
|
||
| FFmpeg 环境检查 | 同包的 ffmpeg | 固定本地视频解码并检查两帧哈希输出；当前业务入口未提供通用转码/滤镜命令 |
|
||
| `media_info` | **Windows x64 的 MediaInfo.dll** 及其依赖 | 先读 PE 位数，再在独立子进程加载并调用所需 API，最后解析固定 AVI。GUI 或 mediainfo.exe 不能代替此 DLL 后端 |
|
||
| `analyze_pcap` | 完整 Wireshark/TShark 安装 | 离线读取固定 PCAP 的包号、地址、端口；已有 PCAP 的读取不依赖 Npcap |
|
||
| `capture_packets` | dumpcap、Npcap、合适权限 | 自检只枚举接口，不抓包。实际所选网卡、驱动、权限仍须按任务核实 |
|
||
| `scan_ports` | 完整 Nmap 安装 | 自检用空目标列表检查本地 XML 输出，禁用 DNS；不扫描任何地址。正式入口只做显式单 IP/数字 TCP 端口连接检查 |
|
||
| `scan_firmware` | 可用的原生 Binwalk，或单独准备的 Binwalk Python 环境 | 固定本地 gzip 签名，核对偏移；不解包。旧 Binwalk 2.x 可能需要兼容 Python（原资料的 2.3.2 曾使用单独 3.11 环境），历史版本记录不是最新版推荐 |
|
||
| `capture_serial` | PowerShell、串口适配器驱动、可用 COM | 自检检查 SerialPort 类型和端口枚举，不打开 COM、不切换 DTR/RTS、不读写设备；正式采样需要明确端口、波特率、时长及独占权限 |
|
||
| V1/V2 查询及固件预检 | 包内标准库协议脚本、实际网络和目标身份 | 不依赖配置工具 GUI；doctor 不发送设备发现包。正式发现、查询和固件流程仍通过当前 Artemis 任务执行 |
|
||
| PC 配置程序、移动视联、mainThread、SecureCRT | 对应合法可用的完整软件、授权视觉插件 | 需要实际窗口及任务权限。串口只读采集有独立入口，不要求 SecureCRT |
|
||
| 客诉、联楹/连楹、DM、软探针、路由器等网站 | 已确认地址、网络、授权会话及视觉插件 | PATH 不创建登录状态；按原路由人工登录，再观察实际业务页面 |
|
||
| 固件加密、算法 OTA 等厂商能力 | 对应厂商 SDK/程序、操作契约与权限 | 不能由通用 Binwalk 或端口检查代替 |
|
||
| Android APP 测试 | Artemis 已有 Android 工具、目标设备及 APP 环境 | 在当前任务核对设备，外部工具的本地自检不验证手机业务 |
|
||
|
||
依赖官方入口：[FFmpeg](https://ffmpeg.org/download.html)、[MediaInfo Windows（区分 GUI/CLI/DLL）](https://mediaarea.net/en/MediaInfo/Download/Windows)、[Wireshark Windows 安装](https://www.wireshark.org/docs/wsug_html_chunked/ChBuildInstallWinInstall.html)、[Nmap](https://nmap.org/download.html)、[Binwalk](https://github.com/ReFirmLabs/binwalk)。Npcap 是否已安装、许可和权限由接收方按自己的部署要求核实。不要运行工具包中无关的激活器。
|
||
|
||
## 4. 刷新环境并在插件内验收
|
||
|
||
MCP 继承 **Artemis 主进程启动时的 PATH**，不会读取系统设置后自动替换已有进程的环境。修改 PATH 后，等当前任务结束，从已获得新环境的入口重新启动 Artemis，再运行插件自检。新终端的 `where.exe ffprobe` 成功只说明该终端能找到，不能证明运行中的 Artemis 已看到新 PATH。统一目录配置变更由后续插件会话使用，无需为了设置路径终止正在运行的任务。
|
||
|
||
在正常 Artemis 任务中选择本插件；纯电脑任务同时选择已授权的视觉插件。可直接提供以下任务说明：
|
||
|
||
```text
|
||
只调用家庭安防多工具测试插件的 environment_doctor，设置 check_functional=true。
|
||
逐项报告发现、启动/DLL 加载、本地样本结果和能力状态，保存实际 JSON 证据。
|
||
不扫描设备、不抓包、不打开串口、不执行固件操作。缺失只阻塞依赖它的能力。
|
||
```
|
||
|
||
也可在解压后的插件目录使用 Artemis Python 独立检查，无需插件依赖已能导入：
|
||
|
||
```powershell
|
||
& '<Artemis Python 的绝对路径>' -I -B .\dependency_runner.py --timeout 42 doctor
|
||
& '<Artemis Python 的绝对路径>' -I -B .\dependency_runner.py --timeout 42 doctor --check-versions
|
||
& '<Artemis Python 的绝对路径>' -I -B .\dependency_runner.py --tool-root 'D:\ArtemisTools' --timeout 42 doctor --check-functional
|
||
```
|
||
|
||
工具参数 `check_versions=true` 运行版本/帮助或 DLL 加载 API 检查；`check_functional=true` 自动包含启动检查，并额外运行固定本地样本。默认两项为 false，只发现路径和模块、读取 DLL PE 头，不执行外部程序。
|
||
|
||
报告的 `tools[].discovery/startup/functional` 分开记录。`capabilities` 中 `blocked` 表示该项依赖缺失或检查失败，`available_unverified` 表示已发现但尚未完成功能自检，`local_verified` 表示通过所列本地检查。每个工具的失败独立记录；MediaInfo 缺失或 Binwalk 失败不妨碍 ffprobe 查询视频。
|
||
|
||
总时限受插件及宿主预算限制，单项自检最多三秒。慢机器可能出现 `timed_out`，预算耗尽的剩余项为 `budget_exhausted`，均不能当作已经验证；可在正确的宿主/插件预算下复查。接口枚举、COM 枚举只报告本机条件，不承诺驱动、抓包权限、串口通信或业务验收已通过。
|
||
|
||
## 常见排查
|
||
|
||
- **本机可运行，插件提示 missing**：检查 Artemis 继承的 PATH；将完整软件目录加入 PATH，或只设置一次 tool_root。清除移植时误带的旧 profile。
|
||
- **MediaInfo 位数错误**：安装与插件 Python 匹配的 x64 DLL。自动发现会跳过不匹配候选；显式指定错误 DLL 会直接报错。PE 匹配后仍可能因缺失依赖/API 而加载失败，以 startup 和 functional 为准。
|
||
- **Binwalk 帮助成功但样本失败**：说明入口存在，签名分析仍不可用；检查完整安装、模块及数据依赖。不要改动 Artemis Python 解决旧模块的兼容问题。
|
||
- **TShark 可分析但不能抓包**：分别检查 dumpcap、Npcap、目标网卡及权限。Wireshark 静默安装不自动静默安装 Npcap。
|
||
- **插件启用但网站不可用**：核对网络、实际浏览器会话和授权；软件发现不等于已经登录。
|
||
|
||
运行时回执可能含本机工具路径，供本机排查；对团队分享前按资料权限处理。发布 ZIP 不纳入这些回执。固件写入默认关闭，环境准备和自检不会开启它。
|