工具规则

腾讯云代码分析目前已集成众多自研、知名开源工具，并采用分层分离的架构，可以快速对接企业内部团队研发的工具，并将其集成到平台内供企业内部团队使用，满足快速自助的管理工具。

工具分为平台提供的工具，以及团队接入的工具：

  • 平台工具：由平台侧提供的一系列自研工具或知名开源工具，此类工具都为公开工具，任何团队都可以使用此工具及工具规则进行代码分析。

  • 团队工具：由团队自行接入的工具，默认该工具仅能在团队内使用。

提示

某些工具具备一定的自定义配置能力：

  • 支持配置定制规则：仅 RegexFileScan、RegexScan、TCA-Armory-R 工具。

  • 支持指定环境变量：需在分析方案内指定环境变量。如 Eslint 工具的 NODE_OPTIONS="--max-old-space-size=32768"环境变量配置。

  • 支持调整规则参数：需在分析方案内编辑规则参数。如 CppLint 工具的 whitespace/line_length 规则。

自定义规则接入

团队管理员可以在支持自定义规则的工具内，根据业务需求定制规则。

适用场景

业务团队根据自身需求，由业务团队自行设计规则。

自定义规则权限说明

  • 并非所有工具都支持自定义规则，仅开放了自定义规则功能的工具可添加自定义规则；

  • 对于开放了自定义规则功能的工具，仅团队管理员可添加自定义规则；

  • 默认填加的自定义规则是团队隔离的，即仅该团队内可见可用；

正则工具 RegexScan 说明

正则工具 RegexScan 即为开放了自定义规则功能的工具，可进入工具管理页面，搜索工具名称RegexScan，查看该工具已存在的规则以及根据团队业务需求，添加自定义规则。

适用场景

通过正则表达式，能够匹配到目标代码的情况。

自定义规则步骤

  1. 根据团队业务需求设计正则表达式

    提示

    建议先测试好正则表达式是否正确，正则表达式测试网站推荐：http://tool.oschina.net/regex

    规则示例：

    • 规则分析场景

      分析代码中的 usleep() 方法调用，如果参数小于 100 ，容易造成 CPU 使用率过高，造成性能浪费，判断为缺陷。

    • 正则表达式

      匹配 usleep() 字符串，括号中的内容为 1 位或 2 位整数，那么正则表达式可以写成 \busleep\s*\(\s*\d{1,2}\s\*\)，这里考虑了字符串中存在空格的情况。

  2. 进入正则工具添加自定义规则

    进入工具管理页面，找到正则工具RegexScan，并点击进入自定义规则列表页，点击添加规则按钮。

  3. 填写规则信息

    规则参数填写说明（必要）：

    参数格式类似 ini 的格式， 也就是 key = value 的格式

    • 【必要】 regex 参数，用于指定分析的正则表达式， 例如: regex = \busleep\s*\(\s*\d{1,2}\s\*\)。

    • 【必要】 msg 参数，用于展现 issue 说明， 例如： msg = 函数方法%s 已经废弃，请使用 xxx 方法。

      msg 中的“%s”使用 regex 中的 group（用“()"括起来的部分）一一匹配。

      如果 regex 没有定义 group，则 msg 最多有一个%s, 并由整个 regex 匹配的字符串替代

      如果 msg 里没有包含“%s”，则直接显示 msg

      如果 msg 没有提供，则默认为“发现不规范代码：%s”（不建议使用默认格式，太笼统）

    • 【可选填】 ignore_comment 参数，用于指定是否忽略注释代码，可选值：True、true、False、false 。例如 ignore_comment=True, 默认是 False

    • 【可选填】 include 参数，用于将指定分析文件匹配范围，使用 unix 的文件匹配格式，多项使用英文分号;隔开。例如 include = path/to/dir;path/to/\*.cpp

    • 【可选填】 exclude 参数，用于指定不分析的文件。格式参考 include 参数。

  4. 将自定义规则添加到项目分析方案中

    添加完成，可在分析方案中添加该自定义规则。

自定义工具接入

团队管理员可以自行接入工具，默认该工具仅能在团队内使用。

适用场景

自定义规则无法满足团队业务复杂需求，需要更多的代码逻辑来匹配目标代码的情况。通常需要团队业务方自行实现对应代码分析工具。

只需要几步操作：

  1. 编写代码，实现扫描工具逻辑
  2. 提交工具到 git 代码库
  3. 在页面创建新工具
  4. 为工具添加规则
  5. 将工具配置到执行节点
  6. 在项目分析方案中添加规则

扩展集成工具免责声明

  • 被扩展集成进腾讯云代码分析系统的任何非官方工具，该类工具对于腾讯云代码分析系统等于黑盒，腾讯云代码分析系统不对该类工具负责，由该类工具方承担所有责任（包括但不限于分发被分析代码，产生代码以及相关信息泄漏）。

  • 您应当自行查阅被集成进腾讯云代码分析系统的第三方工具的授权协议，您承诺遵守一切相关的法律法规，并在授权范围内使用第三方工具。如您集成第三方工具的行为对腾讯云造成损害的，您承诺负责消除损害并赔偿由此带来的一切损失。

自定义工具权限说明

  • 团队管理员才能创建工具，添加工具规则等，具备该工具全部权限。

  • 团队内所有成员可使用该工具规则，如在规则配置中添加此工具规则，团队普通成员仅只读权限。

自定义工具接入步骤

第一步，编写代码，实现分析工具逻辑

根据需要匹配的目标代码场景，编写对应的工具逻辑。 可以参考 Python 写的 Demo 项目

必要：

  • 运行方式：支持命令行执行，比如 python run.py 或 run.exe，执行命令的工作目录为工具代码的根目录。

  • 运行环境说明：

    • 建议将工具打包编译成可执行程序，拉取下来直接可以执行。
    • 如果工具需要在特定的环境中运行，比如python、java环境，平台提供了丰富的工具依赖包，可以在工具管理-工具依赖中查看，创建工具时可供选择，执行时会自动配置好依赖环境。
    • 如果现有的工具依赖包未支持所需依赖，也可以创建新的工具依赖使用。

  • 平台已提供的环境变量

    SOURCE_DIR：要扫描的代码目录路径
DIFF_FILES: 值为一个json文件路径，文件内容为增量扫描的文件列表(增量扫描时可用)
SCAN_FILES: 值为一个json文件路径，文件内容为需要扫描的文件列表(增量或全量扫描均可用)
TASK_REQUEST: 值为一个json文件路径，文件内容为当前扫描任务参数
RESULT_DIR: 结果result.json输出的结果目录路径，请将结果输出到该目录下

    有些结果处理的阶段可以跳过，可以在工具环境变量配置里，设置一下：

    FILTER_TYPE=NO_VERSION_FILTER
IGNORE_TYPE=NO_ISSUE_IGNORE
BLAME_TYPE=NO_BLAME

    以上这些字段根据各自需要可以自定义添加到环境配置中，具体需不需要要看自己的工具需求，这些环境变量可以自定义，并且可以在程序中获取。

  • 工具命令声明

    在工具仓库根目录下，添加一个tool.json文件，声明工具的检查和扫描命令，比如：

    {
  "check_cmd": "python src/main.py check",
  "run_cmd": "python src/main.py scan"
}

    参数说明：

    • check_cmd：
      • 功能：判断当前执行环境是否满足工具要求（如果不需要检查，也可以没有这个命令）。 比如某些工具只能在linux下执行，需要判断当前是否为linux环境。
      • 输出：将判断结果输出到check_result.json文件中，文件内容为{"usable": true}或{"usable": false}。
    • run_cmd：
      • 功能：扫描代码，执行自定义检查器逻辑（该命令必须存在）。
      • 输出：按照指定格式，输出结果到result.json文件中。

  • 工具输出格式要求

    • 将扫描结果输出到当前工作目录下的result.json文件中（Python 示例代码）
    import json
with open("result.json", "w") as fp:
    json.dump(result, fp, indent=2)
    • result.json 文件格式如下：
    [
    {
        "path": "文件绝对路径",
        "line": "行号，int类型",
        "column": "列号, int类型，如果工具没有输出列号信息，可以用0代替",
        "msg": "提示信息",
        "rule": "规则名称,可以根据需要输出不同的规则名",
        "refs": [
            {
                "line": "回溯行号",
                "msg": "提示信息",
                "tag": "用一个词简要标记该行信息，比如uninit_member,member_decl等，如果没有也可以都写成一样的",
                "path": "回溯行所在文件绝对路径"
            },
            ...
        ]
    },
    ...
]

    refs 字段说明：

    非必需项，可无。该字段记录问题回溯路径信息。比如当前行的代码问题，是经过上下文的三行代码执行路径而导致的，可以将这三行的位置及提示信息，按顺序添加到 refs 数组中。

第二步，提交工具到 git 代码库

  • 创建代码库，将工具源代码或编译打包后的可执行文件，提交到代码仓库中（建议提交到master分支，TCA默认拉取的是master分支），仅支持CODING代码库。

  • 建议代码库中加入 README.md 文件，说明工具功能和维护人。

  • 后续需要修改工具实现逻辑，可以直接更新代码库，TCA 平台在执行该工具时，会自动拉取最新工具代码版本。

第三步，在工具管理页面中创建工具

  • 进入工具管理页面，点击创建工具

    enter image description here

  • 填写工具信息

    enter image description here

    部分参数说明：

    • 工具仓库地址，即前述步骤中提交的工具 git 代码库地址，默认拉取的是master分支

    • 执行命令，该命令会在工具根目录下执行

    • 环境变量，工具执行所需的环境变量

    • 适用系统，工具执行所需的机器系统

    • License，如果是开源工具，填写工具遵循的开源协议，或者填写自研共建

    • 是否为编译型工具，表示在使用该工具对用户代码进行分析时，是否要求代码需要编译或可执行编译

    • 注意：针对特殊扫描场景的工具（比如检查代码库下是否包含某些第三方依赖目录，结果不涉及单个代码文件的），无法对结果进行代码文件处理，可以通过设置以下环境变量，跳过一些通用的结果处理步骤，避免问题结果被过滤掉：

      • BLAME_TYPE=NO_BLAME，跳过对代码行/代码文件进行文件责任人定位（结果非单个文件/代码行时使用）
      • FILTER_TYPE=NO_VERSION_FILTER，跳过检查问题路径（path字段）是否为已提交到代码库中的文件（结果非单个文件/代码行时使用）
      • IGNORE_TYPE=NO_ISSUE_IGNORE，跳过注释忽略处理（结果非单个文件/代码行时使用）

第四步，为工具添加规则

  • 完成工具创建后，进入规则列表，为工具添加规则

    enter image description here

  • 填写规则信息

    部分参数说明：

    • 规则简介：简要描述规则发现的是什么问题，扫描结果中会作为问题标题展示

    • 详细描述：可详细描述规则，以及规则的解决方式，建议附上解决案例 demo

    • 解决方法：按照实际情况，说明该代码问题的解决方法，建议附上解决案例 demo

    • 规则参数：如果不需要通过规则参数传递信息，可留空

第五步，将工具配置到执行节点

提示

需要节点管理员协助操作，在节点管理中选择编译需要配置的机器节点，在工具子进程配置中，找到对应工具，勾选对应工具进程，团队工具会有相应的前缀。

完成节点配置工具进程后，才能在项目中采用该工具进行分析。

enter image description here

第六步，完成上述操作，在项目中使用工具规则

  • 进入到项目中，在分析方案-代码检查进行规则配置。

  • 点击添加规则，找到对应工具规则进行添加。

  • 添加完成后，启动分析，为了将规则应用到所有代码文件，建议启动一次全量分析（增量分析只会分析自上次扫描后变更的文件）。

最近更新时间:
贡献者: nickctang, faberihe, kylinye