API

Every securitytrails.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.

New to Corsair? See API access, authentication, and error handling.

Account

ping

account.ping Verify the configured SecurityTrails API key is accepted and the API is reachable. Risk: read

await corsair.securitytrails.api.account.ping({});

Input: empty object Output

Name	Type	Required	Description
`success`	`boolean`	No	—

usage

account.usage Return the current and allowed monthly API usage for the account. Risk: read

await corsair.securitytrails.api.account.usage({});

Input: empty object Output

Name	Type	Required	Description
`current_monthly_usage`	`number`	No	—
`allowed_monthly_usage`	`number`	No	—

Company

associatedIps

company.associatedIps List the CIDR blocks associated with a company domain. Paginated. Risk: read

await corsair.securitytrails.api.company.associatedIps({});

Input

Name	Type	Required	Description
`domain`	`string`	Yes	—
`page`	`number`	No	—
`page_size`	`number`	No	—

Output

Name	Type	Required	Description
`records`	`object[]`	No	—
`query`	`string`	No	—
`record_count`	`number`	No	—
`domain`	`string`	No	—
`page`	`number`	No	—
`page_size`	`number`	No	—
`redir`	`string`	No	—

records full type

{
  cidr?: string
}[]

Domain

get

domain.get Get current DNS records (A, AAAA, MX, NS, SOA, TXT) and co-occurrence statistics for a hostname. Risk: read

await corsair.securitytrails.api.domain.get({});

Input

Name	Type	Required	Description
`hostname`	`string`	Yes	—

Output

Name	Type	Required	Description
`hostname`	`string`	No	—
`alexa_rank`	`number`	No	—
`current_dns`	`object`	No	—

current_dns full type

{
  a?: {
    first_seen?: string | null,
    values?: {
      ip?: string,
      ip_count?: number
    }[]
  },
  aaaa?: {
    first_seen?: string | null,
    values?: {
      ip?: string,
      ip_count?: number
    }[]
  },
  mx?: {
    first_seen?: string | null,
    values?: {
      priority?: number,
      host?: string,
      host_count?: number
    }[]
  },
  ns?: {
    first_seen?: string | null,
    values?: {
      nameserver?: string,
      nameserver_count?: number
    }[]
  },
  soa?: {
    first_seen?: string | null,
    values?: {
      ttl?: number,
      email?: string,
      email_count?: number
    }[]
  },
  txt?: {
    first_seen?: string | null,
    values?: {
      value?: string
    }[]
  }
}

ssl

domain.ssl List current and historical SSL/TLS certificates for a hostname, optionally including subdomains. Paginated. Risk: read

await corsair.securitytrails.api.domain.ssl({});

Input

Name	Type	Required	Description
`hostname`	`string`	Yes	—
`include_subdomains`	`boolean`	No	—
`status`	`valid \| all \| expired`	No	—
`page`	`number`	No	—

Output

Name	Type	Required	Description
`endpoint`	`string`	No	—
`meta`	`object`	No	—
`record_count`	`number`	No	—
`records`	`object[]`	No	—

meta full type

{
  max_page?: number,
  page?: number,
  total_pages?: number,
  query?: {
  }
}

records full type

{
  dns_names?: string[],
  fingerprints?: {
    sha1?: string,
    sha256?: string
  },
  issuer?: {
    common_name?: string,
    country?: string[],
    organization?: string[]
  },
  subject?: {
  },
  not_after?: number | null,
  not_before?: number | null,
  serial_number?: string
}[]

Ips

search

ips.search Search the IP dataset with a DSL query, returning matching addresses, PTR records and open ports. Paginated. Risk: read

await corsair.securitytrails.api.ips.search({});

Input

Name	Type	Required	Description
`query`	`string`	Yes	—
`page`	`number`	No	—

Output

Name	Type	Required	Description
`endpoint`	`string`	No	—
`records`	`object[]`	No	—
`record_count`	`number`	No	—
`meta`	`object`	No	—

records full type

{
  ip?: string,
  ptr?: string | null,
  ports?: number[]
}[]

meta full type

{
  total_pages?: number,
  query?: string,
  page?: number,
  max_page?: number
}

stats

ips.stats Return aggregate open-port and PTR-pattern statistics for a DSL query over the IP dataset. Risk: read

await corsair.securitytrails.api.ips.stats({});

Input

Name	Type	Required	Description
`query`	`string`	Yes	—

Output

Name	Type	Required	Description
`endpoint`	`string`	No	—
`top_ptr_patterns`	`object[]`	No	—
`ports`	`object[]`	No	—
`total`	`number`	No	—

top_ptr_patterns full type

{
  key?: string,
  count?: number
}[]

ports full type

{
  key?: number,
  count?: number
}[]

Projects

bulkStaticAssetRules

projects.bulkStaticAssetRules Add or remove static asset rules for an ASI project, changing which assets are in the project’s monitoring scope. Up to 1000 rules per request. Risk: write

await corsair.securitytrails.api.projects.bulkStaticAssetRules({});

Input

Name	Type	Required	Description
`project_id`	`string`	Yes	—
`add_rules`	`object[]`	No	—
`remove_rules`	`object[]`	No	—

add_rules full type

{
  asset: string,
  membership_type: include | exclude,
  static_type: ipv4 | hostname | wildcard
}[]

remove_rules full type

{
  asset: string,
  membership_type: include | exclude,
  static_type: ipv4 | hostname | wildcard
}[]

Output

Name	Type	Required	Description
`data`	`object`	No	—
`meta`	`object`	No	—
`complete`	`boolean`	No	—
`task_ids`	`string[]`	No	—

data full type

{
  added?: {
    asset: string,
    membership_type: include | exclude,
    static_type: ipv4 | hostname | wildcard
  }[],
  removed?: {
    asset: string,
    membership_type: include | exclude,
    static_type: ipv4 | hostname | wildcard
  }[],
  errors?: {
    rule?: {
      asset: string,
      membership_type: include | exclude,
      static_type: ipv4 | hostname | wildcard
    } | null,
    failed?: boolean | null,
    messages?: string[] | null
  }[]
}

meta full type

{
  params?: {
  } | null,
  counts?: {
    total?: number | null,
    returned?: number
  } | null,
  pagination?: {
    next_cursor?: string | null,
    limit?: number,
    total?: number | null,
    sort?: string[][] | null
  } | null,
  request_id?: string | null
}

list

projects.list List the Attack Surface Intelligence projects the API key can access. Risk: read

await corsair.securitytrails.api.projects.list({});

Input

Name	Type	Required	Description
`sort_direction`	`asc \| desc`	No	—

Output

Name	Type	Required	Description
`data`	`object[]`	No	—
`meta`	`object`	No	—

data full type

{
  id: string,
  title: string,
  scanning_enabled?: boolean | null,
  last_scanned_at?: string | null,
  inserted_at?: string | null,
  max_exposure_score?: number | null
}[]

meta full type

{
  params?: {
  } | null,
  counts?: {
    total?: number | null,
    returned?: number
  } | null,
  pagination?: {
    next_cursor?: string | null,
    limit?: number,
    total?: number | null,
    sort?: string[][] | null
  } | null,
  request_id?: string | null
}

Scroll

get

scroll.get Fetch the next page of a DSL search using a scroll cursor from a previous response. Risk: read

await corsair.securitytrails.api.scroll.get({});

Input

Name	Type	Required	Description
`scroll_id`	`string`	Yes	—

Output: object

Output full type

{
}

Sql

query

sql.query Run a SQL-like query against the hosts or ips tables. Returns up to 100 records plus a scroll cursor. Risk: read

await corsair.securitytrails.api.sql.query({});

Input

Name	Type	Required	Description
`query`	`string`	Yes	—
`page`	`number`	No	—

Output

Name	Type	Required	Description
`query`	`string`	No	—
`id`	`string`	No	—
`total`	`object`	No	—
`records`	`object[]`	No	—

total full type

{
  value?: string | number,
  relation?: string
}

records full type

{
}[]

scroll

sql.scroll Fetch the next 100 records for an open SQL API scroll cursor. Risk: read

await corsair.securitytrails.api.sql.scroll({});

Input

Name	Type	Required	Description
`id`	`string`	Yes	—

Output

Name	Type	Required	Description
`query`	`string`	No	—
`id`	`string`	No	—
`total`	`object`	No	—
`records`	`object[]`	No	—

total full type

{
  value?: string | number,
  relation?: string
}

records full type

{
}[]

Overview

Plugins

Account

ping

usage

Company

associatedIps

Domain

get

ssl

Ips

search

stats

Projects

bulkStaticAssetRules

list

Scroll

get

Sql

query

scroll

​Account

​ping

​usage

​Company

​associatedIps

​Domain

​get

​ssl

​Ips

​search

​stats

​Projects

​bulkStaticAssetRules

​list

​Scroll

​get

​Sql

​query

​scroll

Account

ping

usage

Company

associatedIps

Domain

get

ssl

Ips

search

stats

Projects

bulkStaticAssetRules

list

Scroll

get

Sql

query

scroll