Bishop Fox Cosmos

External Attack Surface Management

Overview

The BishopFox connector integrates with Bishop Fox Cosmos, an External Attack Surface Management (EASM) platform. It synchronizes the organization's external attack surface — registered domains, IP ranges, DNS records, subdomains, IP addresses, open ports, and discovered services — together with pentest findings and their definitions.

Data retrieved from BishopFox

Connector Object	Required	Maps to Data Model
Domain	Yes	Site
Network	Yes	Ip Range
DnsRecord	Yes	DnsRecord
Subdomain	Yes	Host
IpAddress	Yes	Host
Port	Yes	Port
IpService	Yes	Api Endpoint
HostnameService	Yes	Api Endpoint
Finding	Yes	Pentest Finding
FindingDefinition	Yes	Pentest Finding Definition

Model relationships

note

For detailed steps on how to view the data retrieved from BishopFox in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select BishopFox from the Connector dropdown and provide the following:

Setting	Required	Default	Description
API URL	Yes	https://api.cosmos.bishopfox.com	BishopFox API URL
Token URL	Yes	https://bishopfox.auth0.com/oauth/token	BishopFox API authentication token URL. Defaults to 'https://bishopfox.auth0.com/oauth/token'
OAuth audience	Yes	cosmos_public	Defaults to cosmos_public
Client ID	Yes	—	BishopFox API client ID
Client secret	Yes	—	BishopFox API client secret
Organization ID	No	—	BishopFox organization ID
Page size	No	100	Maximum number of records to get per API request
Parallel requests	No	min(4, cores)	Maximum number of parallel page-number page fetches per sync. Has no effect on cursor-paginated endpoints, which must run sequentially.

Authentication

OAuth 2.0 client-credentials grant. The connector exchanges an API key + secret for a 10-hour bearer token at the Bishop Fox Auth0 token endpoint, then includes the token in Authorization on every Cosmos API request.

Endpoint

Method	URL
POST	https://bishopfox.auth0.com/oauth/token (default; override via the loginUrl config)

Request Headers

Header	Value
Content-Type	application/x-www-form-urlencoded

Request Body

grant_type=client_credentials
audience=cosmos_public
client_id=<API Key>
client_secret=<API Secret>

Sample Response

{
  "access_token": "eyJhbGciOi...",
  "scope": "get:assets get:findings list:assets read:ingest update:assets update:findings write:ingest",
  "expires_in": 36000,
  "token_type": "Bearer"
}

Response Fields

Field	Type	Description
access_token	string	JWT bearer token for subsequent requests
token_type	string	Always Bearer
expires_in	integer	Token lifetime in seconds (36000 = 10 hours)
scope	string	Space-separated list of granted scopes

Usage

The connector caches the token in memory and refreshes when expires_in elapses. Subsequent requests carry:

Authorization: Bearer <access_token>
Content-Type: application/json

---

How to obtain BishopFox credentials

Obtain the required credentials (url, loginUrl, audience, clientId, clientSecret, orgUid) from your BishopFox administrator or the BishopFox admin console, then enter them in the connection settings above.

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

Domain

Source Field Name	SDM Attribute
(computed)	LAST_CAPTURED
asset_type	TYPE
client_id	CLIENT_ID
cloud	CLOUD
confidence_level	CONFIDENCE_LEVEL
created_at	SOURCE_CREATED_DATE
customer_id	CUSTOMER_ID
data_updated_at	LAST_SCANNED
domain	NAME
domain	DOMAIN_NAME
enabled	ENABLED
engagements	ENGAGEMENTS
expiry	EXPIRY
id	UID
organization_id	ORGANIZATION_ID
origination	ORIGINATION
ownership	OWNERSHIP
parent_asset_id	PARENT_ASSET_ID
parent_asset_type	PARENT_ASSET_TYPE
registrant_organization	REGISTRANT_ORGANIZATION
registrar	REGISTRAR
reserved_engagements	RESERVED_ENGAGEMENTS
tags	TAGS
updated_at	SOURCE_LAST_MODIFIED

Network

Source Field Name	SDM Attribute
(envelope)	TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
address	ADDRESS
address/prefix	NAME
address/prefix	IPV4_RANGES
address/prefix	IPV6_RANGES
asset_type	TYPE
confidence_level	CONFIDENCE_LEVEL
id	UID
prefix	PREFIX

DnsRecord

Source Field Name	SDM Attribute
(envelope)	TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
asset_type	TYPE
cdn_category	CDN_CATEGORY
cdn_vendor	CDN_VENDOR
designation	DESIGNATION
hostname	NAME
hostname	HOSTNAME
id	UID
record_type	RECORD_TYPE
ttl	TTL
value	RECORD_VALUE

Subdomain

Source Field Name	SDM Attribute
(envelope)	TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
asset_type	TYPE
confidence_level	CONFIDENCE_LEVEL
designation	DESIGNATION
hostname	NAME
hostname	HOST
hostname	HOSTNAMES
id	UID
is_apex	IS_APEX
orphaned_cname	ORPHANED_CNAME
rfc1918	RFC1918
serviceable	SERVICEABLE
viable	VIABLE
wildcard	WILDCARD
wildcard_scan_override	WILDCARD_SCAN_OVERRIDE

IpAddress

Source Field Name	SDM Attribute
(envelope)	TYPE, TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
aged_out	AGED_OUT
aged_out_source	AGED_OUT_SOURCE
correlation_id	CORRELATION_ID
created_by	CREATED_BY
deleted	DELETED
deleted_at	DELETED_AT
id	UID
ip_address	NAME
ip_address	IP_ADDRESSES
ip_address (when classified as public)	PUBLIC_IP_ADDRESSES
location	LOCATION
refreshed_at	REFRESHED_AT
scan_level_override	SCAN_LEVEL_OVERRIDE
sources[*].system	SOURCES
updated_by	UPDATED_BY

Port

Source Field Name	SDM Attribute
(envelope)	TYPE, TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
(rich envelope)	SOURCES, CORRELATION_ID, CREATED_BY, UPDATED_BY, DELETED, DELETED_AT, AGED_OUT, AGED_OUT_SOURCE, SCAN_LEVEL_OVERRIDE, REFRESHED_AT
first of suggested_protocols	PROTOCOL
first_reachable_at	FIRST_REACHABLE_AT
first_verified_at	FIRST_VERIFIED_AT
id	UID
ip_address	IP_ADDRESSES
ip_address/port	NAME
last_probed_at	LAST_PROBED_AT
last_reachable_at	LAST_REACHABLE_AT
last_verified_at	LAST_VERIFIED_AT
parent_asset_id (when parent_asset_type=ip-address)	HOSTS
port	PORT
reachable	REACHABLE
suggested_protocols	SUGGESTED_PROTOCOLS
transport_protocol	TRANSPORT_PROTOCOL
verified	VERIFIED

IpService

Source Field Name	SDM Attribute
(envelope)	TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
(resolved via Port)	HOSTS
application_protocol	PROTOCOL
asset_type	TYPE
cdn_name, cdn_type	CDN_NAME, CDN_TYPE
cpe_list[*].cpes[*]	CPE_RECORDS
id	UID
ip_address	IP_ADDRESSES
port	PORT

HostnameService

Source Field Name	SDM Attribute
(envelope)	TAGS, SOURCE_CREATED_DATE, SOURCE_LAST_MODIFIED, LAST_SCANNED, CUSTOMER_ID, ORGANIZATION_ID, PARENT_ASSET_ID, PARENT_ASSET_TYPE, ENABLED, OWNERSHIP, CLIENT_ID, ORIGINATION, CLOUD, ENGAGEMENTS, RESERVED_ENGAGEMENTS, LAST_CAPTURED
application_protocol	PROTOCOL
asset_type	TYPE
cdn_name, cdn_type	CDN_NAME, CDN_TYPE
cpe_list[*].cpes[*]	CPE_RECORDS
hostname	HOST
id	UID
ip_list	IP_ADDRESSES
parent_asset_id	HOSTS
path	PATH
port	PORT

Finding

Source Field Name	SDM Attribute
(computed)	LAST_CAPTURED
finding_id	TYPE
MD5(finding_id, subject_id)	UID
normalized subject.status	SOURCE_STATUS
subject.asset_id	TARGETS
subject.asset_id	ASSET_ID
subject.asset_type	ASSET_TYPE
subject.client_id	CLIENT_ID
subject.client_note	CLIENT_NOTE
subject.created_at	SOURCE_CREATED_DATE
subject.remediated_at	LAST_FIXED
subject.remediation_description	RECOMMENDATION
subject.retest_count	RETEST_COUNT
subject.status	PROVIDER_STATUS
subject.updated_at	SOURCE_LAST_MODIFIED

FindingDefinition

Source Field Name	SDM Attribute
(computed)	LAST_CAPTURED
additional_resources	REFERENCES
bfid	BFID
bfid (or finding_id)	NAME
category ∪ sub_category	CATEGORIES
client_note	CLIENT_NOTE
definition	DESCRIPTION
delivery_date	PUBLISHED_DATE
details	DETAILS
emerging_threat_id	EMERGING_THREAT_ID
engagement_id	ENGAGEMENT_ID
finding_id	UID
normalized + raw severity	SEVERITY, SOURCE_SEVERITY, SEVERITY_SCORE
organization_id	ORGANIZATION_ID
recommendations	RECOMMENDATION
reported_at	SOURCE_CREATED_DATE
source	SOURCE
sub_category	SUB_CATEGORY
tags	TAGS
type	FINDING_TYPE
updated_at	SOURCE_LAST_MODIFIED

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

Domain

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/domains
• Default filters: None (full sync — since is ignored)

Network

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/networks
• Default filters: None (full sync — since is ignored)

DnsRecord

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/dns-records
• Default filters: None (full sync — since is ignored)

Subdomain

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/subdomains
• Default filters: None (full sync — since is ignored)

IpAddress

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/ip-addresses
• Default filters: None (full sync — since is ignored)

Port

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/ports
• Default filters: None (full sync — since is ignored)

IpService

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/ip-services
• Default filters: None (full sync — since is ignored)

HostnameService

Operation options

This object does not support any operation options.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/asset-view/hostname-services
• Default filters: None (full sync — since is ignored)

Finding

Operation options

Option	Type	Default	Description
status	string (CSV)	Filter by Bishop Fox finding status. Emitted as repeated query keys per the v5 spec.
category	string (CSV)	Filter by finding category. Emitted as repeated query keys.
TRANSACTION_ID	string	Used by the shared local-store (Finding + FindingDefinition share /v5/findings).

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/findings
• Default filters: None by default. Optional status and category operation options are emitted as repeated query keys. since/severity are not supported server-side and are never sent.

FindingDefinition

Operation options

Option	Type	Default	Description
status	string (CSV)	Same as Finding
category	string (CSV)	Same as Finding
TRANSACTION_ID	string	Required for the shared API-response store and the dedup store.

Delta sync

The connector README does not document sync behavior for this object.

API

• Type: REST · Endpoint: GET /v5/findings
• Default filters: None by default. Optional status and category operation options are emitted as repeated query keys. since/severity are not supported server-side and are never sent.

Changelog

Changelog

The BishopFox connector has undergone the following changes:

Version	Description	Migration Steps
3.0.1	Bug Fixes - Projection-restricted asset types no longer fail the sync. Some asset types (notably ports and IP addresses) are not exposed under the cosmos_public audience and the Bishop Fox API rejects them with a 400 public projection not supported for this asset type. The connector now detects this response and skips the affected asset type — logging a warning — instead of failing the run. IP service syncs still complete in this case, just without the port-derived host back-link. To ingest ports and IP addresses, configure an audience whose token is entitled to the private projection. - Findings pagination. The connector now retrieves every page of /v5/findings, not just the first. Previously a token-based pagination loop terminated after page 1 because the Bishop Fox v5 API is page-number-based and never returns the expected token field — so customers with more than one page (100 records) of findings or finding definitions were missing the rest of their data. Improvements - Parallel page-number pagination. Endpoints that advertise total + limit (currently /v5/findings and /v5/asset-view/networks, with others auto-detected at runtime) now fetch their pages concurrently, bounded by the Parallel requests configuration property (default: 4). For large tenants this dramatically shortens sync time — a customer with ~200,000 records that previously took hours now completes in a fraction of that, scaling with the configured parallelism. Cursor-paginated endpoints (e.g. /v5/asset-view/hostname-services) stay sequential because each page's continuation token is only known after the previous response. - Attribute consolidation precedence. All custom Bishop Fox attributes now participate in the platform's data-consolidation pipeline at the standard connector priority (50) instead of being last-in. In practical terms, when the same record receives values from multiple sources, the values reported by this connector now win ties against non-connector channels (manual UI edits, bulk imports, etc.) — matching how every other Brinqa connector already behaves.	N/A
3.0.0	Overview The BishopFox connector integrates with Bishop Fox Cosmos (External Attack Surface Management) to synchronize asset surface data — registered domains, network ranges, DNS records, subdomains, IP addresses, open ports, and discovered services — together with pentest findings and their definitions. Category: External Attack Surface Management Models	• Schema rebuild required. All ten model schemas changed: standard connectors-model AttributeInfos (UID, HOST, IP_ADDRESSES, PORT, PROTOCOL, etc.) replace the previous String-keyed attributes; OBJECT_TYPE constants stabilized; LAST_CAPTURED added everywhere. Action: re-sync all data after upgrade. • Hierarchy expanded. Three asset classes that were previously implicit are now first-class models: IpAddress, Port, and DnsRecord. Action: enable them in your sync schedule if you want the full asset graph. • UDM targets assigned. Subdomain and IpAddress map to Host; HostnameService and IpService map to ApiEndpoint; Domain to Site; Network to IpRange; Finding/FindingDefinition to PentestFinding/PentestFindingDefinition. Action: review downstream feeds that key on these UDMs. • Asset → Host references are now explicit via the HOSTS attribute on HostnameService (links to Subdomain) and IpService (links to IpAddress, resolved via Port lookup). The platform-reserved TARGETS is no longer used on assets — only on Findings. • Findings API behavior fixed. The legacy connector sent since, severity, and CSV-formatted status to /v5/findings, all of which the v5 API rejects with 400 validation failed. The new connector sends only documented parameters; status and category are emitted as repeated keys per the v5 spec.