KSWORD / 5.1

OPERATOR DOCUMENTATION

软件使用文档

只写会影响操作结果的前置条件、顺序、降级路径和故障判断。

01

先判断这次操作是否需要 R0

不需要先加载驱动

浏览普通进程列表、查看基础文件信息、读取大部分系统配置、查看日志和只读 R3 页面。

必须先加载驱动

CE 桥接、R3/R0 Cross-view、内核内存与页表、驱动对象证据、回调操作、受保护进程操作以及任何明确标为 R0 的功能。

不要用“按钮能点”判断功能是否真的走 R0。

实际标准是客户端能打开 \\.\KswordARKLog，目标 IOCTL 被当前驱动支持，并且该功能所需的 DynData/Capability 已就绪。

02

主程序、驱动、Profiles 和插件必须来自同一套发行包

不要只替换 EXE，也不要保留旧 SYS。

客户端会把部分 ERROR_INVALID_FUNCTION、ERROR_NOT_SUPPORTED 和 ERROR_INVALID_PARAMETER 识别为“驱动过旧或缺少该 IOCTL”。混用时最常见的表现不是完全打不开，而是某些页面空白、Unsupported 或只返回部分字段。

  1. 1
    退出 KSword、CE 和所有插件进程。

    仍持有设备句柄的进程会让你误判新驱动是否已经生效。

  2. 2
    卸载旧服务后再替换整套目录。

    不要让服务 ImagePath 继续指向旧目录里的 SYS。

  3. 3
    从同一目录启动主程序。

    同时使用该目录下的语言包、profiles、插件和驱动。

依据：ArkDriverClient.cpp 的旧 IOCTL 分类与统一设备路径。

03

“服务已启动”不等于驱动已可用

服务层
  • 服务存在
  • StartService 成功
  • ImagePath 指向正确 SYS
通信层
  • 能打开 \\.\KswordARKLog
  • 协议/IOCTL 匹配
  • 功能所需 Capability 可用

驱动加载后，先看 Driver Status，再看 DynData。不要先去具体功能页反复点击按钮。

设备打不开

先查管理员权限、服务状态、签名、SYS 路径和设备创建。此时 DynData 还不是问题。

设备能打开但旧驱动不支持

说明通信存在，但当前 SYS 没有该控制码。换回同一 Release 的驱动。

IOCTL 返回失败 NTSTATUS

设备和协议都已到达驱动，继续看 R0 日志、目标状态和参数，不要再重装服务。

依据：DriverClient::open()、deviceIoControl()。

04

DynData 决定的是“哪些 R0 功能能安全运行”

设备 Loaded 只代表通道存在。依赖内核结构偏移、全局 RVA、函数 RVA 或类型大小的功能，还要求 profile 与当前内核身份匹配并被驱动接受。

Matched

本地 profile 与当前模块身份匹配，仍需看 Accepted items 和 Capability。

Missing items

只禁用依赖这些字段的功能；不要把单项缺失误判为整个 R0 失效。

旧驱动不支持 V4 查询

主程序比驱动新。不要手工复制一个 JSON 试图解决协议缺失。

Profile 不匹配

不要套用“相近 Windows 版本”的偏移。错误偏移可能产生比安全降级更严重的结果。

Windows 更新后第一次运行，先检查 DynData，再做内核修改。

同一主版本的 Windows 也可能更换内核构建和 PDB 身份。

依据：KernelDock.DynData.cpp 的 matched、accepted、missing 和 capability 状态。

05

Cheat Engine 必须从 KSword 启动

先加载 R0，再从选中进程的 KSword 操作中启动 CE。

集成启动器会先检查设备，设置桥接 DLL、状态文件和目标 PID，然后启动随包 CE。Lua 自动脚本先加载桥接，再延迟打开目标，确保第一次 OpenProcess 就经过 KSword。

桥接接管
  • OpenProcess
  • VirtualQueryEx
  • ReadProcessMemory
  • WriteProcessMemory
桥接不接管
  • 调试器
  • 远程线程
  • 远程内存分配
  • 页面保护修改
  • 插件初始化时打不开 \\.\KswordARKLog，会拒绝安装 Hook，不会假装启用后回退普通 Win32 读写。
  • 读取按最大 1 MiB 分片；写入按最大 256 KiB 分片。
  • 写入只带 UI_CONFIRMED，不会自动使用 FORCE。
  • CE 已经单独打开后再加载驱动，早期建立的句柄和枚举状态不会自动重建；关闭 CE 后从 KSword 重启。
r0_required

取消启动，回 KSword 加载驱动。

bridge_not_ready

CE 已创建但桥接没确认 Ready。关闭该 CE，不要继续扫描。

launch_failed

随包 CE、桥接 DLL 或目录结构不完整，重新解压整套插件载荷。

依据：CheatEngineExecutablePlugin/LauncherMain.cpp、10_ksword_bridge.lua、KswordCeBridge.cpp。

06

进程操作不能只看 PID

结束、挂起、保护级别、隐藏或批量操作前先刷新。

KSword 用 PID + creationTime100ns 识别进程，因为退出后的 PID 会被复用。停留很久的旧行可能已经不是原进程。

  • 应用聚合行的右键和批量动作会作用于组内全部真实成员，不是只操作当前显示的一行。
  • “进程友好视图”和父子树视图表达不同关系；在判断父进程链前切回父子树。
  • PID 0、PID 4、当前 KSword 进程和关键系统进程不要作为写操作测试目标。
  • 隐藏进程前记录路径、创建时间和原 PID；恢复依赖驱动保存的记录。恢复完成前不要卸载驱动。
  • R3 与 R0 枚举不一致是证据，不要为了“让列表一致”直接删除或隐藏对象。

依据：进程 identity、应用聚合批量动作、R0 visibility 记录。

07

内存读取成功不代表写入条件满足

读正常、写失败

页保护、驱动写策略或目标状态拒绝写入。CE 桥接不接管 VirtualProtectEx，也不会自动 FORCE。

Partial Copy

某个分片未完整返回。先确认目标没有退出或更换，再缩小地址范围；不要把部分数据当完整扫描结果。

内存区域枚举停住

桥接会拒绝零长度、越界或不覆盖查询地址的区域，防止 CE 无限循环。优先检查驱动/客户端是否混版。

PTE/内核内存页面不可用

先看对应 DynData item 和 Capability，不要只看设备 Loaded。

  • 目标进程重启后，旧地址、旧句柄和旧扫描结果全部作废。
  • 修改前保存原字节，不要只记修改后的值。
  • 跨多个区域的大范围读写应关注实际完成字节数，而不是只看函数是否返回。

08

文件 Unlocker 不是“自动关闭所有占用”

解锁时必须手动确认具体进程和句柄。

项目特意取消了无选择的自动解锁路径，避免关闭错误进程里的同名或相关句柄。关闭远程句柄可能让持有进程崩溃、丢失未写入数据或进入异常状态。

  1. 1
    先查看文件占用列表。

    核对进程路径、PID、创建时间和句柄类型。

  2. 2
    优先正常退出持有程序。

    只有无法正常释放时才使用关闭句柄。

  3. 3
    一次只处理一个确认过的持有者。

    每次处理后重新刷新占用列表，再决定是否继续。

  4. 4
    再执行移动、删除或替换。

    不要把“列表暂时为空”当作文件内容已经安全落盘。

  • 映射文件反查显示 Unsupported 时，只能说明当前驱动缺接口，不能证明没有进程映射该文件。
  • 文件恢复、删除、完整性标签和强制操作前，先复制原文件或记录元数据。

依据：Unlocker 必须手动选进程的防误触改动、文件映射 R0 查询。

09

内核页先采证，再修改

回调移除、Hook 修改和驱动卸载都应视为会改变被调查系统。

先导出当前地址、所属模块、签名、来源视图和时间，再执行修改。修改后重新刷新，而不是继续使用旧表格判断结果。

  • 回调列表和模块状态会变化；操作前最后刷新一次，并核对目标仍属于同一模块。
  • 删除第三方安全驱动回调可能破坏其内部状态，测试应放在可回滚虚拟机。
  • 驱动调试输出页只显示通过当前内核筛选器的消息；“没有日志”不等于代码没有执行。
  • 页面显示 Partial/Unsupported 时保留原始状态，不要把缺失字段补成“正常”。
  • 卸载 KswordARK 前，先关闭 CE、停止持续监控并恢复由驱动维护的临时状态。

10

网络页面里有些功能会改变系统状态

抓包与 NIDS

主要用于观察。NIDS 告警不是自动阻断结论，需要结合连接、进程和时间线确认。

终止连接与限速

会直接影响现有业务连接；执行前记录 PID、端点和协议。

HTTPS 分析

可能涉及本地代理、系统代理配置和证书状态，不是纯只读功能。

  1. 启用 HTTPS 分析前记录当前 Windows 代理设置。
  2. 结束后先在 KSword 中停止代理，再检查系统代理是否恢复。
  3. KSword 异常退出后若浏览器突然无法联网，先查系统代理和本地监听端口。
  4. 不要同时运行多个会修改系统代理的工具。

11

插件“安装成功”和“运行协议正常”是两件事

  • 市场插件包应完整下载、校验并解压；不要把源码文件当作运行入口，实际入口由 plugin.json 的 runtime/entrypoint 决定。
  • 可执行插件通过 JSON Lines 报告 ready、进度、结果和完成事件；原始文本或不合法 JSON 不会自动变成结构化扫描结果。
  • 扫描页长时间停在等待状态时，先看插件进程是否退出、stderr 和协议事件，不要只重开 UI。
  • 取消任务只保证宿主发出终止/取消流程；插件自身创建的子进程或外部状态仍需检查。
  • 更新插件时先关闭其运行实例，避免旧 DLL/EXE 仍被占用。
CE 插件是 hybrid executable，不是普通扫描插件。

它有独立的 driver check、launch、tab 和 info 命令，并维护一条持续的驱动会话。

依据：PluginHost.cpp、插件 manifest 和 scan-table 协议。

12

注册表、启动项、服务和磁盘编辑都先准备回滚材料

注册表

修改前导出目标键，不要只截屏。值类型、数据和权限都要保留。

启动项/服务

禁用前记录原启动类型、ImagePath、账户和依赖关系。删除服务前先确认不是共用驱动服务。

磁盘编辑

任何原始扇区写入前先保存目标范围或完整镜像；不要在系统盘上测试写入。

  • “优化”不代表对所有机器安全。逐项应用，重启验证后再继续下一组。
  • 服务停止成功不代表其驱动对象、设备或过滤器已安全清理。
  • 磁盘写入后的撤销依赖你保存的原始字节，不依赖 UI 历史记录。

13

做过 R0 修改时，退出顺序也有要求

  1. 1
    停止新的扫描、监控和插件任务。

    等待 Current Operations 清空或明确取消。

  2. 2
    关闭 CE 和其他持有 KswordARK 设备句柄的插件。

    防止旧会话继续调用正在卸载的驱动。

  3. 3
    恢复临时修改。

    包括隐藏进程、代理设置、已知的测试状态和可恢复的系统改动。

  4. 4
    导出日志和证据。

    修改后的刷新结果与修改前快照应一起保存。

  5. 5
    最后再卸载驱动或退出 KSword。

    不要把卸载驱动当作自动恢复所有内核修改的方法。

14

按症状定位到正确层级

所有 R0 页面都不可用

先查设备句柄、管理员权限、服务和签名，不要先换 profile。

只有部分 R0 页面不可用

查该功能的 IOCTL、Missing items 和 Capability，通常不是整个驱动失败。

CE 能启动但没有自动打开目标

桥接 DLL 初始化或延迟 openProcess(pid) 失败。关闭后从 KSword 重启。

CE 读正常但写失败

写策略或页面条件不满足；桥接不会 FORCE，也不接管改页保护。

文件仍提示占用

刷新占用列表，确认是否还有映射、第二个句柄或新创建的进程实例。

网络工具退出后无法联网

先查系统代理、证书和本地代理进程，不要先重置整个网络栈。

插件安装完成但没有结果

查看 manifest 入口、插件退出码、stderr 和 JSONL 协议事件。

更新后出现大量 Unsupported

检查 EXE、SYS、profiles 和插件是否来自同一个 Release。

提交 Issue 至少附带

版本组合

KSword、SYS、插件和 profile 来源。

目标身份

PID、路径、创建时间和 Windows Build。

R0 状态

设备打开结果、协议错误、Missing items 和 Capability。

精确错误

Win32 Error、NTSTATUS、事件码和发生时间。

操作顺序

驱动、KSword、插件、CE 的启动顺序，以及中途是否替换文件。

提交 GitHub Issue ↗