Overview
About the Balbix REST API
Balbix offers a REST API for programmatic access to information about Assets and their associated Vulnerabilities, Misconfigurations, and Software Inventories, Applications and related Artifacts. This API is under active development, with many new endpoints and query parameters planned to facilitate a wide range of use cases.
Current Limitations
There are a number of limitations to be aware of when using the API:
1. The API is currently read-only; it is not possible to modify assets, interact with the UI, upload data, or modify tags via the API, although these features are planned.
2. The API also pulls from a replica database, so a slight delay may occur between live data in the UI and the results retrieved from the API.
3. Although there are no hard-coded rate limits, the API only supports 4 concurrent sessions per customer; new sessions will be processed once previous requests have been handled.
4. The API is not suitable for bulk data exports, but instead for the retrieval of data regarding individual or small numbers of Assets.
Requesting API Credentials
Currently, API credentials can only be created by Balbix Engineers & Balbix Customer Success. Credentials are created per customer tenant. A future update to the UI will allow users to create and manage their own credentials. Upon request, Balbix will provide the following to you:
1. The Base URL for your API Endpoints
2. A static Username and Password for initial authentication to the Token endpoint
3. A corresponding Customer Key to be included as a parameter when accessing the Token endpoint 4. A Client API Key which uniquely identifies your specific tenant
Using the Balbix REST API
Obtaining a Session Authorization Token
All Balbix API endpoints require an Authorization Token in conjunction with the Client API Key. The Authorization Token is granted by the /apis/v1/gen_token endpoint; these tokens expire after 30 minutes.
Unset
curl --location --user 'YOUR_USERNAME:YOUR_PASSWORD'
'https://rs005tra.balbix.net/apis/v1/gen_token?key=YOUR_CUSTOMER_KEY
Retrieving Device IDs
All Assets in Balbix have a unique identifier known as a Device ID. The Device ID ensures that Assets with the same Hostname or IP Address can be uniquely identified. The /asset_list endpoint is designed to take any combination of Hostname, IP Address, and MAC Address to search for a specific Asset. Here is an example of how to combine all three searchable attributes alongside the appropriate headers:
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/asset_list' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100,
"host_name": "BTD-SRV-2016-QA",
"ip": "10.1.4.254",
"mac": "00:50:56:bc:ff:ff"
}'
Response: Response has been shortened for documentation to indicate the existence of dev_id
{
"data": [
{
"agent_type": "{\"Amazon Web Services (AWS)\"}",
"data_observers":null
"dev_id": 12345,
"device_subtype": "Excluded",
"device_tags": [],
"device_type": "Unexamined",
"device_zone": null,
"final_name": null,
"groups": null
"host_name": null,
"ip": null,
"likelihood": null
"operatingsystem": null,
"os_arch": null,
"os_name": null,
"os_vendor": null,
"os_version": null,
"serial_number": null
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1500
}
}
If the provided parameters match multiple Assets, those Assets will be returned in a list. The specific Device ID can be found in the response by searching for “dev_id” -
Unset
"dev_id": 12345,
Making API Calls with Device ID
Given a specific Device ID, Balbix offers four API endpoints which can be used to retrieve information about an Asset:
1. Asset Details
2. Vulnerabilities
3. Misconfigurations
4. Software Details
Retrieving Asset Details with Device ID
Returns all Attributes for a given Asset; does not implement pagination as only a single result is expected.
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/asset_details/DEVICE_ID' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json'
Response: Sample Response has been shortened for documentation to indicate the existence of details
{
"data": {
"agent_type": "{\"Amazon Web Services (AWS)\"}",
"created_at": null,
"data_observers": null
"dev_id": 12345,
"device_guid": null,
"device_roles": null,
"device_subtype": "Excluded",
"device_tags": [],
"device_type": "Unexamined",
"groups": [
"All Assets"
],
"host_name": null,
"impact": 0.0,
"interfaces": [],
"ip": null,
"likelihood": null
"mac": null,
"operatingsystem": null,
"os_arch": null,
"os_name": null,
"os_vendor": null,
"os_version": null,
"serial_number": null,
"site_name": null,
"smbios_version": null,
"system_manufacturer": null,
"system_model": null,
"total_physical_mem_mb": null,
"unique_identifier": null,
}
}
Retrieving Vulnerabilities with Device ID
Returns all Vulnerabilities for a given Asset. Implements pagination up to 1000 results.
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/vulns/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 1000,
}'
Response
{
"data": [
{
"id": "123f280f-3e66-5288-b53c-95dce2f9a1f3",
"attck": [
"TA0040<-->T1499",
"TA0002"
],
"balbix_device_subtype": "",
"balbix_device_type": "",
"component_instance_id": "ccfdaccc-588f-5ea7-a505-8f23bdc55920",
"component_name": "Tomcat",
"component_state": "UNPATCHED",
"component_tracking_id": null,
"component_type": "",
"component_version": "v1",
"components": null,
"consolidated_components": [],
"consolidated_vulns": [],
"cpe": "",
"created_at": null,
"cve_id": "",
"cvss_score": null,
"cvss_severity": 0.0,
"cwe_id": [],
"data_sources": null,
"description": null,
"dev_id": 1234,
"exposure_score": 78.0,
"exposure_severity": "HIGH",
"first_seen": null,
"fixes": [],
"mitre_attck_id": "",
"vuln_first_detected_at": null,
"vuln_instance_created_at": null,
"vuln_instance_details": "",
"vuln_instance_detection_method": "",
"vuln_instance_mitigated_at": null,
"vuln_instance_state": "",
"vuln_name": "CVE-2024-50379",
"vuln_published_date": null,
"vuln_tags": null,
"vuln_tracking_id": "",
"vuln_type": "CVE",
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1000
}
}
Retrieving Misconfigurations with Device ID
Returns all Misconfigurations for a given Asset. Implements pagination up to 100 results.
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/misconfig_details/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100,
}'
Response:
"data": [
{
"id": "123f280f-3e66-5288-b53c-95dce2f9a1f3",
"component_instance_id": "ccfdaccc-588f-5ea7-a505-8f23bdc55920",
"component_name": "Tomcat",
"component_state": "UNPATCHED",
"component_type": "",
"component_version": "v1",
"cve_id": "",
"cvss_score": null,
"cvss_severity": 0.0,
"cwe_id": [],
"dev_id": 1234,
"exposure_score": 78.0,
"exposure_severity": "HIGH",
"first_seen": null,
"fixes": [],
"vuln_first_detected_at": null,
"vuln_instance_state": "",
"vuln_name": "Sample custom Vuln",
"vuln_published_date": null,
"vuln_tags": null,
"vuln_tracking_id": "",
"vuln_type": "NON-CVE",
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1000
}
}
Retrieving Software Details with Device ID
Returns all Software Inventory for a given Asset, including Operating System. Implements pagination up to 100 results.
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/asset/sw_details/DEVICE_ID \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100,
}'
Response:
"data": [
{
"bomRef": "",
"category": "",
"componentInstanceId": "1234a71f-5393-5d12-803d-835ea937c5f0",
"componentState": "UNPATCHED",
"dataSources": [
"Defender"
],
"installPath": "C:\\Users\\sample\\AppData\\Local\\Programs\\Python\\Python310\\python.exe",
"installTime": null,
"name": "Python",
"product": "Python",
"type": "APPLICATION",
"vendor": "Python",
"version": "3.10.0.0",
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1000
}
}
Retrieveing Application IDs
All applications in Balbix have a unique identifier known as Application ID. The Application ID ensures that applications with the same name or alias or url can be uniquely identified. The app_list end point is designed to take any combination of appname, app_id, or app_url to search for a specific Application.
Here is an example of how to combine all three searchable attributes alongside the appropriate headers:
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/app_list' \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100,
"application_name": "Business Application",
"application_id": "BTD-1234"
"app_url": "www.testapp.com"
}'
Response:Response has been shortened for documentation to indicate the existence of app_id
{
"data": [
{
"data_observers":null
"app_id": 6815282,
"app_tags": [],
"app_type": "Unexamined",
"application_name": null
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 26954
}
}
If the provided parameters match multiple Applications, those Applications will be returned in a list. The specific App ID can be found in the response by searching for app_id
Unset
"app_id": 17092777
Making API Calls with App ID
Given a specific App ID, Balbix offers 4 API endpoints which can be used to retrieve information about an Application:
1. Application Details
2. Application Artifacts
3. Vulnerabilities
4. Application Infrastructure Assets
Retrieving Application Details with App ID
Returns all Attributes for a given Applications; does not implement pagination as only a single result is expected.
Here is an example of an application:
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/app_details/APP_ID' \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json
Response: Response has been shortened for documentation to indicate few application details
{
"name": "Sample Application",
"app_id": 1234,
"alias": "",
"application_id": "APP1234",
"application_owner": "",
"business_criticality": null,
"business_owner": "No Owner",
"data_sources": null,
"infrastructure": [
{
"dev_id": 12345
}
],
"repository_type": null,
"repository": null,
"url": "https://sample.com"
}
Retrieving Application Artifacts with App ID
Returns all Application artifacts like repositories, projects, deployments for a given Application. Implements pagination up to 100 results.
Here is an example of application related artifacts:
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/artifacts/APP_ID
\
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100,
}'
Response:Response has been shortened for documentation to indicate the existence of sample Artifacts
{
"data": [
{
"name": "Sample Artifact",
"app_id": 1234,
"tags":null,
"dataSources": [
"SAST",
"SCA"
],
"repository": null,
"repository_tyype": null,
"maxExposure": 72,
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1500
}
}
Retrieving Vulnerabilities with App ID
Returns all Vulnerabilities for a given Application. Implements pagination up to 1000 results.:
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/vulns/APP_ID \
--header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 1000,
}'
Response:Response has been shortened for documentation to indicate the existence of sample vulnerabilities
{
"data": [
{
"id": "",
"assessment_type": "SCA",
"app_id": 1234,
"component_id": "",
"component_name": null,
"component_page_name": null,
"component_page_path": null,
"component_type": "DEPENDENCY",
"component_version": "",
"created_at": "",
"cve_severity": 0,
"cvss_score": 0.0,
"cvss_severity": 0.0,
"cwe_id": [],
"cwe_ids": [],
"data_sources": null,
"first_seen": null,
"fixes": [],
"name": null,
"project_names": [],
"projects": [],
"url": [],
"vm_owner": "No Owner",
"vuln_description": "Sample vuln Description",
"vuln_details": null,
"vuln_name": "Sample vuln",
"vuln_tags": null,
"vuln_type": "cve",
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1500
}
}
Retrieving Infrastructure Asset by App ID
Returns all infrastructure assets for a given Application. Implements pagination up to 100 results.
Unset
curl --location 'https://rs005tra.balbix.net/apis/v1/bx-it/application/infra-assets/APP_ID' \ --header 'Authorization: YOUR_ACCESS_TOKEN' \
--header 'Client-API-Key: YOUR_CLIENT_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
"page_offset": 0,
"page_limit": 100
}'
Response: Response has been shortened for documentation to indicate few details about infrastructure assets
{
"data": [
{
"agent_type": "{\"Amazon Web Services (AWS)\"}",
"data_observers":null
"dev_id": 12345,
"device_subtype": "Excluded",
"device_tags": [],
"device_type": "Unexamined",
"device_zone": null,
"final_name": null,
"groups": null
"host_name": null,
"ip": null,
"likelihood": null
"operatingsystem": null,
"os_arch": null,
"os_name": null,
"os_vendor": null,
"os_version": null,
"serial_number": null
}
],
"meta": {
"filters": "",
"page_limit": 1,
"page_offset": 0,
"sort": "",
"total_count": 1500
}
}
\