- 新手指南
- 平台常见问题
- 法律条文
- 任务中心
- API中心
1. 更新历史
序号 | 发布日期 | 版本号 | 说明 |
---|---|---|---|
1 | 2024/08/30 | v1.0 | 初始创建。 新增签名机制。 新增接口:获取文件上传地址、创建检测任务、检测任务状态查询、检测任务结果-统计、检测任务结果-组件列表、检测任务结果-漏洞列表、检测任务结果-许可列表、查询组件详情、查询漏洞详情、查询许可详情、查询字典。 |
2. API概览
接口名称 | 接口功能 | 频率限制 |
---|---|---|
获取文件上传地址 | 获取待检测文件上传到OBS的地址 | 不限制 |
创建检测任务 | 上传文件及发起检测 | 不限制 |
检测任务状态查询 | 通过检测任务唯一标识查询任务当前检测进度及状态 | 不限制 |
检测任务结果-统计 | 通过检测任务唯一标识查询任务检测结果,包括组件数量、漏洞数量、许可数量 | 不限制 |
检测任务结果-组件列表 | 通过检测任务唯一标识查询任务检测结果的组件列表 | 不限制 |
检测任务结果-漏洞列表 | 通过检测任务唯一标识查询任务检测结果的漏洞列表 | 不限制 |
检测任务结果-许可列表 | 通过检测任务唯一标识查询任务检测结果的许可列表 | 不限制 |
查询组件详情 | 通过组件唯一标识查询组件详情 | 不限制 |
查询漏洞详情 | 通过漏洞的sz编号查询漏洞详情 | 不限制 |
查询许可详情 | 通过许可简称查询许可详情 | 不限制 |
查询字典 | 通过字典编码查询字典信息 | 不限制 |
3. 调用方式
为了保证数据传输过程中的真实性,完整性和不可抵赖,我们需要对数据进行数字签名,签名需要加入秘钥对(accessKeyId与accessKeySecret),在接收签名数据之后进行数据签名校验。签名算法为HMAC-MD5算法,结果为十六进制字符串。签名的目的是为了防止客户端提交的请求以及通知数据被非法篡改。
3.1 获取安全凭证
安全凭证包括 :accessKeyId 和 accessKeySecret。
● accessKeyId:密钥ID
● accessKeySecret:密钥KEY
3.2 生成签名串
3.2.1 排序
首先对所有请求参数按参数名的字典序( ASCII 码)升序排序
注意:
1)所有请求的参数中都需添加13位毫秒值时间戳,5分钟内有效;
2)只按参数名进行排序,参数值保持对应即可,不参与比大小;
3)按 ASCII 码比大小;
4)忽略null值。
请求参数示例
{
"taskId":"api-test-001",
"timestamp":1724728924857
}
排序生成压缩JSONString后示例
{"taskId":"api-test-001","timestamp":1724728924857}
3.2.2 生成签名
此步骤生成签名串signature。
具体代码如下,以Java语言为例
//创建SecretKey对象 accessKeySecret为密钥ID
SecretKey secretKey = new SecretKeySpec(accessKeySecret.getBytes(StandardCharsets.UTF_8), "HmacMD5");
//获取Mac实例
Mac mac = Mac.getInstance(secretKey.getAlgorithm());
//初始化Mac实例
mac.init(secretKey);
//获取签名
String signature = Hex.encodeHexString(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)))
3.2.3 请求头赋值
所有接口调用时,在请求头中进行赋值
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
accessKeyId | string | N | 密钥ID |
signature | string | N | 签名串 |
请求头示例:
请求体示例:
4. 获取文件上传地址
4.1 接口描述
获取待检测文件上传到OBS的地址。
4.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址: https://www.wanyun.cn/gateway/sca/external/upload/url
4.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
fileName | string | N | 文件完整名称(带文件后缀,目前支持3G以内的zip、rar、7z、war、 jar、tar.gz等格式的压缩文件,以及包管理器特征文件。) |
timestamp | Long | N | 13位时间戳 |
4.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | object | 数据对象 |
data.fileId | string | 文件id |
data.temporarySignature | object | 华为云OBS临时上传地址信息 |
华为云OBS临时上传地址信息 temporarySignature:
定义 | 类型 | 描述 |
---|---|---|
signedUrl | string | 上传地址 |
actualSignedRequestHeaders | object | 上传请求头属性 |
actualSignedRequestHeaders.Content-Type | string | Content-Type |
actualSignedRequestHeaders.Host | string | Host |
上传方式代码参考:
JAVA:
import cn.hutool.core.io.FileUtil;
import com.obs.services.model.TemporarySignatureResponse;
import okhttp3.Call;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import java.io.File;
import java.io.IOException;
import java.util.Map;
public class UploadUtil {
/**
* 上传文件示例
*
* @param response 调用获取文件上传地址接口返回的数据中的data.temporarySignature
* @throws IOException
*/
public static void upload(TemporarySignatureResponse response) throws IOException {
Request.Builder builder = new Request.Builder();
for (Map.Entry<String, String> entry : response.getActualSignedRequestHeaders().entrySet()) {
builder.header(entry.getKey(), entry.getValue());
}
String contentType = "application/octet-stream";
// 要上传的文件
File file = new File("/file/upload/PurexxxV1.0.zip");
byte[] fileBytes = FileUtil.readBytes(file);
// 使用PUT请求上传对象
Request httpRequest =
builder.url(response.getSignedUrl())
.put(RequestBody.create(MediaType.parse(contentType), fileBytes))
.build();
OkHttpClient httpClient =
new OkHttpClient.Builder()
.followRedirects(false)
.retryOnConnectionFailure(false)
.cache(null)
.build();
Call c = httpClient.newCall(httpRequest);
Response res = c.execute();
System.out.println("Status:" + res.code());
res.close();
System.out.println("PutObject successfully");
}
}
5. 创建检测任务
5.1 接口描述
上传文件及发起检测。
5.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/createTask
5.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
taskId | string | N | 任务唯一ID |
taskName | string | N | 任务名称 |
callbackUrl | string | Y | 回调地址,不为空时,检测完成后根据地址进行回调 |
fileId | string | N | 检测文件Id |
timestamp | Long | N | 13位时间戳 |
5.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | Object | 返回数据 |
5.5 回调数据
回调接口采用POST回调:
定义 | 类型 | 描述 |
---|---|---|
taskId | string | 任务唯一ID |
taskName | string | 任务名称 |
errorMassage | string | 错误说明 |
status | int | 状态:2:检测成功 3:检测失败 |
startTime | string | 开始检测时间 |
endTime | string | 结束检测时间 |
6. 检测任务状态查询
6.1 接口描述
通过检测任务唯一标识查询任务当前检测进度及状态。
6.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/status
6.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
taskId | string | N | 任务唯一ID |
timestamp | Long | N | 13位时间戳 |
6.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | object | 数据对象 |
data.status | int | 状态: 0:排队中1:正在检测2:检测完成3:检测失败 |
data.process | string | 进度 |
data.startTime | string | 检测开始时间 |
data.endTime | string | 检测结束时间 |
data.time | string | 检测实际时长(单位:秒) |
7. 任务检测结果-统计
7.1 接口描述
通过检测任务唯一标识查询任务检测结果,包括组件数量、漏洞数量、许可数量。
7.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/statistics
7.3 输入参数
定义 | 数据类型 | 可选 | 描述 |
---|---|---|---|
taskId | string | N | 任务唯一ID |
timestamp | Long | N | 13位时间戳 |
7.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | obj | 数据对象 |
data.componentNum | int | 组件数量 |
data.vulNum | int | 漏洞数量 |
data.licenseNum | int | 许可数量 |
8. 任务检测结果-组件列表
8.1 接口描述
通过检测任务唯一标识查询任务检测结果的组件列表。
8.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/components/page
8.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
current | int | N | 当前页数,大于0 |
size | int | N | 每页行数,1~500 |
taskId | string | N | 任务唯一ID |
timestamp | Long | N | 13位时间戳 |
8.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 信息 |
ok | boolean | 是否成功 |
data | object | 数据对象 |
data.total | int | 组件总数 |
data.current | int | 页数 |
data.size | int | 每页条数 |
data.records | List | 组件列表 |
组件详情componentList:
定义 | 类型 | 描述 |
---|---|---|
componentUuid | String | 组件唯一标识 |
groupId | String | 组织 |
artifactId | String | 组件名称 |
grade | String | 风险等级,字典编码:JARRISK(详情见接口3.11) |
gradeDesc | String | 风险等级描述 |
version | String | 版本 |
recommendVersion | String | 推荐版本 |
releaseTime | Long | 发布时间 |
compomentFixDetailVoList | list | 解决方案列表 |
解决方案详情compomentFixDetailVoList:
定义 | 类型 | 描述 |
---|---|---|
depRank | String | 依赖类型 |
depSource | String | 引用类型标识 |
depSourceName | String | 引用类型名称 |
depScope | String | 作用域 |
desc | String | 修复建议描述 |
9. 任务检测结果-漏洞列表
9.1 接口描述
通过检测任务唯一标识查询任务检测结果的漏洞列表,可添加组件唯一标识参数查询本次检测结果中该组件的漏洞列表。
9.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/vulnerability/page
9.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
current | int | N | 当前页数,大于0 |
size | int | N | 每页行数,1~500 |
taskId | string | N | 任务唯一ID |
componentUuid | string | Y | 组件唯一标识 |
timestamp | Long | N | 13位时间戳 |
9.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 信息 |
ok | boolean | 是否成功 |
data | object | 数据对象 |
data.total | int | 漏洞总数 |
data.current | int | 页数 |
data.size | int | 每页条数 |
data.records | list | 漏洞列表 |
漏洞详情vulnerabilities:
定义 | 类型 | 描述 |
---|---|---|
customSzNo | String | sz编号 |
customCveNo | String | Cve编号 |
customCnnvdNo | String | Cnnvd编号 |
affectComponentCount | Integer | 影响组件数 |
customCnvdNo | String | Cnvd编号 |
grade | String | 风险等级,字典编码:CVERISK(详情见接口3.11) |
gradeDesc | String | 风险等级描述 |
cwe | String | 弱点类型编号 |
vulnerabilityName | String | 漏洞名称 |
cweName | String | 弱点类型名称 |
description | String | 漏洞描述 |
releaseDate | Long | 发布时间 |
10. 任务检测结果-许可列表
10.1 接口描述
通过检测任务唯一标识查询任务检测结果的许可列表,可添加组件唯一标识参数查询本次检测结果中该组件的许可列表。
10.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/vulnerability/page
10.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
current | int | N | 当前页数,大于0 |
size | int | N | 每页行数,1~500 |
taskId | string | N | 任务唯一ID |
componentUuid | string | Y | 组件唯一标识 |
timestamp | Long | N | 13位时间戳 |
10.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 信息 |
ok | boolean | 是否成功 |
data | object | 数据对象 |
data.total | int | 许可总数 |
data.current | int | 页数 |
data.size | int | 每页条数 |
data.records | list | 许可列表 |
许可详情LicenseList:
定义 | 类型 | 描述 |
---|---|---|
licenseId | string | 许可简称 |
licenseName | string | 许可全称 |
grade | string | 风险等级,字典编码:LICENSERISK(详情见接口3.11) |
gradeDesc | string | 风险等级描述 |
11. 查询组件详情
11.1 接口描述
通过组件唯一标识查询组件详情。
11.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/component/detail
11.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
componentUuid | string | N | 组件唯一标识 |
timestamp | Long | N | 13位时间戳 |
11.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | object | 数据对象 |
data.groupId | String | 组织 |
data.artifactId | String | 组件名称 |
data.componentUuid | String | 组件唯一标识 |
data.grade | String | 风险等级,字典编码:JARRISK(详情见接口3.11) |
data.gradeDesc | String | 风险等级描述 |
data.language | String | 语言 |
data.licenses | List<String> | 许可列表 |
data.jarInfoAddFrom | String | 语言字典值, 字典编码COMPUTERLANGUAGE |
data.version | String | 版本 |
data.recommendVersion | String | 推荐版本 |
data.releaseTime | Long | 发布时间 |
data.homePage | String | 主页 |
data.sourceCode | String | 源码 |
data.latestVersion | String | 最新版本 |
data.versionEntities | List<Object> | 版本信息 |
data.privatePublicStatus | Integer | 组件状态编码,0 开源,1自研,2开源(未收录),3 非开源,4 开源(已修改),5 自研(废弃) |
data.privatePublicStatusName | String | 组件状态中文 |
data.country | String | 所属国家 |
data.countryChineseName | String | 所属国家的中文名称 |
版本信息versionEntities:
定义 | 类型 | 描述 |
---|---|---|
releaseDate | String | 发布时间 |
version | String | 版本 |
grade | String | 风险等级,字典编码:JARRISK(详情见接口3.11) |
gradeDesc | String | 风险等级描述 |
12. 查询漏洞详情
12.1 接口描述
通过漏洞的sz编号查询漏洞详情。
12.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/vulnerability/detail
12.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
customSzNo | string | N | sz编号 |
timestamp | Long | N | 13位时间戳 |
12.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | object | 数据对象 |
data.customSzNo | string | sz编号 |
data.customCveNo | String | Cve编号 |
data.customCnnvdNo | String | Cnnvd编号 |
data.customCnvdNo | String | Cnvd编号 |
data.grade | String | 风险等级,字典编码:CVERISK(详情见接口3.11) |
data.gradeDesc | String | 风险等级描述 |
data.cwe | String | Cwe |
data.description | String | 漏洞描述 |
data.vulnerabilityName | String | 漏洞名称 |
data.cweName | String | 弱点类型名称 |
data.releaseDate | Long | 发布时间 |
data.updateDate | Long | 更新时间 |
data.announcement | String | 漏洞建议 |
data.referenceVoList | object | 参考链接 |
data.cvss3 | object | cvss3 |
data.cvss2 | object | cvss2 |
data.cpe | List<String> | cpe |
data.isRepair | String | 是否修复 |
data.utilization | String | EXP成熟度 |
data.cnnvdPatchPo | List<object> | 补丁信息 |
data.vulUseDifficulty | String | 漏洞利用难度 |
data.vulUseDifficultyDesc | String | 漏洞利用难度描述, 字典编码:VULNERABILITYUSEDIFFICULTYTYPE(详情见接口3.11) |
data.pocusesTime | String | poc利用时间 |
参考链接referenceVoList:
定义 | 类型 | 描述 |
---|---|---|
source | string | 来源 |
link | string | 链接 |
CVSS3:
定义 | 类型 | 描述 |
---|---|---|
baseScore | string | cvss3基础分数 |
impact | string | cvss3影响 |
developAble | string | cvss3可开发性 |
attackWay | string | cvss3攻击途径 |
attackComplexity | string | cvss3攻击复杂度 |
userInteraction | string | cvss3用户交互 |
usabilityImpact | string | cvss3可用性影响 |
integrityEffect | string | cvss3完整性影响 |
confidentialityImpact | string | cvss3机密性影响 |
scope | string | cvss3作用域 |
permission | string | cvss3权限要求 |
CVSS2:
定义 | 类型 | 描述 |
---|---|---|
baseScore | string | cvss2基础分数 |
impact | string | cvss2影响 |
developAble | string | cvss2可开发性 |
attackWay | string | cvss2攻击途径 |
attackComplexity | string | cvss2攻击复杂度 |
usabilityImpact | string | cvss2可用性影响 |
integrityEffect | string | cvss2完整性影响 |
confidentialityImpact | string | cvss2机密性影响 |
authentication | string | Cvss2认证 |
cnnvdPatchPo:
定义 | 类型 | 描述 |
---|---|---|
patchId | string | 补丁编号 |
title | string | 补丁名称 |
link | string | 补丁链接地址 |
publishDate | string | 补丁发布时间 |
szId | string | 该补丁所修复的漏洞编号 |
referenceUrl | string | 参考网址 |
13. 查询许可详情
13.1 接口描述
通过许可简称查询许可详情。
13.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/task/license/detail
13.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
licenseId | string | N | 许可简称 |
timestamp | Long | N | 13位时间戳 |
13.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | object | 数据对象 |
data.detailsUrl | String | 详细地址 |
data.grade | String | 风险等级,字典编码:LICENSERISK(详情见接口3.11) |
data.gradeDesc | String | 风险等级描述 |
data.reference | String | 参考地址 |
data.licenseName | String | 许可全称 |
data.licenseId | String | 许可简称 |
data.osi | String | 字典编码:COMFIRM(详情见接口3.11) |
data.fsf | String | 字典编码:COMFIRM(详情见接口3.11) |
data.description | String | 描述信息 |
data.allow | list | 允许许可权限 |
data.attention | list | 注意许可权限 |
data.must | list | 必须许可权限 |
data.expire | boolean | 是否过期,true:是,false:否 |
allow:
定义 | 类型 | 描述 |
---|---|---|
permissions | string | 许可权限(允许) |
description | string | 许可权限(允许描述) |
attention:
定义 | 类型 | 描述 |
---|---|---|
permissions | string | 许可权限(注意) |
description | string | 许可权限(注意描述) |
must:
定义 | 类型 | 描述 |
---|---|---|
permissions | string | 许可权限(必须) |
description | string | 许可权限(必须描述) |
14. 字典
14.1 接口描述
通过字典编码查询字典信息。
14.2 请求定义
请求方式:post
请求头类型:Content-Type: application/json
请求地址:https://www.wanyun.cn/gateway/sca/external/dict/type/list
14.3 输入参数
定义 | 类型 | 可选 | 描述 |
---|---|---|---|
dictType | string | N | 字典编码 |
timestamp | Long | N | 13位时间戳 |
14.4 输出参数
定义 | 类型 | 描述 |
---|---|---|
code | int | 消息编码 |
msg | string | 错误描述 |
data | List<Dict> | 数据对象 |
Dict
定义 | 类型 | 描述 |
---|---|---|
dictKey | string | 字典编码 |
dictValue | string | 字典名称 |
sort | int | 排序 |