--- agentTools: projectIndex: https://regscale.readme.io/llms.txt --- # 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` | > **`POST` here is still a read.** Axonius accepts AQL query criteria in the request body, so retrieving assets and counts is done with `POST`. 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" == "")`. 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. ```yaml axoniusUrl: "https://mycompany.axonius.com" axoniusApiKey: "" axoniusApiSecret: "" 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 * `axoniusApiKey` and `axoniusApiSecret` are **secrets**. Protect `init.yaml` with 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: ```bash # 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 ''` | 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 `customCaCert` configured, for on-premise instances * [ ] RegScale service account can create/update Assets, Vulnerabilities, and Issues in the target SSP * [ ] `list_tags`, `count`, and a `--dry-run` sync all succeed