zhaolei/MeshSate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: zhaolei:a372ee5a087211a5bd8073648ef7519183206cac
Branches Tags
zhaolei:main
zhaolei:v0.2.3 zhaolei:v0.2.2 zhaolei:v0.2.1
...
compare: zhaolei:d697f8a2f4ceacca17a1f465039a53ea682ea7e6
Branches Tags
zhaolei:main
zhaolei:v0.2.3 zhaolei:v0.2.2 zhaolei:v0.2.1

2 Commits
a372ee5a08 ... d697f8a2f4

Author SHA1 Message Date
zhaolei
d697f8a2f4 docs: 接口文档 v1.2 同步响应字段精简 
- §4.1 POST /scans 同步响应示例: 精简为 7 顶层字段
- §4.2 GET /scans/{id} pending 状态示例: 去掉 verdict/score
- §5 数据模型重写:
  - §5.1 响应字段: 精简为 6 个（task_id/action/reason/status/file/meta）
  - §5.2 action 取值: 去掉 pass_with_flag（合并进 pass）
  - §5.3 file 结构: 精简为 5 字段，砍 real_ext/declared_ext
  - §5.4 meta 结构: 精简为 2 字段（scan_duration_ms/scanned_at）
  - §5.5 新增内部判定字段章节: verdict/score/findings/triggered/open_risk/extracted 标注为内部使用不对外暴露
- §6 检测规则清单: 更新说明（findings 不对外暴露）
- 文档版本号: v1.1 → v1.2
 2026-10-29 16:29:55 +08:00
zhaolei
d99d179f0b refactor: API 响应彻底精简，只暴露调用方必须字段 
to_response() 重写：砍掉内部实现细节，对外只暴露 7 个顶层字段

保留: task_id, action, reason, status, file(精简), meta(精简)
砍掉: verdict, score, open_risk, findings, extracted, triggered
      meta 里的 engines/engine_errors/clamav/policy_version/policy_sha256
      file 里的 real_ext/declared_ext

设计原则: 调用方拿了就用，不暴露内部权重/严重度/引擎层/策略链
  - action:    调用方直接据此放行/拦截/转人工
  - reason:    人可读的判定理由
  - file.*:    哈希 + 真实类型，用于追溯举证
  - meta.*:    仅耗时 + 时间戳，排除实现细节

影响范围: 仅 to_response() 序列化方法
  - API POST/GET /api/v1/scans* 响应 → 精简 ✅
  - Console 控制台 → 直接用 ScanOutcome 对象属性，不受影响
  - DB 写入 persist_to_db() → 直接用 ScanOutcome 对象，不受影响
 2026-10-29 16:27:18 +08:00
2 changed files with 85 additions and 112 deletions
Expand all files Collapse all files

34
app/services/scanner.py
View File

@@ -159,21 +159,37 @@ class ScanOutcome:
)
def to_response(self, include_details: bool = True) -> Dict[str, Any]:
"""对外接口响应组装。
设计原则：调用方拿了就用，不暴露内部权重、严重度、引擎层、
策略链等实现细节。保留追溯所需的 task_id / file 哈希 / 时间戳。
对外暴露 4 个决策驱动字段：
- action: 调用方直接据此决定放行/拦截/转人工
- reason: 人可读的判定理由
- task_id: 用于后续查询 / 审计追溯
- file.*: 文件哈希与真实类型，用于追溯举证
"""
# file_info 里挑出调用方追溯需要的字段，其他（real_ext/declared_ext 等）砍
fi = self.file_info or {}
file_out = {k: fi.get(k) for k in (
"filename", "sha256", "md5", "size", "real_type",
) if fi.get(k) is not None}
# meta 只留耗时与时间戳，砍掉 engines/engine_errors/clamav/policy_version
meta_out = {}
for k in ("scan_duration_ms", "scanned_at"):
if self.meta and k in self.meta:
meta_out[k] = self.meta[k]
payload: Dict[str, Any] = {
"task_id": self.task_id,
"verdict": self.verdict,
"score": self.score,
"action": self.action,
"reason": self.reason,
"status": "completed",
"file": self.file_info,
"meta": self.meta,
"open_risk": self.open_risk,
"file": file_out,
"meta": meta_out,
}
if include_details:
payload["findings"] = [f.to_dict() for f in self.findings]
payload["extracted"] = self.extracted
payload["triggered"] = self.triggered
return payload

163
docs/接口文档.md
View File

@@ -2,7 +2,7 @@
| 项目 | 内容 |
|---|---|
| 文档版本 | v1.1（2026-10-27 对齐当前代码实现） |
| 文档版本 | v1.2（2026-10-29 响应字段精简，只暴露调用方必需字段） |
| 接口版本 | `/api/v1` |
| 适用系统 | 光闸内外网文件摆渡系统 |
| 保密级别 | **内部交付文档**，请勿公开传播 |
@@ -286,51 +286,25 @@ signature = HMAC-SHA256(response_key, payload) → 小写十六进制
```json
{
"task_id": "3f8a9c2e1b7d4e6f8a0b2c4d6e8f0a1b",
"verdict": "malicious",
"score": 85.0,
"action": "reject",
"reason": "检测到 VBA 宏 + DDEAUTO 自动执行",
"status": "completed",
"file": {
"filename": "起诉状.docx",
"sha256": "a1b2c3...",
"md5": "d4e5f6...",
"size": 284915,
"real_type": "Microsoft Word 2007+",
"real_ext": ".docx",
"declared_ext": ".docx",
"filename": "起诉状.docx"
"real_type": "Microsoft Word 2007+"
},
"findings": [
{
"engine": "document",
"layer": "L2",
"severity": "critical",
"rule": "DDEAutoExecution",
"detail": "检测到 DDE/DDEAUTO 字段：DDEAUTO c:\\windows\\system32\\cmd.exe",
"extracted_path": "word/settings.xml",
"weight": 65.0,
"meta": {}
}
],
"extracted": [
{ "path": "word/vbaProject.bin", "filename": "vbaProject.bin", "size": 10240, "depth": 1, "sha256": "" }
],
"triggered": [
{ "type": "rule_override", "rule": "DDEAutoExecution", "action": "reject", "engine": "document" }
],
"meta": {
"scan_duration_ms": 1840,
"engines": ["structure", "clamav", "document", "keywords", "yara", "binary"],
"engine_errors": [],
"clamav": { "version": "ClamAV 1.5.4", "signature_date": "2026-10-27" },
"policy_version": "2026.10.1",
"policy_sha256": "…",
"scanned_objects": 3,
"scanned_at": "2026-10-27T08:30:00+00:00"
"scanned_at": "2026-10-27T08:30:00Z"
}
}
```
> **设计原则**：接口只暴露调用方必须知道的字段，内部权重、严重度、引擎层、策略链等实现细节不对外返回。调用方拿到 `action` 即可直接决策，无需二次分析。
**响应 200（异步受理）**
```json
@@ -350,11 +324,11 @@ if result["status"] != "completed":
action = result["action"]
if action == "reject":
reject_transfer(reason=result["reason"]) # 拒绝并向用户展示 reason
reject_transfer(reason=result["reason"]) # 拦截，向用户展示 reason
elif action == "manual_review":
route_to_human_review(result["task_id"]) # 转人工
route_to_human_review(result["task_id"]) # 暂不放行，转人工
else:
allow_transfer() # pass / pass_with_flag
allow_transfer() # pass，正常放行
```
---
@@ -373,9 +347,7 @@ else:
{
"task_id": "…",
"status": "running",
"verdict": "pending",
"action": "pending",
"score": 0.0,
"reason": ""
}
```
@@ -506,93 +478,78 @@ else:
## 5. 数据模型
### 5.1 结论字段
### 5.1 响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `task_id` | string | 任务标识，全局唯一 |
| `verdict` | enum | 总体判定，见 §5.2 |
| `score` | float | 风险评分，0~100 |
| `action` | enum | 处置建议，见 §5.3 |
| `task_id` | string | 任务标识，全局唯一，用于后续查询与审计追溯 |
| `action` | enum | **调用方决策依据**，见 §5.2 |
| `reason` | string | 人可读的判定理由，可直接展示给用户 |
| `status` | enum | `pending` / `running` / `completed` / `failed` |
| `file` | object | 文件追溯信息，见 §5.3 |
| `meta` | object | 基础元信息，见 §5.4 |
### 5.2 verdict 取值
### 5.2 action 取值（调用方唯一决策依据）
| 值 | 含义 | 调用方动作 |
|---|---|---|
| `pass` | 未发现风险或仅极轻微信号 | 正常放行 |
| `manual_review` | 可疑，需人工判断 | **暂不放行**，转入人工复核流程 |
| `reject` | 判定不可放行 | 拒绝传输，向用户展示 `reason` |
| `pending` | 异步尚未完成 | 等待轮询 |
> **`action` 是调用方唯一需要判断的字段**，不需要关心内部权重、严重度、触发了几条规则。
### 5.3 file 结构
| 字段 | 说明 |
|---|---|
| `filename` | 原始文件名 |
| `sha256` | 文件哈希，用于去重与追溯举证 |
| `md5` | 文件哈希，兼容场景使用 |
| `size` | 字节数 |
| `real_type` | 内容判定的真实类型描述（如 `JPEG image data`） |
> 不对外暴露 `real_ext` / `declared_ext`（内部判定使用）。
### 5.4 meta 结构
| 字段 | 说明 |
|---|---|
| `scan_duration_ms` | 本次检测耗时（毫秒） |
| `scanned_at` | 检测时间（UTC） |
> 不对外暴露 `engines` / `engine_errors` / `clamav` 版本 / `policy_version` / `policy_sha256` / `scanned_objects` 等内部实现细节。这些信息保留在服务端控制台与审计日志中，运维人员按需查询。
---
### 5.5 内部判定字段（不对外暴露）
以下字段存在于服务端内部（控制台、审计日志、DB 记录），不通过 API 返回。调用方无需关心。
**verdict（内部总体判定）**
| 值 | 含义 |
|---|---|
| `clean` | 未发现风险 |
| `suspicious` | 存在可疑信号，需要关注或人工判断 |
| `suspicious` | 存在可疑信号 |
| `malicious` | 判定为恶意 |
| `error` | 检测过程异常（如引擎不可用），结论不可信 |
| `error` | 检测过程异常 |
| `pending` | 尚未完成 |
### 5.3 action 取值
**score（内部权重和，0~100）** — 调用方不做二次分析，不对外暴露。
| 值 | 含义 | 建议调用方动作 |
|---|---|---|
| `pass` | 未发现问题 | 正常放行 |
| `pass_with_flag` | 存在低风险信号 | 放行，但建议记录标记 |
| `manual_review` | 需人工判断 | **暂不放行**，转入人工复核流程 |
| `reject` | 判定不可放行 | 拒绝传输，向用户展示 `reason` |
| `pending` | 尚未裁决 | 等待异步结果 |
**findings（内部命中信号列表）** — 每条含 engine / layer / severity / rule / detail / weight / meta 等字段，供安全团队审计与问题追溯。不对外暴露。
> **`action` 与 `verdict` 解耦使用。** 业务逻辑请依据 `action`，`verdict` 供人查看与统计。
**triggered（内部策略链触发记录）** — rule_override / zero_tolerance 等，不对外暴露。
### 5.4 findings 结构
| 字段 | 类型 | 说明 |
|---|---|---|
| `engine` | string | 引擎名：`structure` / `extractor` / `clamav` / `document` / `yara` / `binary` |
| `layer` | string | 检测层：`L0` / `L1` / `L2` / `L2B` / `L3` |
| `severity` | enum | `info` / `low` / `medium` / `high` / `critical` |
| `rule` | string | 规则标识 |
| `detail` | string | 命中详情 |
| `extracted_path` | string | 信号来自哪个内部路径（顶层文件为空） |
| `weight` | float | 该信号的风险权重 |
| `meta` | object | 引擎附加信息 |
### 5.5 严重度与权重对照
| 严重度 | 典型含义 | 权重区间 |
|---|---|---|
| `critical` | 确凿的恶意行为，自动执行、外联、路径穿越 | 50 ~ 90 |
| `high` | 高度可疑，宏调用、危险 API、高熵加壳 | 30 ~ 80 |
| `medium` | 可疑但存在合理场景，外部链接、可疑导入 | 15 ~ 45 |
| `low` | 轻微信号，仅编码字符串、无签名 | 5 ~ 20 |
| `info` | 信息性提示 | 0 |
### 5.6 file 结构
| 字段 | 说明 |
|---|---|
| `sha256` / `md5` | 文件哈希，用于去重与追溯 |
| `size` | 字节数 |
| `real_type` | 内容判定的真实类型描述 |
| `real_ext` | 真实扩展名（由内容推导） |
| `declared_ext` | 文件名声明的扩展名 |
| `filename` | 原始文件名 |
### 5.7 meta 结构
| 字段 | 说明 |
|---|---|
| `scan_duration_ms` | 检测耗时（毫秒） |
| `engines` | 参与的引擎列表 |
| `engine_errors` | 不可用的引擎列表，非空说明结论可能不完整 |
| `clamav` | ClamAV 版本与签名库编号 |
| `policy_version` | 判定所依据的策略版本 |
| `policy_sha256` | 策略文件哈希 |
| `scanned_objects` | 实际检测的对象数（含递归解包出的子文件） |
| `scanned_at` | 检测时间（UTC） |
> **`meta.clamav` 与 `meta.policy_version` 建议留存**，用于检测结果的有效性举证。
**open_risk / extracted（内部辅助分析与解包过程）** — 不对外暴露。
---
## 6. 检测规则清单
以下规则命中时会出现在 `findings` 中。**规则清单公开用于解释结论，不含检测规则的具体实现内容。**
以下规则命中时会在服务端审计日志中留下记录，调用方通过 `reason` 字段获得人可读的结论说明。**规则清单公开用于解释结论，不含检测规则的具体实现内容。**
### 6.1 L0 结构层