Halo Security
External Attack Surface Management- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The Halo Security Connector integrates with the Halo Security External Attack Surface Management (EASM) platform to synchronize hosts, scans, security issues, and issue definitions. It connects to the Halo Security API to fetch discovery data, scan results, and vulnerability findings across an organization's external attack surface.
Data retrieved from Halo Security
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Host | Yes | Host |
| Scan | Yes | Assessment |
| Issue | Yes | Vulnerability |
| Issue Definition | Yes | Vulnerability Definition |
Model relationships
For detailed steps on how to view the data retrieved from Halo Security in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select Halo Security from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| API URL | Yes | https://api.halosecurity.com | Halo Security API URL |
| API key | Yes | — | Halo Security API key |
| Page size | No | 100 | Maximum number of records to get per API request |
| Parallel requests | No | 4 | Maximum number of parallel API requests |
| Max retries | No | 5 | Maximum number of retry attempts before giving up a request |
| Requests per minute | No | 300 | Maximum number of API requests per minute |
Authentication
The connector uses API key (Bearer token) authentication with the Halo Security API. Create an API key with type "Account" in the Halo Security portal and supply it as the apiKey configuration property. The connector sends the key as a bearer token on every request and validates the configuration during connection testing by requesting a single record from the host-list endpoint.
Endpoint
The connection test issues the following request:
| Method | URL |
|---|---|
GET | https://api.halosecurity.com/api/v1/discovery/host-list.json?limit=1&start=0 |
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <API_KEY> |
Content-Type | application/json |
Accept | application/json |
Sample Response
{
"list": [
{
"fqdn": "go.brinqa.com",
"connected_score_percent": 0,
"target": {
"ip": "104.16.94.80",
"name": "",
"host": "go.brinqa.com",
"id": 345367,
"scan_id": "2026010108394Fv3mTp6n134HTp8hVh1",
"tags": ["auto-add-subdomains"]
}
}
]
}
Response Fields
| Field | Type | Description |
|---|---|---|
list | Array | Page of host records |
fqdn | String | Fully qualified domain name |
connected_score_percent | Integer | Host connection score percentage |
target | Object | Target metadata for the host |
A successful response (HTTP 200) confirms the API key and base URL are valid.
Usage
Once configured, all API requests include the API key as a bearer token:
Authorization: Bearer <API_KEY>
How to obtain Halo Security credentials
Generate Halo Security API keys
- Log in to the Halo Security portal.
- Go to the Account/API section.
- Create an API key with the type "Account".
- Copy the generated API key.
Note: If you do not have permissions to create a key, contact your Halo Security administrator. For additional information, see Halo Security API Documentation.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Host
| Source Field Name | SDM Attribute |
|---|---|
HostList.connected_score_percent | CONNECTED_SCORE_PERCENT |
HostList.fqdn | UID |
HostList.fqdn | NAME |
HostList.fqdn | FQDN |
HostList.target.host | DNS_NAMES |
HostList.target.id | HOST_ID |
HostList.target.ip | IP_ADDRESSES |
HostList.target.ip | PUBLIC_IP_ADDRESSES |
HostList.target.scan_id | SCAN_ID |
HostList.target.tags | TAGS |
| — | CATEGORIES |
Scan
| Source Field Name | SDM Attribute |
|---|---|
ScanList.scan.date | SCAN_DATE |
ScanList.scan.scan_id | UID |
ScanList.scan.scan_id | NAME |
ScanList.target.host | HOST |
ScanList.target.id | TARGETS |
ScanList.target.id | TARGET_ID |
ScanList.target.tags | TAGS |
Issue
| Source Field Name | SDM Attribute |
|---|---|
IssueInstance.instance.first_found_date | FIRST_FOUND |
IssueInstance.instance.hash | HASH |
IssueInstance.instance.pci | PCI |
IssueInstance.instance.port | PORT |
IssueInstance.instance.protocol | PROTOCOL |
IssueInstance.instance.summary | NAME |
IssueInstance.instance.summary | SUMMARY |
IssueInstance.instance.target_detail | TARGET_DETAIL |
IssueInstance.instance.uri | URI |
IssueInstance.issue.issue_id | ISSUE_ID |
IssueInstance.issue.issue_id | TYPE |
IssueInstance.issue.name | ISSUE_NAME |
IssueInstance.status.status | PROVIDER_STATUS |
IssueInstance.status.target_id | TARGET_ID |
IssueInstance.target.host | TARGETS |
IssueInstance.target.scan_id | SCAN_ID |
MD5(issue.issue_id, instance.hash) | UID |
normalizeFindingStatus(status.status) | SOURCE_STATUS |
Issue Definition
| Source Field Name | SDM Attribute |
|---|---|
getFindingSeverityScore(issue.severity) | SEVERITY_SCORE |
IssueMetadata.consequence | POTENTIAL_IMPACT |
IssueMetadata.cve_ids | CVE_IDS |
IssueMetadata.cve_ids | CVE_RECORDS |
IssueMetadata.cvss_base_score | CVSS_BASE_SCORE |
IssueMetadata.date_last_modified | LAST_FOUND |
IssueMetadata.description | SUMMARY |
IssueMetadata.description | DESCRIPTION |
IssueMetadata.issue_id | UID |
IssueMetadata.name | NAME |
IssueMetadata.pci | PCI |
IssueMetadata.severity | SOURCE_SEVERITY |
IssueMetadata.solution | RECOMMENDATION |
IssueMetadata.type | ISSUE_TYPE |
normalizeFindingSeverity(issue.severity) | SEVERITY |
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).
Host
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 · Endpoint:
GET /api/v1/discovery/host-list.json
Scan
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 · Endpoint:
GET /api/v1/scan/list.json
Issue
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 · Endpoint:
GET /api/v1/issue/list.json
Issue Definition
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 · Endpoint:
GET /api/v1/issue/get.json
Changelog
The Halo Security connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.0.3 | Improvements - Updated to the latest connector platform libraries (http-connectors-parent 2.1.12, connectors-model 1.6.17) for improved stability and compatibility with the broader connector ecosystem. | N/A |
| 3.0.2 | Improvements Dependency Upgrades Upgraded internal framework and model libraries to the latest stable versions for improved reliability, security patches, and alignment with the rest of the connector platform. | N/A |
| 3.0.1 | New Features - Added a configurable Requests per minute setting that lets you cap how many API calls the connector makes to Halo Security each minute, helping you stay within your account's rate limits and avoid throttling during syncs. Improvements - Issue instance retrieval now runs in parallel, speeding up synchronization for environments with large numbers of issues. | N/A |
| 3.0.0 | Overview The Halo Security connector integrates with Halo Security to synchronize external attack surface assets, security scans, and the issues and issue definitions discovered against them. Category: External Attack Surface Management Models | N/A |