Skyeye Sensor Use

SkyEye Sensor 数据查询

如果是分析平台日志检索，不要用这个 skill，改用 skyeye-use。

适用范围

这个 skill 主要覆盖传感器侧接口：

• 告警统计
• 告警列表

不适合：

• Lucene 日志检索
• 专家模式管道检索
• 分析平台资产与系统模块
• 传感器枚举接口、License、权限和菜单配置

零、登录认证

对后台任务 / 定时任务，或系统不支持可视化，使用 browser-use 的 cdp-headless 模式。

State 文件路径：~/.flocks/browser/skyeye-sensor/auth-state.json（固定，全局唯一）。 自动登录配置路径：~/.flocks/browser/skyeye-sensor/auth-config.json（只保存 base_url、state 路径和 secret 引用；密码写入 Flocks secret）。

跨平台执行约定（必须遵守）

scripts/skyeye_sensor_auth.py 和 scripts/skyeye_sensor_cli.py 都是 skill-relative 路径。执行任何脚本前，必须先把当前工作目录切到 skill_load 输出中的 Base directory，不要假设当前 shell 已经在 skill 目录，也不要拼未加引号的绝对路径。

推荐方式：

• 如果工具支持 workdir 参数，直接把 workdir 设为 skill_load 输出的 Base directory，再运行 uv run python scripts/...。
• 如果只能写 shell 命令，先进入 Base directory，再运行脚本。
• 跨平台示例优先使用 --base-url、--auth-state 等 CLI 参数，少用 shell 环境变量前缀。
• Windows PowerShell 设置环境变量必须用 $env:NAME = 'value'；不要用 POSIX 的 NAME=value command。
• macOS/Linux shell 可以用 NAME=value command 或 export NAME=value。
• 路径含空格时必须整体加引号。Windows 下优先用 Set-Location -LiteralPath '<skill-dir>'，macOS/Linux 下优先用 cd "$SKILL_DIR"。
• 不要在 glob / 文件工具的 path 参数里写 $env:USERPROFILE、$HOME 这类 shell 变量；这些参数通常不会做 shell 展开。需要用户目录时，用 ~/.flocks/... 或先在 shell 里展开后再传入。

Windows PowerShell 模板：

Set-Location -LiteralPath '<skill-load 输出的 Base directory>'
uv run python scripts/skyeye_sensor_auth.py --base-url 'https://<skyeye-sensor-domain>' validate
uv run python scripts/skyeye_sensor_cli.py --base-url 'https://<skyeye-sensor-domain>' alarm list --days 7

macOS/Linux 模板：

cd "<skill-load 输出的 Base directory>"
uv run python scripts/skyeye_sensor_auth.py --base-url 'https://<skyeye-sensor-domain>' validate
uv run python scripts/skyeye_sensor_cli.py --base-url 'https://<skyeye-sensor-domain>' alarm list --days 7

首次登录 / Session 过期重新登录

打开 SkyEye Sensor 页面或执行 CLI 前，必须按下面顺序处理登录态，不要一开始就要求用户提供账密：

1. 先检查 auth-state.json 是否可用。
2. 如果 state 可用，直接复用登录态继续打开页面或执行 CLI 获取数据。
3. 如果 state 不存在或失效，但本地已有可用于自动登录的配置，先在 skill Base directory 中执行自动刷新：uv run python scripts/skyeye_sensor_auth.py ensure。
4. 如果没有可用 state，也没有保存账密配置，再引导用户选择：
   • 提供 SkyEye Sensor 地址、用户名、密码，自动登录并保存账密配置，后续 state 失效时可直接自动刷新；
   • 不提供账密，走浏览器手动登录流程。
5. 只有自动登录失败、验证码 OCR / MFA / 登录页 DOM 变化 / 登录成功检测失败，或用户拒绝提供账密时，才回退手动登录。

只读查看本地是否具备自动刷新条件（需在 skill Base directory 中执行）：

uv run python scripts/skyeye_sensor_auth.py status

检查 state 是否可用（需在 skill Base directory 中执行）：

uv run python scripts/skyeye_sensor_auth.py --base-url https://<skyeye-sensor-domain> validate

如果 validate 返回 valid: true，继续后续页面操作或 CLI 查询；如果返回 auth_state_not_found、auth_state_expired_or_login_page 或 auth_state_load_failed，再看 status 中 can_auto_refresh 是否为 true。

有已保存账密配置时自动刷新（需在 skill Base directory 中执行）：

uv run python scripts/skyeye_sensor_auth.py ensure

自动刷新成功后继续执行原页面或 CLI 操作；失败才进入下方用户选择流程。

flocks browser --doctor

如果 flocks browser --doctor 提示浏览器已运行，但 daemon 或 active browser connection 不可用，先执行 flocks browser --setup 触发 attach，不要先要求用户重复勾选 Allow remote debugging。

1. 执行 flocks browser --setup 触发交互式 attach，不要用短超时包装该命令。
2. 再运行 flocks browser --doctor 做只读确认。
3. 如果 --setup 或 --doctor 明确提示 remote debugging 未启用，再提示用户打开 inspect 页面（例如 chrome://inspect/#remote-debugging 或 edge://inspect/#remote-debugging）并勾选 Allow remote debugging。
4. 如果还失败，先执行 flocks browser --reload 清理旧 daemon，再重新执行 flocks browser --setup，避免因为残留 daemon 造成干扰。
5. 只有随后 --doctor 通过后，才继续后面的登录或页面操作。

当必须询问用户时，说明两种选择并尊重用户偏好：

• 提供账密并保存：调用 scripts/skyeye_sensor_auth.py，通过 browser daemon / CDP 驱动真实登录页自动登录。脚本会优先从登录页验证码图片元素动态获取图片、OCR 识别、填入页面、保存 state，并把用户名/密码写入 Flocks secret，把基础配置保存到 ~/.flocks/browser/skyeye-sensor/auth-config.json。后续 auth-state.json 失效时，可在 skill Base directory 中直接执行 uv run python scripts/skyeye_sensor_auth.py ensure。
• 不提供账密：沿用原有浏览器登录流程。打开登录页后由用户手动完成登录（含短信验证码 / MFA 等），登录成功后保存 state。

手动登录时，打开登录页并等待用户完成登录：

flocks browser -c '
tid = new_tab("https://<skyeye-sensor-domain>/login", activate=True)
wait_for_load()
print(tid)
import json
print(json.dumps(page_info(), ensure_ascii=True))
'

自动执行上述命令，等待用户登录结束，收到通知后继续：

# 登录成功后立即保存 state
flocks browser state save ~/.flocks/browser/skyeye-sensor/auth-state.json

提供账密并保存时，执行自动登录：

uv run python scripts/skyeye_sensor_auth.py --base-url https://<skyeye-sensor-domain> ensure --username '<username>' --password '<password>'

下次 auth-state.json 失效且本地保存过账密配置时，可直接执行：

uv run python scripts/skyeye_sensor_auth.py ensure

也可以在查询命令前直接带账密或使用已保存账密刷新登录态：

uv run python scripts/skyeye_sensor_cli.py \
  --base-url https://<skyeye-sensor-domain> \
  --username '<username>' \
  --password '<password>' \
  alarm count

uv run python scripts/skyeye_sensor_cli.py --auto-login alarm list

如果验证码 OCR、MFA、登录页 DOM 变化或登录成功检测失败，回退到上面的手动登录流程。

CLI 认证失败时的恢复流程

当 CLI 出现以下任一情况，优先判定为认证问题（不要立刻要求用户重新登录）：

• 返回 HTTP 401 / 403
• 返回内容包含 Unauthorized、login、未登录、认证失败
• auth-state.json 存在，但 CLI 请求仍失败

恢复步骤（最多尝试 1 次）：

# 1) 重新加载 state（强制刷新浏览器会话）
flocks browser state load ~/.flocks/browser/skyeye-sensor/auth-state.json --url "https://<skyeye-sensor-domain>"

# 2) 读取当前页面状态
flocks browser -c '
import json
print(json.dumps(page_info(), ensure_ascii=True))
'

# 3) 根据结果决策
URL=$(flocks browser -c '
import json
info = page_info()
print(info.get("url", ""))
' | tail -n 1)
if [[ "$URL" == *"/login"* ]]; then
  echo "Session 仍无效，需重新登录"
  # → 走上方「首次登录 / 重新登录」流程
else
  flocks browser state save ~/.flocks/browser/skyeye-sensor/auth-state.json
  echo "Session 已恢复，可重试 CLI"
  # → 重试一次 CLI；若仍失败，再走重新登录，不要无限循环
fi

执行约定

CLI 在 skill 内：

scripts/skyeye_sensor_cli.py

执行命令时：

1. 必须先进入 skill_load 输出的 Base directory，或把命令工具的 workdir 设置为该目录。
2. 优先使用 uv run python scripts/skyeye_sensor_cli.py ...
3. 认证优先使用浏览器导出的 auth-state.json

可选认证环境变量：

• SKYEYE_SENSOR_BASE_URL=https://<skyeye-sensor-domain>
• SKYEYE_SENSOR_AUTH_STATE=~/.flocks/browser/skyeye-sensor/auth-state.json
• 如有单独 Cookie 文件，可用 SKYEYE_SENSOR_COOKIE_FILE
• 没有 state/cookie 时，再考虑 SKYEYE_SENSOR_CSRF_TOKEN

常用命令

如果已经通过环境变量或 CLI 参数设置好认证信息：

# 默认输出 JSON
uv run python scripts/skyeye_sensor_cli.py alarm count --days 7
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --page 1 --page-size 10
uv run python scripts/skyeye_sensor_cli.py alarm list --hours 6 --sip 1.1.1.1

# 配合 jq 提取字段
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --hazard-level "3,2" | jq '.items[].threat_name'

# 加 --table 输出格式化表格（人工阅读用）
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --table

带认证的完整单行格式（无需提前 export，适合 Windows/macOS/Linux 直接执行）：

uv run python scripts/skyeye_sensor_cli.py --base-url https://<skyeye-sensor-domain> --auth-state ~/.flocks/browser/skyeye-sensor/auth-state.json alarm list --days 7 --hazard-level "3,2"

查询策略

• 用户问"最近几天告警数量变化"时，优先 alarm count
• 用户问"列出具体告警"时，使用 alarm list
• 需要按更多页面字段精确过滤时，先查 references/API_REFERENCE.md 中"API Client 已支持"部分

常见过滤条件

时间：--days / --hours

IP 相关：--sip --dip --alarm-sip --attack-sip

告警分类：--hazard-level --threat-type --attack-type --threat-name --attack-stage --attack-dimension

处置状态：--status --attack-result --host-state --is-read --user-label

网络特征：--proto --sport --dport --host --uri --xff --status-http

威胁情报：--ioc --attck-org --attck --alert-rule --is-web-attack

网络标识：--src-mac --dst-mac --vlan-id --vxlan-id --gre-key

标签与来源：--marks --ip-labels --alarm-source

时间与文件：--start-update-time --end-update-time --pcap-filename

完整参数说明见 references/API_REFERENCE.md。

常用查询示例

高危及以上告警

# 最近 7 天，严重 + 高危告警列表
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --hazard-level "3,2"

# 最近 24 小时，高危以上告警数量趋势
uv run python scripts/skyeye_sensor_cli.py alarm count --hours 24 --hazard-level "3,2"

攻击成功的告警

# 最近 7 天攻击成功告警
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --attack-result "攻击成功"

# 高危以上 + 攻击成功
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --hazard-level "3,2" --attack-result "攻击成功"

# 统计最近 7 天攻击成功告警数量
uv run python scripts/skyeye_sensor_cli.py alarm count --days 7 --attack-result "攻击成功"

未处置告警

# 最近 7 天未处置告警（status=0）
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --status "0"

# 高危以上 + 未处置
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --hazard-level "3,2" --status "0"

指定 IP 的告警

# 某 IP 作为流量源 IP 的告警
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --sip "1.1.1.1"

# 某 IP 作为流量目的 IP 的告警
uv run python scripts/skyeye_sensor_cli.py alarm list --days 7 --dip "192.168.1.100"

按威胁类型 + 主机状态过滤

# 威胁类型 2、3，主机状态包含失陷（-1）
uv run python scripts/skyeye_sensor_cli.py alarm list \
  --days 7 \
  --threat-type "2,3" \
  --host-state "0,1,2,-1"

告警数量变化趋势

# 最近 30 天每天告警数
uv run python scripts/skyeye_sensor_cli.py alarm count --days 30

# 最近 7 天，仅高危以上
uv run python scripts/skyeye_sensor_cli.py alarm count --days 7 --hazard-level "3,2"

当查询字段或条件不在常用查询字段/示例中，请阅读完整字段列表、CLI 参数说明、查询示例：references/API_REFERENCE.md

边界说明

• 如果用户要求"原始日志检索 / Lucene / 字段状态 / expert_model"，这是分析平台能力，切换到 skyeye-data-fetch
• 这个 skill 是天眼流量传感器平台适用， CLI只保留 alarm list 和 alarm count

重要提醒

• Session 管理：详见零、登录认证。任务开始前先用 skyeye_sensor_auth.py validate 确认 auth-state.json 可用；CLI 认证失败时先走恢复流程，不要立刻要求用户重新登录。
• 禁止连续失败循环：同一命令最多重试 2 次；认证恢复流程只走一次，仍失败则提示用户手动重新登录。
  • 以下错误属于需要用户干预的基础设施问题，立即停止所有重试，直接告知用户处理：
    • ERR_CERT_AUTHORITY_INVALID：站点证书不被本机信任，使用--ignore-https-errors 或 请求用户处理。

参考文档

• 完整字段列表、CLI 参数说明、查询示例：references/API_REFERENCE.md