opencode-build/skills/pyspark-sql-guardrails/SKILL.md

name, description

name	description
pyspark-sql-guardrails	当生成、展示、评审或执行 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 自带脚本：

scripts/sql_guard.py       校验库
scripts/validate_sql.py    命令行入口
scripts/test_sql_guard.py  标准测试集

校验一条 SQL：

python scripts/validate_sql.py "SELECT 1"

从文件校验：

python scripts/validate_sql.py --file query.sql

JSON 输出：

python scripts/validate_sql.py --json "SELECT 1"

允许 overwrite 时：

python scripts/validate_sql.py --allow-overwrite "INSERT OVERWRITE target SELECT * FROM source"

输出格式

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。