API 使用指南#

# 方式一：直接运行
python -m api.app --host 0.0.0.0 --port 8000

# 方式二：通过 CLI
python main.py serve --port 8000

python scripts/export_openapi.py --output docs/openapi.json

POST /api/scan

{
  "target": "http://example.com/",
  "mode": "u",
  "cms": "",
  "threads": 1,
  "rate": 0,
  "proxy": "",
  "timeout": 10,
  "debug": false,
  "report_format": "html",
  "no_dedup": false,
  "pass_level": "full",
  "portscan": false,
  "ports": "",
  "bypass_waf": "auto",
  "crawl": false,
  "crawl_depth": 2,
  "crawl_max_pages": 50,
  "subdomain": false,
  "js_extract": false,
  "template": "",
  "auth": null
}

{
  "cookies": {"session": "abc123"},
  "headers": {"Authorization": "Bearer token"},
  "type": "session"
}

{
  "task_id": "a1b2c3d4e5f6",
  "status": "pending",
  "target": "http://example.com/",
  "created_at": 1721480000.0
}

# 基础扫描
curl -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"target": "http://192.168.1.100:8080/", "mode": "u"}'

# 带认证的深度扫描
curl -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d '{
    "target": "http://192.168.1.100:8080/",
    "mode": "p",
    "auth": {"cookies": {"session": "admin_token"}},
    "template": "deep"
  }'

GET /api/scan/{task_id}

{
  "task_id": "a1b2c3d4e5f6",
  "status": "done",
  "target": "http://example.com/",
  "mode": "u",
  "started_at": 1721480000.0,
  "finished_at": 1721480030.0,
  "duration": 30.5,
  "request_count": 152,
  "result_count": 18,
  "confirmed_count": 5,
  "error": "",
  "fingerprint": {
    "cms": "ruoyi",
    "confidence": 0.95,
    "matched": ["login_page"]
  },
  "waf": null,
  "report_paths": ["/data/reports/a1b2c3d4e5f6/report.html"]
}

GET /api/scan/{task_id}/results

[
  {
    "kind": "vuln",
    "name": "SQL注入-角色列表",
    "severity": "high",
    "status": "CONFIRMED",
    "url": "http://example.com/system/role/list",
    "evidence": "Boolean-based blind SQL injection detected",
    "cve": "CVE-2023-XXXX",
    "timestamp": 1721480010.0
  }
]

GET /api/scan/{task_id}/report?format=html

WS /ws/scan/{task_id}

// 有 Key 模式：子协议数组第二项为密钥；无 Key 模式仅传 URL
const ws = new WebSocket('ws://localhost:8000/ws/scan/a1b2c3d4e5f6', ['ruoyi-scan-api-key', 'your-secret-key']);
ws.onmessage = (e) => {
    const event = JSON.parse(e.data);
    console.log(`[${event.type}]`, event.data);

    if (event.type === 'result') {
        console.log(`${event.data.name}: ${event.data.status}`);
    }
    if (event.type === 'complete') {
        console.log(`扫描完成，耗时 ${event.data.duration}s`);
        ws.close();
    }
};

import websockets
import asyncio
import json

async def listen(task_id):
    # 有 Key 模式：subprotocols 第二项为密钥；无 Key 模式可省略
    uri = f"ws://localhost:8000/ws/scan/{task_id}"
    async with websockets.connect(uri, subprotocols=["ruoyi-scan-api-key", "your-secret-key"]) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"[{event['type']}] {event.get('data', {})}")
            if event['type'] == 'complete':
                break

asyncio.run(listen("a1b2c3d4e5f6"))

GET /api/plugins
GET /api/plugins/{name}

{
  "detail": "任务不存在: invalid_task_id"
}

# 1. 提交扫描任务
TASK_ID=$(curl -s -X POST http://localhost:8000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"target": "http://192.168.1.100:8080/", "mode": "u"}' \
  | python -c "import sys,json; print(json.load(sys.stdin)['task_id'])")

echo "任务 ID: $TASK_ID"

# 2. 轮询任务状态（也可用 WebSocket 实时订阅）
while true; do
  STATUS=$(curl -s http://localhost:8000/api/scan/$TASK_ID | python -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "状态: $STATUS"
  if [ "$STATUS" = "done" ] || [ "$STATUS" = "failed" ]; then
    break
  fi
  sleep 2
done

# 3. 获取扫描结果
curl -s http://localhost:8000/api/scan/$TASK_ID/results | python -m json.tool

# 4. 下载 HTML 报告
curl -o report.html http://localhost:8000/api/scan/$TASK_ID/report?format=html
echo "报告已下载: report.html"

# 生成静态 HTML 文档（需安装 redoc-cli）
npx redoc-cli bundle docs/openapi.json -o docs/api-docs.html

# 导入 Postman
# Postman → Import → 选择 docs/openapi.json

# 导入 Apifox
# Apifox → 导入数据 → 选择 OpenAPI/Swagger → docs/openapi.json