FOFA 搜索服务 API 文档

FOFA 资产搜索 HTTP 接口，使用前请先获取访问令牌（API Key）。

接口地址：https://fofa.ssgonet.com（公网）
协议：HTTPS / JSON

1. 认证

所有请求需携带令牌，二选一：

请求头方式（推荐）

X-API-Key: <你的令牌>

查询参数方式

?api_key=<你的令牌>

令牌由服务提供方分配。若尚未获取或需要调整额度，请联系管理员。

测试令牌

先试用可以直接用这一张，无需申请：

X-API-Key: a5867f6b8728d921635b6a2be1d8d8e8

项	值
每日额度	1000 次（每日 0 点重置，北京时间 UTC+8）
有效期	长期
用途	联调、验证接入，正式使用请申请独立令牌

测试令牌为公开共享，额度可能被他人占用。正式环境请使用分配给你的独立令牌。

2. 搜索接口

POST /api/search
Content-Type: application/json

请求参数

参数	类型	必填	说明
query	string	是	搜索语法，见下方「查询语法」
page	int	否	页码，从 1 开始，默认 1
size	int	否	每页返回条数，范围 2 ~ 50，默认 10

page × size ≤ 60：单次查询最多返回 60 条。越界返回 400，附明确提示。

请求示例

curl -X POST https://fofa.ssgonet.com/api/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <你的令牌>" \
  -d '{"query":"title=\"login\"","page":1,"size":10}'

响应示例

{
  "code": 0,
  "query": "title=\"login\"",
  "page": 1,
  "size": 10,
  "fields": ["ip", "port", "protocol", "host", "title", "domain", "country", "region", "city", "server", "banner", "status", "org", "mtime"],
  "total": 30081754,
  "remaining_today": 997,
  "assets": [
    {
      "ip": "52.70.38.235",
      "port": 443,
      "protocol": "https",
      "host": "https://52.70.38.235",
      "title": "Airflow - Login",
      "domain": "",
      "country": "美国",
      "region": "Virginia",
      "city": "Ashburn",
      "server": "gunicorn",
      "banner": "",
      "status": 200,
      "org": "",
      "mtime": "2026-08-19 08:00:00"
    }
  ]
}

响应字段说明

字段	类型	说明
code	int	0 表示成功，非 0 见「错误码」
query	string	回显请求的查询语句
page / size	int	回显本次翻页参数
fields	array	本次返回的资产字段列表
total	int	匹配该查询的资产总数
remaining_today	int	今日剩余搜索次数（每日重置）
warning	string	提示：今日额度即将用完（剩余 ≤10%）
assets	array	资产列表

翻页

# 第 1 页
-d '{"query":"domain=\"baidu.com\"","page":1,"size":50}'
# 第 2 页（注意：2*50=100 > 60，会被拒；改用 size=10 可翻 6 页）
-d '{"query":"domain=\"baidu.com\"","page":2,"size":10}'

单次查询上限 60 条。需要更多数据请用切片：把大查询拆成多个互斥子查询，每片独立享有 60 条额度。详见切片搜索进阶指南。

3. 查询语法

与 FOFA 网页版语法一致：

目的	查询语句
标题包含 login	`title="login"`
域名	`domain="baidu.com"`
指定 IP	`ip="1.2.3.4"`
端口	`port="443"`
协议	`protocol="https"`
国家/地区	`country="CN"`、`region="Beijing"`
组合条件	`title="login" && country="CN"`
排除	`title="login" && country!="US"`

注意：不存在的字段（如 nosuchfield="x"）返回 820000 语法错误；但纯单词（如 bad）不报错，会当全文关键词搜索。

4. 错误码

code	HTTP	含义	处理方式
0	200	成功	—
400	400	请求格式错误 / 查询语法错误 / `page*size` 超 60	检查请求体与查询语法
401	401	令牌无效或缺失	检查 `X-API-Key`
403	403	今日额度用完	等次日 0 点（北京时间）重置
405	405	请求方法不是 POST	使用 POST
429	429	请求过于频繁	降速后重试
502	502	服务暂不可用	稍后重试；持续出现请联系管理员

5. 令牌信息查询

GET /api/token-info

curl -H "X-API-Key: <你的令牌>" https://fofa.ssgonet.com/api/token-info

{
  "code": 0,
  "user_name": "用户A",
  "remark": "月卡批次",
  "daily_quota": 1000,
  "today_used": 1,
  "today_remaining": 999
}

按激活制发放的令牌，在首次调用前不会返回 expires_at；首次调用后即开始计时。

6. 健康检查

GET /health      → {"ok":true,"time":"..."}

返回 200 表示服务可用。

7. 代码示例

Python

import requests

API = "https://fofa.ssgonet.com/api/search"
KEY = "<你的令牌>"

def search(query, page=1, size=10):
    resp = requests.post(API, headers={"X-API-Key": KEY},
                         json={"query": query, "page": page, "size": size})
    resp.raise_for_status()
    return resp.json()

# 单次搜索：total 是匹配总数
data = search('title="login"', size=50)
print("匹配总数:", data.get("total"))
for asset in data.get("assets", []):
    print(asset["ip"], asset["port"], asset["title"])

# 翻页：page*size 必须 <= 60
for page in range(1, 7):
    data = search('title="login"', page=page, size=10)
    for asset in data.get("assets", []):
        print(asset["ip"], asset["port"], asset["title"])

命令行

curl -s -X POST https://fofa.ssgonet.com/api/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <你的令牌>" \
  -d '{"query":"title=\"login\"","page":1,"size":10}'