qianxin-hunter-api

奇安信 Hunter API 调用技能。支持查询接口和导出任务（批量查询）。需配置 QIANXIN_HUNTER_API_KEY 环境变量。

Security Scan

The skill's code, instructions, and requested environment variables align with its stated purpose (calling Qianxin Hunter APIs); nothing in the package indicates covert behavior or unrelated credential access.

Purpose & Capability

Name and description match the actual artifacts: the script talks to hunter.qianxin.com and requires QIANXIN_HUNTER_API_KEY. Required binary (python3) and declared primaryEnv are appropriate for a Hunter API CLI.

Instruction Scope

SKILL.md instructs only how to run the included Python CLI for search and batch export, how to provide the API key, and how to use files for batch queries. The runtime script only reads the provided CSV file (when --file is used) and the QIANXIN_HUNTER_API_KEY environment variable; it does not attempt to read unrelated system files or other environment variables.

Install Mechanism

This is instruction-only (no install spec), which minimizes risk. The README notes the Python 'requests' package is required but there is no automatic install step; the environment must provide python3 and requests. No downloads from arbitrary URLs or extract steps are present.

Credentials

Only QIANXIN_HUNTER_API_KEY is requested and declared as primary credential, which is proportionate for an API client. No unrelated secrets or config paths are requested.

Persistence & Privilege

The skill does not request always: true and makes no changes to other skills or global agent config. It is a normal, on-demand tool with no elevated persistence requirements.

Assessment

This package appears coherent for accessing the Qianxin Hunter API: it requires a single API key and python3 (plus the requests library). Before installing: 1) only store the API key via your platform's secure skill config (do not paste it in chat), 2) ensure the requests package is available in the runtime environment, 3) be aware that any CSV file you pass will be uploaded to the Hunter service, and downloaded results will be saved locally (check output path and permissions), and 4) treat the API key as sensitive — rotate it if you suspect leakage. If you need higher assurance, verify the API host (https://hunter.qianxin.com) matches your expected endpoint and review network policies for outbound calls.

本工具集成奇安信 Hunter 平台的查询接口和导出任务（批量查询），可通过命令行处理：语法查询、提交导出（批量查询）任务、查询导出进度、下载导出文件。

📦 依赖

• Python 3.10+
• Python Package requests
• 需配置环境变量

QIANXIN_HUNTER_API_KEY="XXXXX"

🚀 核心功能用例

1. 查询接口

适用于快速检索小批量数据分页获取，直接在终端查看结果。

# 仅指定查询语法，其他参数默认（默认获取第1页数据）
python3 scripts/query.py --search 'web.title="login"'

# 指定查询语法，其他可选参数：分页参数、时间范围、返回字段、资产类型（is_web）
python3 scripts/query.py --search 'app="OpenClaw"' --page 1 --page_size 10 --start '2026-01-01' --end '2026-03-01' --fields 'ip,port,domain' --is_web 1

2. 导出任务（批量查询）

适用于大规模资产导出，也适用于批量ip/domain/company目标查询导出，导出结果通过csv文件形式下载。

第一步：提交任务 (submit)

支持通过语法或本地 CSV 文件提交。

• 语法方式：

  # 仅指定查询语法进行导出，其他参数默认（默认返回可导出的全部数据）
  python3 scripts/query.py submit --search 'ip="1.1.1.1/24" && ip.port="80"' 
  
  # 指定查询语法进行导出，其他可选参数：最大返回的资产数、时间范围、返回字段、资产类型（is_web）
  python3 scripts/query.py submit --search 'ip="1.1.1.1/24" && ip.port="80"' --limit 500 --start '2026-01-01' --end '2026-03-01' --fields 'ip,port,domain' --is_web 1
  

• 文件方式（需符合官方模板）：

  # 指定本地csv文件进行导出，文件类型默认为all（可以是ip、domain和company混合的文件）
  python3 scripts/query.py submit --file targets.csv
  
  # 指定本地csv文件进行导出，文件类型为ip
  python3 scripts/query.py submit --file targets.csv --type ip
  
  # 指定本地csv文件进行导出，文件类型为domain，其他可选参数：最大返回的资产数、时间范围、返回字段、资产类型（is_web）
  python3 scripts/query.py submit --file targets.csv --type domain --limit 500 --start '2026-01-01' --end '2026-03-01' --fields 'ip,port,domain' --is_web 1
  

第二步：查看进度 (status)

使用提交任务返回的 task_id 追踪状态。

python3 scripts/query.py batch status --task_id 1234

第三步：下载结果 (download)

当状态显示为“已完成”时，下载导出的 CSV 文件。

# 仅指定task_id，不指定保存文件名，默认保存文件名为 results_{task_id}.csv
python3 scripts/query.py batch download --task_id 1234

# 指定task_id，指定保存文件名
python3 scripts/query.py batch download --task_id 1234 --output results.csv

---

📋 参数速查表

全局子命令

• search: 查询模式。
• batch: 批量导出模式（含 submit, status, download 动作）。

查询参数

长参数	说明
--search	Hunter 查询语法（原始字符串），用于即时查询或批量查询/导出任务
--page	页码，默认 1
--page_size	每页条数，默认 10
--start	开始时间 (格式: 2021-01-01)
--end	结束时间 (格式: 2021-03-01)
--is_web	资产类型：1 (Web), 2 (非Web), 3 (全部)，默认为全部。
--fields	返回字段，以逗号分隔（如 ip,port,domain），默认返回权限内所有可导出字段。
--file	上传的CSV文件路径，用于批量查询
--type	上传文件的类型，即检索类型：all (混合ip/domain/company), ip(批量ip), domain(批量域名), company(批量企业名称)，用于批量查询
--limit	最大导出资产数
--task_id	任务 ID，用于查看进度或下载文件
--output	下载的输出文件名，用于下载文件命名

🛠️ 脚本工具

• scripts/query.py

📚 参考文档

• reference/api.md: Hunter 查询接口文档
• reference/api_batch.md: Hunter 批量查询相关接口文档
• reference/batch_file_template.csv: 批量查询时使用的上传文件模板