RunZero
The RunZero connector enables automated exports of user, software, and asset inventories in JSON or CSV formats, integrating seamlessly with security workflows.
RunZero is a comprehensive network discovery and asset inventory platform that provides detailed insights into networked assets. The RunZero Turbine Connector allows users to export asset, software, and user inventories in JSON and CSV formats directly into Swimlane Turbine, facilitating enhanced security automation and asset management. By integrating with RunZero, Swimlane Turbine users can leverage detailed asset data to enrich security playbooks, streamline incident response, and maintain up-to-date asset inventories for compliance and risk management.
Limitations
Export tokens provide read-only access to the Export API only. When using an Account API token (CT prefix) for organization-scoped export endpoints, you must specify the organization by including the _oid query parameter with the organization ID.
Supported Version
The RunZero connector supports the following authentication and API usage:
- Export token (ET): Read-only access to Export API endpoints. Organization is encoded in the token; no _oid required.
- Organization token (OT): Read and write access to a single organization; can also call Export API for that organization.
- Account token (CT): Account-level access (Platform license). For Export or org-specific calls, include _oid=<organization-id> in the query parameters.
Configuration
Prerequisites
To effectively utilize the RunZero connector for Turbine, ensure you have the following:
- Bearer token authentication with these parameters:
- URL: Endpoint for the RunZero API.
- Token: A valid Export, Organization, or Account API token from RunZero.
- OAuth 2.0 client credentials with these parameters:
- URL: Endpoint for the RunZero API.
- Client ID: Your specific client identifier for OAuth 2.0.
- Client Secret: The secret key associated with your client ID for OAuth 2.0.
- Token URL: The endpoint URL to obtain the OAuth 2.0 access token.
Authentication Methods
HTTP Bearer Token Authentication
Setup Instructions:
You need a RunZero account and an API token. Export tokens are recommended for read-only export use cases. Follow the steps below:
- Log in to the RunZero console at console.runzero.com.
- For an Export token: go to Organizations, select the desired organization, then Edit organization and scroll to the Export tokens section. Generate or copy the token (ET prefix).
- For an Organization token: from the organization details page, Edit organization and use the Organization API tokens section to generate a named token (OT prefix).
- For an Account token (Platform license): go to Account settings and create an account API token (CT prefix). Use _oid=<organization-id> in query parameters when calling Export or org-specific endpoints.
All API requests must include the header: Authorization: Bearer <your_token>.
Document References:
Troubleshoot Tips
API calls are rate limited per day based on licensed assets. Response headers include X-API-Usage-Remaining, X-API-Usage-Limit, and X-API-Usage-Today. If you receive HTTP 429, wait before retrying; there is also a limit of 2,000 requests per 5 minutes per source IP.
Capabilities
- Export Assets (JSON)
- Export Software (JSON)
- Export Assets OS (CSV)
- Export Directory Users (JSON)
Export Assets (JSON)
Exports the asset inventory in JSON format. Supports optional query parameters such as search, fields, page_size, and start_key for filtering and pagination. When page_size is set, the response is an object with an assets array and next_key for pagination; otherwise the response is a JSON array of assets.
More details can be found here.
Export Software (JSON)
Exports the software inventory in JSON format. Supports optional query parameters such as search, fields, page_size, and start_key for filtering and pagination. When page_size is set, the response is an object with a software array and next_key; otherwise the response is a JSON array of software.
More details can be found here.
Export Assets OS (CSV)
Exports top asset operating systems and counts as CSV. Optional _oid query parameter specifies the organization when using an Account token.
More details can be found here.
Export Directory Users (JSON)
Exports the user (directory) inventory in JSON format. Supports optional query parameters such as _oid, search, and fields for filtering and field selection.
More details can be found here.
Configurations
HTTP Bearer Authentication
Authenticates using a Bearer token (Export, Organization, or Account API token).
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | RunZero console base URL. | string | Required |
token | API token with ET OT or CT prefix. | string | Required |
verify_ssl | Verify SSL certificate. | boolean | Optional |
http_proxy | Proxy URL to route requests through. | string | Optional |
headers | Additional headers per request. | object | Optional |
Oauth 2.0 Client Credentials
Authenticates using oauth 2.0 client credentials
Configuration Parameters
Parameter | Description | Type | Required |
|---|---|---|---|
url | A URL to the target host. | string | Required |
token_url | ο»Ώ | string | Required |
client_id | The client ID | string | Required |
client_secret | The client secret. | string | Required |
scope | Permission scopes for this action. | array | Optional |
verify_ssl | Verify SSL certificate | boolean | Optional |
http_proxy | A proxy to route requests through. | string | Optional |
Actions
Export Assets (JSON)
Exports the asset inventory from RunZero as a JSON file, providing a comprehensive overview of networked assets.
Endpoint
- URL: api/v1.0/export/org/assets.json
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters._oid | string | Optional | Current organization ID for account tokens. |
parameters.search | string | Optional | Search query in runZero search query syntax. |
parameters.fields | string | Optional | Comma-separated list of fields to export. |
parameters.page_size | integer | Optional | Number of results per request for pagination. |
parameters.start_key | string | Optional | Next page key from previous response next_key. |
Input Example
{"parameters":{"_oid":"string","search":"string","fields":"string","page_size":123,"start_key":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"reason":"OK","response_headers":{"Content-Type":"application/json"},"json_body":[{"id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","created_at":1576300370,"updated_at":1576300370,"organization_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","site_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","scanned":true,"alive":true,"first_seen":1576300370,"last_seen":1576300370,"detected_by":"icmp","type":"Server","os":"Ubuntu Linux","os_version":"18.04","hw":"Dell PowerEdge 2500","addresses":[]}]}
Export Assets OS (CSV)
Exports a CSV file listing the top asset operating systems along with their counts from RunZero.
Endpoint
- URL: api/v1.0/org/assets/os.csv
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters._oid | string | Optional | Current organization ID for account tokens. |
Input Example
{"parameters":{"_oid":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"reason":"OK","response_headers":{"Content-Type":"text/csv"},"json_body":"id,name,os\n123,Asset 1,Windows\n456,Asset 2,Linux"}
Export Software (JSON)
Exports the software inventory from RunZero as a JSON file, providing a comprehensive overview of installed applications.
Endpoint
- URL: api/v1.0/export/org/software.json
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters._oid | string | Optional | Current organization ID for account tokens. |
parameters.search | string | Optional | Search query in runZero search query syntax. |
parameters.fields | string | Optional | Comma-separated list of fields to export. |
parameters.page_size | integer | Optional | Number of results per request for pagination. |
parameters.start_key | string | Optional | Next page key from previous response next_key. |
Input Example
{"parameters":{"_oid":"string","search":"string","fields":"string","page_size":123,"start_key":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"reason":"OK","response_headers":{"Content-Type":"text/csv"},"json_body":[{"id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","software_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","software_asset_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","software_organization_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","software_source_id":1,"software_created_at":1576300370,"software_updated_at":1576300370,"software_service_address":"192.168.0.1","software_service_transport":"tcp","software_service_p...
Export Directory Users (JSON)
Exports the user inventory from RunZero as a JSON file, providing a comprehensive list of users.
Endpoint
- URL: api/v1.0/export/org/users.json
- Method: GET
Input
Argument Name | Type | Required | Description |
|---|---|---|---|
parameters._oid | string | Optional | Current organization ID for account tokens. |
parameters.search | string | Optional | Search query in runZero search query syntax. |
parameters.fields | string | Optional | Comma-separated list of fields to export. |
Input Example
{"parameters":{"_oid":"string","search":"string","fields":"string"}}
Output
Parameter | Type | Description |
|---|---|---|
status_code | number | HTTP status code of the response |
reason | string | Response reason phrase |
Output Example
{"status_code":200,"reason":"OK","response_headers":{"Content-Type":"application/json"},"json_body":[{"id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","directory_user_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","directory_user_organization_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","directory_user_site_id":"e77602e0-3fb8-4734-aef9-fbc6fdcb0fa8","directory_user_source_id":1,"directory_user_created_at":1576300370,"directory_user_updated_at":1576300370,"directory_user_user_id":"e77602e0-3fb8-4734-aef9-fb...
Response Headers
Header | Description | Example |
|---|---|---|
Content-Type | The media type of the resource | application/json |