工具盘点与有界 CLI

scripts/tool_runner.py 仅依赖 Python 3.10+ 标准库；实际工具、Binwalk 模块和 MediaInfo DLL 需本机单独配置。它收集可复核证据，不判定测试通过。所有公开命令返回都有 execution_status 和 test_verdict: "not_evaluated"。completed 只代表进程退出码为 0；端口状态、媒体指标和采集覆盖度仍需与用例标准比对。

配置与盘点

从 Skill 根目录运行下面示例。全局选项放在子命令之前。执行网络、抓包或串口命令前，须已确定用户授权的目标、网卡/串口、端口、时长和证据目录；本适配器不自动发现设备、不推断路由器入口。

python scripts/tool_runner.py list
python scripts/tool_runner.py --tool-root 'D:\ApprovedTools' doctor
python scripts/tool_runner.py --profile .\device-profile.json doctor --check-versions

list / doctor 默认只查文件；只有显式 --check-versions 才运行已定位的可执行程序的版本/帮助参数，每个进程最多 5 秒。--dry-run doctor --check-versions 不启动程序。--tool-root 可重复，扫描最多 4 层、每个根目录最多 20000 个文件名，不解压包。只将用户明确指定的可信已解压目录传给该参数。

原生可执行体发现顺序：profile.tools → --tool-root → PATH。Binwalk 的显式 Python 运行时优先于此顺序，MediaInfo DLL 只从显式 libraries.mediainfo 读取，详见下方配置。可执行文件名必须匹配工具 ID 的固定候选名；不接受 cmd、wsl、shell wrapper 或安装器代替工具。powershell 同时接受 powershell.exe / pwsh.exe。profile 中的相对路径按 profile 所在目录解析。

{
  "tools": {
    "ffprobe": "D:/ApprovedTools/ffmpeg/bin/ffprobe.exe",
    "ffmpeg": "D:/ApprovedTools/ffmpeg/bin/ffmpeg.exe",
    "tshark": "D:/ApprovedTools/Wireshark/tshark.exe",
    "dumpcap": "D:/ApprovedTools/Wireshark/dumpcap.exe",
    "nmap": "D:/ApprovedTools/Nmap/nmap.exe"
  },
  "runtimes": { "binwalk_python": "D:/ApprovedTools/binwalk-env/Scripts/python.exe" },
  "libraries": { "mediainfo": "D:/ApprovedTools/MediaInfo/MediaInfo.dll" },
  "auth": { "password_env": "DEVICE_PASSWORD" }
}

以上路径只是格式示例，按实际已安装位置填写；不必列出未安装工具。分发脚本不含开发机的安装路径。profile 不能保存明文密码、token、带认证信息的 URL 或 RTSP URL。password_env 等环境变量引用可以保留，但工具不会自动使用密码登录。

runtimes 只接受 binwalk_python；libraries 只接受 mediainfo。这两处只填本地文件路径，不接受对象、模块名、脚本路径、命令行或额外参数。相对路径同样以 profile 所在目录为基准。binwalk_python 配置优先于 tools.binwalk，固定执行 python -I -m binwalk；Python 文件名须为 python.exe、python 或相应 python3[.N] 名称。未配置时仍使用原来的 Binwalk 可执行体发现方式。MediaInfo 只接受显式配置的 MediaInfo.dll，不会运行 GUI 或安装器。

availability	含义
`executable-found`	找到名字匹配的文件；未证明驱动、依赖、权限、版本兼容或设备连通性
`python-module-configured`	找到配置的 Python；须通过 `--check-versions` 确认 Binwalk 模块能加载
`library-found`	找到配置的 MediaInfo DLL；须通过版本检查确认可加载，再用实际媒体验证解析
`package-only`	在指定 root 中只看到对应 `.zip` / `.7z` 文件；没有可执行体
`missing`	当前 profile/root/PATH 未定位工具；静态 `package_evidence` 仍可记录历史包证据
`manual-interface`	原网页或 GUI；此适配器没有其专有 CLI，不表示程序缺失，也不阻止宿主原生 GUI/浏览器路由
`mcp-check-required`	已确认的MCP路由；CLI不检查MCP连接、Android设备或任务就绪性，需使用相应MCP工具
`orchestrator-context`	Codex协作编排上下文；不作为独立PC工具安装状态

完整固定 ID 与证据见 assets/tool-catalog.json。Wireshark/Nmap ZIP 有相应 EXE 成员；Binwalk 外层 ZIP 有源码、教程及 Python 安装器，固定隔离模块入口已有本地样本验证；FFmpeg 7z 的包版本不能代替实际运行版本。mainThread 的真实程序和手册已取得，其专有能力仍按原生窗口路由。压缩包存在、已启动或版本检查通过均不等于登录及业务可用。内部配置、移动视联、客诉、联楹、路由器保留原入口；账号统计表未读取或复制。

子命令

子命令	必填输入	固定行为与边界
`probe`	`--input FILE` 或 `--rtsp-env NAME`	FFprobe；输出选定编解码/分辨率/帧率/格式字段；本地输入只允许 `file` 协议
`media-info`	`--input FILE`	Windows MediaInfo DLL；拒绝直接URL/UNC输入，回读确认Internet选项关闭；每类最多100路，输出通用/视频/音频白名单字段
`analyze-pcap`	`--input PCAP`	TShark `-r -n -T fields`；默认1000、最多10000包；仅时间、长度、地址、端口、协议列
`capture`	`--interface ID --host IP --duration SEC --output PCAPNG`	Dumpcap；`host IP` 过滤；1..600秒；100MiB上限；snaplen=256
`scan`	`--host IP --ports 22,80,554`	Nmap TCP connect `-sT -n -Pn`，最多128个明确端口；无NSE、网段、主机名、服务版本探测
`firmware-scan`	`--input FILE`	`binwalk FILE` 或固定 Python 模块入口，默认签名分析；不自动解包、不执行提取物；本地实测版本为2.3.2，其他版本另核验
`serial`	`--port COMx --baud N --duration SEC --output LOG`	PowerShell串口脚本；1..600秒；原始字节与时间戳文本；不发登录或其他命令。可显式指定 `--dtr-enable` / `--rts-enable`，两者默认关闭

所有进程使用参数数组及 shell=False，没有 --args / 任意参数透传。默认进程时限60秒，串口/抓包为时长+10秒；--timeout 可设1..3600的整数，抓包/串口须至少比采集时长多5秒。输出目录须已存在，输出文件和串口 .raw.bin 必须不存在，防止追加或覆盖已有证据。

python scripts/tool_runner.py --profile .\device-profile.json probe --input .\recording.mp4
python scripts/tool_runner.py --profile .\device-profile.json media-info --input .\recording.mp4
python scripts/tool_runner.py --profile .\device-profile.json analyze-pcap --input .\capture.pcapng --max-packets 500
python scripts/tool_runner.py --profile .\device-profile.json --dry-run capture --interface 1 --host 192.0.2.10 --duration 30 --output .\evidence\device.pcapng
python scripts/tool_runner.py --profile .\device-profile.json --dry-run scan --host 192.0.2.10 --ports 22,80,554
python scripts/tool_runner.py --profile .\device-profile.json firmware-scan --input .\firmware.bin
python scripts/tool_runner.py --dry-run serial --port COM9 --baud 115200 --duration 60 --output .\evidence\serial.log

示例使用文档地址 192.0.2.10；必须替换为用户明确提供且授权的单个目标。--dry-run 仍检查输入和可执行体，输出脱敏后的参数计划，不启动进程。计划确认后移除 --dry-run 才执行。无需把整个工具目录提取或安装到 Skill；工具包和驱动安装属于独立的环境准备操作。

Binwalk 与 MediaInfo 运行条件

Binwalk 2.3.2 的 Python 源码依赖 imp，不兼容 Python 3.12+；本机已用 Python 3.11 的独立 venv 安装用户提供源码并验证签名扫描。团队部署时使用已验证的独立环境或相容的原生 Binwalk，不更换 Artemis 的 Python。-I 忽略用户 site/PYTHONPATH；每次调用另设空的临时 XDG_CONFIG_HOME，避免自动加载用户自定义插件。不会自动安装模块。doctor --check-versions 成功只能证明模块帮助可运行，扫描仍需本地文件验证。

MediaInfo 使用与当前 Python 位数匹配的 Windows DLL；32/64位不匹配、DLL 缺依赖或 API 缺失会返回失败。解析在运行器自己启动的固定子进程中执行，沿用 --timeout；内部 _media-info-worker 是实现细节，不用于直接调用或替换超时入口。它将 Internet 设为空字符串，并严格要求 Internet_Get 返回空字符串，否则拒绝解析；21.09 中 No 等非空值反而启用该选项。直接URL/UNC输入已拒绝，但此配置不是操作系统级网络隔离保证。输出不含 CompleteName、标题、标签或完整 Inform 文本。Duration 使用 MediaInfo 原生毫秒值，FrameRate 为帧/秒，FileSize 为字节；不要直接与 FFprobe 的秒制 Duration 相减。已用 MediaInfoLib 21.09 在 Python 3.14 及 Artemis 当前 Python 验证本地样本，不代表所有媒体格式或 GUI 功能均已验收。

RTSP 凭据

用户必须提供完整 URL，不能猜测通道路径。只从指定环境变量读取，不接受 --url 或 profile 中的 URL。交互式 PowerShell 可避免把完整 URL 写入命令历史：

$rtspInput = Read-Host '输入完整 RTSP URL' -AsSecureString
$env:CAMERA_RTSP = [System.Net.NetworkCredential]::new('', $rtspInput).Password
try {
    python scripts/tool_runner.py --profile .\device-profile.json probe --rtsp-env CAMERA_RTSP --transport tcp
} finally {
    Remove-Item Env:CAMERA_RTSP -ErrorAction SilentlyContinue
    $rtspInput.Dispose()
}

JSON输出、计划、异常不回显完整URL或其中的凭据；FFprobe只输出固定字段并对文本二次脱敏，合法的数值/帧率字段作为测量值保留，避免短查询值（如 token=1）误伤 20/1、8000 等指标。完整URL在计划中整体替换，stderr直接丢弃，子进程移除 FFREPORT 防止工具日志持久化完整命令行。FFprobe需要在其进程参数中接收URL，因此同一主机上有进程查看权限的程序仍可能看到它；不能声称环境变量消除了这一点。不要保存终端明文输入或环境快照。

证据限制

抓包默认仅截取前256字节，适合连接/协议/时序分析，不能作为完整负载或码流内容证据。抓包文件和串口原始日志仍可能包含设备发送的敏感信息；命令不把其内容打印到JSON，分享前按项目规则脱敏。运行器抑制所有外部工具stderr；非零退出码、超时只给固定错误码，排错先核对工具、文件、权限和参数，不以打印含凭据命令替代诊断。

Nmap的主机时限可能让部分端口未完成；execution_status=completed 不等于所有请求端口都被覆盖。FFprobe元数据不等于持续码率、丢帧率或长期流稳定性；Binwalk签名结果不等于固件安全结论；本适配器不据此输出PASS/FAIL。

Nmap XML可能把同状态端口折叠到 <extraports>。扫描结果保留 requested_ports、逐端口 ports 及 aggregate_states（state/count/reasons）。每个主机的 ports_not_individually_reported 列出缺少明确TCP端口状态的请求端口，individual_port_coverage 为 complete / partial / none，只描述逐端口结果覆盖度。聚合组即使计数与剩余端口数量相等，也不会被展开为各端口状态；多个聚合组之间更不能猜测端口归属。没有主机结果时 host_results_present=false。这些字段用于暴露证据缺口，不能把聚合计数、退出码0或缺失端口解释为全覆盖或测试通过。

串口来源

scripts/vendor/serial_monitor.ps1 从用户给定参考包 embedded-app-pc-debug/scripts/serial_monitor.ps1 原样复制。SHA-256：

173584db05950b9842f2485eec5b33c0b16062f944216c283a18e038a9138a67

包装器每次构造计划时校验该哈希。脚本独占打开COM口，默认8N1、无流控、DTR/RTS不启用，记录 LOG 和 LOG.raw.bin；包装器不暴露发送命令。--dtr-enable / --rts-enable 分别映射原脚本已有的 -DtrEnable / -RtsEnable，用于复现已确认且获授权的现场会话设置，JSON同时记录实际开关值。它们不启用RTS/CTS或DTR/DSR握手，不应仅因一次无数据就盲目组合切换。某些设备将控制线用于复位，已知会触发复位时不能把它当作一般只读采集。没有参数时行为保持不变。

下面仅演示一个已确认需要同时启用DTR/RTS的本机会话；不是所有设备的默认配置。profile.serial 当前只作为环境资料，本运行器不会从中读取控制线或其他串口参数；实际行为由命令行显式值决定。

python scripts/tool_runner.py --profile .\device-profile.json serial --port COM9 --baud 115200 --duration 5 --output .\evidence\serial.log --dtr-enable --rts-enable

打开串口仍依赖设备、驱动与操作系统权限，并可能改变端口占用；运行适配器允许在授权目标上做限定时长的现场验证。若用户终端占用端口，报告占用并等待释放，不关闭或抢占其会话。现场结果放到独立的运行报告，不作为其他机器可用性的保证。执行策略若阻止脚本，报告环境条件，不自动绕过策略。

状态与退出码

execution_status	CLI退出码	解释
`planned` / `completed`	0	计划构造成功或进程结束；无测试结论
`failed` / `timed_out` / `launch_failed` / `output_invalid`	1	工具失败、超时、无法启动或输出格式异常
`invalid_arguments` / `configuration_error`	2	参数/本地文件配置错误；不回显原始参数
`tool_missing`	3	缺少对应执行文件、已配置Python或DLL；按上文tools/runtimes/libraries配置，MediaInfo不查PATH

官方参数来源

FFprobe 官方文档：元数据、JSON writer、字段选择。
TShark 手册：离线输入与 fields 输出。
Dumpcap 手册：网卡、capture filter、停止条件与snaplen。
Nmap 参考指南：显式目标、TCP connect、端口与时限选项。
Binwalk 官方项目：默认固件签名分析，提取是单独选项。
MediaInfo DLL 官方接口：固定 New/Open/Get/Count_Get/Option/Close/Delete API。
MediaInfo SDK Quick Start：API 初始化及版本读取。
MediaInfo 21.09 配置实现：Internet 空字符串关闭及 Internet_Get 回读语义。

测试：python -m unittest discover -s tests -p test_tool_runner.py -v。单元测试只构造命令并模拟外部进程结果；不会连接设备、扫描或抓包。实际可用性由当前机器的doctor、限定本地样本及经授权的现场验证分别说明，不能从一次适配器执行成功推广成实机功能验收。

15 KiB Raw Blame History Unescape Escape