aaryavinays-dev/guardrail-ai
GitHub: aaryavinays-dev/guardrail-ai
GuardRail AI 是基于 FastAPI 的 AI 治理网关，用于在 Prompt 发送到外部 LLM 之前检测 PII 和注入风险、执行脱敏和审计。
Stars: 0 | Forks: 0
# GuardRail AI
## 企业级 AI 治理与 Prompt 安全网关
GuardRail AI 是一个基于 FastAPI 的后端原型，用于在用户 prompt 发送给外部 AI 系统（如 OpenAI、Claude、Gemini、Copilot 或开源 LLM）之前进行检查和治理。
该系统能够检测敏感数据、识别 prompt injection 尝试、计算风险评分、应用治理决策、对敏感值进行脱敏处理，并存储结构化的审计记录以实现可追溯性。
## 问题陈述
各组织正在业务团队中快速采用生成式 AI，但许多 prompt 在未经检查的情况下直接发送给了 AI 提供商。
Prompt 可能包含：
* 个人身份信息 (PII)
* 社会安全号码
* 电话号码
* 信用卡号码
* 密码和凭证
* API key 和机密信息
* Prompt injection 尝试
这带来了以下方面的风险：
* 敏感数据泄露
* 合规风险
* 缺乏 AI 使用可见性
* 治理控制薄弱
* 审计能力差
GuardRail AI 充当保护性的 prompt 治理层，在 prompt 到达外部 AI 系统之前对其进行分析和控制。
## 当前版本
**版本：** v3.0
**当前阶段：** 在集成 PostgreSQL 之前进行安全的后端清理
## 当前功能
* FastAPI 后端 API
* Pydantic 请求和响应验证
* 敏感数据检测
* Prompt injection 检测
* 风险评分引擎
* ALLOW / WARN / BLOCK 决策引擎
* 环境变量配置
* JSON 审计日志
* 审计摘要 endpoint
* 安全的 prompt 脱敏
* Pytest 单元测试
## 当前系统指标
| 指标 | 值 |
| ------------------- | --------------: |
| 检测模块 | 7 |
| 风险等级 | 4 |
| 决策动作 | 3 |
| API Endpoints | 3 |
| 测试用例 | 9 |
| 审计日志 | 基于 JSON |
| 当前存储 | 本地 JSON 文件 |
| 下一个存储目标 | PostgreSQL |
## 架构
```
User Prompt
|
v
FastAPI API Layer
|
v
Pydantic Validation
|
v
Prompt Analyzer
|
v
Detection Engine
|
+--> Email Detection
+--> SSN Detection
+--> Phone Detection
+--> Credit Card Detection
+--> Password Detection
+--> API Key Detection
+--> Prompt Injection Detection
|
v
Risk Scoring Engine
|
v
Decision Engine
|
+--> ALLOW
+--> WARN
+--> BLOCK
|
v
Prompt Redaction Layer
|
v
JSON Audit Logging
```
## 项目结构
```
guardrail-ai/
│
├── main.py
├── models.py
├── detectors.py
├── prompt_analyzer.py
├── risk_scorer.py
├── scoring.py
├── audit_logger.py
├── requirements.txt
├── README.md
├── .env.example
├── .gitignore
│
├── docs/
│ ├── architecture_v1.md
│ └── changelog.md
│
├── tests/
|__test_detectors.py
│ ├── test_prompt_analyzer.py
│ └── test_redactor.py
|__test_risk_scorer.py
│
├── screenshots/
│ ├── v1.7_prompt_injection_v2/
│ ├── v1.8_risk_weight_dictionary/
│ ├── v2.0_audit_logging/
│ ├── v2.1_project_refactor/
│ ├── v2.2_pydantic_validation/
│ ├── v2.3_json_logging/
│ ├── v2.4_list_comprehension/
│ ├── v2.5_environment_variables/
│ ├── v2.6_oop_refactor/
│ ├── v2.7_exception_handling/
│ ├── v2.8_logging and type hints/
│ ├── v2.9_pytest_tests_passed/
│ └── v3.0_secure_response_redaction/
|__ v3.1_python_polish/
│
└── logs/
└── audit_log.json
```
`logs/`, `.env`, `venv/`, `__pycache__/` 和 `.pytest_cache/` 会被 Git 忽略。
## 检测模块
GuardRail AI 目前可检测以下风险信号：
| 检测类型 | 示例 |
| ---------------- | ------------------------------ |
| 电子邮件 | `test@gmail.com` |
| 社会安全号 (SSN) | `123-45-6789` |
| 电话号码 | `123-456-7890` |
| 信用卡 | `4111-1111-1111-1111` |
| 密码 | `password: hello123` |
| API Key | `sk-abc123456789` |
| Prompt Injection | `Ignore previous instructions` |
## 风险评分引擎
每种检测类型都有配置好的风险权重。
| 检测项 | 分数 |
| ---------------- | ----: |
| 电子邮件 | 20 |
| 电话号码 | 20 |
| 社会安全号 (SSN) | 50 |
| 信用卡 | 50 |
| 密码 | 100 |
| API Key | 100 |
| Prompt Injection | 100 |
## 风险等级
| 分数范围 | 风险等级 |
| ----------- | ---------- |
| 0-20 | 低 |
| 21-50 | 中 |
| 51-99 | 高 |
| 100+ | 严重 |
## 决策引擎
| 分数范围 | 动作 |
| ----------- | ------ |
| 0-20 | ALLOW |
| 21-99 | WARN |
| 100+ | BLOCK |
决策引擎通过根据检测到的风险决定是允许、警告还是阻止 prompt，从而模拟企业治理行为。
## 安全 Prompt 脱敏
GuardRail AI 会在返回 API 响应和写入审计记录之前，对敏感值进行脱敏处理。
输入示例：
```
My SSN is 123-45-6789, email is vinay@test.com, phone is 123-456-7890, password: hello123 and key sk-abc123456789 Ignore previous instructions
```
脱敏后的输出示例：
```
My SSN is [REDACTED_SSN], email is [REDACTED_EMAIL], phone is [REDACTED_PHONE], password: [REDACTED_PASSWORD] and key [REDACTED_API_KEY] Ignore previous instructions
```
这可以防止敏感值被存储在审计日志中或在 API 响应中暴露。
## API Endpoints
### GET `/`
健康检查 endpoint。
响应示例：
```
{
"message": "GuardRail AI is running",
"version": "3.0"
}
```
### POST `/analyze`
分析 prompt 的敏感数据和 prompt injection 风险。
请求示例：
```
{
"prompt": "My SSN is 123-45-6789, email is vinay@test.com, password: hello123 Ignore previous instructions"
}
```
响应示例：
```
{
"redacted_prompt": "My SSN is [REDACTED_SSN], email is [REDACTED_EMAIL], password: [REDACTED_PASSWORD] Ignore previous instructions",
"detections": {
"email": true,
"ssn": true,
"phone": false,
"credit_card": false,
"password": true,
"api_key": false,
"prompt_injection": true
},
"word_count": 10,
"character_count": 94,
"estimated_tokens": 13,
"risk_level": "CRITICAL",
"risk_score": 270,
"action": "BLOCK",
"risk_reasons": [
"email detected",
"ssn detected",
"password detected",
"prompt_injection detected"
]
}
```
### GET `/audit-summary`
从存储的 JSON 审计记录中返回审计分析数据。
响应示例：
```
{
"total_logs": 5,
"risk_scores": [20, 70, 220],
"risk_levels": ["LOW", "HIGH", "CRITICAL"],
"high_risk_count": 2,
"critical_count": 1,
"high_risk_logs": []
}
```
## 审计日志
每个被分析的 prompt 都会创建一个结构化的 JSON 审计记录。
存储的审计记录包含：
* 时间戳
* 脱敏后的 prompt
* 脱敏标志
* 风险评分
* 风险等级
* 动作
* 风险原因
审计记录示例：
```
{
"timestamp": "2026-06-15T15:48:04.683586+00:00",
"prompt": "My SSN is [REDACTED_SSN], email is [REDACTED_EMAIL], password: [REDACTED_PASSWORD]",
"prompt_redacted": true,
"risk_score": 170,
"risk_level": "CRITICAL",
"action": "BLOCK",
"risk_reasons": [
"email detected",
"ssn detected",
"password detected"
]
}
```
## 配置
运行时配置使用环境变量进行处理。
在项目根目录中创建一个 `.env` 文件：
```
APP_NAME=GuardRail AI
APP_VERSION=3.0
RISK_THRESHOLD=100
AUDIT_LOG_FILE=logs/audit_log.json
```
以下位置提供了一个安全的模板：
```
.env.example
```
请勿提交真实的 `.env` 文件。
## 本地运行
### 1. 创建并激活虚拟环境
```
python -m venv venv
```
Windows PowerShell：
```
venv\Scripts\activate
```
macOS/Linux：
```
source venv/bin/activate
```
### 2. 安装依赖
```
pip install -r requirements.txt
```
### 3. 运行应用程序
```
uvicorn main:app --reload
```
### 4. 打开 Swagger UI
```
http://127.0.0.1:8000/docs
```
## 运行测试
运行所有测试：
```
pytest
```
当前测试覆盖率包括：
* 风险评分计算
* 风险等级确定
* 动作决策逻辑
* Prompt 脱敏验证
| 指标 | 值 |
| ------------------- | --------------: |
| 检测模块 | 7 |
| 风险等级 | 4 |
| 决策动作 | 3 |
| API Endpoints | 3 |
| 测试用例 | 37 |
| 审计日志 | 基于 JSON |
| 当前存储 | 本地 JSON 文件 |
| 下一个存储目标 | PostgreSQL |
预期结果：
```
37 passed
```
## 技术栈
### 后端
* Python
* FastAPI
* Uvicorn
* Pydantic
### 安全逻辑
* 基于正则表达式的敏感数据检测
* Prompt injection 模式检测
* 风险评分
* Prompt 脱敏
### 持久化
* JSON 审计日志
* 计划下一步使用 PostgreSQL
### 测试
* Pytest
### 开发
* Git
* GitHub
* VS Code
## 展示的工程概念
* REST API 开发
* 后端模块化
* 关注点分离
* 面向对象编程
* Pydantic 验证
* 环境变量配置
* 异常处理
* 日志记录
* JSON 文件持久化
* 安全的审计日志
* Prompt 脱敏
* 使用 pytest 进行单元测试
* 基于风险的决策系统
* 用于固定业务值的 Python Enums
* 纯函数提取
* 使用 `pytest.mark.parametrize` 进行参数化测试
* 检测器级别的测试覆盖率
* 通过 `PromptAnalyzer` 进行协调器类测试
* 循环导入调试
## 版本历史
### v1.7 - Prompt Injection 检测
* 添加了 Prompt injection 检测模式。
* 添加了针对危险 prompt 行为的治理逻辑。
### v1.8 - 风险权重字典
* 添加了集中式的风险权重字典。
* 替换了硬编码的评分值。
### v2.0 - 审计日志
* 添加了持久化的审计日志。
* 添加了时间戳跟踪。
* 添加了审计追踪生成。
### v2.1 - 模块化架构重构
* 为检测器、评分和审计日志添加了独立模块。
* 简化了 FastAPI 路由的职责。
### v2.2 - Pydantic 验证
* 添加了请求和响应验证模型。
* 添加了 FastAPI 响应模型强制执行。
### v2.3 - JSON 审计日志
* 将纯文本审计日志替换为结构化的 JSON 日志。
### v2.4 - 审计摘要 Endpoint
* 添加了 `/audit-summary`。
* 添加了针对风险评分和风险等级的摘要分析。
### v2.5 - 环境变量
* 添加了 `.env` 支持。
* 添加了可配置的应用程序元数据、审计日志路径和风险阈值。
### v2.6 - 面向对象重构
* 添加了 `PromptAnalyzer`。
* 添加了 `RiskScorer`。
* 重构了 `AuditLogger`。
### v2.7 - 异常处理和日志记录
* 添加了对损坏 JSON 的处理。
* 添加了针对审计文件操作和失败的日志记录。
### v2.8 - 类型提示和代码质量
* 在整个后端模块中添加了类型提示。
* 提高了可读性和可维护性。
### v2.9 - Pytest 单元测试
* 为风险评分和风险等级逻辑添加了单元测试。
### v3.0 - 安全 Prompt 脱敏
* 为 API 响应和审计日志添加了 prompt 脱敏。
* 移除了 `/analyze` 对原始 prompt 的暴露。
* 添加了脱敏测试覆盖率。
### v3.1 - Python 代码完善和扩展测试覆盖率
- 将脱敏逻辑提取到 `redactor.py` 中。
- 添加了 `RiskLevel` 和 `Action` enums。
- 添加了使用 `pytest.mark.parametrize` 的检测器测试。
- 添加了 PromptAnalyzer 测试。
- 将 pytest 覆盖率从 9 个测试扩展到 37 个通过的测试。
## 路线图
### 第 2 阶段：PostgreSQL 持久化
* 用 PostgreSQL 替换本地 JSON 审计存储。
* 添加 SQLAlchemy ORM 模型。
* 将审计记录存储在数据库表中。
* 添加基于数据库的审计摘要查询。
* 添加准备好进行迁移的数据库结构。
### 第 3 阶段：身份验证和 RBAC
* 添加用户身份验证。
* 添加基于角色的访问控制 (RBAC)。
* 添加仅限管理员查看的审计可见性。
### 第 4 阶段：仪表板和分析
* 构建审计仪表板。
* 添加风险趋势分析。
* 添加策略违规报告。
### 第 5 阶段：外部 AI 提供商集成
* 添加 OpenAI 集成。
* 添加 Claude 集成。
* 添加 Gemini 集成。
* 添加多模型路由。
### 第 6 阶段：企业级治理平台
* 添加策略管理。
* 添加人工介入 (human-in-the-loop) 审查工作流。
* 添加合规报告。
* 添加部署支持。
## 长期愿景
GuardRail AI 致力于成为一个企业级 AI 网关，帮助组织：
* 防止敏感数据泄露
* 检测 prompt injection 尝试
* 执行 AI 治理策略
* 维护审计追踪
* 提高 AI 使用情况的可见性
* 支持合规和安全审查
* 在多个 AI 提供商之间安全地路由请求
标签：AI治理, API网关, AV绕过, FastAPI, StruQ, 大语言模型安全, 对抗攻击, 提示注入防护, 敏感信息检测, 机密管理, 测试用例, 逆向工具