CFTQ反病毒云API文档

本文档说明范围主要覆盖CFTQ反病毒云的文件分析API接口的 调用说明、云服务状态查询、API认证方式(匿名访问格式及API Key用法)、文件上传/分析方式、接口响应格式、引擎证据树的导出方式以及HTTP响应状态码汇总。

调用说明

1. API接口支持匿名访问，即支持不提供API Key的扫描请求，且匿名访问模式与API Key访问模式具有相同的请求权限，但匿名访问有调用速率限制，单IP最高调用速率为每分钟一次扫描请求。

2. API接口允许用户申请并使用API Key，进行不限制调用频率的请求，但对请求并发数进行了限制，单API Key最高并发数为2。

3. API接口允许的最大上传文件大小为200MB。

4. 对于超额、超并发数或超过文件大小限制的访问，CFTQ反病毒云不会采取封禁API Key的行为，但是会对影响到服务正常运营的IP给予永久封禁。

5. 关于API Key的获取，用户可以申请加入CFTQ用户群(QQ1053168772)，并联系管理员获取API Key。

6. CFTQ反病毒云引擎只支持x86 32位及64位PE程序的分析，其他类型文件不支持分析。

云服务状态查询

CFTQ反病毒云在线API支持用户查询当前的云服务状态：

curl -s https://starlight-v3.ternaryop.top/health

预期响应（云服务状态正常）：

{"status":"ok","model_version":"26.08.04","concurrency_in_use":0}

响应体说明：该接口返回数据为json文本，status字段代表模型状态，model_version代表模型当前版本，concurrency_in_use代表当前IP已用并发数。

API认证方式

CFTQ反病毒云在线API支持如下三种鉴权方式（为方便测试，所有示例请求均使用访客模式执行）：

# 访客模式(无api_key，每IP每分钟最多请求1次，超限返回429)
curl -F "file=@sample.exe" https://starlight-v3.ternaryop.top/scan

# API Key模式：api_key附加到请求头调用(推荐使用，不限制调用速率，最大并发数为2)
curl -F "file=@sample.exe" -H "X-API-Key: $KEY" https://starlight-v3.ternaryop.top/scan

# API Key模式：api_key附加到查询参数(不限制调用速率，最大并发数为)
curl -F "file=@sample.exe" "https://starlight-v3.ternaryop.top/scan?api_key=$KEY"

文件上传/分析方式

CFTQ反病毒云在线API支持如下两种文件上传形式（为确保标准，所有示例请求均使用multipart/form-data形式执行）：

# multipart/form-data上传：file字段为样本，原始文件名取自该字段
curl -F "file=@/path/启动游戏.exe" https://starlight-v3.ternaryop.top/scan

# 原始二进制上传：将文件的原始二进制数据作为请求题，需要附加X-Filename头传递文件名
curl --data-binary @sample.exe -H "X-Filename: sample.exe" https://starlight-v3.ternaryop.top/scan

接口响应格式

CFTQ反病毒云在线API通过返回json文本的形式，对请求进行响应，字段说明如下：

• 分析成功时的响应json：

• 分析失败时的响应json：

• 分析成功响应示例：

{
  "code": 0,
  "model": {
    "version": "26.08.04",
    "tspm_trie_node_count": 6545210
  },
  "file": {
    "name": "sample.exe",
    "size": 94208,
    "machine": "x86_64",
    "import_count": 134,
    "efg_node_count": 372,
    "efg_edge_count": 1028,
    "sha256": "34e640085bda4a851559bb958e59525d764240681aecc4593f04d2336ce04819",
    "md5": "782c5b25d5053b83a90830e0818f7aa5"
  },
  "result": {
    "type": "malware",
    "confidence": 0.997319,
    "analyzing_time_ms": 39.5
  },
  "tspm": {
    "final_score": 0.911864,
    "malware_score": 3142.782769,
    "benign_score": -144.879949,
    "malware_call_chain_count": 503,
    "benign_call_chain_count": 95,
    "malware_call_count": 1416,
    "benign_call_count": 247
  }
}

• 分析失败响应示例：

{
  "code": 1,
  "error": "invalid api key"
}

引擎证据树导出方式

CFTQ反病毒云支持以DOT图格式导出引擎在推理过程中的匹配树，即证据树，包含引擎在目标程序上匹配到的具有恶意或良性意图的调用链，其调用方法如下：

# 附加export_evidence=true查询参数，证据树DOT图数据将附加在响应json文本的evidence_dot字段中
curl -F "file=@sample.exe" "https://starlight-v3.ternaryop.top/scan?api_key=$KEY&export_evidence=true"

# 可以使用Python脚本将返回的证据树保存为dot文件
curl -s -F "file=@sample.exe" "https://starlight-v3.ternaryop.top/scan?api_key=$KEY&export_evidence=true" \
 | python3 -c "import sys,json; print(json.load(sys.stdin)['evidence_dot'])" > evidence.dot

HTTP响应状态码汇总