FeeiCN/Cobra项目规则模板详解与编写指南

FeeiCN/Cobra项目规则模板详解与编写指南

Cobra Source Code Security Audit (源代码安全审计) 项目地址: https://gitcode.com/gh_mirrors/cob/Cobra

项目简介

FeeiCN/Cobra是一款专注于源代码安全审计的静态代码分析工具，它通过自定义规则对代码进行扫描，帮助开发者发现潜在的安全问题。本文将详细介绍该工具中规则模板的编写规范和使用方法，帮助安全研究人员和开发人员快速上手规则编写。

规则模板结构解析

规则模板采用XML格式编写，包含多个关键字段，每个字段都有其特定的作用和意义。下面我们通过一个典型的"硬编码Token/Key"检测规则来解析模板结构：

<?xml version="1.0" encoding="UTF-8"?>
<cobra>
    <name value="硬编码Token/Key"/>
    <language value="*"/>
    <match mode="regex-only-match"><![CDATA[(?![\d]{32})(?![a-fA-F]{32})([a-f\d]{32}|[A-F\d]{32})]]></match>
    <level value="2"/>
    <test>
        <case assert="true" remark="sha1"><![CDATA["41a6bc4d9a033e1627f448f0b9593f9316d071c1"]]></case>
        <case assert="false"><![CDATA[please like and subscribe to my]]></case>
    </test>
    <solution>
        ## 安全风险
        硬编码密码
        
        ## 修复方案
        将密码抽出统一放在配置文件中，配置文件不放在git中
    </solution>
    <status value="on"/>
    <author name="Feei" email="feei@feei.cn"/>
</cobra>

核心字段详解

1. 基本信息字段

• name：规则名称，简明扼要地描述规则检测的内容
• language：规则适用的编程语言，支持多种语言或使用*表示通用
• level：问题危害等级，1-10数字表示，数值越大危害越高
• status：规则启用状态，on表示启用，off表示禁用
• author：规则作者信息，包含姓名和联系方式

2. 匹配规则字段

<match>主匹配规则

• 必填字段，用于定义主要的匹配逻辑
• mode属性指定匹配模式，常见的有：
  • regex-only-match：正则表达式匹配（默认）
  • regex-param-controllable：参数可控性检查
  • function-param-controllable：函数参数可控性检查
  • find-extension：文件扩展名匹配

<match2>辅助匹配规则

• 可选字段，用于在<match>基础上进一步限定匹配条件
• block属性指定匹配范围，如函数体内、文件内等

<repair>修复规则

• 可选字段，用于定义修复模式，匹配到此规则则不算问题

3. 测试用例字段<test>

每个规则必须包含充分的测试用例，用于验证规则的准确性：

• assert="true"：表示该用例应该被检测为问题
• assert="false"：表示该用例不应该被检测为问题
• remark：可选备注，说明用例的特殊情况

4. 解决方案字段<solution>

提供问题的详细说明和修复建议，采用Markdown格式：

• 安全风险：说明问题可能造成的危害
• 修复方案：提供具体的修复方法和最佳实践

匹配模式深度解析

1. 正则仅匹配模式(regex-only-match)

最常用的模式，通过正则表达式直接匹配代码内容。例如检测硬编码密钥的规则：

<match mode="regex-only-match">
<![CDATA[(?![\d]{32})(?![a-fA-F]{32})([a-f\d]{32}|[A-F\d]{32})]]>
</match>

这个正则表达式会匹配32位的哈希值，但排除了纯数字和纯字母的情况。

2. 参数可控模式(regex-param-controllable)

用于检测用户输入是否能够控制特定参数：

<match mode="regex-param-controllable">
<![CDATA[mysql_query\((.*)\)]]>
</match>

3. 函数参数可控模式(function-param-controllable)

专门针对函数调用的参数可控性检查：

<match mode="function-param-controllable">
<![CDATA[system]]>
</match>

4. 文件扩展名匹配(find-extension)

用于检测特定类型的文件：

<match mode="find-extension">
<![CDATA[\.pem$]]>
</match>

匹配区块详解

当使用<match2>或<repair>时，可以通过block属性限定匹配范围：

| 区块 | 描述 | |-----------------|----------------------------------------------------------------------| | in-current-line | 仅在触发第一条规则的同一行内匹配 | | in-function | 在触发第一条规则的整个函数体内匹配 | | in-function-up | 在触发第一条规则的函数体内，从开始到触发行之间的部分匹配 | | in-function-down| 在触发第一条规则的函数体内，从触发行到函数结束之间的部分匹配 | | in-file | 在整个文件范围内匹配 | | in-file-up | 在文件中从开始到触发行之间的部分匹配 | | in-file-down | 在文件中从触发行到文件结束之间的部分匹配 |

规则编写最佳实践

1. 精准的正则表达式：确保正则表达式既能捕获所有问题情况，又不会产生过多误报
2. 充分的测试用例：包含各种边界情况和正常用例，验证规则的准确性
3. 清晰的解决方案：提供具体、可操作的修复建议，帮助开发者快速解决问题
4. 合理的危害等级：根据问题实际危害设置适当的等级，便于优先级排序
5. 详细的注释说明：在复杂规则中添加注释，说明设计思路和匹配逻辑

实际应用示例

下面是一个检测SQL注入问题的完整规则示例：

<?xml version="1.0" encoding="UTF-8"?>
<cobra>
    <name value="SQL注入风险"/>
    <language value="php"/>
    <match mode="regex-param-controllable"><![CDATA[mysql_query\((.*)\)]]></match>
    <level value="8"/>
    <test>
        <case assert="true"><![CDATA[mysql_query("SELECT * FROM users WHERE id = ". $_GET['id']);]]></case>
        <case assert="false"><![CDATA[mysql_query("SELECT * FROM users WHERE id = 1");]]></case>
    </test>
    <solution>
        ## 安全风险
        未过滤的用户输入直接拼接到SQL语句中，可能导致SQL注入问题
        
        ## 修复方案
        1. 使用预处理语句(PDO/mysqli)
        2. 如果必须使用拼接，确保对用户输入进行严格的过滤和转义
    </solution>
    <status value="on"/>
    <author name="Security Researcher" email="researcher@example.com"/>
</cobra>

通过本文的详细讲解，相信您已经掌握了FeeiCN/Cobra项目中规则模板的编写方法和技巧。合理编写规则可以显著提高代码安全审计的效率和准确性，帮助开发团队在早期发现并修复安全问题。

Cobra Source Code Security Audit (源代码安全审计) 项目地址: https://gitcode.com/gh_mirrors/cob/Cobra