86 lines
2.4 KiB
Markdown
86 lines
2.4 KiB
Markdown
---
|
||
name: pyspark-sql-guardrails
|
||
description: 当生成、展示、评审或执行 PySpark/Spark SQL 字符串时使用。它负责将 SQL 限制在 SELECT、WITH...SELECT、INSERT...SELECT 安全白名单内，并阻止危险 DDL/DML/维护语句、堆叠语句和未确认的 INSERT OVERWRITE。
|
||
---
|
||
|
||
# PySpark SQL Guardrails（SQL 安全闸门）
|
||
|
||
## 目标
|
||
|
||
在 SQL 被展示、写入 PySpark 脚本或交给 `spark.sql` 前，先通过白名单校验。通过本 skill 只代表 SQL 语句类型安全，不代表业务逻辑正确。
|
||
|
||
## 允许
|
||
|
||
- `SELECT ...`
|
||
- `WITH ... SELECT ...`
|
||
- `INSERT INTO ... SELECT ...`
|
||
- `INSERT OVERWRITE ... SELECT ...`，但必须拿到用户明确允许 overwrite 的确认，并使用 `allow_overwrite=true`
|
||
|
||
## 禁止
|
||
|
||
- `DROP`、`DELETE`、`UPDATE`、`MERGE`、`ALTER`、`CREATE`、`REPLACE`
|
||
- `TRUNCATE`、`MSCK`、`REFRESH`、`ANALYZE`、`CACHE`、`UNCACHE`
|
||
- `VACUUM`、`OPTIMIZE`、`CALL`、`GRANT`、`REVOKE`
|
||
- 用分号堆叠多条语句
|
||
- `INSERT ... VALUES` 或不基于 `SELECT` 的写入
|
||
- 未校验就直接进入 `spark.sql(sql)`
|
||
|
||
## 使用脚本
|
||
|
||
本 skill 自带脚本：
|
||
|
||
```text
|
||
scripts/sql_guard.py 校验库
|
||
scripts/validate_sql.py 命令行入口
|
||
scripts/test_sql_guard.py 标准测试集
|
||
```
|
||
|
||
校验一条 SQL：
|
||
|
||
```bash
|
||
python scripts/validate_sql.py "SELECT 1"
|
||
```
|
||
|
||
从文件校验：
|
||
|
||
```bash
|
||
python scripts/validate_sql.py --file query.sql
|
||
```
|
||
|
||
JSON 输出：
|
||
|
||
```bash
|
||
python scripts/validate_sql.py --json "SELECT 1"
|
||
```
|
||
|
||
允许 overwrite 时：
|
||
|
||
```bash
|
||
python scripts/validate_sql.py --allow-overwrite "INSERT OVERWRITE target SELECT * FROM source"
|
||
```
|
||
|
||
## 输出格式
|
||
|
||
```yaml
|
||
sql_guard:
|
||
status: PASS | FAIL
|
||
first_keyword: select | with | insert | unknown
|
||
reason: "失败原因，PASS 时为空"
|
||
```
|
||
|
||
## 必须执行的关口
|
||
|
||
1. SQL 生成后、展示给用户前，先运行 guard。
|
||
2. PySpark 代码中出现 `spark.sql(...)` 时，SQL 字符串必须先通过 guard。
|
||
3. guard 失败时，回到 SQL 生成步骤修 SQL，不要削弱校验器。
|
||
4. guard 通过后仍然必须进入 `sql-review`。
|
||
|
||
## 规则
|
||
|
||
- 校验必须针对最终要展示或执行的那条 SQL。
|
||
- 肉眼看过不算通过。
|
||
- 一条类似 SQL 通过，不代表当前 SQL 通过。
|
||
- 字符串字面量和注释里的危险词不应误报。
|
||
- 反引号字段名里的危险词不应误报，但不建议这样命名。
|
||
- `INSERT OVERWRITE` 默认失败，除非用户明确确认 overwrite。
|