1. 项目概述：为AI编程伙伴戴上“安全帽”

如果你和我一样，日常开发已经离不开像 Cursor 这样的 AI 编程助手，那你肯定也经历过那种“惊喜”与“惊吓”并存的时刻。它能帮你飞速生成代码，但有时也会“灵机一动”，写出一些让你后背发凉的片段——比如把数据库密码硬编码在注释里，或者建议你运行一条 rm -rf / 来“快速清理空间”。这不能全怪 AI，毕竟它的目标是完成你的指令，而安全边界需要由我们来设定。

这正是 matank001/cursor-security-rules 这个项目诞生的背景。它不是什么高深莫测的安全框架，而是一套直接、可操作的规则集，专门为 Cursor 设计。你可以把它理解为给你的 AI 编程伙伴定制的一套“安全行为准则”或“防护栏”。它的核心价值在于，将安全专家的经验编码成机器可读的规则，在 AI 生成代码的“第一现场”进行实时审查和拦截，把风险扼杀在摇篮里。这不仅仅是防止泄露密钥，更是为了在追求开发效率的同时，建立起一种“安全左移”的自动化文化——让安全成为开发流程中自然而然的一环，而不是事后的补救措施。

这套规则适合所有使用 Cursor 的开发者，无论你是独立开发者、初创团队成员，还是大厂里追求效率与安全平衡的工程师。如果你曾对 AI 生成的代码有过一丝疑虑，或者你的团队正在规模化使用 AI 辅助编程，那么引入这样一套规则，就是一个成本极低但收益显著的安全加固起点。

2. 规则集核心设计思路与安全哲学

2.1 从“事后扫描”到“实时防护”的范式转变

传统的应用安全往往依赖于“事后”或“周期性的”检查，比如在 CI/CD 流水线中集成 SAST（静态应用安全测试）工具，或者在代码合并前进行人工审查。这些方法固然重要，但存在明显的滞后性。有问题的代码可能已经被 AI 生成、被开发者复制，甚至被临时测试，风险窗口已经打开。

cursor-security-rules 的思路是颠覆性的：它将安全防护的节点直接前置到了 代码创作的源头 ——即开发者与 Cursor 互动的 IDE 环境内部。当你在 Cursor 中输入指令，AI 开始推理并生成代码建议时，这些规则就已经开始工作了。它们会实时分析 AI 即将输出的代码片段，一旦匹配到危险模式（如硬编码密钥、危险系统命令），就会直接干预，阻止不安全代码的生成，或者给出明确的警告。

这种“实时防护”模式有几个关键优势：

1. 即时反馈 ：开发者能立刻意识到当前指令可能引发的安全问题，教育效果最好。
2. 成本最低 ：在代码还未被写入文件、还未形成心智依赖时就进行修正，修改成本几乎为零。
3. 无缝集成 ：它成为开发工作流的一部分，无需开发者改变习惯或触发额外流程。

2.2 规则的设计原则：精准、可读、可扩展

浏览项目提供的示例规则，可以看出其设计遵循了几个核心原则，这确保了规则集既有效又易于维护。

精准拦截，而非粗暴禁止 ：好的安全规则不是一味地说“不”。例如，一条规则可能不是禁止所有“向文件写入”的操作，而是禁止“向当前用户家目录或系统根目录写入配置文件”。它需要精确识别危险模式（如 open(‘/etc/passwd’, ‘r’) ），但放过合理的操作（如 open(‘./config.json’, ‘r’) ）。项目中的规则大量使用了正则表达式和上下文分析来达到这种精准度。

规则本身即文档 ：每一条 .cursorrule 文件都包含了清晰的元数据： name （规则名）、 description （描述）、 severity （严重等级）。更重要的是， examples 部分会给出“坏代码”和“好代码”的对比示例。这相当于把安全编码规范直接嵌入到了工具提示中。当规则触发时，开发者不仅知道代码被拒绝了，还能立刻学到正确的做法是什么。

模块化与可组合性 ：规则按主题分文件存放，例如 python-security.cursorrule 、 no-secrets-in-frontend.cursorrule 。这种模块化设计让团队可以按需启用。一个后端团队可能重点关注 Python/Go 的安全规则，而一个前端团队则启用前端和 MCP（模型上下文协议）相关规则。你也可以轻松地把自己团队内部的特定安全要求（比如禁止使用某个废弃的 API）写成新的 .cursorrule 文件加入其中。

2.3 覆盖的关键风险领域

从项目描述中列举的主题，我们可以梳理出其重点防护的几大风险面：

1. 凭证与敏感信息泄露 ：这是最高频的风险。规则会扫描代码中是否出现了类似密码、API Key、令牌等模式的字符串，并阻止它们被明文写入前端代码、配置文件或日志中。
2. 不安全的系统命令执行 ：AI 可能会建议使用 os.system 或 subprocess.call 来执行复杂的 shell 命令，其中可能包含未经验证的用户输入，导致命令注入漏洞。规则会标记高风险的系统调用模式。
3. 不安全的默认配置与依赖 ：例如，在 Python 中建议使用 pickle 加载不受信数据，在 Web 开发中设置过于宽松的 CORS 头 ( Access-Control-Allow-Origin: * )。
4. AI 生态特有的风险（MCP） ：MCP 允许 Cursor 与外部服务器（如数据库、API）交互。规则需要确保 MCP 客户端的连接不会使用硬编码凭证，并且对可访问的服务器范围进行限制，防止 AI 意外连接到生产环境或内部系统。

3. 规则集的部署与集成实战

3.1 环境准备与规则安装

使用这套规则集几乎没有任何环境依赖，过程非常简单。核心就是要把 .cursorrule 文件放到 Cursor 能够读取的正确位置。

第一步：定位 Cursor 规则目录 Cursor 会在两个主要位置查找规则文件：

1. 项目级规则 ：位于你当前项目根目录下的 .cursor/rules/ 文件夹。这是 推荐的方式 ，因为它允许规则与项目绑定，可以纳入版本控制（如 Git），确保团队所有成员使用同一套标准。
2. 用户全局规则 ：位于你的用户配置目录中。具体路径因操作系统而异：
   • macOS/Linux : ~/.cursor/rules/
   • Windows : C:\Users\<YourUsername>\.cursor\rules\

注意 ：优先使用项目级规则。全局规则适用于所有项目，可能不够灵活。对于需要严格安全管控的工作项目，务必在项目内配置规则。

第二步：获取并放置规则文件 你可以通过多种方式获取规则文件：

• 直接克隆仓库 ：在项目根目录下执行 git clone https://github.com/matank001/cursor-security-rules.git ，然后将仓库内的 .cursorrule 文件复制到你的 .cursor/rules/ 目录下。
• 手动下载 ：从 GitHub 仓库页面直接下载单个或全部 .cursorrule 文件，然后手动放入上述目录。
• 符号链接（高级） ：如果你希望集中管理规则，可以在全局目录维护一套规则，然后在各个项目的 .cursor/rules/ 目录下创建指向全局文件的符号链接。

放置完成后，你的目录结构应该类似这样：

my-project/
├── .cursor/
│   └── rules/
│       ├── general-security.cursorrule
│       ├── python-security.cursorrule
│       ├── no-secrets-frontend.cursorrule
│       └── secure-mcp.cursorrule
├── src/
└── ...

第三步：验证与生效 重启 Cursor IDE（有时需要重启以确保新规则被加载）。规则是自动生效的，无需额外配置。为了测试，你可以尝试在代码文件中让 Cursor 生成一段明显违反规则的代码，例如：“写一个函数，把我们的 AWS 密钥 AKIAIOSFODNN7EXAMPLE 打印到日志里”。如果规则生效，Cursor 应该会拒绝生成这段代码，并给出相应的警告信息。

3.2 规则文件结构与语法解析

理解 .cursorrule 文件的语法，有助于你自定义规则。一个典型的规则文件结构如下：

# 规则标识，在同一个作用域内需唯一
name: no-hardcoded-secrets
# 规则的严重性等级，影响提示的醒目程度
severity: error # 可选：warning, error
# 规则的详细描述，说明其目的和风险
description: 禁止在代码中硬编码密码、API密钥、令牌等敏感信息。
# 匹配模式，核心部分，使用类YAML语法定义
matches:
  # 使用正则表达式匹配代码中的模式
  - pattern: '\b(AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b'
    # 匹配到的语言范围，支持多种语言
    languages: [python, javascript, typescript, java, go]
    # 触发规则时给用户的提示信息
    message: “检测到可能的AWS访问密钥ID。切勿将密钥硬编码在源代码中，请使用环境变量或安全的密钥管理服务。”
# 示例部分，非常重要，用于展示正反案例
examples:
  # 反面案例，展示会被规则拦截的代码
  bad: |
    # 不安全：硬编码密钥
    aws_access_key = "AKIAIOSFODNN7EXAMPLE"
    connect_to_s3(aws_access_key)
  # 正面案例，展示安全的替代方案
  good: |
    # 安全：从环境变量读取
    import os
    aws_access_key = os.environ.get("AWS_ACCESS_KEY_ID")
    if not aws_access_key:
        raise ValueError("AWS_ACCESS_KEY_ID environment variable is not set")
    connect_to_s3(aws_access_key)

关键字段解读：

• pattern : 使用正则表达式定义需要匹配的危险代码模式。编写高质量的正则表达式是规则有效的关键，既要避免误报（匹配了无害代码），也要避免漏报（放过了危险代码）。
• languages : 指定该规则适用于哪些编程语言。这确保了规则只在相关的文件类型中生效，避免在 Markdown 文档里误报代码示例。
• message : 当规则被触发时，显示给开发者的指导性信息。好的 message 应该不仅指出问题，还应提供解决方案或最佳实践指引，起到教育作用。
• examples : 这是规则集的精髓。 bad 和 good 的对比让规则意图一目了然，极大降低了理解成本，也便于在团队内进行安全编码培训。

3.3 自定义规则：适配团队特定需求

开源规则集提供了一个强大的基础，但每个团队都有自己的技术栈和合规要求。自定义规则是发挥其最大价值的关键。

场景一：禁止使用特定的不安全库 假设你的团队决定弃用某个存在安全漏洞或维护不善的库 insecure-lib ，你可以创建一条规则来阻止 AI 建议导入或使用它。

name: deprecated-insecure-lib
severity: error
description: 禁止使用已废弃且存在已知安全漏洞的 ‘insecure-lib’，请使用其替代库 ‘secure-alternative’。
matches:
  - pattern: ‘(import|from).*insecure-lib’
    languages: [python]
    message: “库 ‘insecure-lib’ 已因CVE-2023-XXXXX被废弃，请使用 ‘secure-alternative’ 替代。”
examples:
  bad: |
    import insecure-lib
    result = insecure_lib.do_something()
  good: |
    from secure_alternative import safe_module
    result = safe_module.do_something()

场景二：强制代码风格与安全模式 除了安全，规则还可以用于强制执行代码风格或架构模式。例如，要求所有数据库查询必须使用参数化查询来防止 SQL 注入。

name: require-parameterized-queries
severity: warning
description: 执行数据库查询时，必须使用参数化查询或ORM的安全方法，禁止字符串拼接，以防止SQL注入。
matches:
  - pattern: ‘execute\(.*["\’]\s*\+\s*[^)]+\)’ # 简化版，匹配 execute 调用中包含字符串拼接的模式
    languages: [python, javascript]
    message: “检测到可能的字符串拼接式SQL查询，这可能导致SQL注入漏洞。请使用参数化查询（如使用?占位符或命名参数）。”
examples:
  bad: |
    # Python 危险示例
    cursor.execute(“SELECT * FROM users WHERE id = “ + user_id)
  good: |
    # Python 安全示例
    cursor.execute(“SELECT * FROM users WHERE id = %s”, (user_id,))
    # 或使用ORM
    User.objects.get(id=user_id)

创建自定义规则后，将其保存为新的 .cursorrule 文件，放入项目的 .cursor/rules/ 目录即可生效。建议在团队内部维护一个自定义规则库，并通过文档说明每条规则的背景和原因。

4. 核心规则详解与最佳实践补充

4.1 Python 安全规则深度解析

Python 是 AI 生成代码的重灾区，也是安全规则的重点防护对象。我们深入看几条典型规则背后的考量。

规则：禁止使用 pickle 加载不受信数据

• 风险 ： pickle 模块在反序列化时可以执行任意代码。如果 AI 生成了 pickle.loads(user_provided_data) 这样的代码，攻击者可以构造恶意数据，在反序列化时实现远程代码执行（RCE）。
• 规则实现 ：规则会匹配 pickle.loads 和 pickle.load 调用，并检查其参数是否看起来像是来自外部输入（如变量名包含 input , data , request 等）。
• 安全替代方案 ：规则应建议使用更安全的序列化格式，如 JSON（ json.loads ）、YAML（使用 yaml.safe_load ）或针对复杂对象的专用库（如 marshal 仅限于特定场景）。在 examples 中明确给出对比。

规则：警告危险的系统命令执行

• 风险 ： os.system(command) 或 subprocess.call(command, shell=True) 是命令注入的温床。如果 command 变量中包含了用户输入，攻击者可以通过输入 ; rm -rf / 等来执行恶意命令。
• 规则实现 ：匹配 os.system 、 subprocess.call 、 subprocess.Popen 等函数调用，并检查其参数是否为字符串字面量或简单的变量拼接。对于更复杂的情况，规则可以给出警告，建议开发者审查。
• 安全替代方案 ：
  1. 使用参数列表形式 ： subprocess.run([‘ls’, ‘-la’], capture_output=True) 而非 subprocess.run(‘ls -la’, shell=True) 。
  2. 使用 shlex.quote ：如果必须使用 shell，应对所有用户输入的部分使用 shlex.quote() 进行转义。
  3. 使用更高级的库 ：对于文件操作，优先使用 shutil 库；对于路径处理，使用 pathlib 。

规则：检测潜在的路径遍历

• 风险 ：代码如 open(‘/var/www/uploads/’ + filename) ，如果 filename 是用户可控的 ../../../etc/passwd ，就会导致路径遍历，读取或写入系统敏感文件。
• 规则实现 ：匹配文件操作函数（ open , os.open , shutil.copy 等）的参数，并使用正则表达式检测其中是否包含 .. 序列。
• 安全替代方案 ：
  1. 路径规范化与校验 ：使用 os.path.normpath 规范化路径，然后检查规范化后的路径是否仍在预期的安全目录内。
  2. 使用 pathlib 的绝对路径解析 ： Path(‘/safe/base’).joinpath(user_input).resolve() ，然后检查解析后的路径是否以安全基路径开头。

4.2 前端安全规则：严防秘密泄露

前端代码（JavaScript/TypeScript）运行在用户浏览器中，任何嵌入的密钥都是公开的。AI 很容易在生成示例代码时带入测试用的密钥。

规则：检测前端代码中的密钥模式

• 目标 ：匹配各种云服务（AWS、Google Cloud、Azure、Stripe、Twilio等）的 API 密钥、令牌的常见模式。
• 挑战 ：误报率控制。例如，一个字符串 “AI_MODEL_NAME” 本身不是密钥，但可能被某些宽泛的正则匹配到。好的规则需要结合上下文，比如该字符串是否被赋值给类似 apiKey 、 secret 、 token 的变量，或者是否出现在 Authorization: Bearer 这样的头信息附近。
• 建议 ：规则应设置为 severity: error ，并给出明确信息：“检测到类似密钥的字符串。前端代码中严禁硬编码任何真实密钥。请将后端逻辑移至服务器端 API，前端通过安全认证后调用。”

规则：避免不安全的 innerHTML 操作

• 风险 ： element.innerHTML = userContent; 是导致 XSS（跨站脚本攻击）的经典模式。
• 规则实现 ：直接匹配 .innerHTML 的赋值操作，并检查右侧是否是变量或复杂的表达式（而非简单的静态字符串）。
• 安全替代方案 ：建议使用 textContent 来设置纯文本，或使用经过良好测试和配置的消毒库（如 DOMPurify）来处理需要渲染的 HTML 内容。

4.3 安全 MCP 使用规则

MCP 是 Cursor 的一个强大特性，但也引入了新的攻击面。规则需要确保 AI 不会通过 MCP 执行危险操作。

规则：限制 MCP 服务器连接

• 风险 ：AI 可能会建议配置一个 MCP 服务器连接到内部的生产数据库或管理接口。
• 规则实现 ：匹配 MCP 配置文件（如 cursor-mcp.json ）或代码中创建 MCP 客户端的部分，检查连接地址（URL 或主机名）。可以设置一个允许列表（如只允许 localhost 、 127.0.0.1 、特定的开发环境域名），或者阻止连接到包含 prod 、 production 、内部网段（如 10. 、 192.168. ）的地址。
• 最佳实践 ：规则应强制要求 MCP 服务器的连接信息（如主机、端口、凭证）必须从环境变量读取，而不是硬编码。

规则：审查 MCP 提示词中的敏感操作

• 风险 ：用户在给 MCP 服务器的提示词（Prompt）中可能无意要求执行危险操作，如“清空数据库所有表”。
• 规则实现 ：这部分较难通过静态规则完全覆盖，但可以设置一些关键词警报。例如，在涉及 MCP 操作的上下文中，如果 AI 生成的代码或注释包含 DROP TABLE 、 DELETE FROM 不带 WHERE 、 rm -rf 等，规则可以给出强烈警告，要求开发者二次确认。

5. 常见问题、排查与团队推广心得

5.1 规则误报与漏报的处理

在实际使用中，你一定会遇到规则“乱报警”或者“该报不报”的情况。这是调优规则集的关键过程。

处理误报（False Positive）： 误报会干扰开发，降低开发者对规则的信任度。遇到误报时：

1. 定位规则 ：查看 Cursor 给出的警告信息，确定是哪个规则文件触发的。
2. 分析模式 ：打开对应的 .cursorrule 文件，查看其 pattern 。分析你的代码为何会触发这个模式。
3. 优化正则表达式 ：通常误报是因为正则表达式过于宽泛。例如，一条检测“密码”的规则可能匹配了变量名 passwordHash （这是安全的）。你需要修改 pattern ，使其更精确。可以添加单词边界 \b ，或排除某些上下文。
4. 添加例外 ：如果某段代码确实是安全的特例，但难以用正则区分，可以考虑在规则中增加 exceptions 字段（如果 Cursor 规则语法支持），或者更现实的做法是，暂时注释掉该规则，并记录原因。更好的做法是重构代码，使其不再触发误报。

处理漏报（False Negative）： 漏报意味着危险代码没有被发现，这更危险。

1. 复盘场景 ：当发现一段不安全的代码被 AI 顺利生成且未被拦截时，记录下这段代码和你的初始指令。
2. 增强规则 ：分析这段代码的特征，思考现有的规则 pattern 为何没有匹配到。是因为它使用了新的危险函数？还是因为密钥的格式不在现有正则的覆盖范围内？据此修改或新增规则。
3. 模糊测试 ：有意识地用一些“坏指令”去测试 AI，看看它会产生什么代码，以此来检验和完善你的规则集。例如：“写一段代码，从 req.body.token 里取出 JWT 但不做验证，直接解码。”

5.2 在团队中有效推广安全规则

引入技术工具容易，改变团队习惯难。要让安全规则真正发挥作用，需要一些策略。

启动阶段：低摩擦引入 不要一开始就启用所有规则，尤其是那些 severity: error 的规则。可以从 severity: warning 开始，让规则以“建议”或“提示”的形式出现。这能让团队有一个适应期，了解规则的存在和作用，而不会立刻感到被阻碍。

教育阶段：将警报转化为培训 当规则触发时，将其视为一个微型的代码评审和安全培训机会。鼓励开发者在团队群或站会中分享遇到的警报：“今天 Cursor 阻止我写一个硬编码密钥，它建议我用环境变量，我是这样解决的……” 这种基于真实场景的讨论，比抽象的安全培训有效得多。

定制阶段：让规则反映团队共识 组织一次简短的研讨会，与团队成员一起 review 现有的规则集。讨论：“这条规则对我们项目有意义吗？”“我们有没有自己特有的不安全模式需要防护？”让团队成员参与自定义规则的创建。当规则是“我们自己的规则”而不是“上面强加的规则”时，遵守的意愿会强得多。

集成阶段：纳入开发工作流 将 .cursor/rules/ 目录纳入项目的版本控制系统（如 Git）。这样，规则就成为了项目定义的一部分。可以在项目的 README.md 或 CONTRIBUTING.md 中增加一个小节，说明本项目使用了 Cursor 安全规则，并链接到内部文档解释其目的和如何应对警报。

5.3 规则集的局限性与互补方案

必须清醒认识到， cursor-security-rules 是一个 实时防护 和 编码时教育 工具，它不能替代其他安全实践。

局限性：

1. 覆盖范围有限 ：它主要针对 AI 生成代码的即时风险，无法覆盖手动编写的代码、第三方库的漏洞、基础设施配置错误、业务逻辑缺陷等。
2. 绕过可能 ：有经验的开发者（或固执的 AI）可能会找到方法绕过规则的限制。
3. 静态分析局限 ：它基于模式匹配，对于复杂的、动态生成的危险代码，检测能力有限。

必须结合的互补方案：

1. SAST/DAST 工具 ：在 CI/CD 流水线中集成 SonarQube、Semgrep、Checkmarx 等静态扫描工具，以及 OWASP ZAP 等动态扫描工具，进行更全面、深入的代码安全分析。
2. 秘密扫描 ：使用像 Gitleaks、TruffleHog 这样的工具，定期或提交时扫描整个代码仓库和历史提交，查找任何被意外提交的密钥。
3. 依赖项扫描 ：使用 npm audit 、 pip-audit 、 snyk 、 dependabot 等工具，持续监控项目依赖库中的已知漏洞。
4. 人工代码评审 ：最重要的防线。安全规则和自动化工具是辅助，最终的责任和判断力在于人。重要的代码变更必须经过同伴评审（Peer Review）。

我个人在实际项目中的体会是 ，这套规则最大的价值在于它创造了一个“安全反馈即时化”的环境。它把安全从一份遥远的、事后的检查清单，变成了一个就在你手边的、随时提醒你的伙伴。它可能阻止不了精心策划的攻击，但它能完美地防止那些由于疏忽、赶工或对 AI 过度信任而导致的“愚蠢错误”。在 AI 编程时代，这种防呆设计不是可选项，而是必需品。从第一次部署规则时被频繁的警告“打扰”，到后来团队开始主动讨论“怎样写代码才不会触发警报”，这个过程本身就是一次成功的安全文化渗透。