WG-Win-Check-Pro API 接口文档

1. 基础约定

1.1 服务地址

本地 API 默认关闭，需要在程序顶部的“接口”入口中手动启用。

启用后服务只监听本机回环地址：

http://127.0.0.1:{port}

端口默认从 11070 开始监听。如果端口已被占用，程序会从 11071 起依次递增尝试。实际地址可在“本地 API”弹窗中查看。

1.2 认证

除健康检查外，所有接口都需要 Token。

支持两种认证方式：

Authorization: Bearer <Token>

或：

X-WG-Api-Token: <Token>

Token 可在“本地 API”弹窗中查看、复制或重新生成。

1.3 请求格式

POST 接口请求体必须是 JSON 对象：

Content-Type: application/json

当前本地服务最大请求体大小为 2 MB。超过后返回 413 payload_too_large。

1.4 统一响应格式

成功：

{
  "ok": true,
  "data": {}
}

失败：

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "错误说明"
  }
}

1.5 常见 HTTP 状态码

2. 快速调用示例

PowerShell 示例：

$base = "http://127.0.0.1:11070"
$token = "<Token>"
$headers = @{ Authorization = "Bearer $token" }

Invoke-RestMethod "$base/api/v1/health"
Invoke-RestMethod "$base/api/v1/modules" -Headers $headers
Invoke-RestMethod "$base/api/v1/module/process/records?key=1234" -Headers $headers

POST 示例：

$body = @{
  pid = 1234
  includeMetadata = $true
  includeSignature = $true
} | ConvertTo-Json

Invoke-RestMethod "$base/api/v1/tool/process-dlls" `
  -Method Post `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

3. 基础接口

3.1 健康检查

GET /api/v1/health

认证：不需要。

返回字段：

示例响应：

{
  "ok": true,
  "data": {
    "app": "WG-Win-Check-Pro",
    "apiVersion": "v1",
    "enabled": true,
    "localOnly": true,
    "readOnly": false,
    "commandExecutionEnabled": false,
    "host": "WINDOWS-BU4URMF",
    "privilege": "管理员",
    "baseUrl": "http://127.0.0.1:11070"
  }
}

3.2 模块列表

GET /api/v1/modules

返回字段：

模块字段：

当前模块：

3.3 风险概览

GET /api/v1/risk/findings

返回字段：

风险字段：

4. 模块 records 接口

4.1 查询模块结果

GET /api/v1/module/{moduleId}/records

查询参数：

返回字段：

行字段：

示例：

{
  "ok": true,
  "data": {
    "moduleId": "process",
    "module": "进程排查",
    "paginated": false,
    "snapshotAt": "2026-06-21 10:20:30",
    "key": "1234",
    "keyApplied": true,
    "available": true,
    "columns": ["进程名", "PID", "PPID", "命令行"],
    "count": 1,
    "total": 1,
    "rows": [
      {
        "row": 0,
        "depth": 0,
        "cells": ["example.exe", "1234", "1000", "\"C:\\example.exe\""]
      }
    ]
  }
}

4.2 key 核心字段过滤规则

key 仅匹配以下模块的核心字段。其他模块传入 key 时不应用过滤，返回 keyApplied=false。

4.3 特殊模块说明

file

file records 是分页接口。如果尚未扫描或加载缓存，返回：

{
  "available": false,
  "reason": "尚未扫描或加载缓存",
  "hint": "可先调用 POST /api/v1/module/file/refresh 尝试加载缓存",
  "count": 0,
  "total": 0,
  "rows": []
}

activity

activity records 是分页接口。如果尚未扫描或加载缓存，返回类似 file 的不可用结构。

threat

如果尚未执行威胁检索，返回：

{
  "available": false,
  "reason": "尚未执行威胁检索",
  "hint": "可调用 POST /api/v1/module/threat/refresh 发起扫描",
  "scanning": false,
  "hasResult": false,
  "progress": {},
  "count": 0,
  "total": 0,
  "rows": []
}

5. 模块 refresh 接口

POST /api/v1/module/{moduleId}/refresh

支持模块：

risk, user, process, network, autorun, service, task, file, threat, activity

不支持模块返回：

{
  "ok": false,
  "error": {
    "code": "refresh_not_supported",
    "message": "该模块暂不支持 API 刷新"
  }
}

5.1 普通模块刷新

适用模块：

user, process, network, autorun, service, task

请求：

{}

响应：

{
  "ok": true,
  "data": {
    "status": "refresh_started",
    "moduleId": "process",
    "module": "进程排查"
  }
}

说明：

• network 刷新会触发网络连接重新采集。

• 不进入任务中心。

• 不影响 UI 自动刷新设置。

5.2 风险概览刷新

POST /api/v1/module/risk/refresh

会依次刷新核心风险模块：

user, process, autorun, service, task

5.3 文件排查 refresh

POST /api/v1/module/file/refresh

默认加载缓存：

{
  "mode": "cache"
}

触发真实扫描：

{
  "mode": "scan"
}

mode=cache 响应字段：

mode=scan 响应字段：

如果扫描正在运行，返回：

{
  "ok": false,
  "error": {
    "code": "scan_busy",
    "message": "文件扫描正在运行"
  }
}

扫描结果通过 records 分页读取：

GET /api/v1/module/file/records?offset=0&limit=500

5.4 活动痕迹 refresh

POST /api/v1/module/activity/refresh

当前只加载缓存，不触发真实扫描。

响应字段类似文件模块的 mode=cache。

5.5 威胁检索 refresh

POST /api/v1/module/threat/refresh

查询状态：

{
  "statusOnly": true
}

发起扫描：

{
  "ioc": "malware.example.com",
  "pid": 0,
  "includeSystemProcesses": false,
  "firstMatchOnly": true,
  "maxRegionSizeMB": 256,
  "maxResults": 5000
}

请求字段：

如果正在扫描，返回：

{
  "ok": false,
  "error": {
    "code": "scan_busy",
    "message": "威胁检索正在运行，请稍后再试"
  }
}

6. 事件日志原始查询接口

POST /api/v1/event/query

该接口面向 Agent 自定义查询，直接返回 Windows Event Log 原始 XML，不进行事件字段解析。

请求：

{
  "channel": "Security",
  "query": "*[System[(EventID=4624)]]",
  "limit": 100,
  "timeoutMs": 10000,
  "direction": "reverse"
}

请求字段：

响应字段：

事件项：

{
  "index": 0,
  "xml": "<Event>...</Event>"
}

7. 工具接口

7.1 文件 Hash

POST /api/v1/tool/hash

请求：

{
  "paths": [
    "C:/Windows/System32/notepad.exe"
  ]
}

即使只查询一个文件，也必须使用 paths 数组。

响应字段：

结果字段：

7.2 批量文件信息

POST /api/v1/tool/file-info

请求：

{
  "paths": [
    "C:/Windows/System32/notepad.exe"
  ],
  "includeMetadata": true,
  "includeSignature": true,
  "limit": 500
}

请求字段：

响应字段：

结果字段：

属性字段：

签名详情字段：

7.3 指定 PID 的 DLL 模块列表

POST /api/v1/tool/process-dlls

请求：

{
  "pid": 1234,
  "processName": "example.exe",
  "includeMetadata": true,
  "includeSignature": true,
  "limit": 3000
}

请求字段：

响应字段：

模块字段：

7.4 VirusTotal 查询

POST /api/v1/tool/vt

请求：

{
  "hashes": [
    "44d88612fea8a8f36de82e1278abb02f"
  ]
}

即使只查询一个 Hash，也必须使用 hashes 数组。

说明：

• 支持 MD5、SHA1、SHA256。

• 不接受文件路径，不自动计算文件 Hash。如需计算文件 Hash，请先调用 /api/v1/tool/hash。

• 查询前会检查 VT 网络可达性。

• 如果 VT 未收录，结果显示 0/0，found=false。

响应字段：

结果字段：

7.5 IP 归属查询

POST /api/v1/tool/ip-location

请求：

{
  "ips": [
    "8.8.8.8",
    "192.168.1.1"
  ]
}

即使只查询一个 IP，也必须使用 ips 数组。

说明：

• 内网、回环、本地监听、组播地址会本地分类，不进行外部查询。

• 公网 IP 使用 ip-api.com/batch?lang=zh-CN 批量查询。

• 每批最多 100 个公网 IP。

响应字段：

结果字段：

7.6 读取文件内容

POST /api/v1/tool/file-read

该接口一次只读取一个文件，用于外部 Agent 按需查看文本、配置或日志片段，避免一次返回过大的内容。

请求：

{
  "path": "C:/Windows/System32/drivers/etc/hosts",
  "mode": "text",
  "encoding": "auto",
  "offset": 0,
  "maxBytes": 262144
}

请求字段：

响应字段：

8. 命令执行接口

POST /api/v1/command/exec

命令执行接口有独立开关。即使本地 API 已启用，该接口默认仍不可用，需要在“本地 API”弹窗中手动启用“命令执行”。

请求只支持 program + args，不支持裸命令字符串。

请求：

{
  "program": "cmd.exe",
  "args": ["/c", "whoami"],
  "cwd": "C:/Users/worker",
  "timeoutMs": 10000,
  "maxOutputBytes": 1048576
}

请求字段：

响应字段：

注意：

• 不提供 stdin。

• 不做命令语义审查。

• 不自动提升权限。

• 要执行 shell 内建命令，需要显式调用 shell，例如 cmd.exe /c dir。

• 管道、重定向、通配符、环境变量展开等 shell 语法也需要显式调用 cmd.exe /c 或 powershell.exe -Command。

• 输出按文本返回，stdout 和 stderr 分别捕获；超出 maxOutputBytes 会截断并设置 truncated=true。

• 交互式命令、长时间运行的命令或等待输入的命令不适合该接口，会在 timeoutMs 后被终止。

• 外部 Agent 应自行检查和限制命令。

调用示例：

PowerShell 通用调用模板：

$base = "http://127.0.0.1:11070"
$token = "<API Token>"
$headers = @{ Authorization = "Bearer $token" }

$body = @{
  program = "cmd.exe"
  args = @("/c", "whoami /all")
  cwd = "C:/"
  timeoutMs = 10000
  maxOutputBytes = 1048576
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Method Post `
  -Uri "$base/api/v1/command/exec" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

直接执行普通程序：

{
  "program": "whoami.exe",
  "args": ["/user"],
  "timeoutMs": 10000
}

执行 CMD 内建命令、管道或重定向：

{
  "program": "cmd.exe",
  "args": ["/c", "dir /a C:\\Windows\\Temp & echo. & netstat -ano | findstr ESTABLISHED"],
  "timeoutMs": 15000,
  "maxOutputBytes": 2097152
}

执行 PowerShell 查询：

{
  "program": "powershell.exe",
  "args": [
    "-NoProfile",
    "-ExecutionPolicy",
    "Bypass",
    "-Command",
    "Get-Process | Select-Object -First 10 Name,Id,Path | ConvertTo-Json -Depth 3"
  ],
  "timeoutMs": 15000
}

指定工作目录执行：

{
  "program": "cmd.exe",
  "args": ["/c", "dir"],
  "cwd": "C:\\Users\\worker\\Desktop",
  "timeoutMs": 10000
}

未启用时返回：

{
  "ok": false,
  "error": {
    "code": "command_disabled",
    "message": "命令执行接口未启用，请在 API 接口服务窗口中手动开启"
  }
}