# 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`
- `X-Api-Key`：`ak_3ebc8929866e41689ab373c2c1a383b6`
- `X-Api-Secret`：`sk_6fde3569aaa44b29b226a7264623778e0a95e22677b746969f97f193ac4ae581`

## 2. 认证方式
### 2.1 Header 鉴权
每次请求必须携带以下请求头：
- `X-Api-Key`
- `X-Api-Secret`

### 2.2 凭证发放与生命周期
- 凭证来源：`system` 用户管理。
- 用户新增时：若凭证为空，系统自动生成 `apiKey/apiSecret`。
- 用户编辑时：默认保持原值不变；仅当凭证字段被设置为空时，重新生成。
- 服务启动时：会对缺失凭证的用户自动初始化。

### 2.3 认证失败返回
- HTTP 状态：`200`
- 业务码：`code=401`
- 示例：
```json
{
  "code": 401,
  "msg": "apiSecret 错误"
}
```

## 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",
  "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`、`callerId`、`reqData`。
- `reqData` 内部可直接放三类网关原始入参，不强制重组。
- 系统会优先使用顶层字段做 ACL 与审计，`reqData` 用于内容检测与原文追溯。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| sourceIp | string | 是 | 来源 IP（ACL IP 规则依赖） |
| path | string | 是 | 请求路径（ACL 接口规则依赖） |
| method | string | 是 | 请求方法（ACL 接口规则依赖） |
| interfaceType | string | 是 | 接口类型：`AGENT` / `LLM` / `VLM`（分流） |
| 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 | 否 | 原始业务参数，统一纳入规则匹配语料 |

## 4. 响应体
### 4.1 成功响应结构
```json
{
  "code": 200,
  "msg": "来源IP不在白名单；命中攻击特征；命中内容DLP规则",
  "data": {
    "requestId": "req-001",
    "traceId": "trace-001",
    "decision": "BLOCK",
    "alerted": true,
    "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` 成功，`401` 认证失败 |
| msg | string | 命中说明汇总（`hits.message` 去重后以 `；` 拼接）；未命中时为“未命中规则，允许通过” |
| data.requestId | string | 请求 ID |
| data.traceId | string | 链路 ID |
| data.decision | string | 最终决策：`ALLOW` / `BLOCK` |
| data.alerted | boolean | 是否命中任意规则 |
| 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）
```bash
curl -sS "http://ip:6201/open-api/openapi/guard/check" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ak_3ebc8929866e41689ab373c2c1a383b6" \
  -H "X-Api-Secret: sk_6fde3569aaa44b29b226a7264623778e0a95e22677b746969f97f193ac4ae581" \
  -d '{
    "sourceIp":"10.0.0.1",
    "path":"/api/llm/chat/completion/V2",
    "method":"POST",
    "interfaceType":"LLM",
    "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"
        }
      ]
    }
  }'
```

## 9. 对接注意事项
- 顶层必填字段：`sourceIp`、`path`、`method`、`interfaceType`、`callerId`、`reqData`。缺失会返回 `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 等）：便于运营统计与分流。