Skip to content

🎨更新自定义工具帮助文档,增加从开源社区快速添加工具方式 #1229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 11, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions doc/en/guide/工具管理/自定义工具.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,27 @@

只需要几步操作:

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

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

## 自定义工具步骤说明
## 方式一:从开源社区快速添加
- 适用场景:如果接入的是业界常用的代码分析工具,可能已经有开源社区开发者实践过,建议先在开源代码库中搜索,如果开源社区已有该工具的TCA插件(已符合TCA工具接入规范),则可以直接使用开源工具插件仓库,快速接入。
- 接入步骤:
- 1. 直接使用开源工具TCA插件仓库,或按需fork到自己名下,或提交到自己搭建的私有化git服务上
- 2. 将仓库中的工具json文件,通过工具管理页面,或TCA server后台load的方式,加载到TCA平台上,即可在TCA页面上查看到新工具及其规则列表
- 3. 在节点管理页面,添加该工具进程到机器节点中,则对应机器即可接收执行该工具的代码分析任务
- 4. 在项目分析方案中添加该工具规则,启动代码分析,即可执行该工具进行代码分析
- Tips:一般在对应工具插件仓库的 README 文档中也会有接入指引,可参考[第三方工具列表](工具列表.md)。

## 方式二:自定义开发工具
- 适用场景:自主研发自定义工具,或开源社区未找到已有工具插件,可以通过该方式自定义接入。

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

Expand All @@ -28,7 +37,7 @@

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

- **运行环境说明**:
- **运行环境说明**:
- 建议将工具打包编译成可执行程序,拉取下来直接可以执行。
- 如果工具需要在特定的环境中运行,比如python、java环境,平台提供了丰富的工具依赖包,可以在`工具管理`-`工具依赖`中查看,创建工具时可供选择,执行时会自动配置好依赖环境。
- 如果现有的工具依赖包未支持所需依赖,也可以创建新的工具依赖使用。
Expand All @@ -43,9 +52,9 @@
TASK_REQUEST: 值为一个json文件路径,文件内容为当前扫描任务参数
RESULT_DIR: 结果result.json输出的结果目录路径
```

- **工具命令声明**

在工具仓库根目录下,添加一个`tool.json`文件,声明工具的检查和扫描命令,比如:
```json
{
Expand All @@ -55,13 +64,13 @@
```
参数说明:
- `check_cmd`:
- 功能:判断当前执行环境是否满足工具要求(如果不需要检查,也可以没有这个命令)。
- 功能:判断当前执行环境是否满足工具要求(如果不需要检查,也可以没有这个命令)。
比如某些工具只能在linux下执行,需要判断当前是否为linux环境。
- 输出:将判断结果输出到`check_result.json`文件中,文件内容为`{"usable": true}`或`{"usable": false}`。
- 输出:将判断结果输出到`check_result.json`文件中,文件内容为`{"usable": true}`或`{"usable": false}`。
- `run_cmd`:
- 功能:扫描代码,执行自定义检查器逻辑(该命令必须存在)。
- 输出:按照指定格式,输出结果到结果目录下的`result.json`文件中。

- **工具输出格式要求**

- 将扫描结果输出到`RESULT_DIR`环境变量指定的目录下的`result.json`文件中(Python 示例代码)
Expand Down Expand Up @@ -111,6 +120,8 @@

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

- Tips:除了通过页面手动添加的方式,也可以通过编写工具json的方式,将工具和规则配置到json文件中,通过load json文件的方式来加载工具和规则。

- 进入工具管理页面,点击创建工具

![enter image description here](../../../images/customtool_01.png)
Expand Down Expand Up @@ -143,7 +154,7 @@
![enter image description here](../../../images/customtool_03.png)

添加完成后,会展示已添加的依赖方案:

![enter image description here](../../../images/customtool_04.png)

**工具依赖说明:**
Expand Down
23 changes: 17 additions & 6 deletions doc/zh/guide/工具管理/自定义工具.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,27 @@

只需要几步操作:

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

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

## 自定义工具步骤说明
## 方式一:从开源社区快速添加
- 适用场景:如果接入的是业界常用的代码分析工具,可能已经有开源社区开发者实践过,建议先在开源代码库中搜索,如果开源社区已有该工具的TCA插件(已符合TCA工具接入规范),则可以直接使用开源工具插件仓库,快速接入。
- 接入步骤:
- 1. 直接使用开源工具TCA插件仓库,或按需fork到自己名下,或提交到自己搭建的私有化git服务上
- 2. 将仓库中的工具json文件,通过工具管理页面,或TCA server后台load的方式,加载到TCA平台上,即可在TCA页面上查看到新工具及其规则列表
- 3. 在节点管理页面,添加该工具进程到机器节点中,则对应机器即可接收执行该工具的代码分析任务
- 4. 在项目分析方案中添加该工具规则,启动代码分析,即可执行该工具进行代码分析
- Tips:一般在对应工具插件仓库的 README 文档中也会有接入指引,可参考[第三方工具列表](工具列表.md)。

## 方式二:自定义开发工具
- 适用场景:自主研发自定义工具,或开源社区未找到已有工具插件,可以通过该方式自定义接入。

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

Expand Down Expand Up @@ -111,6 +120,8 @@

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

- Tips:除了通过页面手动添加的方式,也可以通过编写工具json的方式,将工具和规则配置到json文件中,通过load json文件的方式来加载工具和规则。

- 进入工具管理页面,点击创建工具

![enter image description here](../../../images/customtool_01.png)
Expand Down