llh
/
llm-guard-server
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
llm-guard-server/doc/open-api-interface.md

18 KiB
Raw Blame History

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
  • 示例：
{
  "code": 400,
  "msg": "reqData 不能为空"
}

3. 检测接口

3.1 接口定义

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

3.2 请求体

{
  "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 请求体示例

{
  "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 成功响应结构

{
  "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

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

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_* 日志。