tduarte-eng/MIAGUARD

# POC Guardrails V2 基于 FastAPI 的 Guardrails API，用于在调用 LLM 之前验证用户输入。 ## 目标 在进入主流程之前拦截高风险内容（prompt injection、PII、有害内容等），并通过 Langfuse 实现可观测性，同时集成 LiteLLM。 ## 架构（摘要） - `main.py` - 暴露 HTTP 端点（`/health`, `/guards/{guard_name}/validate`） - 从 payload 中提取文本（`llmOutput`, `prompt`, `text`, `messages`） - 根据 guard 配置文件选择扫描器（`GUARDS_CONFIG`） - 拦截时返回 `400`（避免客户端 fail-open） - `guardrails_logic.py` - 包含输入/输出契约 - 定义扫描器提示词（`S01`…`S11`） - 以**顺序**方式执行扫描器，并采用 **fail-fast** 策略 - 基础设施出错时应用 **fail-secure** 行为 - `observability.py` - 初始化 Langfuse 客户端 - 创建主 trace 及每个扫描器的 observation - 为每次请求生成安全评分 - `deploy_lab.sh` - 在 ACR 中构建并推送镜像 - 更新 Azure Container App - 将 `.env` 中的变量应用到 Container App ## Guard 配置文件（endpoint） 主要端点： ``` POST /guards/{guard_name}/validate ``` 可用配置文件： - `default_guard`: `S01`, `S02` - `strict_financial_guard`: `S01`, `S02`, `S07`, `S08`, `S09` - `content_moderation_guard`: `S06`, `S10` - `test_always_block_guard`: `S11` - `full_paranoid_mode`: `S01..S10` ## 当前决策流程 1. 接收文本并从 guard 中选择扫描器列表。 2. **按列表顺序**执行扫描器。 3. 如果某个扫描器检测到风险，则中断（`break`）并拦截。 4. 如果出现 RBAC/Azure 错误，返回基础设施拦截。 5. 如果出现未映射的错误，视为风险处理（fail-secure）。 ## 本地运行 ### 前置条件 - Docker 和 Docker Compose - Python 3.11+（可选，用于不带 Docker 的本地测试） - 已配置 `.env` 文件 ### 启动本地 API ``` docker-compose up -d --build ``` ### 快速测试 ``` curl -X POST "http://localhost:8080/guards/default_guard/validate" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Quais boas práticas de estudo?", "messages": [{"role":"user","content":"Quais boas práticas de estudo?"}] }' ``` ## 部署到 Azure 官方脚本： ``` ./deploy_lab.sh ``` 该脚本执行： 1. 登录 ACR 2. 构建/推送镜像 3. 创建/更新 Container App 4. 在 Container App 中应用环境变量 ## 在 Azure 中验证变量 ### 1) 查看已配置的环境变量名称 ``` az containerapp show \ -n aca-mia-miaguard-lab-brazilsouth \ -g rg-mia-lab \ --query "properties.template.containers[0].env[].name" -o tsv ``` ### 2) 检查容器内的运行时 ``` az containerapp exec \ -n aca-mia-miaguard-lab-brazilsouth \ -g rg-mia-lab \ --command "env | grep -E 'LITELLM_|OPENAI_|LANGFUSE_'" ``` ### 3) 验证存在性而不泄露密钥 ``` az containerapp exec \ -n aca-mia-miaguard-lab-brazilsouth \ -g rg-mia-lab \ --command "python -c \"import os; ks=['LITELLM_API_KEY','LITELLM_API_BASE_URL','LITELLM_MODEL_NAME','LANGFUSE_HOST']; [print(k, bool(os.getenv(k)), len(os.getenv(k,'') or '')) for k in ks]\"" ``` ### 4) 对比本地 `.env` 与 Azure（仅名称） ``` python3 - <<'PY' from pathlib import Path import json, subprocess local = [ l.split('=',1)[0].strip() for l in Path('.env').read_text().splitlines() if l.strip() and not l.strip().startswith('#') and '=' in l ] raw = subprocess.check_output([ 'az','containerapp','show', '-n','aca-mia-miaguard-lab-brazilsouth', '-g','rg-mia-lab','-o','json' ], text=True) obj = json.loads(raw) az = [e.get('name') for e in obj['properties']['template']['containers'][0].get('env', [])] print('faltando_no_azure:', sorted(set(local) - set(az))) print('extras_no_azure:', sorted(set(az) - set(local))) PY ``` ## 故障排除 ### 错误 `RBAC: access denied` 如果出现在端点返回中： - 验证 Container App 中的 `LITELLM_API_*` 变量 - 从运行时测试对 LiteLLM 的访问 - 检查 Container Apps 之间的 ingress/IP allowlist 规则 ### 可观测性错误（Langfuse） POC 已在 `observability.py` 中包含针对 `Langfuse.__init__` 签名的兼容性补丁。 ## 后续步骤（路线图） 1. **异步调用扫描器** - 将顺序执行迁移为并行/异步执行。 - 定义结果聚合策略（例如：只要有扫描器标记风险即拦截）。 - 保持每次请求的全局超时设置。 2. **将 guardrails 扩展至输入和输出** - 保留输入验证（调用前）。 - 增加输出验证（调用后）及专用端点/流程。 - 按类型对策略进行版本控制（`input_policy`, `output_policy`）。 3. **通过 Session ID 增强可观测性** - 端到端传递 `session_id`（request -> trace -> scanners）。 - 规范化缺失时 `session_id` 的生成方式。 - 便于关联同一用户/会话的多次调用。 4. **从 Azure 捕获用户以填充 `user_id`** - 通过 Azure 环境的 headers/token 获取调用方的身份/认证信息。 - 在 Langfuse 中填充真实的 `user_id`，而非静态值。 - 在身份不可用时实现安全降级。 ## 建议的下一步 - 使用 `asyncio.gather` 实现异步扫描器 POC。 - 为输出验证引入独立的契约。 - 定义身份标准（`session_id`, `user_id`）和遥测规范。

标签：AI 防火墙, API 安全, API密钥检测, API集成, AV绕过, Azure Container Apps, CISA项目, DNS 反向解析, Docker, Fail-Secure, FastAPI, GraphQL安全矩阵, Guardrails, Langfuse, LiteLLM, LLM 安全, PII 脱敏, Python, 人工智能安全, 内容审核, 可观测性, 合规性, 安全扫描器, 安全防御评估, 提示词注入防护, 敏感数据泄露, 数据防泄漏 (DLP), 无后门, 生产环境安全, 请求拦截, 越狱防护, 输入验证, 逆向工具