Axonius — Access & Permission Requirements
This page lists everything the RegScale CLI's Axonius V2 integration (regscale axonius_v2) needs in order to run: the Axonius credentials and role permissions, the API endpoints it calls, network access, and the RegScale-side permissions.
The integration is read-only against Axonius. It never creates, modifies, or deletes anything in your Axonius tenant.
1. Axonius credentials
| Item | Where to get it | How it's used |
|---|---|---|
| Instance URL | Your Axonius tenant address, e.g. https://mycompany.axonius.com | Configured as axoniusUrl. Supply the host only — the CLI appends /api itself. |
| API Key | Axonius → My Account → API Key | Sent in the api-key request header. |
| API Secret | Displayed alongside the API key | Sent in the api-secret request header. Shown only once — capture it when you generate it. |
Axonius API keys are issued per user account and inherit that account's role permissions. There is no separate "API role."
Recommendation: create the key under a dedicated service account (for example
svc-regscale) rather than a named person's account. This keeps the integration's access independently auditable, avoids breakage when staff change, and lets you revoke the key without affecting a real user.
2. Axonius role permissions to grant
The service account's role needs View (read) access only. Grant the following:
| Axonius permission | Why it's needed | Required for |
|---|---|---|
| Devices → View devices | Retrieves device/asset records; also used by the connection check that runs before every sync | Always required |
| Vulnerabilities → View vulnerabilities | Retrieves vulnerability findings | sync_findings, sync_all, sync_saved_queries |
| Tags → View tags | Lists available tags and supports --tags filtering | list_tags, and any run using --tags |
| Saved Queries → View saved queries | Resolves saved queries by name | saved-query mode and sync_saved_queries only |
Permissions to withhold
The CLI never calls these APIs. Leaving them off limits the blast radius if the key is ever exposed:
- Adapter configuration or adapter credential management
- Starting or stopping discovery cycles
- User management
- Creating, editing, or deleting saved queries
- Creating, editing, or deleting tags
- Enforcement actions / enforcement sets
- Any Write, Edit, or Delete permission on any object
3. Axonius API endpoints called
| Endpoint | Method | Effect | Called by |
|---|---|---|---|
/api/v2/assets/devices | POST | Read — device query | sync_assets, sync_all, sync_saved_queries |
/api/v2/assets/vulnerabilities | POST | Read — vulnerability query | sync_findings, sync_all, sync_saved_queries |
/api/v2/assets/{type}/count | POST | Read — result count | count, and the pre-sync connection check |
/api/v2/tags | GET | Read — tag list | list_tags |
POSThere is still a read. Axonius accepts AQL query criteria in the request body, so retrieving assets and counts is done withPOST. These calls do not create, modify, or delete any Axonius data.
Saved-query mode does not call a separate saved-queries endpoint — it filters the assets endpoint with an AQL expression of the form ("saved_query_name" == "<your query>"). The service account must still be permitted to see that saved query for Axonius to resolve it.
Axonius fields read
The integration reads standard aggregated fields under specific_data.data.*:
- Devices:
hostname,hostname_preferred,network_interfaces.ips,network_interfaces.ips_v6,network_interfaces.mac,os.type,os.os_str,serial_number,aws_device_type,azure_device_id,gcp_project_id,tags,last_seen - Vulnerabilities:
cve_id,title,description,severity,solution,cvss_score,cvss_v2_score,plugin_id,plugin_name,associated_device_id,first_seen,last_seen
If your Axonius role uses field-level restrictions, make sure these fields are visible to the service account — otherwise assets and findings will sync with missing attributes.
4. Network access
| From | To | Protocol / Port |
|---|---|---|
| Host running the RegScale CLI | Your Axonius instance | HTTPS / TCP 443 |
Outbound HTTPS only. No inbound connection to the CLI host is required, and Axonius never initiates a connection to RegScale.
If your Axonius tenant restricts API access by source IP, allow-list the egress IP of the host (or container/cluster) running the CLI.
TLS certificates
Certificate verification is on by default and is controlled by the top-level sslVerify key shared by every RegScale CLI integration — there is no Axonius-specific switch.
For an on-premise Axonius instance using an internal certificate authority, install the issuing CA in the CLI host's trust store, or point the top-level customCaCert key at your CA bundle. Do not set sslVerify: false — that disables verification for every integration, not just Axonius.
5. RegScale-side permissions
The RegScale user account whose API token is stored in init.yaml must be able to do the following within the target Security Plan (SSP):
| Capability | Why |
|---|---|
| Read the Security Plan | The sync target is identified by SSP ID |
| Create and update Assets | Devices from Axonius become RegScale Assets |
| Create and update Vulnerabilities | Axonius vulnerability findings become RegScale Vulnerabilities |
| Create and update Issues, including closing them | Findings raise Issues; resolved findings are closed automatically |
| Create Asset ↔ Vulnerability and Asset ↔ Issue mappings | Links each finding back to the affected asset |
As with Axonius, use a dedicated RegScale service account for the integration rather than a named user's token.
6. Configuration keys
Add the following to init.yaml on the host running the CLI. These are flat, top-level keys — do not nest them under an axonius: block.
axoniusUrl: "https://mycompany.axonius.com"
axoniusApiKey: "<your-api-key>"
axoniusApiSecret: "<your-api-secret>"
axoniusTimeout: 120
axoniusPageSize: 2000
# Shared by every integration, not Axonius-specific:
sslVerify: true
| Key | Type | Default | Description |
|---|---|---|---|
axoniusUrl | string | — | Axonius instance URL. Required. (Legacy spelling axoniusHost is also accepted.) |
axoniusApiKey | string | — | Axonius API key. Required. |
axoniusApiSecret | string | — | Axonius API secret. Required. |
axoniusTimeout | integer | 120 | HTTP request timeout, in seconds |
axoniusPageSize | integer | 2000 | Records fetched per API page (maximum 2000) |
axoniusSavedQueryConfig | dict or list | — | Saved-query to SSP mappings, for saved-query mode |
axoniusStateDir | string | artifacts/axonius | Directory holding the incremental-sync state file |
sslVerify | boolean | true | Top-level, shared by all integrations. Verify TLS certificates |
customCaCert | string | — | Top-level, shared by all integrations. Path to a CA bundle for an internal certificate authority |
Credential handling
axoniusApiKeyandaxoniusApiSecretare secrets. Protectinit.yamlwith restrictive file permissions, or supply the values through your platform's secret store or environment variables rather than committing them to source control.- The CLI redacts credentials from its logs and error output.
7. Verifying access
Once the credentials and permissions are in place, confirm connectivity before running a full sync:
# 1. Confirm the key can read tags (validates URL + credentials)
regscale axonius_v2 list_tags
# 2. Confirm the account can see devices, and check how many are in scope
regscale axonius_v2 count --asset-type devices
# 3. Dry run — fetches and counts records without writing anything to RegScale
regscale axonius_v2 sync_assets --regscale_ssp_id 100 --dry-run
Common permission errors
| Symptom | Likely cause |
|---|---|
Axonius authentication failed | Wrong or revoked API key/secret, or the key belongs to a disabled account |
Cannot reach Axonius at '<url>' | Wrong axoniusUrl, firewall or egress rule blocking TCP 443, or a source-IP restriction on the tenant |
| TLS / certificate verification error | Internal CA not trusted by the CLI host — install the CA or set customCaCert |
count returns 0, or a sync produces no records | The role lacks View devices / View vulnerabilities, or a tag/saved-query filter matches nothing |
| Saved-query mode returns nothing | The role lacks View saved queries, or the query name in the config does not match Axonius exactly |
Summary checklist
- Dedicated Axonius service account created
- Role grants View on Devices, Vulnerabilities, and Tags (plus Saved Queries if using saved-query mode)
- No Write, Edit, or Delete permissions granted
- API key and secret generated and stored securely
- Outbound HTTPS (TCP 443) allowed from the CLI host to Axonius
- CLI host IP allow-listed in Axonius, if tenant restricts by IP
- Internal CA installed or
customCaCertconfigured, for on-premise instances - RegScale service account can create/update Assets, Vulnerabilities, and Issues in the target SSP
-
list_tags,count, and a--dry-runsync all succeed
Updated 4 days ago