安全检查监控(secwatch) 指南

在界面上查看路由到组织(csn)的 SQL 注入二次判定结果(通知/复核/记录)，并通过以组织 SK 读取的只读 API 查询相同内容，使 AI 能够定期检查异常迹象。

🛡️ 前往安全检查监控 →

📋 概览

GIIP 的 secwatch(基于 Jev 的 SQL 注入二次判定)会把采集器(lssn)发来的可疑事件，经由网关的一次确定性规则 + 二次 AI 判定进行分类，写入 tKVSSecurityCheck，并把每条判定分为路由对象。

路由(kscRoutedTo)	界面显示	含义
alert	通知	疑似泄露/写入尝试或高可信度攻击 —— 立即通知对象
review	复核	存在攻击可能但未达自动通知阈值 —— 需人工复核对象
log	记录	判定为正常/噪声 —— 不通知，仅记录数量

界面(/zh-CN/admin/secwatch-monitor)会按时间段(最近 1 小时/6 小时/24 小时/7 天)和路由对象(全部/通知/复核/记录)筛选并展示这些结果。该界面对登录用户开放，只显示路由到本组织(csn)的结果(由服务端 SP 保障)。

🔎 如何阅读界面

界面由两个区域组成。

1. 采集覆盖率面板 —— "正在检查什么，哪里出现了异常"。按来源显示检查件数(scanned)、检测件数(flagged)和最后检查时刻，flagged 为 0 时为 🟢 正常，1 件以上时为 🔴 异常。即使没有检测到异常，也能确认"检查仍在运行"。
2. 判定结果卡片 —— 每条判定对应 1 张卡片。显示项目:

界面项目	字段	含义
时刻	kscRegdt	判定写入时刻
路由徽章	kscRoutedTo	通知(alert)/复核(review)/记录(log)
事件类型	kscFactor	事件种类(secevt_*)
注入概率	kscIsInjection	SQL 注入/攻击准备概率(0~1，界面显示为 %)
严重度	kscSeverity	0 噪声 · 1 侦察 · 2 枚举·读取 · 3 认证信息·个人信息读取 · 4 写入·权限操纵
攻击类型	kscAttackType	分类后的攻击种类
模式	kscPatternNo	相同手法(csn 内模式序号) —— 用于追踪重复攻击
攻击者 IP	kscActorIp	攻击来源 IP(用于追踪·封堵)
标志	kscIsInjection/kscDataExtracted/kscWriteAttempt	各概率达到 0.7 以上时显示注入/数据泄露/写入尝试徽章
可信度	kscConfidence	分类/严重度判定的可信度(0~1)
引擎	kscEngine	判定引擎
采集器	kscKey	上报结果的采集器(lssn)
路由理由	kscWhy	网关留下的路由事由

注入概率·数据泄露·写入尝试为 0~1 的概率值，界面将 0.7 以上视为"成立"并显示徽章。

🔌 API 参考 (只读 —— 供 AI/外部客户端使用)

这是用组织标识值(csn)和该组织的密钥(SK)读取与界面相同内容的只读 API。通过通用分发器 giipApiSk4 调用两个 SP。不包含数据写入·判定·封堵功能。

通用调用约定

项目	值
方法	POST (或 GET)
URL	https://giipfaw.azurewebsites.net/api/giipApiSk4
正文(form-urlencoded) 或查询	text=<命令>, token=<SK>, jsondata=<JSON>

• text 的第一个 token 是命令名称，之后的 token 是与 jsondata 的键一一对应的字段名。不写某个 token 时，该参数使用 SP 默认值(下方示例是最安全的形式)。
• token 中填入组织的 SK。SK 只返回该 SK 所属组织(csn)的结果(即使不单独传 csn，也会自动限定为该组织)。
• 响应始终为 HTTP 200，正文为 { "data": [ ... ], "debug": { ... } } 格式。认证/参数错误也以 HTTP 200 返回，data[0] 中包含 { "RstVal": 401|403, "RstMsg": "..." } —— AI 必须先确认 data[0].RstVal。

(1) 判定结果查询 —— KVSSecurityCheckWindow

字段(jsondata)	必填	含义
minutes	可选	查询时间窗(分钟)。默认 60，最大 10080(7 天)。1 小时=60 / 6 小时=360 / 24 小时=1440 / 7 天=10080
routedTo	可选	alert/review/log 之一。省略则为全部

请求示例 (最近 24 小时全部 —— 最安全的默认形式)

export GIIP_API_BASE_URL="https://giipfaw.azurewebsites.net"
export GIIP_SK="仅在运行时设置"

curl --fail-with-body -X POST "${GIIP_API_BASE_URL}/api/giipApiSk4" \
  --data-urlencode "text=KVSSecurityCheckWindow minutes" \
  --data-urlencode "token=${GIIP_SK}" \
  --data-urlencode 'jsondata={"minutes":1440}'

请求示例 (最近 24 小时中仅通知对象)

curl --fail-with-body -X POST "${GIIP_API_BASE_URL}/api/giipApiSk4" \
  --data-urlencode "text=KVSSecurityCheckWindow minutes routedTo" \
  --data-urlencode "token=${GIIP_SK}" \
  --data-urlencode 'jsondata={"minutes":1440,"routedTo":"alert"}'

成功响应 (每条判定对应 data[] 中一行)

{
  "data": [
    {
      "kscsn": 0, "kscKey": "12345", "kscFactor": "secevt_...",
      "kscIsInjection": 0.97, "kscAttackType": "...", "kscSeverity": 4,
      "kscDataExtracted": 0.10, "kscWriteAttempt": 0.95, "kscConfidence": 0.9,
      "kscEngine": "...", "kscRoutedTo": "alert", "kscActorIp": "...",
      "kscPatternNo": 1, "kscStatus": "...", "kscRegdt": "...", "kscWhy": "..."
    }
  ],
  "debug": { }
}

• 每一行与界面卡片的项目一一对应(参见上方"如何阅读界面"表)。
• SK/AK/密钥/DB 连接信息不会包含在任何响应中。

(2) 采集覆盖率查询 —— KVSSecurityCoverageWindow

这是"已检查但未发送(含正常)"的按来源汇总。与界面顶部覆盖率面板内容相同。

字段(jsondata)	必填	含义
minutes	可选	查询时间窗(分钟)。默认 1440，最大 10080

请求示例

curl --fail-with-body -X POST "${GIIP_API_BASE_URL}/api/giipApiSk4" \
  --data-urlencode "text=KVSSecurityCoverageWindow minutes" \
  --data-urlencode "token=${GIIP_SK}" \
  --data-urlencode 'jsondata={"minutes":1440}'

成功响应

{
  "data": [
    { "ksvSource": "...", "ksvSystem": "...", "scanned": 1200, "flagged": 0, "lastTs": "...", "status": "normal" }
  ],
  "debug": { }
}

• status 在 flagged 为 0 时为 normal，1 件以上时为 anomaly。

错误响应(两个 API 通用)

包含在 data[0] 中返回(HTTP 状态码始终为 200)。

条件	RstVal	RstMsg
SK 缺失或无效	401	Invalid sk
请求 csn 与 SK 的 csn 不同(跨 csn 阻断)	403	csn mismatch (sk 의 csn 과 다름)

⚠️ 安全: 请勿把 SK 放入 URL、issue、代码仓库、提示正文、日志中。只能从运行时环境变量或密钥存储中传入。

🤖 AI 调用固定流程 (异常迹象判定)

1. 按组织查询: 用要检查的各组织的 SK 调用 KVSSecurityCheckWindow。时间窗与检查周期一致(例如每小时检查则 minutes=60，每日一次则 minutes=1440)。
2. 确认认证: 若响应的 data[0].RstVal 为 401/403，则报告该组织 SK 错误或无法访问，并跳到下一个组织。
3. 异常迹象判定: 在 data[] 中，只要有任意一行的 kscRoutedTo 为 alert(通知)或 review(复核)，就报告为异常迹象。若仅有 log(记录)，则视为正常记录。
4. 优先级排序: 报告时按 kscSeverity(严重度 0~4)和 kscIsInjection(注入概率)从高到低排序，并用 kscActorIp·kscPatternNo 一并标注是否存在同一攻击者/同一手法的重复。
5. 覆盖率交叉确认: 用 KVSSecurityCoverageWindow 确认各来源是否实际在被检查。若某来源的 status 为 anomaly，则优先检查该来源；若预期的来源在覆盖率中根本不存在，则一并报告为"可能采集缺失"。
6. 全组织扫描: 对账号可访问的每个组织(csn)重复 1~5。SK 以组织为单位，因此要检查多个组织时，需用各组织的 SK 分别调用。

🛠 问题排查

症状	原因	解决
界面显示"拒绝访问"	已登录但没有该组织(csn)的上下文/归属	用归属于该组织的账号登录。通过 API 使用该组织 SK 即可无需界面查询
API data[0].RstVal=401	SK 缺失或无效	在 token 中传入正确的组织 SK(环境变量)
API data[0].RstVal=403	请求 csn 与 SK 的 csn 不同	不要单独传 csn，只使用该组织 SK(由 SK 决定 csn)
data 为空数组	该时间窗内没有该组织的判定结果	视为正常(无异常迹象)。可增大 minutes 后重新查询
覆盖率为空	该时间窗内没有采集覆盖率汇总	确认采集器是否在运行，并增大 minutes 后重新查询

API 参考

本指南在上方"🔌 API 参考"一节中自完整地包含了 API 详情(端点·参数·响应·错误)。没有单独的 API 指南。

---

版本: 1.0 最后更新: 2026-10-30 变更记录: giip 4314 —— 新增 secwatch 安全检查监控用户指南。文档化判定结果(KVSSecurityCheckWindow)·采集覆盖率(KVSSecurityCoverageWindow) SK 只读 API，并包含 AI 异常迹象判定固定流程。 源文件: giipv3/public/help/secwatch.zh-CN.md