REST API 参考

NGFW One 提供 REST API，用于将防火墙能力集成到 SOAR、SIEM、工单系统、自动化脚本中。企业版与数据中心版提供完整读写接口；WAF 免费版仅提供只读 API。如需让 AI Agent 直接调用，请参阅 MCP 接入，功能介绍见开放接口。

基础信息

创建 API Key

1. 以管理员登录后台，进入「系统 → 开放接口 → API Key」。
2. 点击「新建」，填写名称与用途说明，并设置：
   • 角色：只读、运维、管理员。只读可查询；运维可执行封停、解封、黑白名单等日常操作；管理员可修改策略与系统配置。
   • IP 白名单：仅允许指定来源地址使用该 Key。
   • 过期时间：到期自动失效。
   • 调用频率限制：单位时间内允许的最大请求数。
3. 保存后 Key 仅完整显示一次，请立即妥善保存。丢失后只能重新生成。

通用约定

分页

列表接口使用 page（从 1 开始）与 page_size 参数。响应示例：

{
  "items": [ { "id": "blk_01", "ip": "203.0.113.7" } ],
  "page": 1,
  "page_size": 20,
  "total": 135
}

page_size 的上限以产品正式说明为准。

错误格式

出错时返回相应的 HTTP 状态码，响应体统一为：

{
  "error": {
    "code": "forbidden",
    "message": "当前 API Key 角色无权执行此操作"
  }
}

error.code 的完整取值以产品正式说明为准，程序判断建议以 HTTP 状态码为主。

主要资源端点

单个资源一般通过 /资源/{id} 访问。各端点的完整字段、过滤参数与可用版本以产品内置的接口文档为准。免费版不包含的功能（如蜜罐、网内设备管理）对应端点不可用。

curl 示例

export NGFW_HOST=192.0.2.10
export NGFW_API_KEY=替换为你的Key

# 查询系统状态
curl -s -H "Authorization: Bearer $NGFW_API_KEY" \
  "https://$NGFW_HOST:9443/api/v1/system/status"

# 分页查询告警
curl -s -H "Authorization: Bearer $NGFW_API_KEY" \
  "https://$NGFW_HOST:9443/api/v1/alerts?page=1&page_size=50"

# 封停一个 IP 1 小时（需运维及以上角色，企业版/数据中心版）
curl -s -X POST \
  -H "Authorization: Bearer $NGFW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.7", "duration": 3600, "reason": "SOAR 剧本自动处置"}' \
  "https://$NGFW_HOST:9443/api/v1/blocklist"

请求体字段名为示例，以产品内置接口文档为准。若管理端口使用自签名证书，请用 --cacert 指定 CA 证书，不建议使用 -k 跳过校验。

Python 示例

import os
import requests

BASE = f"https://{os.environ['NGFW_HOST']}:9443/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NGFW_API_KEY']}"
session.verify = "/etc/ssl/ngfw-ca.pem"  # 设备管理证书的 CA


def search_logs(query: dict) -> list:
    resp = session.post(f"{BASE}/logs/search", json=query, timeout=30)
    if resp.status_code != 200:
        err = resp.json().get("error", {})
        raise RuntimeError(f"{resp.status_code} {err.get('code')}: {err.get('message')}")
    return resp.json()["items"]


def list_all_alerts(page_size: int = 100):
    page = 1
    while True:
        r = session.get(f"{BASE}/alerts", params={"page": page, "page_size": page_size}, timeout=30)
        r.raise_for_status()
        data = r.json()
        yield from data["items"]
        if page * page_size >= data["total"]:
            break
        page += 1


for alert in list_all_alerts():
    print(alert.get("id"), alert.get("severity"), alert.get("src_ip"))

Webhook

Webhook 用于在事件发生时主动推送到你的系统，无需轮询。在「系统 → 开放接口 → Webhook」中添加接收地址并勾选订阅事件。

推送为 HTTPS POST，请求体为 JSON。以下为结构示意，实际字段以产品正式说明为准：

{
  "event": "block.created",
  "id": "evt_8f2c1a",
  "occurred_at": "2026-01-01T08:00:00+08:00",
  "data": {
    "ip": "203.0.113.7",
    "reason": "honeypot: ssh-decoy-01",
    "duration": 3600
  }
}

接收端建议：

• 使用 HTTPS 接收地址，并在 5 秒内返回 2xx，耗时处理放入异步队列。
• 按事件 id 去重，以应对网络重试导致的重复推送。
• 限制只接受来自设备地址的请求；如后台提供签名密钥，请按后台说明校验签名。