llm-guard-server/doc/open-api-interface.md

# LLM Guard OpenAPI 对外接口文档

## 1. 文档说明
- 文档版本：v1.0
- 适用服务：`llm-guard-open-api`
- 基础路径：`/openapi`
- 字符集：`UTF-8`
- 请求/响应格式：`application/json`

## 1.1 测试环境信息
- 接口地址：`http://49.233.48.5:6201/open-api/openapi/guard/check`

## 2. 调用方式
### 2.1 请求格式
- 请求方法：`POST`
- Content-Type：`application/json`
- 鉴权要求：当前版本无需传 `X-Api-Key`、`X-Api-Secret`

### 2.2 参数错误返回
- HTTP 状态：`200`
- 示例：
```json
{
  "code": 400,
  "msg": "reqData 不能为空"
}
```

## 3. 检测接口
### 3.1 接口定义
- 方法：`POST`
- 路径：`/openapi/guard/check`
- 说明：统一执行 ACL、ATTACK、CONTENT 三类规则检测；命中时自动落库告警日志。
- 兼容性：顶层固定为 `reqData`，`reqData` 内支持原始网关请求体原样提交，不强制重组字段。

### 3.2 请求体
```json
{
  "sourceIp": "10.0.0.1",
  "path": "/api/llm/chat/completion/V2",
  "method": "POST",
  "interfaceType": "LLM",
  "model": "qwen-max",
  "callerId": "partner-a",
  "reqData": {
    "messages": [
      {
        "role": "user",
        "content": "please union select password and email test_user@demo.com"
      }
    ],
    "model": "通义千问2.5-72B",
    "stream": false
  }
}
```

### 3.3 请求字段说明
说明：
- 顶层固定字段：`sourceIp`、`path`、`method`、`interfaceType`、`model`、`callerId`、`reqData`。
- `reqData` 内部可直接放三类网关原始入参，不强制重组。
- 系统会优先使用顶层字段做 ACL 与审计，`reqData` 用于内容检测与原文追溯。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sourceIp | string | 是 | 来源 IP（ACL IP 规则依赖） |
| path | string | 是 | 请求路径（ACL 接口规则依赖） |
| method | string | 是 | 请求方法（ACL 接口规则依赖） |
| interfaceType | string | 是 | 接口类型：`AGENT` / `LLM` / `VLM`（分流） |
| model | string | 是 | 模型标识（业务关联字段） |
| callerId | string | 是 | 调用方标识（调用方追踪） |
| reqData | object | 是 | 业务原始请求体 |
| reqData.requestId | string | 否 | 请求唯一标识；为空时系统自动生成 |
| reqData.traceId | string | 否 | 链路追踪标识；为空时系统自动生成 |
| reqData.scopeCode | string | 否 | 规则作用域；默认 `GLOBAL` |
| reqData.stream | boolean | 否 | 是否流式；默认 `false` |
| reqData.text/messages/files/metadata/payload/其他任意字段 | mixed | 否 | 原始业务参数，统一纳入规则匹配语料 |

### 3.4 模型返回数据检测接口（补充）
- 方法：`POST`
- 路径：`/openapi/guard/check/response`
- 说明：用于检测模型输出内容（响应侧检测），会执行与请求侧一致的规则引擎，但检测阶段为 `RESPONSE`。
- 兼容性：顶层结构与 `/openapi/guard/check` 一致，差异是必须传 `respData`（`reqData` 可选用于补充上下文）。

#### 3.4.1 请求体示例
```json
{
  "sourceIp": "10.0.0.1",
  "path": "/api/llm/chat/completion/V2",
  "method": "POST",
  "interfaceType": "LLM",
  "model": "gpt-4o-mini",
  "callerId": "partner-a",
  "reqData": {
    "requestId": "req-demo-002",
    "traceId": "trace-demo-002",
    "scopeCode": "GLOBAL",
    "model": "gpt-4o-mini"
  },
  "respData": {
    "output": "answer: User_ID:9527 | Timestamp:2026/02/07 13:47:54",
    "content": "我的邮箱是 test_user@demo.com"
  }
}
```

#### 3.4.2 字段说明（与 `/check` 对比）
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sourceIp | string | 是 | 来源 IP（ACL IP 规则依赖） |
| path | string | 是 | 请求路径（ACL 接口规则依赖） |
| method | string | 是 | 请求方法（ACL 接口规则依赖） |
| interfaceType | string | 是 | 接口类型：`AGENT` / `LLM` / `VLM` |
| model | string | 是 | 模型标识（业务关联字段） |
| callerId | string | 是 | 调用方标识 |
| reqData | object | 否 | 请求上下文（用于 requestId/traceId/scopeCode 等补充） |
| respData | object | 是 | 模型返回数据，作为响应侧检测输入；为空时返回 `code=400` |

#### 3.4.3 响应说明
- 响应结构与 `/openapi/guard/check` 完全一致（`code/msg/data`）。
- `data.hits` 仍包含 `moduleType/eventType/ruleCode/action/message`。
- 命中响应侧规则后会写入告警日志，供“提示词防护/漏洞防护/协议安全/DDos”等页面聚合查询。

## 4. 响应体
### 4.1 成功响应结构
```json
{
  "code": 200,
  "msg": "来源IP不在白名单；命中攻击特征；命中内容DLP规则",
  "data": {
    "requestId": "req-001",
    "traceId": "trace-001",
    "decision": "BLOCK",
    "alerted": true,
    "rejectCode": 403,
    "rejectAction": "blocked",
    "rejectMsg": "内容不合规",
    "hits": [
      {
        "moduleType": "ACL",
        "eventType": "ACL_IP_WHITELIST",
        "ruleId": null,
        "ruleCode": null,
        "action": "BLOCK",
        "message": "来源IP不在白名单"
      },
      {
        "moduleType": "ATTACK",
        "eventType": "ATTACK_SIGNATURE",
        "ruleId": "sig_multi_1",
        "ruleCode": "ATTACK_SQL_MULTI",
        "action": "ALERT",
        "message": "命中攻击特征"
      },
      {
        "moduleType": "CONTENT",
        "eventType": "CONTENT_DLP",
        "ruleId": "dlp_multi_1",
        "ruleCode": "DLP_EMAIL_MULTI",
        "action": "ALERT",
        "message": "命中内容DLP规则"
      }
    ]
  }
}
```

### 4.2 响应字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| code | number | 业务码；`200` 成功，`400` 请求参数错误 |
| msg | string | 命中说明汇总（`hits.message` 去重后以 `；` 拼接）；未命中时为“未命中规则，允许通过” |
| data.requestId | string | 请求 ID |
| data.traceId | string | 链路 ID |
| data.decision | string | 最终决策：`ALLOW` / `BLOCK` |
| data.alerted | boolean | 是否命中任意规则 |
| data.rejectCode | number | 命中内容合规拦截时返回的拒绝码（来自“拒绝描述配置”） |
| data.rejectAction | string | 命中内容合规拦截时返回的动作标识 |
| data.rejectMsg | string | 命中内容合规拦截时返回的提示文案 |
| data.hits | array | 命中明细列表 |
| data.hits[].moduleType | string | 模块：`ACL` / `ATTACK` / `CONTENT` |
| data.hits[].eventType | string | 事件类型 |
| data.hits[].ruleId | string | 命中的规则/特征 ID |
| data.hits[].ruleCode | string | 命中的规则编码 |
| data.hits[].action | string | 命中动作：`ALLOW` / `BLOCK` / `ALERT` / `MASK` / `REPLACE` |
| data.hits[].message | string | 命中说明 |

### 4.3 判定规则（调用方重点）
- 是否允许放行：看 `data.decision`
  - `ALLOW`：允许通过
  - `BLOCK`：不允许通过
- 是否触发告警：看 `data.alerted`
  - `true`：已触发告警并写日志
  - `false`：未触发告警
- 命中明细：看 `data.hits[]`
  - 可用于前端展示、审计留痕、二次策略路由。

## 5. 检测范围与执行逻辑
### 5.1 检测模块
- ACL：IP 白黑名单、接口封堵、自定义组合规则
- ATTACK：攻击规则 + 特征签名（如 SQL 注入、越狱等）
- CONTENT：DLP（邮箱/手机号/证件等）、内容策略、脱敏模板策略
- 内容审核页面联动：`合规检测范围` 可控制是否执行输入侧内容检测；`词库管理` 会参与内容命中；`拒绝描述配置` 会覆盖拦截文案与返回字段。

### 5.2 语料拼接范围
系统会将下列字段聚合后参与规则匹配：
- `text`
- `path`
- `method`
- `callerId`
- `messages`（递归提取）
- `files`（递归提取）
- `metadata`（递归提取）
- `payload`（递归提取）

## 6. 告警与审计
命中规则时，系统自动写入：
- 事件表：`d_log_alert_event`
- 命中明细表：`d_log_alert_hit`

写入内容包含请求标识、模块类型、事件类型、动作、命中说明、来源 IP、调用方等字段，可直接用于审计与报表。

## 7. 三类网关报文适配建议
### 7.1 智能体接口（AGENT）
- 建议映射：`text`、`files`、`metadata`。
- 原始结构可同时放入 `payload` 便于追溯。

### 7.2 语义模型接口（LLM）
- 建议映射：`messages`。
- 补充模型请求参数到 `metadata/payload`。

### 7.3 多模态接口（VLM）
- 建议映射：`messages`（含文本/图片等多模态内容）。
- 文件或大对象建议放 `files` 并保留 `payload` 原文。

## 8. 调用示例（cURL）
### 8.1 请求侧检测：`/openapi/guard/check`
```bash
curl -sS "http://ip:6201/open-api/openapi/guard/check" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIp":"10.0.0.1",
    "path":"/api/llm/chat/completion/V2",
    "method":"POST",
    "interfaceType":"LLM",
    "model":"qwen-max",
    "callerId":"partner-a",
    "reqData":{
      "requestId":"req-demo-001",
      "traceId":"trace-demo-001",
      "scopeCode":"GLOBAL",
      "messages":[
        {
          "role":"user",
          "content":"please union select password and email test_user@demo.com"
        }
      ]
    }
  }'
```

### 8.2 响应侧检测：`/openapi/guard/check/response`
```bash
curl -sS "http://ip:6201/open-api/openapi/guard/check/response" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceIp":"10.0.0.1",
    "path":"/api/llm/chat/completion/V2",
    "method":"POST",
    "interfaceType":"LLM",
    "model":"gpt-4o-mini",
    "callerId":"partner-a",
    "reqData":{
      "requestId":"req-demo-002",
      "traceId":"trace-demo-002",
      "scopeCode":"GLOBAL",
      "model":"gpt-4o-mini"
    },
    "respData":{
      "output":"answer: User_ID:9527 | Timestamp:2026/02/07 13:47:54",
      "content":"我的邮箱是 test_user@demo.com"
    }
  }'
```

## 9. 对接注意事项
- 顶层必填字段（`/openapi/guard/check`）：`sourceIp`、`path`、`method`、`interfaceType`、`model`、`callerId`、`reqData`。缺失会返回 `code=400`。
- 顶层必填字段（`/openapi/guard/check/response`）：`sourceIp`、`path`、`method`、`interfaceType`、`model`、`callerId`、`respData`。缺失会返回 `code=400`。
- 建议调用方保证 `requestId` 全局唯一，方便对账和审计检索。
- 建议统一使用 `scopeCode=GLOBAL`（或双方约定的租户/场景编码）。
- 当 `decision=BLOCK` 时，调用方应立即拦截业务请求，不再透传下游。
- 当 `decision=ALLOW` 且 `alerted=true` 时，建议记录风控告警但允许继续处理。

## 10. 建议额外字段
建议这些字段放在 `reqData` 内（如无对应值可不传）：

- 强烈建议：
- `sourceIp`：用于 ACL 白名单/黑名单判断。
- `path`：用于接口封堵规则判断。
- `method`：与 `path` 组合判断 ACL 接口规则。
- `interfaceType`：标识 `AGENT/LLM/VLM`，便于策略分层与审计。
- `callerId`：用于区分调用方、追踪告警来源。

- 可选增强：
- `tenantId` / `appId` / `bizCode`：多租户或多应用隔离策略。
- `reqTimestamp`（毫秒时间戳）：用于请求时序核对。
- `clientVersion`：便于回溯某版本客户端行为。
- `channel`（web/app/openapi 等）：便于运营统计与分流。

## 11. 与“注入攻击防护”页面的数据关联
- 配置侧页面接口：
  - `GET /config/attack/injection/page`：页面聚合（不分页，仅返回引擎状态 + 卡片统计）。
  - `GET /config/attack/injection/rule/list`：按分类查询“细分规则管理”列表（弹窗）。
  - `POST /config/attack/injection/rule`：新增细分规则。
  - `PUT /config/attack/injection/rule`：编辑细分规则（规则名称/描述/风险等级等）。
  - `PUT /config/attack/injection/rule/status`：启停细分规则。
  - `DELETE /config/attack/injection/rule/{ids}`：删除细分规则。
  - `GET /config/attack/injection/monitor/list`：实时拦截流分页。
  - `GET /config/attack/injection/monitor/export`：实时拦截流导出。
- 页面数据来源：`open-api` 在调用 `/openapi/guard/check`（请求侧）或 `/openapi/guard/check/response`（响应侧）命中 ATTACK 规则后写入的告警日志。
- 关键落库表：`d_log_alert_event`（字段如 `module_type/event_type/rule_code/hit_message/source_ip/request_path/action_taken/occurred_at`）。
- 页面“实时拦截流”即查询 `module_type=ATTACK` 的告警事件；引擎卡片命中数由同表聚合得到。
- 若调用方需在页面展示更准确的“目标服务”，建议在请求中稳定传递 `callerId`（已写入 `d_log_alert_event.caller_id`）。
- 规则编辑与检测联动：`open-api` 规则匹配仍基于 `d_attack_rule.rule_code/category/sub_type/action/status` + `d_attack_signature`；当细分规则 `sub_type` 为 `SQL_UNION/SQL_ERROR/CMD_TIME` 等扩展值时，`open-api` 会自动归并到对应注入引擎开关（如 `INJECTION_SQL`、`INJECTION_CMD`）进行启停控制。

## 12. 与“提示词安全”页面的数据关联
- 配置侧页面接口：
  - `GET /config/attack/prompt/page`：页面聚合（不分页，仅返回引擎状态、卡片统计、防御等级、特征库数量）。
  - `GET /config/attack/prompt/rule/list`：规则管理弹窗列表（不分页）。
  - `GET /config/attack/prompt/rule/{id}`：规则详情。
  - `POST /config/attack/prompt/rule`：新增规则。
  - `PUT /config/attack/prompt/rule`：编辑规则。
  - `PUT /config/attack/prompt/rule/status`：启停规则。
  - `DELETE /config/attack/prompt/rule/{ids}`：删除规则。
  - `POST /config/attack/prompt/rule/import`：导入规则。
  - `GET /config/attack/prompt/rule/export`：导出规则。
  - `GET /config/attack/prompt/log/list`：防护日志分页（来源于 open-api 写入日志）。
  - `GET /config/attack/prompt/log/export`：导出防护日志。
- 页面数据来源：`open-api` 在调用 `/openapi/guard/check`（请求侧）或 `/openapi/guard/check/response`（响应侧）命中 ATTACK 规则后写入的告警日志。
- 关键落库表：`d_attack_rule`（提示词规则）、`d_attack_signature`（攻击特征）、`d_attack_switch`（提示词开关）、`d_log_alert_event`（命中日志）。
- 防护日志字段来源：`d_log_alert_event` 提供时间/处置动作，`d_attack_rule(category=PROMPT)` 提供分类，`d_log_alert_hit.actual_value_preview/confidence` 提供提示词片段与置信度。
- 规则编辑与检测联动：当 `d_attack_rule.category=PROMPT` 时，`open-api` 会按 `sub_type` 自动映射提示词开关键（如 `PROMPT_JAILBREAK`、`PROMPT_INJECTION`、`PROMPT_INDUCEMENT`、`PROMPT_SEMANTIC`、`PROMPT_RULE_MATCH`、`PROMPT_SIGNATURE`）决定是否参与检测。

## 13. 与“DDoS 防护”页面的数据关联
- 配置侧页面接口：
  - `GET /config/attack/ddos/page`：DDoS 页面聚合（状态、指标卡、模块开关、风险提示，不含趋势/熔断列表）。
  - `GET /config/attack/ddos/trend/list`：流量清洗趋势分页（从聚合页拆分）。
  - `GET /config/attack/ddos/circuit/list`：智能熔断监控分页（从聚合页拆分）。
  - `POST /config/attack/ddos/report/generate`：生成完整防护报表（聚合快照）。
  - `GET /config/attack/ddos/switch/config/{switchKey}`：查询单个 DDoS 模块阈值配置。
  - `PUT /config/attack/ddos/switch/config`：更新单个 DDoS 模块阈值配置。
- 页面数据来源：`open-api` 在调用 `/openapi/guard/check`（请求侧）或 `/openapi/guard/check/response`（响应侧）命中 DDoS 策略后写入告警日志。
- 关键落库表：`d_log_alert_event`（`module_type=DDOS` 的记录用于趋势与监控）、`d_attack_switch`（`DDOS_%` 开关矩阵）。
- 检测联动说明：`open-api` 会根据 `DDOS_CONN_LIMIT/DDOS_RATE_LIMIT/DDOS_TOKEN_RATE/DDOS_CONCURRENCY` 开关键执行限流判定；阈值读取自 `d_attack_switch.switch_desc` 的 JSON 配置（如 `threshold/windowSec`），命中后写入 `d_log_alert_event`，并反映到 DDoS 页面指标与熔断监控。

## 14. 与“协议安全”页面的数据关联
- 配置侧页面接口：
  - `GET /config/attack/protocol/page`：协议安全页面聚合（引擎状态 + 模块卡片，不分页）。
  - `GET /config/attack/protocol/switch/config/{switchKey}`：查询某个协议模块的深度防护配置（细分规则 + 最近违规审计）。
  - `PUT /config/attack/protocol/switch/config`：保存某个协议模块的深度防护配置（支持模块总开关 + 细分规则开关）。
  - `PUT /config/attack/protocol/probe/enabled`：启停“协议漏洞主动探测引擎”。
- 页面数据来源：`open-api` 调用 `/openapi/guard/check` 或 `/openapi/guard/check/response` 时触发协议检测，命中后写入告警日志。
- 关键落库表：
  - `d_attack_switch`：存储 `PROTOCOL_%` 模块开关与 `switch_desc` JSON（细分规则开关）。
  - `d_log_alert_event`：存储 `module_type=PROTOCOL` 的违规命中记录，作为“最近协议违规审计”数据源。
- 检测联动说明：`open-api` 在 `checkProtocolRules` 中按 `PROTOCOL_%` 模块开关和细分规则配置执行协议层检测（方法限制、头字段检查、内容类型检查、参数检查、加密与证书校验、漏洞与异常检测等）；其中漏洞/异常探测受 `PROTOCOL_PROBE_ENGINE` 控制。命中后按 `rule_code=PROTOCOL_*` 写入日志并回传命中详情。

## 15. 与“漏洞防护”页面的数据关联
- 配置侧页面接口：
  - `GET /config/attack/vuln/page`：漏洞防护页面聚合（规则库版本 + 模块卡片，不分页）。
  - `GET /config/attack/vuln/switch/config/{switchKey}`：查询单个漏洞模块配置（趋势、风险、检测逻辑、拦截样本）。
  - `PUT /config/attack/vuln/switch/config`：更新单个漏洞模块配置与开关状态。
  - `POST /config/attack/vuln/rule-base/sync`：同步漏洞规则特征库版本。
  - `POST /config/attack/vuln/asset/bind`：将漏洞补丁策略与资产（接口/调用方）关联。
  - `GET /config/attack/vuln/patch/status`：查询“高危漏洞虚拟补丁状态”卡片数据。
- 页面数据来源：`open-api` 调用 `/openapi/guard/check` 或 `/openapi/guard/check/response` 触发漏洞检测，命中后写入告警日志。
- 关键落库表：
  - `d_attack_switch`：存储 `VULN_%` 漏洞模块开关与精简检测逻辑配置（`switch_desc` JSON）。
  - `d_log_alert_event`：存储 `module_type=VULNERABILITY` 的命中事件。
  - `d_log_alert_hit`：存储命中载荷片段，用于“拦截攻击样本”展示。
- 检测联动说明：`open-api` 在 `checkVulnerabilityRules` 中按 `VULN_%` 配置执行目录遍历、XSS、CSRF、文件包含、信息泄露、规则自定义、扫描、补丁、规则库同步等检测，并按模块生成 `rule_code=VULN_*` 日志。