# safe-sql-agent 

**Repository Path**: ywangchuang/safe-sql-agent

## Basic Information

- **Project Name**: safe-sql-agent 
- **Description**: 基于Spring Boot + Alibaba Spring AI的Text-to-SQL智能助手
用户可以用自然语言查询数据库，无需编写SQL
支持MySQL、PostgreSQL、SQL Server等
基于Redis 的会话记忆，支持多轮上下文对话
使用Reasoning + Acting 模式，AI会先探索数据库结构再生成查询
四层安全防护体系，防止Prompt注入和SQL注入攻击
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Safe SQL Agent

基于 Spring Boot 和阿里云 AI 服务构建的安全 AI 驱动的 SQL 查询助手。

## 项目简介

Safe SQL Agent 是一个 REST API 服务，使用户能够通过自然语言与数据库进行交互。它利用 AI Agent 理解用户意图并生成安全的 SQL 查询，具有多层安全防护，可防止注入攻击和提示词注入。

## 核心特性

- **自然语言转 SQL**：将自然语言查询转换为 SQL 语句
- **多层安全防护**：四层安全架构，防止各种攻击
- **会话管理**：基于 Redis 的对话历史管理
- **实时验证**：每个层面都进行输入输出验证
- **审计日志**：全面的安全监控日志记录

## 技术栈

- Java 17
- Spring Boot 3.4.5
- MySQL 数据库
- Redis（会话和状态管理）
- 阿里云 AI（DashScope）
- Spring AI Alibaba Framework

## 架构设计

### 安全防护层级

1. **第一层：输入验证（PromptInjectionDetector）**
   - 检测用户输入中的提示词注入攻击
   - 防止指令覆盖尝试
   - 阻止直接在提示词中的 SQL 注入尝试

2. **第二层：SQL 安全验证（SqlSecurityValidator）**
   - 在执行前验证 AI 生成的 SQL
   - 阻止危险的 SQL 模式：
     - UNION 注入攻击
     - 文件操作（INTO OUTFILE, LOAD_FILE）
     - 时间盲注（SLEEP, BENCHMARK）
     - 系统表访问（information_schema, mysql.user）
     - DML 操作（INSERT, UPDATE, DELETE）
     - 堆叠查询

3. **第三层：响应验证（ResponseValidator）**
   - 在响应返回用户前进行验证
   - 确保响应安全性和正确性

4. **第四层：审计日志（SecurityAuditLogger）**
   - 记录所有安全事件
   - 提供事后取证能力

### 可用工具

- **ListTablesTool**：列出数据库中的所有表
- **GetSchemaTool**：获取表结构信息
- **QueryCheckerTool**：验证 SQL 查询语法
- **ExecuteQueryTool**：安全执行验证后的 SQL 查询

## API 参考

### 聊天接口

**POST** `/api/sql/chat`

使用自然语言与 SQL Agent 进行交互。

#### 请求体

```json
{
  "message": "查询用户的数量",
  "threadId": "可选的会话ID"
}
```

#### 响应

```json
{
  "response": "查询结果...",
  "threadId": "会话ID",
  "success": true
}
```

#### 示例

```bash
curl -X POST http://localhost:8778/api/sql/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "列出所有用户表",
    "threadId": "user-123"
  }'
```

## 配置说明

### 环境变量

请配置以下环境变量：

```bash
# MySQL 数据库
MYSQL_PWD=your-mysql-password

# 阿里云 DashScope API
DASHSCOPE_API_KEY=your-dashscope-api-key
```

### 应用设置

配置文件位置：`src/main/resources/application.yaml`

主要配置项：
- 服务端口：`8778`
- 数据库连接设置
- Redis 连接设置
- 安全层启用/禁用开关

## 快速开始

### 前置要求

- Java 17 或更高版本
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- 阿里云 DashScope API Key

### 构建项目

```bash
mvn clean install
```

### 运行应用

```bash
mvn spring-boot:run
```

或者运行打包后的 JAR 文件：

```bash
java -jar target/safe-sql-agent-1.0.0.jar
```

### 运行测试

```bash
mvn test
```

## 项目结构

```
src/main/java/com/sonnie/
├── AlibabaAgentApplication.java    # 主应用入口
├── config/                          # 配置类
│   ├── RedisConfig.java            # Redis 配置
│   ├── SecurityProperties.java      # 安全属性配置
│   └── SqlAgentConfiguration.java   # SQL Agent 配置
├── constant/                       # 常量类
│   └── CommonConstant.java
├── controller/                     # REST 控制器
│   └── SqlAgentController.java      # 主要 API 端点
├── entity/                         # 数据实体
│   ├── ChatRequest.java
│   └── ChatResponse.java
├── security/                       # 安全组件
│   ├── PromptInjectionDetector.java   # 第一层安全
│   ├── SqlSecurityValidator.java      # 第二层安全
│   ├── ResponseValidator.java          # 第三层安全
│   └── SecurityAuditLogger.java       # 第四层安全
└── tools/                          # AI Agent 工具
    ├── ExecuteQueryTool.java
    ├── GetSchemaTool.java
    ├── ListTablesTool.java
    └── QueryCheckerTool.java
```

## 安全注意事项

本项目实现了多层安全防护，但安全是一个持续的过程。请注意：

1. 妥善保管 API 密钥，切勿将其提交到版本控制系统
2. 定期更新依赖项以修补安全漏洞
3. 监控审计日志以发现可疑活动
4. 配置适当的数据库用户权限
5. 在生产环境中使用 HTTPS

## 许可证

Apache License 2.0

## 作者

Your Name

## 致谢

- Spring AI Alibaba Framework
- Alibaba Cloud DashScope
- Spring Boot Community