{ "openapi": "3.1.0", "info": { "title": "NGFW One REST API", "version": "1.0.0-draft", "description": "NGFW One 下一代防火墙 REST API（草案）。企业版与数据中心版提供完整读写接口，WAF 免费版仅提供只读接口。字段与示例以产品内置接口文档为准。" }, "servers": [ { "url": "https://{host}:9443/api/v1", "variables": { "host": { "default": "192.0.2.10", "description": "设备管理地址" } } } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "系统", "description": "系统状态" }, { "name": "策略与对象", "description": "安全策略（ACL）与地址对象" }, { "name": "封停与名单", "description": "封停列表、封停白名单、域名黑白名单" }, { "name": "告警与日志", "description": "告警、日志检索与报告" }, { "name": "资产", "description": "网内设备" }, { "name": "蜜罐", "description": "蜜罐及其触发事件" } ], "paths": { "/system/status": { "get": { "tags": [ "系统" ], "summary": "查询系统状态", "responses": { "200": { "description": "系统状态", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemStatus" }, "example": { "version": "1.0.0", "edition": "enterprise", "uptime_seconds": 864000, "cpu_percent": 23.5, "memory_percent": 41.2, "sessions": 18342 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/policies": { "get": { "tags": [ "策略与对象" ], "summary": "列出安全策略", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "安全策略列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Policy" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "策略与对象" ], "summary": "新建安全策略（管理员角色）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyInput" }, "example": { "name": "禁止访客网段访问服务器区", "action": "deny", "src_zone": "guest", "dst_zone": "server", "services": [ "any" ], "enabled": true } } } }, "responses": { "201": { "description": "已创建的安全策略", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "example": { "id": "pol_12", "name": "禁止访客网段访问服务器区", "action": "deny", "src_zone": "guest", "dst_zone": "server", "services": [ "any" ], "enabled": true, "position": 3 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/policies/{id}": { "get": { "tags": [ "策略与对象" ], "summary": "获取安全策略详情", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "安全策略详情", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "example": { "id": "pol_12", "name": "禁止访客网段访问服务器区", "action": "deny", "src_zone": "guest", "dst_zone": "server", "services": [ "any" ], "enabled": true, "position": 3 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "策略与对象" ], "summary": "修改安全策略（管理员角色）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyInput" }, "example": { "name": "禁止访客网段访问服务器区", "action": "deny", "src_zone": "guest", "dst_zone": "server", "services": [ "any" ], "enabled": true } } } }, "responses": { "200": { "description": "修改后的安全策略", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Policy" }, "example": { "id": "pol_12", "name": "禁止访客网段访问服务器区", "action": "deny", "src_zone": "guest", "dst_zone": "server", "services": [ "any" ], "enabled": true, "position": 3 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "策略与对象" ], "summary": "删除安全策略（管理员角色）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/objects/addresses": { "get": { "tags": [ "策略与对象" ], "summary": "列出地址对象", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "地址对象列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "策略与对象" ], "summary": "新建地址对象（管理员角色）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInput" }, "example": { "name": "财务服务器", "type": "host", "value": "10.0.20.15" } } } }, "responses": { "201": { "description": "已创建的地址对象", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "id": "addr_7", "name": "财务服务器", "type": "host", "value": "10.0.20.15" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/objects/addresses/{id}": { "get": { "tags": [ "策略与对象" ], "summary": "获取地址对象详情", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "地址对象详情", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "id": "addr_7", "name": "财务服务器", "type": "host", "value": "10.0.20.15" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "策略与对象" ], "summary": "修改地址对象（管理员角色）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressInput" }, "example": { "name": "财务服务器", "type": "host", "value": "10.0.20.15" } } } }, "responses": { "200": { "description": "修改后的地址对象", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address" }, "example": { "id": "addr_7", "name": "财务服务器", "type": "host", "value": "10.0.20.15" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "策略与对象" ], "summary": "删除地址对象（管理员角色）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/blocklist": { "get": { "tags": [ "封停与名单" ], "summary": "查询封停列表", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "ip", "in": "query", "schema": { "type": "string" }, "description": "按 IP 过滤" } ], "responses": { "200": { "description": "封停列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BlockEntry" } } } } ] }, "example": { "items": [ { "id": "blk_01", "ip": "203.0.113.7", "reason": "honeypot: ssh-decoy-01", "source": "auto", "status": "active", "created_at": "2026-10-09T08:00:00+08:00", "expires_at": "2026-10-10T08:00:00+08:00" } ], "page": 1, "page_size": 20, "total": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "封停与名单" ], "summary": "封停 IP（运维及以上角色，企业版及以上）", "description": "若后台开启了审批流，返回 status 为 pending，审批通过后生效。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockInput" }, "example": { "ip": "203.0.113.7", "duration": 3600, "reason": "SOAR 剧本自动处置" } } } }, "responses": { "201": { "description": "封停记录", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockEntry" }, "example": { "id": "blk_02", "ip": "203.0.113.7", "reason": "SOAR 剧本自动处置", "source": "api", "status": "active", "created_at": "2026-10-09T08:00:00+08:00", "expires_at": "2026-10-10T08:00:00+08:00" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/blocklist/{id}": { "delete": { "tags": [ "封停与名单" ], "summary": "解封（运维及以上角色）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/allowlist": { "get": { "tags": [ "封停与名单" ], "summary": "查询封停白名单", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "白名单", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AllowEntry" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "封停与名单" ], "summary": "添加封停白名单（运维及以上角色）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowInput" }, "example": { "cidr": "10.0.0.1/32", "note": "核心网关" } } } }, "responses": { "201": { "description": "白名单条目", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowEntry" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/allowlist/{id}": { "delete": { "tags": [ "封停与名单" ], "summary": "删除封停白名单条目", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/domains/rules": { "get": { "tags": [ "封停与名单" ], "summary": "查询域名黑白名单规则", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "list", "in": "query", "schema": { "type": "string", "enum": [ "block", "allow" ] } } ], "responses": { "200": { "description": "域名规则", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DomainRule" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "封停与名单" ], "summary": "新增域名规则（运维及以上角色）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRuleInput" }, "example": { "pattern": "*.malicious.example", "list": "block", "note": "情报命中" } } } }, "responses": { "201": { "description": "域名规则", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainRule" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/domains/rules/{id}": { "delete": { "tags": [ "封停与名单" ], "summary": "删除域名规则", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/alerts": { "get": { "tags": [ "告警与日志" ], "summary": "查询告警", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "severity", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] } }, { "name": "since", "in": "query", "schema": { "type": "string" }, "description": "相对时间，如 1h、24h、7d" } ], "responses": { "200": { "description": "告警列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } } } ] }, "example": { "items": [ { "id": "alt_9f1", "severity": "high", "category": "waf", "title": "SQL 注入尝试 /api/login", "src_ip": "198.51.100.7", "dst": "10.0.10.5:443", "action": "blocked", "occurred_at": "2026-10-09T07:58:12+08:00" } ], "page": 1, "page_size": 20, "total": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/alerts/{id}": { "get": { "tags": [ "告警与日志" ], "summary": "告警详情", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "告警详情", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" }, "example": { "id": "alt_9f1", "severity": "high", "category": "waf", "title": "SQL 注入尝试 /api/login", "src_ip": "198.51.100.7", "dst": "10.0.10.5:443", "action": "blocked", "occurred_at": "2026-10-09T07:58:12+08:00" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/logs/search": { "post": { "tags": [ "告警与日志" ], "summary": "检索日志", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogQuery" }, "example": { "type": "attack", "since": "24h", "filters": { "src_ip": "198.51.100.7" }, "page": 1, "page_size": 50 } } } }, "responses": { "200": { "description": "日志", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LogEntry" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/reports": { "get": { "tags": [ "告警与日志" ], "summary": "列出报告", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "报告列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "告警与日志" ], "summary": "生成报告", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportInput" }, "example": { "type": "weekly", "from": "2026-10-01", "to": "2026-10-07", "format": "pdf" } } } }, "responses": { "201": { "description": "报告任务", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Report" }, "example": { "id": "rpt_44", "type": "weekly", "from": "2026-10-01", "to": "2026-10-07", "format": "pdf", "status": "queued", "download_url": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/devices": { "get": { "tags": [ "资产" ], "summary": "网内设备资产（企业版及以上）", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } }, { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "设备列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } } } ] }, "example": { "items": [ { "id": "dev_301", "ip": "10.0.8.15", "mac": "00:1a:2b:3c:4d:5e", "type": "camera", "os": "Linux", "first_seen": "2026-09-30T10:12:00+08:00", "risk": "low" } ], "page": 1, "page_size": 20, "total": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/honeypots": { "get": { "tags": [ "蜜罐" ], "summary": "列出蜜罐", "parameters": [ { "name": "page", "in": "query", "description": "页码，从 1 开始", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "description": "每页条数（上限以产品说明为准）", "schema": { "type": "integer", "minimum": 1, "default": 20 } } ], "responses": { "200": { "description": "蜜罐列表", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Page" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Honeypot" } } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "蜜罐" ], "summary": "新建蜜罐（企业版及以上）", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoneypotInput" }, "example": { "name": "ssh-decoy-01", "type": "ssh", "listen": "10.0.8.200:22", "enabled": true } } } }, "responses": { "201": { "description": "已创建的蜜罐", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Honeypot" }, "example": { "id": "hp_3", "name": "ssh-decoy-01", "type": "ssh", "listen": "10.0.8.200:22", "enabled": true, "triggers_24h": 4 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/honeypots/{id}": { "get": { "tags": [ "蜜罐" ], "summary": "获取蜜罐详情", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "蜜罐详情", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Honeypot" }, "example": { "id": "hp_3", "name": "ssh-decoy-01", "type": "ssh", "listen": "10.0.8.200:22", "enabled": true, "triggers_24h": 4 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "tags": [ "蜜罐" ], "summary": "修改蜜罐（企业版及以上）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HoneypotInput" }, "example": { "name": "ssh-decoy-01", "type": "ssh", "listen": "10.0.8.200:22", "enabled": true } } } }, "responses": { "200": { "description": "修改后的蜜罐", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Honeypot" }, "example": { "id": "hp_3", "name": "ssh-decoy-01", "type": "ssh", "listen": "10.0.8.200:22", "enabled": true, "triggers_24h": 4 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "tags": [ "蜜罐" ], "summary": "删除蜜罐（企业版及以上）", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "资源 ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "已删除" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "alert.created": { "post": { "summary": "产生新告警", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "alert.created", "id": "evt_8f2c1a", "occurred_at": "2026-10-09T08:00:00+08:00", "data": {} } } } }, "responses": { "200": { "description": "接收端在 5 秒内返回 2xx" } } } }, "block.created": { "post": { "summary": "IP 或设备被封停", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "block.created", "id": "evt_8f2c1a", "occurred_at": "2026-10-09T08:00:00+08:00", "data": {} } } } }, "responses": { "200": { "description": "接收端在 5 秒内返回 2xx" } } } }, "block.released": { "post": { "summary": "封停到期或被解封", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "block.released", "id": "evt_8f2c1a", "occurred_at": "2026-10-09T08:00:00+08:00", "data": {} } } } }, "responses": { "200": { "description": "接收端在 5 秒内返回 2xx" } } } }, "device.discovered": { "post": { "summary": "网内发现新设备", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "device.discovered", "id": "evt_8f2c1a", "occurred_at": "2026-10-09T08:00:00+08:00", "data": {} } } } }, "responses": { "200": { "description": "接收端在 5 秒内返回 2xx" } } } }, "honeypot.triggered": { "post": { "summary": "蜜罐被访问或交互", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "honeypot.triggered", "id": "evt_8f2c1a", "occurred_at": "2026-10-09T08:00:00+08:00", "data": {} } } } }, "responses": { "200": { "description": "接收端在 5 秒内返回 2xx" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "在「系统 → 开放接口 → API Key」中创建。角色：只读 / 运维 / 管理员。" } }, "responses": { "BadRequest": { "description": "参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "bad_request", "message": "参数 ip 格式不正确" } } } } }, "Unauthorized": { "description": "未提供 API Key、Key 无效或已过期", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "API Key 无效或已过期" } } } } }, "Forbidden": { "description": "角色权限不足、来源 IP 不在白名单，或当前版本不支持该操作", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "当前 API Key 角色无权执行此操作" } } } } }, "NotFound": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "资源不存在" } } } } }, "TooManyRequests": { "description": "超出调用频率限制", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "请求过于频繁，请稍后重试" } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Page": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" } } }, "SystemStatus": { "type": "object", "properties": { "version": { "type": "string" }, "edition": { "type": "string", "enum": [ "waf-free", "enterprise", "datacenter" ] }, "uptime_seconds": { "type": "integer" }, "cpu_percent": { "type": "number" }, "memory_percent": { "type": "number" }, "sessions": { "type": "integer" } } }, "PolicyInput": { "type": "object", "required": [ "name", "action" ], "properties": { "name": { "type": "string" }, "action": { "type": "string", "enum": [ "allow", "deny" ] }, "src_zone": { "type": "string" }, "dst_zone": { "type": "string" }, "src_addresses": { "type": "array", "items": { "type": "string" } }, "dst_addresses": { "type": "array", "items": { "type": "string" } }, "services": { "type": "array", "items": { "type": "string" } }, "users": { "type": "array", "items": { "type": "string" } }, "schedule": { "type": "string" }, "enabled": { "type": "boolean" } } }, "Policy": { "allOf": [ { "$ref": "#/components/schemas/PolicyInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer" }, "hits": { "type": "integer" } } } ] }, "AddressInput": { "type": "object", "required": [ "name", "type", "value" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "host", "subnet", "range", "fqdn", "group" ] }, "value": { "type": "string" }, "members": { "type": "array", "items": { "type": "string" } } } }, "Address": { "allOf": [ { "$ref": "#/components/schemas/AddressInput" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "BlockInput": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "type": "string", "description": "IPv4 / IPv6 地址或 CIDR" }, "duration": { "type": "integer", "description": "封停时长（秒），0 表示永久" }, "reason": { "type": "string" } } }, "BlockEntry": { "allOf": [ { "$ref": "#/components/schemas/BlockInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "auto", "manual", "api", "mcp", "approval" ] }, "status": { "type": "string", "enum": [ "active", "pending", "expired" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } } } ] }, "AllowInput": { "type": "object", "required": [ "cidr" ], "properties": { "cidr": { "type": "string" }, "note": { "type": "string" } } }, "AllowEntry": { "allOf": [ { "$ref": "#/components/schemas/AllowInput" }, { "type": "object", "properties": { "id": { "type": "string" } } } ] }, "DomainRuleInput": { "type": "object", "required": [ "pattern", "list" ], "properties": { "pattern": { "type": "string", "description": "精确域名或通配符" }, "list": { "type": "string", "enum": [ "block", "allow" ] }, "groups": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } }, "DomainRule": { "allOf": [ { "$ref": "#/components/schemas/DomainRuleInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "hits": { "type": "integer" } } } ] }, "Alert": { "type": "object", "properties": { "id": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "category": { "type": "string", "description": "waf / ids / antivirus / honeypot / dns 等" }, "title": { "type": "string" }, "src_ip": { "type": "string" }, "dst": { "type": "string" }, "action": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "LogQuery": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "access", "attack", "audit", "system" ] }, "since": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "filters": { "type": "object", "additionalProperties": { "type": "string" } }, "page": { "type": "integer" }, "page_size": { "type": "integer" } } }, "LogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "ReportInput": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "daily", "weekly", "monthly", "custom" ] }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "format": { "type": "string", "enum": [ "pdf", "html", "csv" ] } } }, "Report": { "allOf": [ { "$ref": "#/components/schemas/ReportInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "download_url": { "type": [ "string", "null" ] } } } ] }, "Device": { "type": "object", "properties": { "id": { "type": "string" }, "ip": { "type": "string" }, "mac": { "type": "string" }, "type": { "type": "string" }, "os": { "type": "string" }, "first_seen": { "type": "string", "format": "date-time" }, "risk": { "type": "string", "enum": [ "low", "medium", "high" ] } } }, "HoneypotInput": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "ssh", "rdp", "mysql", "redis", "web-admin", "smb" ] }, "listen": { "type": "string" }, "enabled": { "type": "boolean" } } }, "Honeypot": { "allOf": [ { "$ref": "#/components/schemas/HoneypotInput" }, { "type": "object", "properties": { "id": { "type": "string" }, "triggers_24h": { "type": "integer" } } } ] }, "WebhookEvent": { "type": "object", "properties": { "event": { "type": "string" }, "id": { "type": "string", "description": "用于去重" }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "additionalProperties": true } } } } } }