API 详细文档
了解所有可用的API参数、返回值、错误码和评分标准，以便进行深度集成。
接入地址
请求地址https://www.virusmark.com/scan
请求方法POST (必须使用POST方法)
请求体格式
application/x-www-form-urlencodedmultipart/form-data (上传文件)
参数优先级
file > sha256 > md5 > hashes
一个请求对应一条返回信息，云后端优先处理文件上传任务，为兼容旧版接口，按顺序依次最高优先级参数处理返回内容。请求参数说明
| 参数名 | 必填 | 类型 | 标签/优先级 | 说明 |
|---|---|---|---|---|
| token | 必填 | string | - | 访问令牌（示例：f47ac10b-58cc-4372-a567-0e02b2c3d479） |
| hashes推荐 | 可选 | Array[string] | P3 | 哈希数组（可混合MD5/SHA1/SHA256，单次最多10个） |
| file | 可选 | File | P0 | 待分析文件（此参数会覆盖所有哈希类参数） |
| sha256已弃用 | 可选 | string | P1 | 单个文件的SHA256值（此参数会覆盖md5和hashes） |
| md5已弃用 | 可选 | string | P2 | 单个文件的MD5值（仅当无sha256参数时生效） |
文件上传响应示例
{
"status": "Pending",
"response_code": 2,
"message": "文件 'MyMaliciousFile.exe' 已接收，等待处理",
"task_id": "c4ca4238a0b923820dcc509a6f75849b"
}- 01response_code=2 表示上传成功
- 02task_id 用于后续任务状态查询
批量查询响应示例
{
"c660fdb3bdb010d01de1324f1b83cfa3": {
"response_code": 1,
"status": "Malicious",
"score": 18,
"tag": "Malware.MakeDirs.Gen@AI!BM9uMx0Lo",
"md5": "c660fdb3bdb010d01de1324f1b83cfa3",
"sha256": "24c9147cbf25ccf3d5ac465307c5c936a5881a6e9c903832bb50841afbc33d63",
"updatetime": "2025-06-08T11:58:06.143+08:00",
"notes": "这是一种高风险的木马程序..."
},
"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855": {
"response_code": 0,
.......
}
}- 01每个键为请求中的哈希值（支持 MD5/SHA1/SHA256）。
- 02response_code=1 表示命中情报；response_code=0 表示未命中。
- 03updatetime 为该情报的更新时间。
- 04单次请求最多 10 个哈希，超过限制将返回业务码 -6。
- 05notes 为标签的介绍，可能包含风险等级、触发条件等。
文件评分标准
| 状态 | 说明 | hashes 新模式 | md5 旧模式 |
|---|---|---|---|
| Malicious | 确认恶意样本（如病毒、木马） | 0-100 (可信度越高) | 70-100 (风险越大) |
| Suspicious | 存在异常行为特征（如加壳、反调试） | 0-100 (可信度越高) | 50-69 (风险越大) |
| Clean | 无威胁特征（正常软件或零星漏检） | 0-100 (可信度越高) | 40 |
| Safe | 白名单（如官方签名程序） | 0-100 (可信度越高) | -1 |
| Unknown | 未找到匹配情报 | 固定值 0 | 固定值 0 |
使用 hashes 请求时，返回值的 score 将表示状态标识 status 的可信度，范围为 0-100，值越高表示越可信。
业务返回码说明
2文件已接收，正在处理中。
1哈希查询成功，已找到匹配的情报。
0哈希查询成功，未找到匹配情报。
-1哈希格式不正确 (不是有效的 MD5, SHA1,或 SHA256)。
-3认证令牌(Token/OTP)无效或已过期。
-4上传的文件体积过大 (超过 50MB)。
-6单次查询哈希数量过多 (>10)，需要限制每次请求的哈希数量。
-7参数不足（无文件且无哈希），请至少提供一个参数。
-10服务器外部组件错误，联系管理员排查。
-11服务器后端内部错误，联系管理员排查。
方式一：使用扩展组件接入
您可以下载我们为其他开发平台制作的通用接入组件，无需关心底层API请求细节，快速实现文件鉴定功能。
STEP 02
调用组件
使用您的开发语言调用外部程序，然后执行以下命令。请将占位符替换为您的实际值。
Scanner_SDK_HTTP2_SHA256.exe [path] [your_api_token]
示例: 假设您的 API 令牌是 `abc123`，要扫描的文件位于 `C:\files\test.exe`，则命令如下：
Scanner_SDK_HTTP2_SHA256.exe "C:\files\test.exe" abc123
STEP 03
处理输出
程序运行后，将直接在标准输出中打印 JSON 格式的扫描结果字符串。您可以捕获此输出来进行解析。
{"code": 200, "md5": "60823f6bf0020325a1db2d5ed25dba84", "score": 40, "tag": "Unknown"}
如果发生错误，程序将输出包含错误信息的 JSON 字符串。
特别提示：安全校验
请注意核对扩展组件哈希值，防止被植入后门代码。
MD5: 97f4a73cb13a94e698cb6b2330b3fee5
SHA256: f3b8072d1d68cd26fa89aadb203cfc60e9df6b1192f544210fdd23dec5b98836
方式二：直接 API 接入
对于需要更高灵活性和深度定制的开发者，可以直接通过 HTTP 请求与我们的 API 进行交互。以下是 Python 示例。
Python 示例 1: 单个哈希查询（新模式）
import requests
def scan_with_hashes(token, sha256_value):
url = 'https://www.virusmark.com/scan'
data = {
'token': token,
'hashes': [sha256_value]
}
response = requests.post(url, data=data)
print(f"查询哈希: {sha256_value}")
print(f"响应: {response.text}")
# --- 使用 ---
# token = 'your_token_here'
# sha256_value = '24c9147cbf25ccf3d5ac465307c5c936a5881a6e9c903832bb50841afbc33d63'
# scan_with_hashes(token, sha256_value)Python 示例 2: 批量哈希查询（新模式）
import requests
def scan_batch_hashes(token, hashes):
url = 'https://www.virusmark.com/scan'
data = {
'token': token,
'hashes': hashes
}
response = requests.post(url, data=data)
print(f"批量查询: {len(hashes)} 个哈希")
print(f"响应: {response.text}")
# --- 使用 ---
# token = 'your_token_here'
# hashes = [
# 'c660fdb3bdb010d01de1324f1b83cfa3',
# 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855'
# ]
# scan_batch_hashes(token, hashes)Python 示例 3: 直接上传文件（新模式）
import requests
import os
def scan_with_file_upload(token, file_path):
url = 'https://www.virusmark.com/scan'
with open(file_path, 'rb') as f:
files = {'file': (os.path.basename(file_path), f)}
data = {'token': token}
response = requests.post(url, files=files, data=data)
print(f"上传文件: {file_path}")
print(f"响应: {response.text}")
# --- 使用 ---
# token = 'your_token_here'
# file_path = 'path/to/your/file.exe'
# scan_with_file_upload(token, file_path)