# ============================================================================= # 企微IT智能服务台 — 火绒集成数据模型 # ============================================================================= # 说明：火绒API请求/响应的 Pydantic 数据模型 # 包含：终端信息、漏洞信息、病毒事件、任务下发等 # ============================================================================= from typing import Any, Dict, List, Optional from pydantic import BaseModel, Field, model_validator # ========================================================================== # 通用响应模型 # ========================================================================== class HuorongApiResponse(BaseModel): """火绒API统一响应模型。 火绒所有API返回格式一致（官方API文档 v1）： 成功时: { "errno": 0, "errmsg": "", "data": { ... } } 失败时: { "errno": 1, "errmsg": "Authentication failed" } 官方错误码定义： - errno=0: 成功 - errno=1: 认证失败 - errno=2: 参数错误 - errno=3: 服务器内部错误 - errno=4: API未授权 注意：火绒API始终使用 errno（不是 errcode）。 使用 model_validator 在验证前将 errno 归一化为 errcode， 保持内部代码统一使用 errcode 字段。 Attributes: errcode: 错误码，0表示成功（从 errno 归一化而来） errmsg: 错误描述（成功时为空字符串） data: 业务数据（成功时非None） """ @model_validator(mode='before') @classmethod def normalize_error_fields(cls, data: Any) -> Any: """将火绒API返回的 errno 字段归一化为 errcode。 火绒API在认证失败等错误场景下返回 errno 而非 errcode， 此验证器在 Pydantic 字段校验前将 errno 转换为 errcode， 统一后续处理逻辑。 Args: data: 原始输入数据（通常为dict） Returns: 归一化后的数据 """ if isinstance(data, dict) and 'errno' in data and 'errcode' not in data: data['errcode'] = data.pop('errno') return data errcode: int = Field(..., description="错误码，0=成功") errmsg: str = Field(default="ok", description="错误描述") data: Optional[Any] = Field(default=None, description="业务数据") # ========================================================================== # 终端基本信息 — /api/clnts/_list 返回 # ========================================================================== class TerminalBasicInfo(BaseModel): """终端基本信息（_list 接口返回的每条记录）。 字段名严格按照火绒API文档实际返回值定义。 注意：API返回的字段名与之前猜测不同，已根据官方文档修正。 Attributes: id: 内部数据库ID client_id: 终端唯一ID（40位十六进制字符串，用于所有任务下发） client_name: 客户端名称 computer_name: 计算机名 local_ip: 本地IP connect_ip: 连接IP（客户端连接控制中心使用的IP） mac: MAC地址 group_id: 分组ID os_version: 操作系统版本 version: 火绒客户端版本 definitions: 病毒库更新时间 is_online: 在线状态 last_connect_time: 最后连接时间（Unix时间戳） last_seen_time: 最后可见时间（Unix时间戳） first_appear_time: 首次出现时间（Unix时间戳） """ id: Optional[int] = Field(default=None, description="内部数据库ID") client_id: str = Field(..., description="终端唯一ID") client_name: str = Field(default="", description="客户端名称") computer_name: str = Field(default="", description="计算机名") local_ip: str = Field(default="", description="本地IP") connect_ip: str = Field(default="", description="连接IP") mac: str = Field(default="", description="MAC地址") group_id: Optional[Any] = Field(default=None, description="分组ID（int或str）") os_version: str = Field(default="", description="操作系统版本") version: str = Field(default="", description="火绒客户端版本") definitions: str = Field(default="", description="病毒库更新时间") is_online: bool = Field(default=False, description="在线状态") last_connect_time: Optional[int] = Field(default=None, description="最后连接时间") last_seen_time: Optional[int] = Field(default=None, description="最后可见时间") first_appear_time: Optional[int] = Field(default=None, description="首次出现时间") class TerminalListRequest(BaseModel): """终端列表查询请求。 Attributes: group_id: 分组ID（可选，不传则查全部分组） page: 页码（从1开始） per_page: 每页条数 """ group_id: Optional[str] = Field(default=None, description="分组ID") page: int = Field(default=1, ge=1, description="页码") per_page: int = Field(default=20, ge=1, le=100, description="每页条数") # ========================================================================== # 终端详细信息v2 — /api/clnts/_info2 返回 # ========================================================================== class HardwareInfo(BaseModel): """终端硬件信息。 Attributes: cpu: CPU信息 memory: 内存信息 disk: 磁盘信息 motherboard: 主板信息 network_card: 网卡信息 """ cpu: str = Field(default="", description="CPU信息") memory: str = Field(default="", description="内存信息") disk: str = Field(default="", description="磁盘信息") motherboard: str = Field(default="", description="主板信息") network_card: str = Field(default="", description="网卡信息") class SoftwareInfo(BaseModel): """已安装软件条目。 Attributes: name: 软件名称 version: 版本号 publisher: 发布者 """ name: str = Field(default="", description="软件名称") version: str = Field(default="", description="版本号") publisher: str = Field(default="", description="发布者") class AssetInfo(BaseModel): """资产信息。 Attributes: asset_tag: 资产标签 serial_number: 序列号 """ asset_tag: str = Field(default="", description="资产标签") serial_number: str = Field(default="", description="序列号") class NetworkConfig(BaseModel): """网络配置信息。 Attributes: ip: IP地址 gateway: 网关 dns: DNS服务器 adapter_info: 网卡适配器信息 """ ip: str = Field(default="", description="IP地址") gateway: str = Field(default="", description="网关") dns: str = Field(default="", description="DNS服务器") adapter_info: str = Field(default="", description="网卡适配器信息") class TerminalDetailV2(BaseModel): """终端详细信息v2（_info2 接口返回）。 通过 optional_fields 参数指定需要返回的信息块： - hardware: 硬件信息 - software: 已安装软件 - assets: 资产信息 - netconf: 网络配置 Attributes: client_id: 终端唯一ID computer_name: 计算机名 hardware: 硬件信息（可选） software: 已安装软件列表（可选） assets: 资产信息（可选） netconf: 网络配置（可选） """ client_id: str = Field(..., description="终端唯一ID") computer_name: str = Field(default="", description="计算机名") hardware: Optional[HardwareInfo] = Field(default=None, description="硬件信息") software: Optional[List[SoftwareInfo]] = Field(default=None, description="已安装软件") assets: Optional[AssetInfo] = Field(default=None, description="资产信息") netconf: Optional[NetworkConfig] = Field(default=None, description="网络配置") class TerminalDetailRequest(BaseModel): """终端详细信息查询请求。 Attributes: client_id: 终端唯一ID optional_fields: 需要返回的可选信息块列表 """ client_id: str = Field(..., description="终端唯一ID") optional_fields: List[str] = Field( default_factory=lambda: ["hardware", "software", "assets", "netconf"], description="可选信息块: hardware/software/assets/netconf", ) # ========================================================================== # 漏洞信息 — /api/clnts/_leak 返回 # 说明：_leak 接口返回的是"存在高危漏洞未修复的终端列表"， # 每条记录是终端信息（非漏洞详情），API不返回具体漏洞CVE列表。 # 外层还有 all_client（终端总数）和 risk_client（高危终端数）统计。 # ========================================================================== class TerminalLeakInfo(BaseModel): """存在高危漏洞的终端信息（_leak 接口返回的每条记录）。 注意：_leak 返回的是终端维度数据，不是漏洞维度。 字段名严格按照火绒API文档实际返回值定义。 与 _list 接口的字段名不同！ Attributes: cid: 终端唯一ID（_leak 中叫 cid，_list 中叫 client_id） hostname: 计算机名（_leak 中叫 hostname，_list 中叫 computer_name） client_name: 终端名称 group_name: 分组名称 group_id: 分组ID ip_addr: 本地IP（_leak 中叫 ip_addr，_list 中叫 local_ip） call_ip: 连接IP（_leak 中叫 call_ip，_list 中叫 connect_ip） mac: MAC地址 osver: 操作系统版本（_leak 中叫 osver，_list 中叫 os_version） os_type: 终端类型（如 Windows） prodver: 火绒客户端版本（_leak 中叫 prodver，_list 中叫 version） virdb: 病毒库版本（Unix时间戳，_leak 中叫 virdb，_list 中叫 definitions） stat: 在线状态码（1=离线, 2=在线, 3=异常，_list 中是 is_online 布尔值） """ cid: str = Field(..., description="终端唯一ID") hostname: str = Field(default="", description="计算机名") client_name: str = Field(default="", description="终端名称") group_name: str = Field(default="", description="分组名称") group_id: Optional[Any] = Field(default=None, description="分组ID") ip_addr: str = Field(default="", description="本地IP") call_ip: str = Field(default="", description="连接IP") mac: str = Field(default="", description="MAC地址") osver: str = Field(default="", description="操作系统版本") os_type: str = Field(default="", description="终端类型") prodver: str = Field(default="", description="火绒客户端版本") virdb: Optional[Any] = Field(default=None, description="病毒库版本(Unix时间戳)") stat: int = Field(default=1, description="在线状态码: 1=离线 2=在线 3=异常") # ========================================================================== # 病毒事件 — /api/clnts/_virus_events 返回 # 说明：_virus_events 返回终端维度的病毒日志统计， # 含总数(count)和4种处理结果(result)的明细。 # 请求需指定 type: 0=按client_id查, 1=按group_id查, 2=查全部 # ========================================================================== class VirusHandleResult(BaseModel): """病毒事件处理结果统计。 Attributes: success: 处理成功数 fail: 处理失败数 ignored: 暂不处理数 trusted: 已信任数 """ success: int = Field(default=0, description="处理成功数") fail: int = Field(default=0, description="处理失败数") ignored: int = Field(default=0, description="暂不处理数") trusted: int = Field(default=0, description="已信任数") class VirusEventStats(BaseModel): """终端病毒事件统计（_virus_events 接口返回的每条记录）。 字段名严格按照火绒API文档实际返回值定义。 与 _list 接口的字段名基本一致。 Attributes: group_id: 分组ID client_id: 终端唯一ID client_name: 终端名称 computer_name: 计算机名 local_ip: 本地IP connect_ip: 连接IP mac: MAC地址 count: 病毒日志总数 result: 处理结果统计（success/fail/ignored/trusted） """ group_id: Optional[Any] = Field(default=None, description="分组ID") client_id: str = Field(..., description="终端唯一ID") client_name: str = Field(default="", description="终端名称") computer_name: str = Field(default="", description="计算机名") local_ip: str = Field(default="", description="本地IP") connect_ip: str = Field(default="", description="连接IP") mac: str = Field(default="", description="MAC地址") count: int = Field(default=0, description="病毒日志总数") result: Optional[VirusHandleResult] = Field(default=None, description="处理结果统计") # ========================================================================== # 终端任务 — /api/task/_create # ========================================================================== class TaskCreateRequest(BaseModel): """终端任务创建请求。 支持的任务类型： - quick_scan: 快速扫描 - full_scan: 全盘扫描 - custom_scan: 自定义扫描 - netctrl: 终端隔离/解除 - message: 发送通知 Attributes: task_type: 任务类型 client_ids: 目标终端ID列表 net_isolation: 是否隔离（仅 netctrl 类型有效） message_content: 通知内容（仅 message 类型有效） """ task_type: str = Field(..., description="任务类型: quick_scan/full_scan/custom_scan/netctrl/message") client_ids: List[str] = Field(..., min_length=1, description="目标终端ID列表") net_isolation: Optional[bool] = Field(default=None, description="是否隔离（仅netctrl类型）") message_content: Optional[str] = Field(default=None, description="通知内容（仅message类型）") # ========================================================================== # 终端安全画像（聚合模型，供前端直接使用） # ========================================================================== class TerminalSecurityProfile(BaseModel): """终端安全画像（聚合模型）。 将终端基本信息+安全状态聚合成一个模型，供坐席端直接展示。 Attributes: client_id: 终端唯一ID computer_name: 计算机名 ip: 本地IP mac: MAC地址 os_version: 操作系统版本 is_online: 在线状态 group_name: 分组名称 hardware: 硬件概要 high_risk_leaks: 高危漏洞数 uncleaned_virus: 未处理病毒事件数 security_score: 安全评分（0-100，综合漏洞+病毒+在线状态） """ client_id: str = Field(..., description="终端唯一ID") computer_name: str = Field(default="", description="计算机名") ip: str = Field(default="", description="本地IP") mac: str = Field(default="", description="MAC地址") os_version: str = Field(default="", description="操作系统版本") is_online: bool = Field(default=False, description="在线状态") group_name: str = Field(default="", description="分组名称") hardware: Optional[HardwareInfo] = Field(default=None, description="硬件概要") high_risk_leaks: int = Field(default=0, description="高危漏洞数") uncleaned_virus: int = Field(default=0, description="未处理病毒事件数") security_score: int = Field(default=100, description="安全评分(0-100)")