fofa-sdk

A TypeScript SDK for FOFA API.

Installation

pnpm add fofa-sdk

Usage

Initialize Client

import { FofaClient } from 'fofa-sdk'

const client = new FofaClient({
  key: 'your_api_key',
  // Optional
  baseUrl: 'https://fofa.info',
  timeout: 30000,
  retries: 3,
  retryDelay: 1000,
  headers: {
    'User-Agent': 'your-app/1.0.0',
  },
})

Search

const result = await client.search('title="bing"', {
  fields: ['host', 'ip', 'port'],
  page: 1,
  size: 100,
  full: false,
})

console.log(result.results)
// [{ host: 'example.com', ip: '1.2.3.4', port: '80' }, ...]

Continuous Pagination

Set size to the total number of results you want. Requests with size <= 10000 use the normal search endpoint. For size > 10000, the SDK automatically uses FOFA's /search/next cursor endpoint and requests 10,000 results per batch. The cursor requires the batch size to stay unchanged, so the SDK trims the final batch locally to the requested total. Pagination stops when the requested total or FOFA's total response size is reached.

const result = await client.search('title="bing"', {
  fields: ['host', 'ip', 'port'],
  size: 50000,
})

console.log(result.results) // Up to 50,000 results
console.log(result.next) // Present only when FOFA still returned a cursor

The response field size is FOFA's total result count for the query. When pagination is enabled, the SDK stops at Math.min(options.size, response.size) and never uses an empty results array as the normal completion condition.

Use searchNext() when you want to control the cursor manually:

const firstPage = await client.searchNext('title="bing"', {
  size: 10000,
})

const secondPage = firstPage.next
  ? await client.searchNext('title="bing"', {
      size: 10000,
      next: firstPage.next,
    })
  : undefined

Get User Info

const userInfo = await client.getUserInfo()

console.log(userInfo.email)
console.log(userInfo.fpoint)
console.log(userInfo.vip_level)

API

FofaClient

Constructor Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | key | string | - | API key (required) | | baseUrl | string | https://fofa.info | API base URL | | timeout | number | 30000 | Request timeout (ms) | | retries | number | 3 | Retry count | | retryDelay | number | 1000 | Retry delay (ms) | | headers | Record<string, string> | - | Custom request headers |

Methods

search(query, options?)

Search for hosts.

| Option | Type | Default | Description | | --- | --- | --- | --- | | fields | FofaField[] | ['host', 'ip', 'port'] | Fields to return | | page | number | 1 | Page number | | size | number | 100 | Single-request result count (max 10000); values above 10000 automatically enable cursor pagination | | full | boolean | false | Search all data (default: last year) |

When size is greater than 10000, page is ignored and the SDK fetches the result in multiple requests.

searchNext(query, options?)

Fetch one batch through FOFA's /search/next endpoint. Pass the previous response's next value to request the following batch.

getUserInfo()

Get current user information.

Available Fields

type FofaField =
  // No permission required
  | 'ip' | 'port' | 'protocol' | 'country' | 'country_name'
  | 'region' | 'city' | 'longitude' | 'latitude' | 'asn'
  | 'org' | 'host' | 'domain' | 'os' | 'server' | 'icp'
  | 'title' | 'jarm' | 'header' | 'banner' | 'cert'
  | 'base_protocol' | 'link'
  // Personal+
  | 'header_hash' | 'banner_hash' | 'banner_fid'
  // Professional+
  | 'cname' | 'lastupdatetime' | 'product' | 'product_category'
  // Business+
  | 'product.version' | 'icon_hash' | 'cert.is_valid' | 'cname_domain' | 'body'
  // Enterprise
  | 'icon' | 'fid' | 'structinfo'

License

MIT