659 lines
24 KiB
Python
659 lines
24 KiB
Python
|
# =============================================================================
|
|||
|
|
# 企微IT智能服务台 — 火绒终端安全 API 客户端
|
|||
|
|
# =============================================================================
|
|||
|
|
# 说明：封装火绒API的签名、请求、响应处理
|
|||
|
|
# 核心功能：
|
|||
|
|
# 1. HRESS 签名实现（Authorization Header 方式）
|
|||
|
|
# 2. 统一请求封装（超时、重试、异常处理）
|
|||
|
|
# 3. P0 接口：终端列表 _list / 终端详情 _info2 / 高危漏洞 _leak / 病毒事件 _virus_events
|
|||
|
|
# 4. P1 接口：终端隔离/解除 _create(netctrl) / 快速扫描 / 在线终端查询
|
|||
|
|
# 签名算法（来自火绒官方API文档 v1）：
|
|||
|
|
# Authorization = "HRESS" + AccessKeyId + ":" + Expires + ":" + Signature
|
|||
|
|
# Signature = urlencode(base64(hmac-sha1(AccessKeySecret,
|
|||
|
|
# AccessKeyId + "\n" + Expires + "\n" + HTTP-METHOD + "\n"
|
|||
|
|
# + Content-MD5 + "\n" + CanonicalizedResource)))
|
|||
|
|
# CanonicalizedResource = API路径（无前导/），含排序后的查询参数
|
|||
|
|
# Content-MD5 = base64(md5_digest(body_bytes)) — RFC2616
|
|||
|
|
# 使用方式：
|
|||
|
|
# client = HuorongClient(access_key_id="...", access_key_secret="...", base_url="...")
|
|||
|
|
# terminals = await client.list_terminals()
|
|||
|
|
# =============================================================================
|
|||
|
|
|
|||
|
|
import base64
|
|||
|
|
import hashlib
|
|||
|
|
import hmac
|
|||
|
|
import json
|
|||
|
|
import logging
|
|||
|
|
import time
|
|||
|
|
from typing import Any, Dict, List, Optional
|
|||
|
|
from urllib.parse import quote
|
|||
|
|
|
|||
|
|
import httpx
|
|||
|
|
|
|||
|
|
from .exceptions import (
|
|||
|
|
HuorongApiError,
|
|||
|
|
HuorongAuthError,
|
|||
|
|
HuorongConnectionError,
|
|||
|
|
HuorongError,
|
|||
|
|
)
|
|||
|
|
from .models import (
|
|||
|
|
HuorongApiResponse,
|
|||
|
|
TerminalBasicInfo,
|
|||
|
|
TerminalDetailV2,
|
|||
|
|
TerminalLeakInfo,
|
|||
|
|
VirusEventStats,
|
|||
|
|
VirusHandleResult,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
logger = logging.getLogger(__name__)
|
|||
|
|
|
|||
|
|
# 默认请求超时（秒）— 火绒内网响应通常在1秒内，3秒足够兜底
|
|||
|
|
# 注意：_virus_events 查询全部终端时可能较慢，需要更长超时
|
|||
|
|
DEFAULT_TIMEOUT = 10.0
|
|||
|
|
|
|||
|
|
# 默认分页大小
|
|||
|
|
DEFAULT_PAGE_SIZE = 20
|
|||
|
|
|
|||
|
|
# 签名有效期（秒）— 请求签名中的 Expires 字段
|
|||
|
|
SIGN_EXPIRES_SECONDS = 300
|
|||
|
|
|
|||
|
|
|
|||
|
|
class HuorongClient:
|
|||
|
|
"""火绒终端安全 API 客户端。
|
|||
|
|
|
|||
|
|
封装了火绒API的签名认证、请求发送和响应解析。
|
|||
|
|
所有方法均为异步（async），使用 httpx.AsyncClient 发送请求。
|
|||
|
|
|
|||
|
|
签名方式：HRESS Authorization Header
|
|||
|
|
参考：火绒终端安全管理系统API说明文档 v1
|
|||
|
|
|
|||
|
|
Attributes:
|
|||
|
|
access_key_id: 火绒 AccessKey ID（控制中心显示为 Secret ID）
|
|||
|
|
access_key_secret: 火绒 AccessKey Secret（控制中心显示为 Secret Key）
|
|||
|
|
base_url: 火绒API内网地址（如 http://huorong.oa.servyou-it.com:8080）
|
|||
|
|
timeout: 请求超时秒数
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
def __init__(
|
|||
|
|
self,
|
|||
|
|
access_key_id: str,
|
|||
|
|
access_key_secret: str,
|
|||
|
|
base_url: str,
|
|||
|
|
timeout: float = DEFAULT_TIMEOUT,
|
|||
|
|
):
|
|||
|
|
"""初始化火绒API客户端。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
access_key_id: 火绒 AccessKey ID（控制中心显示为 Secret ID）
|
|||
|
|
access_key_secret: 火绒 AccessKey Secret（控制中心显示为 Secret Key）
|
|||
|
|
base_url: 火绒API内网地址（不含尾部斜杠）
|
|||
|
|
timeout: 请求超时秒数，默认3秒
|
|||
|
|
"""
|
|||
|
|
self.access_key_id = access_key_id
|
|||
|
|
self.access_key_secret = access_key_secret
|
|||
|
|
# 确保 base_url 不以 / 结尾，拼接路径时统一加 /
|
|||
|
|
self.base_url = base_url.rstrip("/")
|
|||
|
|
self.timeout = timeout
|
|||
|
|
|
|||
|
|
# ======================================================================
|
|||
|
|
# 签名实现（HRESS Authorization Header 方式）
|
|||
|
|
# ======================================================================
|
|||
|
|
|
|||
|
|
def _compute_content_md5(self, body_bytes: bytes) -> str:
|
|||
|
|
"""计算请求体的 Content-MD5（RFC2616）。
|
|||
|
|
|
|||
|
|
算法步骤：
|
|||
|
|
1. 计算请求体的 MD5 二进制摘要（128位）
|
|||
|
|
2. 对二进制摘要进行 base64 编码
|
|||
|
|
|
|||
|
|
注意：不是对32位十六进制字符串编码，而是对原始二进制摘要编码。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
body_bytes: 请求体的字节内容
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
str: base64 编码的 MD5 摘要
|
|||
|
|
"""
|
|||
|
|
md5_digest = hashlib.md5(body_bytes).digest()
|
|||
|
|
return base64.b64encode(md5_digest).decode("utf-8")
|
|||
|
|
|
|||
|
|
def _build_canonicalized_resource(self, path: str) -> str:
|
|||
|
|
"""构建 CanonicalizedResource。
|
|||
|
|
|
|||
|
|
根据火绒API文档：
|
|||
|
|
1. 将 CanonicalizedResource 置为空字符串
|
|||
|
|
2. 设置要访问的资源路径（去掉前导 /），如 "api/clnts/_list"
|
|||
|
|
3. 如果请求包含子资源（查询参数），按字典序排列，
|
|||
|
|
以 & 为分隔符生成子资源字符串，末尾添加 ? 和子资源字符串
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
- /api/clnts/_list → "api/clnts/_list"
|
|||
|
|
- /api/group/_info?group_id=1 → "api/group/_info?group_id=1"
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
path: 请求路径（如 /api/clnts/_list）
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
str: CanonicalizedResource 字符串
|
|||
|
|
"""
|
|||
|
|
# 去掉前导 /
|
|||
|
|
return path.lstrip("/")
|
|||
|
|
|
|||
|
|
def _sign_request(
|
|||
|
|
self,
|
|||
|
|
method: str,
|
|||
|
|
path: str,
|
|||
|
|
body_bytes: bytes = b"",
|
|||
|
|
) -> Dict[str, str]:
|
|||
|
|
"""生成火绒API请求签名（HRESS Authorization Header 方式）。
|
|||
|
|
|
|||
|
|
签名算法（来自火绒官方API文档）：
|
|||
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|||
|
|
│ Authorization = "HRESS" + AccessKeyId + ":" + Expires + ":" + Signature │
|
|||
|
|
│ │
|
|||
|
|
│ Signature = urlencode(base64(hmac-sha1(AccessKeySecret, │
|
|||
|
|
│ AccessKeyId + "\\n" │
|
|||
|
|
│ + Expires + "\\n" │
|
|||
|
|
│ + HTTP-METHOD + "\\n" │
|
|||
|
|
│ + Content-MD5 + "\\n" │
|
|||
|
|
│ + CanonicalizedResource))) │
|
|||
|
|
└─────────────────────────────────────────────────────────────────┘
|
|||
|
|
|
|||
|
|
其中：
|
|||
|
|
- AccessKeyId: 标识用户身份
|
|||
|
|
- Expires: Unix 时间戳，签名过期时间（当前时间 + 300秒）
|
|||
|
|
- HTTP-METHOD: POST（火绒API统一使用 POST）
|
|||
|
|
- Content-MD5: 请求体的 RFC2616 MD5（base64编码）
|
|||
|
|
- CanonicalizedResource: API资源路径（去掉前导/）
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
method: HTTP方法（POST）
|
|||
|
|
path: 请求路径（如 /api/clnts/_list）
|
|||
|
|
body_bytes: 请求体字节内容
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict[str, str]: 包含 Authorization 和 Content-Type 的 Header 字典
|
|||
|
|
"""
|
|||
|
|
# 1. 计算过期时间（Unix时间戳）
|
|||
|
|
expires = str(int(time.time()) + SIGN_EXPIRES_SECONDS)
|
|||
|
|
|
|||
|
|
# 2. 计算 Content-MD5（RFC2616: MD5 二进制摘要 → base64）
|
|||
|
|
content_md5 = self._compute_content_md5(body_bytes) if body_bytes else ""
|
|||
|
|
|
|||
|
|
# 3. 构建 CanonicalizedResource（去掉前导 /）
|
|||
|
|
canonicalized_resource = self._build_canonicalized_resource(path)
|
|||
|
|
|
|||
|
|
# 4. 构建签名字符串
|
|||
|
|
string_to_sign = (
|
|||
|
|
self.access_key_id + "\n"
|
|||
|
|
+ expires + "\n"
|
|||
|
|
+ method + "\n"
|
|||
|
|
+ content_md5 + "\n"
|
|||
|
|
+ canonicalized_resource
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 5. HMAC-SHA1 签名 → base64 编码 → URL 编码
|
|||
|
|
signature_raw = hmac.new(
|
|||
|
|
self.access_key_secret.encode("utf-8"), # 密钥
|
|||
|
|
string_to_sign.encode("utf-8"), # 待签名字符串
|
|||
|
|
hashlib.sha1, # 算法
|
|||
|
|
).digest()
|
|||
|
|
signature_b64 = base64.b64encode(signature_raw).decode("utf-8")
|
|||
|
|
signature_encoded = quote(signature_b64, safe="")
|
|||
|
|
|
|||
|
|
# 6. 拼接 Authorization Header
|
|||
|
|
# 格式: "HRESS" + AccessKeyId + ":" + Expires + ":" + Signature
|
|||
|
|
authorization = f"HRESS{self.access_key_id}:{expires}:{signature_encoded}"
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
"Authorization": authorization,
|
|||
|
|
"Content-Type": "application/json; charset=utf-8",
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# ======================================================================
|
|||
|
|
# 通用请求方法
|
|||
|
|
# ======================================================================
|
|||
|
|
|
|||
|
|
async def _request(
|
|||
|
|
self,
|
|||
|
|
path: str,
|
|||
|
|
body: Optional[Dict[str, Any]] = None,
|
|||
|
|
) -> HuorongApiResponse:
|
|||
|
|
"""发送签名请求到火绒API。
|
|||
|
|
|
|||
|
|
统一处理：
|
|||
|
|
1. HRESS 签名 Authorization Header 生成
|
|||
|
|
2. HTTP请求发送（POST，超时控制）
|
|||
|
|
3. 响应解析和错误码处理
|
|||
|
|
4. 异常分类（认证/连接/API业务错误）
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
path: API路径（如 /api/clnts/_list）
|
|||
|
|
body: 请求体字典（可选）
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
HuorongApiResponse: 火绒API响应
|
|||
|
|
|
|||
|
|
Raises:
|
|||
|
|
HuorongConnectionError: 网络不通或超时
|
|||
|
|
HuorongAuthError: 签名验证失败
|
|||
|
|
HuorongApiError: 火绒API返回业务错误
|
|||
|
|
"""
|
|||
|
|
# 构建完整URL
|
|||
|
|
url = f"{self.base_url}{path}"
|
|||
|
|
|
|||
|
|
# 序列化请求体为字节（签名基于字节内容）
|
|||
|
|
body_bytes = json.dumps(body, separators=(",", ":")).encode("utf-8") if body else b"{}"
|
|||
|
|
|
|||
|
|
# 生成签名 Header
|
|||
|
|
headers = self._sign_request("POST", path, body_bytes)
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
async with httpx.AsyncClient(timeout=self.timeout) as client:
|
|||
|
|
logger.debug(
|
|||
|
|
f"火绒API请求: POST {url}\n"
|
|||
|
|
f" AccessKeyID: {self.access_key_id}\n"
|
|||
|
|
f" Path: {path}\n"
|
|||
|
|
f" Body: {body_bytes[:200].decode('utf-8', errors='replace')}\n"
|
|||
|
|
f" Authorization: {headers.get('Authorization', 'N/A')[:60]}..."
|
|||
|
|
)
|
|||
|
|
response = await client.post(url, headers=headers, content=body_bytes)
|
|||
|
|
|
|||
|
|
# HTTP层面错误
|
|||
|
|
if response.status_code == 401:
|
|||
|
|
raise HuorongAuthError()
|
|||
|
|
if response.status_code != 200:
|
|||
|
|
raise HuorongApiError(
|
|||
|
|
code=response.status_code,
|
|||
|
|
message=f"HTTP {response.status_code}: {response.text[:200]}",
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 解析JSON响应
|
|||
|
|
resp_data = response.json()
|
|||
|
|
api_resp = HuorongApiResponse(**resp_data)
|
|||
|
|
|
|||
|
|
# 火绒业务错误码处理
|
|||
|
|
# 官方文档定义的错误码：
|
|||
|
|
# - errno=0: 成功
|
|||
|
|
# - errno=1: 认证失败
|
|||
|
|
# - errno=2: 参数错误
|
|||
|
|
# - errno=3: 服务器内部错误
|
|||
|
|
# - errno=4: API未授权
|
|||
|
|
if api_resp.errcode != 0:
|
|||
|
|
if api_resp.errcode == 1 or api_resp.errcode in (401, 403):
|
|||
|
|
raise HuorongAuthError(f"认证/权限失败: {api_resp.errmsg}")
|
|||
|
|
if api_resp.errcode == 4:
|
|||
|
|
raise HuorongApiError(
|
|||
|
|
code=api_resp.errcode,
|
|||
|
|
message=f"API未授权: {api_resp.errmsg}",
|
|||
|
|
)
|
|||
|
|
raise HuorongApiError(
|
|||
|
|
code=api_resp.errcode,
|
|||
|
|
message=api_resp.errmsg,
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
return api_resp
|
|||
|
|
|
|||
|
|
except httpx.TimeoutException:
|
|||
|
|
raise HuorongConnectionError(f"火绒API请求超时（{self.timeout}秒）: {url}")
|
|||
|
|
except httpx.ConnectError:
|
|||
|
|
raise HuorongConnectionError(f"无法连接火绒服务器: {url}")
|
|||
|
|
except (HuorongAuthError, HuorongApiError, HuorongConnectionError):
|
|||
|
|
# 已分类异常，直接向上抛出
|
|||
|
|
raise
|
|||
|
|
except Exception as e:
|
|||
|
|
# 未预期异常，包装为通用错误
|
|||
|
|
logger.error(f"火绒API未预期异常: {type(e).__name__}: {e}")
|
|||
|
|
raise HuorongError(code=-1, message=f"火绒API调用异常: {e}")
|
|||
|
|
|
|||
|
|
# ======================================================================
|
|||
|
|
# P0 接口：查询能力
|
|||
|
|
# ======================================================================
|
|||
|
|
|
|||
|
|
async def list_terminals(
|
|||
|
|
self,
|
|||
|
|
group_id: Optional[str] = None,
|
|||
|
|
page: int = 1,
|
|||
|
|
per_page: int = DEFAULT_PAGE_SIZE,
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""查询终端基本信息列表。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/clnts/_list
|
|||
|
|
官方参数: limit(每页条数, 默认15, 最大200) + offset(起始索引, 默认0)
|
|||
|
|
本方法将 page/per_page 转换为 limit/offset，保持外部接口一致。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
group_id: 分组ID（可选，不传则查全部分组）
|
|||
|
|
page: 页码（从1开始，内部转换为offset）
|
|||
|
|
per_page: 每页条数（内部转换为limit）
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 包含 total(总数) 和 items(TerminalBasicInfo列表)
|
|||
|
|
"""
|
|||
|
|
# 火绒API使用 limit/offset 分页，不是 page/per_page
|
|||
|
|
limit = min(per_page, 200) # 火绒限制最大200
|
|||
|
|
offset = (page - 1) * limit
|
|||
|
|
|
|||
|
|
body: Dict[str, Any] = {
|
|||
|
|
"limit": limit,
|
|||
|
|
"offset": offset,
|
|||
|
|
}
|
|||
|
|
if group_id:
|
|||
|
|
body["group_id"] = int(group_id)
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/clnts/_list", body)
|
|||
|
|
|
|||
|
|
# 解析响应数据
|
|||
|
|
data = resp.data or {}
|
|||
|
|
raw_items = data.get("list", [])
|
|||
|
|
total = data.get("total", 0)
|
|||
|
|
|
|||
|
|
items = [TerminalBasicInfo(**item) for item in raw_items]
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
"total": total,
|
|||
|
|
"items": items,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def get_terminal_detail(
|
|||
|
|
self,
|
|||
|
|
client_id: str,
|
|||
|
|
optional_fields: Optional[List[str]] = None,
|
|||
|
|
) -> TerminalDetailV2:
|
|||
|
|
"""获取终端详细信息v2。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/clnts/_info2
|
|||
|
|
用途：获取终端硬件/软件/资产/网络配置等详细信息
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_id: 终端唯一ID
|
|||
|
|
optional_fields: 需要返回的可选信息块
|
|||
|
|
可选值: hardware, software, assets, netconf
|
|||
|
|
默认全部返回
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
TerminalDetailV2: 终端详细信息
|
|||
|
|
"""
|
|||
|
|
if optional_fields is None:
|
|||
|
|
optional_fields = ["hardware", "software", "assets", "netconf"]
|
|||
|
|
|
|||
|
|
body = {
|
|||
|
|
"client_id": client_id,
|
|||
|
|
"optional_fields": optional_fields,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/clnts/_info2", body)
|
|||
|
|
data = resp.data or {}
|
|||
|
|
|
|||
|
|
return TerminalDetailV2(**data)
|
|||
|
|
|
|||
|
|
async def list_terminal_leaks(
|
|||
|
|
self,
|
|||
|
|
group_id: Optional[str] = None,
|
|||
|
|
page: int = 1,
|
|||
|
|
per_page: int = DEFAULT_PAGE_SIZE,
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""查询存在高危漏洞未修复的终端。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/clnts/_leak
|
|||
|
|
官方参数: limit(每页条数, 默认15, 最大200) + offset(起始索引, 默认0)
|
|||
|
|
说明：返回的是"存在高危漏洞的终端列表"，不是漏洞详情。
|
|||
|
|
每条记录是终端信息，字段名与 _list 不同：
|
|||
|
|
- cid (非 client_id)
|
|||
|
|
- hostname (非 computer_name)
|
|||
|
|
- ip_addr (非 local_ip)
|
|||
|
|
- stat (1=离线,2=在线,3=异常，非 is_online 布尔值)
|
|||
|
|
外层有 all_client（终端总数）和 risk_client（高危终端数）统计。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
group_id: 分组ID（可选，不传则查全部分组）
|
|||
|
|
page: 页码（从1开始，内部转换为offset）
|
|||
|
|
per_page: 每页条数（内部转换为limit）
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 包含 total(高危终端总数), risk_client(高危终端数),
|
|||
|
|
all_client(全部终端数) 和 items(TerminalLeakInfo列表)
|
|||
|
|
"""
|
|||
|
|
# 火绒API使用 limit/offset 分页
|
|||
|
|
limit = min(per_page, 200)
|
|||
|
|
offset = (page - 1) * limit
|
|||
|
|
|
|||
|
|
body: Dict[str, Any] = {
|
|||
|
|
"limit": limit,
|
|||
|
|
"offset": offset,
|
|||
|
|
}
|
|||
|
|
if group_id:
|
|||
|
|
body["group_id"] = int(group_id)
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/clnts/_leak", body)
|
|||
|
|
|
|||
|
|
# 解析响应数据
|
|||
|
|
data = resp.data or {}
|
|||
|
|
raw_items = data.get("list", [])
|
|||
|
|
# _leak 不返回 total，但有 all_client 和 risk_client 统计
|
|||
|
|
all_client = data.get("all_client", 0)
|
|||
|
|
risk_client = data.get("risk_client", 0)
|
|||
|
|
|
|||
|
|
items = [TerminalLeakInfo(**item) for item in raw_items]
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
"total": risk_client, # 高危终端总数 = risk_client
|
|||
|
|
"all_client": all_client, # 全部终端数
|
|||
|
|
"risk_client": risk_client, # 高危终端数
|
|||
|
|
"items": items,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
async def get_virus_events(
|
|||
|
|
self,
|
|||
|
|
client_id: Optional[str] = None,
|
|||
|
|
group_id: Optional[str] = None,
|
|||
|
|
query_type: int = 2,
|
|||
|
|
begin_time: Optional[int] = None,
|
|||
|
|
end_time: Optional[int] = None,
|
|||
|
|
page: int = 1,
|
|||
|
|
per_page: int = DEFAULT_PAGE_SIZE,
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""查询终端病毒事件统计。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/clnts/_virus_events
|
|||
|
|
官方参数:
|
|||
|
|
- type: 查询类型（必填）
|
|||
|
|
0=使用终端唯一标识查询（client_id字段必填）
|
|||
|
|
1=使用分组ID查询（group_id字段必填）
|
|||
|
|
2=查询全部终端日志（client_id和group_id字段可忽略）
|
|||
|
|
- client_id: 终端唯一标识
|
|||
|
|
- group_id: 分组ID
|
|||
|
|
- begin_time/end_time: 日志范围时间（Unix时间戳，默认全部时间）
|
|||
|
|
- limit/offset: 分页参数
|
|||
|
|
说明：返回终端维度的病毒日志统计，含 count(总数) 和
|
|||
|
|
result{success/fail/ignored/trusted}（处理结果明细）。
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_id: 终端唯一ID（type=0时必填）
|
|||
|
|
group_id: 分组ID（type=1时必填）
|
|||
|
|
query_type: 查询类型，默认2(查全部)
|
|||
|
|
begin_time: 日志开始时间（Unix时间戳，可选）
|
|||
|
|
end_time: 日志结束时间（Unix时间戳，可选）
|
|||
|
|
page: 页码（从1开始，内部转换为offset）
|
|||
|
|
per_page: 每页条数（内部转换为limit）
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 包含 total(总数) 和 items(VirusEventStats列表)
|
|||
|
|
"""
|
|||
|
|
# 火绒API使用 limit/offset 分页
|
|||
|
|
limit = min(per_page, 200)
|
|||
|
|
offset = (page - 1) * limit
|
|||
|
|
|
|||
|
|
body: Dict[str, Any] = {
|
|||
|
|
"type": query_type,
|
|||
|
|
"limit": limit,
|
|||
|
|
"offset": offset,
|
|||
|
|
}
|
|||
|
|
# 根据查询类型添加可选参数
|
|||
|
|
if query_type == 0 and client_id:
|
|||
|
|
body["client_id"] = client_id
|
|||
|
|
if query_type in (0, 1) and group_id:
|
|||
|
|
body["group_id"] = int(group_id)
|
|||
|
|
# 时间范围过滤
|
|||
|
|
if begin_time:
|
|||
|
|
body["begin_time"] = begin_time
|
|||
|
|
if end_time:
|
|||
|
|
body["end_time"] = end_time
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/clnts/_virus_events", body)
|
|||
|
|
|
|||
|
|
data = resp.data or {}
|
|||
|
|
raw_items = data.get("list", [])
|
|||
|
|
total = data.get("total", 0)
|
|||
|
|
|
|||
|
|
items = [VirusEventStats(**item) for item in raw_items]
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
"total": total,
|
|||
|
|
"items": items,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# ======================================================================
|
|||
|
|
# P1 接口：控制能力
|
|||
|
|
# ======================================================================
|
|||
|
|
|
|||
|
|
async def isolate_terminal(
|
|||
|
|
self,
|
|||
|
|
client_ids: List[str],
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""隔离终端（断网）。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/task/_create (type=netctrl, net_isolation=true)
|
|||
|
|
安全等级: 🔴 高危操作，调用方必须确保：
|
|||
|
|
1. 仅 admin 角色可调用
|
|||
|
|
2. 已完成二次确认
|
|||
|
|
3. 已记录操作原因
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_ids: 目标终端ID列表
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 火绒API响应的data部分
|
|||
|
|
"""
|
|||
|
|
body = {
|
|||
|
|
"type": "netctrl",
|
|||
|
|
"net_isolation": True,
|
|||
|
|
"clients": client_ids,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/task/_create", body)
|
|||
|
|
logger.warning(f"火绒终端隔离操作: client_ids={client_ids}")
|
|||
|
|
return resp.data or {}
|
|||
|
|
|
|||
|
|
async def unisolate_terminal(
|
|||
|
|
self,
|
|||
|
|
client_ids: List[str],
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""解除终端隔离（恢复网络）。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/task/_create (type=netctrl, net_isolation=false)
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_ids: 目标终端ID列表
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 火绒API响应的data部分
|
|||
|
|
"""
|
|||
|
|
body = {
|
|||
|
|
"type": "netctrl",
|
|||
|
|
"net_isolation": False,
|
|||
|
|
"clients": client_ids,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/task/_create", body)
|
|||
|
|
logger.info(f"火绒终端解除隔离: client_ids={client_ids}")
|
|||
|
|
return resp.data or {}
|
|||
|
|
|
|||
|
|
async def create_scan_task(
|
|||
|
|
self,
|
|||
|
|
client_ids: List[str],
|
|||
|
|
scan_type: str = "quick_scan",
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""创建终端扫描任务。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/task/_create
|
|||
|
|
扫描类型: quick_scan(快速扫描) / full_scan(全盘扫描) / custom_scan(自定义扫描)
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_ids: 目标终端ID列表
|
|||
|
|
scan_type: 扫描类型，默认快速扫描
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 火绒API响应的data部分
|
|||
|
|
"""
|
|||
|
|
body = {
|
|||
|
|
"type": scan_type,
|
|||
|
|
"clients": client_ids,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/task/_create", body)
|
|||
|
|
logger.info(f"火绒终端扫描任务: type={scan_type}, client_ids={client_ids}")
|
|||
|
|
return resp.data or {}
|
|||
|
|
|
|||
|
|
async def send_notification(
|
|||
|
|
self,
|
|||
|
|
client_ids: List[str],
|
|||
|
|
content: str,
|
|||
|
|
) -> Dict[str, Any]:
|
|||
|
|
"""向终端发送通知。
|
|||
|
|
|
|||
|
|
火绒API: POST /api/task/_create (type=message)
|
|||
|
|
|
|||
|
|
Args:
|
|||
|
|
client_ids: 目标终端ID列表
|
|||
|
|
content: 通知内容
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 火绒API响应的data部分
|
|||
|
|
"""
|
|||
|
|
body = {
|
|||
|
|
"type": "message",
|
|||
|
|
"clients": client_ids,
|
|||
|
|
"content": content,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
resp = await self._request("/api/task/_create", body)
|
|||
|
|
logger.info(f"火绒终端通知: client_ids={client_ids}, content={content[:50]}")
|
|||
|
|
return resp.data or {}
|
|||
|
|
|
|||
|
|
# ======================================================================
|
|||
|
|
# 测试连接
|
|||
|
|
# ======================================================================
|
|||
|
|
|
|||
|
|
async def test_connection(self) -> Dict[str, Any]:
|
|||
|
|
"""测试火绒API连接是否正常。
|
|||
|
|
|
|||
|
|
使用 _list 接口（page=1, per_page=1）进行轻量级连接测试，
|
|||
|
|
验证签名是否正确、网络是否可达。
|
|||
|
|
|
|||
|
|
Returns:
|
|||
|
|
Dict: 包含 success(bool) 和 message(str)
|
|||
|
|
"""
|
|||
|
|
try:
|
|||
|
|
result = await self.list_terminals(page=1, per_page=1)
|
|||
|
|
return {
|
|||
|
|
"success": True,
|
|||
|
|
"message": f"连接成功，共 {result.get('total', 0)} 个终端",
|
|||
|
|
"total_terminals": result.get("total", 0),
|
|||
|
|
}
|
|||
|
|
except HuorongAuthError as e:
|
|||
|
|
return {
|
|||
|
|
"success": False,
|
|||
|
|
"message": f"认证失败: {e.message}",
|
|||
|
|
}
|
|||
|
|
except HuorongConnectionError as e:
|
|||
|
|
return {
|
|||
|
|
"success": False,
|
|||
|
|
"message": f"连接失败: {e.message}",
|
|||
|
|
}
|
|||
|
|
except HuorongError as e:
|
|||
|
|
return {
|
|||
|
|
"success": False,
|
|||
|
|
"message": f"测试失败: {e.message}",
|
|||
|
|
}
|