Axonius

Overview

The Axonius V2 integration syncs assets (endpoints) and vulnerabilities from Axonius into RegScale using the Axonius V2 API. It features incremental delta sync to minimize API usage, saved query support for predefined filters, and tag-based filtering for targeted synchronization.

Prerequisites

RegScale CLI installed and configured (regscale init)
An Axonius V2 API key and secret (generated from Axonius Settings > API Keys)
Network access to your Axonius instance
An existing RegScale Security Plan or Component to sync into

Configuration

Add the following variables to your init.yaml file (created by regscale init):

Variable	Type	Required	Default	Description
`axoniusUrl`	string	Yes	—	Axonius instance URL
`axoniusApiKey`	string	Yes	—	V2 API key
`axoniusApiSecret`	string	Yes	—	V2 API secret
`axoniusVerifySsl`	bool	No	`true`	Verify SSL certificates
`axoniusTimeout`	int	No	`120`	Request timeout in seconds
`axoniusPageSize`	int	No	`2000`	Page size for API requests (max 2000)

Example Configuration

axoniusUrl: "https://axonius.mycompany.com"
axoniusApiKey: "your-v2-api-key"
axoniusApiSecret: "your-v2-api-secret"
axoniusVerifySsl: true
axoniusTimeout: 120
axoniusPageSize: 2000

Environment Variable Support

All configuration values can also be set via environment variables with the AXONIUS_ prefix:

export AXONIUS_HOST="https://axonius.mycompany.com"
export AXONIUS_API_KEY="your-v2-api-key"
export AXONIUS_API_SECRET="your-v2-api-secret"

Commands

Sync Assets

Sync Axonius devices into RegScale as assets.

regscale axonius_v2 sync_assets --regscale-ssp-id <ID> [OPTIONS]

Parameters:

Parameter	Required	Default	Description
`--regscale-ssp-id`	Yes	—	ID of the RegScale Security Plan
`--tags, -t`	No	—	Comma-separated Axonius tags to filter by
`--mode, -m`	No	`"hybrid"`	Sync strategy: `"hybrid"` or `"saved-query"`
`--config-file, -c`	No	—	Path to saved query YAML config file
`--offset`	No	`0`	Number of records to skip
`--limit`	No	—	Maximum number of records to process
`--dry-run`	No	`false`	Count records without syncing to RegScale

Examples:

# Sync all Axonius devices to a Security Plan
regscale axonius_v2 sync_assets --regscale-ssp-id 42

# Sync only devices with specific tags
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --tags "production,web-servers"

# Preview how many assets would be synced
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --dry-run

# Use saved query mode with config file
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --mode saved-query --config-file queries.yaml

# Paginate: skip first 1000, process next 500
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --offset 1000 --limit 500

What gets synced:

Each Axonius device is mapped to a RegScale asset with the following fields:

Axonius Field	RegScale Asset Field
Hostname	Asset Name
IP Addresses	IP Address
IPv6 Addresses	IPv6 Address
MAC Addresses	MAC Address
Serial Number	Serial Number
OS Type + Version	Operating System
AWS/Azure/GCP IDs	Cloud identifiers
Device Type	Asset Type

Asset type detection:

Condition	Asset Type
Cloud instance (AWS/Azure/GCP)	Virtual Machine (VM)
OS indicates server	Server
OS indicates workstation/desktop	Workstation
Default	Other

Sync Findings

Sync Axonius vulnerabilities into RegScale.

regscale axonius_v2 sync_findings --regscale-ssp-id <ID> [OPTIONS]

Parameters: Same as sync_assets.

Examples:

# Sync all vulnerabilities
regscale axonius_v2 sync_findings --regscale-ssp-id 42

# Sync vulnerabilities for tagged assets only
regscale axonius_v2 sync_findings --regscale-ssp-id 42 --tags "dmz,external"

# Preview vulnerability count
regscale axonius_v2 sync_findings --regscale-ssp-id 42 --dry-run

Vulnerability Mapping

Axonius Field	RegScale Field
CVE ID	CVE
Title	Title
Description	Description
Severity	Severity
CVSS v3 Score	CVSS Score
Solution	Remediation
First Seen	Date First Found
Last Seen	Date Last Found
Plugin ID	Plugin ID
Plugin Name	Plugin Name
Associated Device ID	Linked Asset

Severity Mapping

The integration uses a multi-tier severity resolution:

1. Explicit Axonius severity string (preferred):

Axonius Severity	RegScale Severity
critical	Critical
high	High
medium	Moderate
low	Low
info / informational	Not Assigned
none	Not Assigned

2. CVSS v3 score fallback (if no explicit severity):

CVSS v3 Score	RegScale Severity
9.0 - 10.0	Critical
7.0 - 8.9	High
4.0 - 6.9	Moderate
0.1 - 3.9	Low
0.0	Not Assigned

3. CVSS v2 score fallback (if no v3 score available, same thresholds apply).

Sync All

Run both asset sync and vulnerability sync in sequence with a single command.

regscale axonius_v2 sync_all --regscale-ssp-id <ID> [OPTIONS]

Parameters: Same as sync_assets.

Examples:

# Full sync: assets then vulnerabilities
regscale axonius_v2 sync_all --regscale-ssp-id 42

# Full sync with tag filtering
regscale axonius_v2 sync_all --regscale-ssp-id 42 --tags "production"

# Full dry run
regscale axonius_v2 sync_all --regscale-ssp-id 42 --dry-run

Execution order:

sync_assets — creates/updates all matching Axonius devices as RegScale assets
sync_findings — creates vulnerabilities linked to those assets

List Tags

List all available tags from your Axonius instance.

regscale axonius_v2 list_tags

Example output:

production (type=custom)
web-servers (type=custom)
pci-scope (type=custom)
aws-ec2 (type=adapter)

Use the tag names with --tags on other commands to filter results.

Count

Count matching assets in Axonius without syncing.

regscale axonius_v2 count [OPTIONS]

Parameters:

Parameter	Required	Default	Description
`--tags, -t`	No	—	Comma-separated tags to filter by
`--asset-type, -a`	No	`"devices"`	Asset type to count

Examples:

# Count all devices
regscale axonius_v2 count

# Count devices with specific tags
regscale axonius_v2 count --tags "production,pci-scope"

# Count vulnerabilities
regscale axonius_v2 count --asset-type vulnerabilities

Sync Saved Queries

Sync assets and vulnerabilities using predefined saved queries from a YAML configuration file.

regscale axonius_v2 sync_saved_queries [OPTIONS]

Parameters:

Parameter	Required	Default	Description
`--config-file, -c`	No	—	Path to saved query YAML config (reads `axoniusSavedQueryConfig` from init.yaml if omitted)
`--offset`	No	`0`	Pagination offset
`--limit`	No	—	Maximum records to process
`--dry-run`	No	`false`	Count without syncing

Examples:

# Sync using config from init.yaml
regscale axonius_v2 sync_saved_queries

# Sync using external config file
regscale axonius_v2 sync_saved_queries --config-file /path/to/queries.yaml

# Preview counts
regscale axonius_v2 sync_saved_queries --dry-run

Saved Query Configuration Format

YAML config file:

- savedQueryName: "Production Servers"
  regscaleSspId: 42
  queryDescription: "All production server assets"
  type: "devices"

- savedQueryName: "Production Vulnerabilities"
  regscaleSspId: 42
  queryDescription: "Vulnerabilities on production servers"
  type: "vulnerabilities"

- savedQueryName: "DMZ Assets"
  regscaleSspId: 100
  type: "devices"

Or configure in init.yaml:

axoniusSavedQueryConfig:
  queryName: "RegScale Default Query"
  queryDescription: "Default query for asset retrieval"
  regscaleSspId: 42
  type: "devices"

Each entry maps a saved Axonius query to a specific RegScale Security Plan, allowing you to route different query results to different plans.

Sync Strategies

The Axonius V2 integration supports two sync strategies, controlled by the --mode option.

Hybrid Delta Strategy (Default)

Mode: --mode hybrid

The hybrid delta strategy performs incremental syncs after the initial full sync:

First run: Full sync — fetches all matching records
Subsequent runs: Delta sync — fetches only records with last_seen >= previous_sync_time

This dramatically reduces API calls and data transfer for large environments.

How it works:

After each successful sync, the timestamp is persisted to ./artifacts/axonius/axonius_v2_last_sync.json
On the next run, only records modified since that timestamp are fetched
State is tracked per Security Plan ID, so different plans can have independent sync schedules

State file example:

{
  "42": "2026-03-26T14:30:00.123456+00:00",
  "100": "2026-03-25T09:15:00.654321+00:00"
}

Saved Query Strategy

Mode: --mode saved-query

Uses predefined Axonius saved queries for precise control over which assets and vulnerabilities are synced. Always performs a full fetch (no incremental state tracking).

Best for:

Environments with complex filtering requirements
Multi-plan setups where different queries route to different Security Plans
Scenarios where Axonius admins maintain query definitions

Tag-Based Filtering

Filter synced data by Axonius tags using the --tags option. Tags are combined into an AQL (Axonius Query Language) filter:

# Single tag
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --tags "production"

# Multiple tags (OR logic - matches any tag)
regscale axonius_v2 sync_assets --regscale-ssp-id 42 --tags "production,staging,development"

Generated AQL filter:

("specific_data.data.tags" in ["production", "staging", "development"])

When combined with incremental sync, both the tag filter and date filter are applied:

("specific_data.data.tags" in ["production"]) AND ("specific_data.data.last_seen" >= date("2026-03-25T14:30:00+00:00"))

Architecture

┌──────────────────────────────┐
│  regscale axonius_v2 <cmd>   │
└──────────────┬───────────────┘
               │
               v
┌──────────────────────────────┐
│   AxoniusV2ScannerIntegration│
│   (ScannerIntegration)       │
└──────────────┬───────────────┘
               │
       ┌───────┴───────┐
       v               v
┌─────────────┐  ┌──────────────┐
│   Hybrid    │  │  Saved Query │
│   Delta     │  │  Strategy    │
│  Strategy   │  │              │
└──────┬──────┘  └──────┬───────┘
       │                │
       v                v
┌──────────────────────────────┐
│      Axonius SDK Client      │
│  (httpx + tenacity retry)    │
└──────────────┬───────────────┘
               │
               v
┌──────────────────────────────┐
│     Axonius V2 API           │
│  - Assets (devices)          │
│  - Vulnerabilities           │
│  - Tags                      │
│  - Saved Queries             │
└──────────────────────────────┘
               │
               v
┌──────────────────────────────┐
│       Data Mappers           │
│  - Asset Mapper              │
│  - Finding Mapper            │
└──────────────┬───────────────┘
               │
               v
┌──────────────────────────────┐
│       RegScale API           │
│  - Assets                    │
│  - Vulnerabilities           │
│  - Issues                    │
└──────────────────────────────┘

Troubleshooting

Issue	Cause	Solution
`AuthenticationError` on sync	Invalid API key or secret	Verify `axoniusApiKey` and `axoniusApiSecret` in init.yaml
`ConnectionError` on sync	Cannot reach Axonius host	Check `axoniusUrl` and network connectivity
SSL certificate errors	Self-signed or internal certificates	Set `axoniusVerifySsl: false` (not recommended for production)
No assets returned	Tags filter too restrictive	Run `list_tags` to verify tag names, or remove `--tags`
Saved query not found	Query name mismatch	Verify the saved query exists in Axonius with the exact name
Rate limit errors (429)	Too many requests	The SDK retries automatically with exponential backoff
Timeout on large environments	Default timeout too low	Increase `axoniusTimeout` to `300` or higher
Stale incremental data	State file out of sync	Delete `./artifacts/axonius/axonius_v2_last_sync.json` to force full sync
Placeholder credential error	Config still has default values	Replace `YOUR_AXONIUS_V2_API_KEY` with actual credentials

Quick Start

# 1. Configure your Axonius credentials
regscale init
# Edit init.yaml with your Axonius URL, API key, and API secret

# 2. Verify connectivity by counting assets
regscale axonius_v2 count

# 3. List available tags (optional)
regscale axonius_v2 list_tags

# 4. Preview what will be synced
regscale axonius_v2 sync_all --regscale-ssp-id 42 --dry-run

# 5. Run the full sync
regscale axonius_v2 sync_all --regscale-ssp-id 42

# 6. Subsequent runs will only sync changes (incremental)
regscale axonius_v2 sync_all --regscale-ssp-id 42