一、简介

本文档用于描述FOFA全网资产收集与检索系统API使用方法,考虑到环境兼容性的问题,建议在Linux环境运行,当然Windows下面大多数也可以运行,本页实例部分的curl请另行安装。

输入必须包含认证信息,见认证 一节。

输出格式为json,正常情况下都在result字段,错误情况见错误和异常 一节。

三、认证

所有的调用都将需要提供身份信息,主要是 email 和 key :

参数 说明
email 注册和登录时填写的email
key 会员到个人资料可得到key,为32位的hash值
  • BASH
  • Ruby
export FOFA_EMAIL=xxx@gmail.com
export FOFA_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
curl "https://fofa.so/api/v1/info/my?email=${FOFA_EMAIL}&key=${FOFA_KEY}"
#1, 安装Ruby
#2, 安装fofagem:
# gem install fofa
#3, 调用SDK
fofa = Fofa::API.new('xxx@gmail.com', 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')

四、错误和异常

任何程序都不可避免出现异常情况,请随时关注可能提示的错误信息。

Attributes

参数 字段类型 说明
error boolean 是否发生错误
errmsg string 错误提示信息

Attributes

{
  "error": true,
  "errmsg": "401 Unauthorized, make sure email and apikey is correct."
}

五、获取IP标签接口

本接口分成两步:一是提交内容;二是查询进度和下载地址。

Step 1. 上传文件

输入下列请求所需的参数,返回json数据格式

请求方式:POST

参数 字段类型 说明
file file 上传后缀为txt的附件,文件内容必须是一行1个IP,ip数量不能超过1万条
  • BASH
  • Ruby
curl -X POST -F "file=@/Users/name/Desktop/ip.txt" "https://fofa.so/api/v1/ip_tags?email=${FOFA_EMAIL}&key=${FOFA_KEY}"
fofa.ip_tags("/Users/name/Desktop/ip.txt")

错误返回

#请上传txt文件
{"error":true,"errmsg":"Please upload the TXT file!"}
#单个文件最多只能上传10000行数据
{"error":true,"errmsg":"A single file can only upload 10000 lines of data!"}
#已经超出每天的数据处理限制(9000/10000)
{"error":true,"errmsg":"Daily data processing limit exceeded (9000/10000)!"}
#每次只能运行一个任务
{"error":true,"errmsg":"Only one task can be run at a time!"}

返回

参数 字段类型 说明
task_id integer 提交成功的任务ID

正确返回结果

{
  "error": false,
  "task_id": 1
}

Step 2. 查询任务进度,进度100%后,自动返回下载地址。

输入下列请求所需的参数,返回json数据格式

请求方式:GET

参数 字段类型 说明
task_id string 任务ID

返回

参数 字段类型 说明
state string 任务状态:init, running, success, failure
progress integer 任务进度,0~100
download_url string 任务进度100时,返回下载地址
  • BASH
  • Ruby
curl "https://fofa.so/api/v1/ip_tags/info?email=${FOFA_EMAIL}&key=${FOFA_KEY}&task_id=1"
fofa.tag_info(1)

正确返回结果

{
  "error": false,
  "state": "success",
  "progress": 100,
  "download_url": "https://fofa.so/file_downloads/ip_tags?filename=581cee346cc22e2adb25888d81613118.json"
}

错误返回

#该任务不存在
{"errmsg":"Task does not exist!","error":true}

六、查询接口

输入下列请求所需的qbase64,返回json数据格式

请求

参数 字段类型 说明
qbase64 string 经过base64编码后的查询语法,支持domain,host,ip,header,body,title,运算符支持== = != =~
page integer 翻页数,默认为第一页
size integer 每次查询返回记录数,默认为100条,最大可设置为10000条
注:body字段包含内容较多,建议每次获取≤100条
fields string 【可选参数】字段列表,默认为host,用逗号分隔多个参数,如(fields=ip,title),可选的列表有:host title ip domain port country province city country_name header server protocol banner cert isp as_number as_organization latitude longitude   structinfo
注意:country是国家代码,例如CN, country_name是国家名称;structinfo仅限企业会员调用
full boolean 默认为false,是否搜索全部数据,默认和页面搜索一样,只能搜索一年内的数据,指定为true搜索全部数据

返回

参数 字段类型 说明
mode string 查询模式 mode返回为"normal"代表普通查询(q=words) mode返回为"extended"代表高级查询(如q=domain=fofa.so,q=title=fofa,采用高级条件搜索)
page integer 当前请求页的页数
size integer 请求返回结果的个数
results array 请求返回结果的详情数组
  • BASH
  • Ruby
echo 'domain="fofa.so"' | base64 - | xargs -I{} curl "https://fofa.so/api/v1/search/all?email=${FOFA_EMAIL}&key=${FOFA_KEY}&qbase64={}"
fofa.search('domain=nosec.org')

正确返回结果

{
  "mode": "extended",
  "error": false,
  "query": "domain=\"nosec.org\"\n",
  "page": 1,
  "size": 6,
  "results": [
    [
      "https://i.nosec.org"
    ],
    [
      "https://nosec.org"
    ],
    [
      "down3.nosec.org"
    ],
    [
      "www.nosec.org"
    ],
    [
      "nosec.org"
    ],
    [
      "cdn.nosec.org"
    ]
  ]
}

错误返回

#服务器异常
{"errmsg":"Internal Server Error!","error":true}
#F币不足
{"errmsg":"FOFA coin is not enough!","error":true}
#结果窗口过大
{"errmsg":"Result window is too large, page must be less than or equal to...","error":true}

七、用户协议

1.定义

1.1 FOFA API开放接口是由白帽汇提供技术标准;

1.2 FOFA API开放接口所有权归白帽汇所有。

2. 使用许可

2.1 用户使用FOFA API数据接口,应遵守被协议的约定及法律、法规之相关规定;

2.2 用户在使用FOFA API数据接口时,如有恶意使用及使用不当,后果由用户自身承担;

2.3 用户不得对所提供的数据内容做出任何修改;

2.4 白帽汇向用户提供API使用的相应技术支持,用户需按照白帽汇所提供的《操作说明》进行;

2.5 用户在获得使用权时,有权根据自身的实际应用场景使用。

3. 保密内容及范围

3.1 双方不得在未经对方允许情况下披露给其他个人或单位信息;

3.2 用户不得向其他单位及个人提供使用FOFA API时必须的相关授权密钥,一经发现可马上终止本协议。

问题反馈