HomeGuidesChangelog
Guides

Wiz

This CLI is provided to perform batch processing and orchestration of the Wiz.io Cloud-Native Application Protection Platform (CNAPP). It is designed to perform bulk processing of Wiz data to create, update, and otherwise sync with RegScale to allow for compliance automation reporting.

The CLI currently supports the following functionalities:

  • authenticate - Authenticate with Wiz and get a JSON Web Token (JWT) for future requests to Wiz
  • add_report_evidence - downloads a Wiz report by ID and attach to Evidence
  • inventory - syncs all Wiz entities into RegScale as assets
  • issues - syncs any identified problems as issues/POAMs to RegScale
  • vulnerabilities - process vulnerabilities from Wiz
  • attach_sbom - downloads SBOM report from Wiz into your security plan
  • compliance_report - process Wiz compliance reports and create assessments in RegScale
  • sync_compliance - (deprecated) syncs compliance posture from Wiz to RegScale, use compliance_report instead

Wiz Service Account Setup

Before using the RegScale CLI with Wiz, you must create a service account in Wiz with the correct permissions. Follow these steps carefully.

Step 1: Create a Service Account in Wiz

  1. Log in to your Wiz tenant
  2. Click the user profile icon in the top right and navigate to Settings > Service Accounts (or use the search bar and enter "Service Accounts")
  3. Click Add Service Account and configure the following fields:
FieldValue
Nameregscale_cli_sa (or your preferred name)
TypeCustom Integration (GraphQL API)
DescriptionRegScale CLI integration
ProjectsLeave empty to grant access to all projects, or select up to 50 specific projects to limit access
Expiration DateOptional - set an expiration date if required by your security policy

Step 2: Configure API Scopes

Under API Scopes, enable the following permissions:

Required Global Scopes:

ScopePermission KeyDescription
Administer all admin entitiesadmin:allRequired for managing reports and configurations
Read all entitiesread:allRequired for reading issues, inventory, vulnerabilities, and compliance data

Required Report Scopes (under Reports section):

All report scopes must be enabled for compliance reporting, SBOM downloads, and evidence collection:

ScopePermission Key
Manage report settingsadmin:reports
Read reportread:reports
Update reportsupdate:reports
Create reportcreate:reports
Delete reportdelete:reports
Create and delete reportswrite:reports

Step 3: Save Credentials

After creating the service account, Wiz will display the Client ID and Client Secret. Copy these values immediately - the Client Secret will not be shown again.

Store the credentials using one of these methods:

Option A: Environment Variables (Recommended)

export WizClientID='YOUR_WIZ_CLIENT_ID'
export WizClientSecret='YOUR_WIZ_CLIENT_SECRET'

Option B: init.yaml Configuration

Add the credentials to your init.yaml file:

wizClientId: YOUR_WIZ_CLIENT_ID
wizClientSecret: YOUR_WIZ_CLIENT_SECRET

Option C: Command-Line Arguments

Pass credentials directly to each command:

regscale wiz authenticate --client_id YOUR_CLIENT_ID --client_secret YOUR_CLIENT_SECRET

Step 4: Get the Wiz API URL

  1. In Wiz, click the user profile icon in the top right and navigate to Tenant Info
  2. Copy the API Endpoint URL and set it in your init.yaml:
wizUrl: https://api.us27.app.wiz.io/graphql

Note for GovCloud customers: The default wizAuthUrl is https://auth.wiz.io/oauth/token. Government customers may need to use an alternate authentication URL. Set wizAuthUrl in your init.yaml if needed.

init.yaml Configuration

The following configuration variables are available for the Wiz integration in your init.yaml file:

VariableTypeDefaultDescription
wizUrlstringhttps://api.us27.app.wiz.io/graphqlGraphQL endpoint for your Wiz instance
wizClientIdstringWiz service account Client ID
wizClientSecretstringWiz service account Client Secret
wizAccessTokenstringAuto-populated after authentication
wizFullPullLimitHoursint8Force full pull if last pull was more than this many hours ago
wizLastInventoryPullstring2022-01-01T00:00:00ZTimestamp of last inventory pull for incremental updates
wizInventoryFilterBystring(default type list)Default JSON filter for inventory pulls
wizIssueFilterBystring{}Default JSON filter for issue pulls
wizVulnerabilitiesFilterBystring{}Default JSON filter for vulnerability pulls
useWizHardwareAssetTypesboolfalseWhether to use wizHardwareAssetTypes to classify hardware vs software assets
wizHardwareAssetTypeslistVIRTUAL_MACHINE, CONTAINER, ...Asset types from Wiz to create as hardware assets in RegScale
wizExcludesstringComma-separated list of asset names to exclude from syncing
wizReportAgeint14Maximum age in days for reusing existing Wiz reports
wizStigMapperFilestringFile path to STIG mapper rules JSON file
issues.wiz.criticalint30Days to set due date for critical severity issues
issues.wiz.highint90Days to set due date for high severity issues
issues.wiz.mediumint90Days to set due date for medium severity issues
issues.wiz.lowint365Days to set due date for low severity issues
issues.wiz.statusstringOpenDefault status for new RegScale issues

Quick Start

  1. Log into RegScale (skip if using a RegScale Service Account):
regscale login
  1. Authenticate to Wiz (credentials auto-detected from environment or init.yaml):
regscale wiz authenticate
  1. Run the desired sync command:
# Sync issues
regscale wiz issues --regscale_ssp_id=5

# Sync inventory
regscale wiz inventory --regscale_ssp_id=5

# Sync vulnerabilities
regscale wiz vulnerabilities -p "project-123" --regscale_ssp_id=5

# Sync compliance
regscale wiz compliance_report -p "project-123" --regscale_id=5

Issue Processing Workflow

The issue sync retrieves all open and in-progress issues from Wiz and creates or updates corresponding issues in RegScale:

  1. Authenticates to Wiz (auto-authenticates if credentials are configured)
  2. Retrieves all existing RegScale issues for the given security plan
  3. Creates an automated report in Wiz to pull all matching issues
  4. For each Wiz issue: updates the existing RegScale issue if found, otherwise creates a new one
  5. Closes any RegScale issues where the corresponding Wiz issue no longer exists (remediated)
# Basic usage
regscale wiz issues --regscale_ssp_id=5

# With project filter and severity filter
regscale wiz issues \
  -p "project-123" \
  --regscale_ssp_id=5 \
  --filter_by_override='{"severity": ["HIGH", "CRITICAL"]}'

Inventory Processing Workflow

The inventory sync retrieves cloud entities from Wiz and creates or updates assets in RegScale:

  1. Authenticates to Wiz
  2. Retrieves all existing assets in RegScale for the given security plan
  3. Pulls entities from Wiz using configured filters or defaults
  4. For each Wiz entity: updates the existing RegScale asset if found, otherwise creates a new one
# Basic usage
regscale wiz inventory --regscale_ssp_id=5

# With project and type filters
regscale wiz inventory \
  --wiz_project_id="project-123" \
  --regscale_ssp_id=5 \
  --filter_by_override='{"type": ["VIRTUAL_MACHINE", "DATABASE"]}'

Filter Parameters

All commands that support --filter_by_override accept a JSON string with one or more of the following parameters:

ParameterTypeDescription
projectstringSingle Wiz project ID (auto-injected from --wiz_project_id for issues/inventory)
projectIdarrayMultiple project IDs (auto-injected from --wiz_project_id for vulnerabilities)
typearrayResource type filter (e.g., ["VIRTUAL_MACHINE", "DATABASE"])
statusarrayIssue status filter (["OPEN", "IN_PROGRESS", "RESOLVED", "REJECTED"])
severityarraySeverity filter (["CRITICAL", "HIGH", "MEDIUM", "LOW"])
searchstringFree text search on resource name
subscriptionExternalIdarrayExternal subscription IDs (AWS Account, Azure Subscription, etc.)
providerUniqueIdarrayCloud provider unique identifiers
updatedAtobjectDate filter with before/after in ISO 8601 format
deletedAtobjectDate filter for deleted resources

Note: The --wiz_project_id parameter is automatically injected into your filter. You do not need to include the project ID in your --filter_by_override JSON.

init.yaml Example

domain: https://mycompany.regscale.com
maxThreads: 1000
wizClientId: your-wiz-client-id
wizClientSecret: your-wiz-client-secret
wizUrl: https://api.us27.app.wiz.io/graphql
wizAuthUrl: https://auth.wiz.io/oauth/token
wizFullPullLimitHours: 8
wizReportAge: 14
wizInventoryFilterBy: '{}'
wizIssueFilterBy: '{}'
wizVulnerabilitiesFilterBy: '{}'
useWizHardwareAssetTypes: true
wizHardwareAssetTypes:
  - VIRTUAL_MACHINE
  - VIRTUAL_MACHINE_IMAGE
  - CONTAINER
  - CONTAINER_IMAGE
  - DB_SERVER
  - SERVER_APPLICATION
  - CLIENT_APPLICATION
  - VIRTUAL_APPLIANCE
wizExcludes: Azure AD Builtin Application Service Principal, Azure Active Directory (AAD) User
wizStigMapperFile: /path/to/stig_mapper_rules.json
issues:
  wiz:
    critical: 30
    high: 90
    low: 365
    medium: 90
    status: Open

Note: The wizAccessToken and wizScope fields are auto-populated after authenticating to Wiz via the CLI.

Building a Bash Script to Execute the CLI

You can chain together RegScale CLI commands using scripts. These scripts could be in Bash, Python, PowerShell, etc. Below is an example Bash file for executing the Wiz CLI:

#!/bin/sh
# Wiz auto-authenticates on every execution of issues or inventory functions
regscale wiz issues --regscale_ssp_id=5
regscale wiz inventory --regscale_ssp_id=5
regscale wiz vulnerabilities -p "project-123" --regscale_ssp_id=5
regscale wiz compliance_report -p "project-123" --regscale_id=5

Compliance Report

Process Wiz compliance reports and create assessments in RegScale. This is the recommended command for compliance sync (replaces the deprecated sync_compliance).

regscale wiz compliance_report [OPTIONS]

Options:
  -p, --wiz_project_id TEXT              Wiz project ID [required]
  --regscale_id INTEGER                  RegScale record ID [required]
  --regscale_module TEXT                 RegScale module (default: securityplans)
  -i, --client_id TEXT                   Wiz Client ID
  -s, --client_secret TEXT               Wiz Client Secret
  -f, --report_file_path TEXT            Path to existing CSV compliance report
  --create-issues/--no-create-issues     Create issues for failed assessments (default: enabled)
  --update-control-status/--no-update-control-status  Update control status (default: enabled)
  --create-poams/--no-create-poams       Mark issues as POAMs (default: disabled)
  --reuse-existing-reports/--no-reuse-existing-reports  Reuse existing Wiz reports (default: enabled)
  --force-fresh-report/--no-force-fresh-report  Force new report creation (default: disabled)

The command can either create a new compliance report from Wiz or process an existing CSV file. By default, it reuses existing compliance reports in Wiz to prevent accumulation of duplicate reports.

# Basic compliance sync
regscale wiz compliance_report -p "project-123" --regscale_id=5

# With POAM creation and fresh report
regscale wiz compliance_report \
  -p "project-123" \
  --regscale_id=5 \
  --create-poams \
  --force-fresh-report

# Process existing CSV report file
regscale wiz compliance_report \
  -p "project-123" \
  --regscale_id=5 \
  --report_file_path=/path/to/compliance_report.csv

SBOM Management

Download and attach SBOMs from Wiz reports:

regscale wiz attach_sbom \
  --regscale_ssp_id=5 \
  --report_id YOUR_WIZ_REPORT_ID \
  --standard CycloneDX

Options:

  • --client_id, -ci - Wiz Client ID (falls back to environment variable)
  • --client_secret, -cs - Wiz Client Secret (falls back to environment variable)
  • --regscale_ssp_id - RegScale SSP ID [required]
  • --report_id, -r - Wiz Report ID [required]
  • --standard, -s - SBOM standard: CycloneDX or SPDX (default: CycloneDX)

Evidence Management

Download a Wiz report and attach it to the RegScale Evidence locker:

regscale wiz add_report_evidence \
  --evidence_id 123 \
  --report_id YOUR_WIZ_REPORT_ID \
  --report_file_name evidence_report \
  --report_file_extension csv

Filtering Guide

Filtering Methods

1. Command-Line Filter Override

The most direct way to apply filters is using the --filter_by_override parameter:

regscale wiz issues --filter_by_override='{"status": ["OPEN"], "severity": ["HIGH", "CRITICAL"]}'

2. Configuration Variables

Set default filters using Wiz-specific configuration variables in your init.yaml file.

3. Environment Variables

Use environment variables to set filter configurations.

4. Programmatic Filtering

Apply filters directly in code when using the integration classes.

Project ID Auto-Injection

Important: When you use the -p or --wiz_project_id option, the project ID is automatically injected into your filter. You do NOT need to include it in your --filter_by_override or init.yaml configuration.

CommandAuto-Injected KeyFormat
inventory"project"String
issues"project"String
vulnerabilities"projectId"Array
# You provide a simple filter (no project ID needed):
regscale wiz vulnerabilities -p "abc123" -f '{"severity": ["CRITICAL", "HIGH"]}'

# CLI automatically creates this filter for the Wiz API:
# {"severity": ["CRITICAL", "HIGH"], "projectId": ["abc123"]}

Multi-Tenant Configuration

This enables easy multi-tenant deployments. Configure a single filter in init.yaml:

# init.yaml - DO NOT include projectId, it's added automatically per run
wizVulnerabilitiesFilterBy: '{"severity": ["CRITICAL", "HIGH"]}'

Then run for different tenants/projects:

regscale wiz vulnerabilities -p "tenant-a-project" -s 123
regscale wiz vulnerabilities -p "tenant-b-project" -s 456

Issue Filtering

By default, the Wiz issue integration applies this filter:

{
  "project": "project-id",
  "status": ["OPEN", "IN_PROGRESS"]
}

Only open and in-progress issues are synchronized unless overridden.

Configuration Variable: wizIssueFilterBy

# init.yaml - project ID is auto-injected from --wiz_project_id, no need to include it
wizIssueFilterBy: '{"status": ["OPEN"], "severity": ["HIGH", "CRITICAL"]}'

Issue Filter Examples

# Filter by severity
regscale wiz issues \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"severity": ["HIGH", "CRITICAL"]}'

# Filter by status and time
regscale wiz issues \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"status": ["OPEN"], "updatedAt": {"after": "2023-06-14T14:07:06Z"}}'

# Complex filtering (project auto-injected from --wiz_project_id)
regscale wiz issues \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"status": ["OPEN", "IN_PROGRESS"], "severity": ["HIGH", "CRITICAL"], "search": "database"}'

Asset Filtering

The asset integration includes a comprehensive default filter for common resource types:

{
  "type": [
    "API_GATEWAY", "BACKUP_SERVICE", "CDN", "CICD_SERVICE",
    "CLOUD_LOG_CONFIGURATION", "CLOUD_ORGANIZATION", "CONTAINER",
    "CONTAINER_IMAGE", "CONTAINER_REGISTRY", "CONTAINER_SERVICE",
    "CONTROLLER_REVISION", "DATABASE", "DATA_WORKLOAD", "DB_SERVER",
    "DOMAIN", "EMAIL_SERVICE", "ENCRYPTION_KEY", "FILE_SYSTEM_SERVICE",
    "FIREWALL", "GATEWAY", "KUBERNETES_CLUSTER", "LOAD_BALANCER",
    "MANAGED_CERTIFICATE", "MESSAGING_SERVICE", "NAMESPACE",
    "NETWORK_INTERFACE", "PRIVATE_ENDPOINT", "PRIVATE_LINK",
    "RAW_ACCESS_POLICY", "REGISTERED_DOMAIN", "RESOURCE_GROUP",
    "SECRET", "SECRET_CONTAINER", "SERVERLESS", "SERVERLESS_PACKAGE",
    "SERVICE_ACCOUNT", "SERVICE_CONFIGURATION", "STORAGE_ACCOUNT",
    "SUBNET", "SUBSCRIPTION", "VIRTUAL_DESKTOP", "VIRTUAL_MACHINE",
    "VIRTUAL_MACHINE_IMAGE", "VIRTUAL_NETWORK", "VOLUME", "WEB_SERVICE"
  ]
}

Configuration Variable: wizInventoryFilterBy

# init.yaml - project ID is auto-injected from --wiz_project_id, no need to include it
wizInventoryFilterBy: '{"type": ["VIRTUAL_MACHINE", "DATABASE"]}'

Asset Filter Examples

# Filter by resource type
regscale wiz inventory \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"type": ["VIRTUAL_MACHINE", "DATABASE"]}'

# Filter by subscription (project auto-injected from --wiz_project_id)
regscale wiz inventory \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"subscriptionExternalId": ["sub-456"]}'

# Time-based filtering for incremental updates
regscale wiz inventory \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"updatedAt": {"after": "2023-06-14T14:07:06Z"}}'

Vulnerability Filtering

The vulnerabilities integration requires a project ID to be specified. The filter uses projectId as an array.

Configuration Variable: wizVulnerabilitiesFilterBy

# init.yaml - projectId is auto-injected from --wiz_project_id, no need to include it
wizVulnerabilitiesFilterBy: '{"severity": ["CRITICAL", "HIGH"]}'

Vulnerability Filter Examples

# Filter by severity
regscale wiz vulnerabilities \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"severity": ["CRITICAL", "HIGH"]}'

# Filter by CVE detection date
regscale wiz vulnerabilities \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"detectedAt": {"after": "2023-06-14T14:07:06Z"}}'

# Filter by exploit availability
regscale wiz vulnerabilities \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"hasExploit": true}'

Detailed Filter Parameters

Project and Subscription Filters

ParameterTypeDescriptionExample
projectstringSingle project ID"project-123"
projectIdarrayMultiple project IDs["project-123", "project-456"]
subscriptionExternalIdarraySubscription external IDs["sub-123", "sub-456"]
providerUniqueIdarrayProvider unique identifiers["provider-123"]

Status Filters

ParameterTypeDescriptionValid Values
statusarrayIssue status filter["OPEN", "IN_PROGRESS", "RESOLVED", "REJECTED"]

Severity Filters

ParameterTypeDescriptionValid Values
severityarraySeverity level filter["CRITICAL", "HIGH", "MEDIUM", "LOW"]

Resource Type Filters

ParameterTypeDescriptionExample
typearrayResource type filter["VIRTUAL_MACHINE", "DATABASE", "CONTAINER"]

Time-based Filters

ParameterTypeDescriptionExample
updatedAtobjectFilter by update time{"after": "2023-06-14T14:07:06Z"}
createdAtobjectFilter by creation time{"before": "2023-12-31T23:59:59Z"}

Search Filters

ParameterTypeDescriptionExample
searchstringText search filter"database"

Filter Usage Examples

High-Priority Security Issues Only

regscale wiz issues \
  --wiz_project_id "prod-project" \
  --regscale_ssp_id 123 \
  --filter_by_override='{"status": ["OPEN"], "severity": ["HIGH", "CRITICAL"]}'

Recent Changes in Specific Resource Types

regscale wiz inventory \
  --wiz_project_id "prod-project" \
  --regscale_ssp_id 123 \
  --filter_by_override='{"type": ["DATABASE", "STORAGE_ACCOUNT"], "updatedAt": {"after": "2023-11-01T00:00:00Z"}}'

Multi-Project Vulnerability Scan

To scan multiple projects, explicitly specify projectId in the filter override (overrides the auto-injected single project):

regscale wiz vulnerabilities \
  --wiz_project_id "prod-project" \
  --regscale_ssp_id 123 \
  --filter_by_override='{"projectId": ["proj-1", "proj-2"], "severity": ["CRITICAL"]}'

Comprehensive Security Review

The project key is auto-injected from --wiz_project_id, so you only need to specify other filters:

{
  "status": ["OPEN", "IN_PROGRESS"],
  "severity": ["HIGH", "CRITICAL"],
  "type": ["DATABASE", "API_GATEWAY", "STORAGE_ACCOUNT"],
  "updatedAt": {"after": "2023-10-01T00:00:00Z"},
  "search": "encryption"
}

Setting Default Filters

In init.yaml

# Issue filtering defaults
wizIssueFilterBy: |
  {
    "status": ["OPEN", "IN_PROGRESS"],
    "severity": ["HIGH", "CRITICAL"]
  }

# Asset filtering defaults
wizInventoryFilterBy: |
  {
    "type": ["VIRTUAL_MACHINE", "DATABASE", "STORAGE_ACCOUNT"],
    "updatedAt": {"after": "2023-01-01T00:00:00Z"}
  }

Environment Variables

export WIZ_ISSUE_FILTER_BY='{"status": ["OPEN"], "severity": ["CRITICAL"]}'
export WIZ_INVENTORY_FILTER_BY='{"type": ["DATABASE", "VIRTUAL_MACHINE"]}'

Time-based Incremental Updates

The integration supports automatic incremental updates using the wizLastInventoryPull variable:

wizLastInventoryPull: "2023-06-14T14:07:06Z"
wizFullPullLimitHours: 8  # Force full pull if last pull was more than 8 hours ago

Filtering Best Practices

  1. Start with broad filters and gradually narrow them down
  2. Use time-based filtering for large environments to reduce data volume
  3. Combine multiple filter types for precise data selection
  4. Test filters before production with a small dataset first
  5. Use specific project IDs when possible for better performance
  6. Document your filters for different environments (production, development, security audit)

Scanner Integration Base Filtering

The Wiz integration extends the base ScannerIntegration class, which provides additional filtering capabilities:

VariableDescriptionDefaultOptions
issueCreationHow issues are created"Consolidated""PerAsset", "Consolidated"
vulnerabilityCreationVulnerability handling"PoamCreation""NoIssue", "IssueCreation", "PoamCreation"
ingestClosedIssuesInclude closed issuesfalsetrue, false
regscale wiz issues \
  --wiz_project_id "project-123" \
  --regscale_ssp_id 456 \
  --filter_by_override='{"status": ["OPEN", "RESOLVED"]}' \
  --config-override='{"ingestClosedIssues": true}'

Filter Troubleshooting

  1. No results returned: Check if your filter criteria are too restrictive
  2. Too many results: Add more specific filters like severity or time ranges
  3. Authentication errors: Ensure your Wiz credentials are correctly configured
  4. Invalid filter format: Verify JSON syntax in filter strings

Enable debug logging to see applied filters:

regscale wiz issues --debug \
  --filter_by_override='{"status": ["OPEN"]}'

STIG Mapper

The STIG Mapper module automatically maps STIGs to assets based on configurable rules. To enable it, set the wizStigMapperFile variable in your init.yaml:

wizStigMapperFile: /path/to/stig_mapper_rules.json

STIG Mapper Rules Format

The rules file uses JSON with comparator-based matching against asset properties:

{
    "rules": [
        {
            "stig": "Windows 2012 Configuration STIG",
            "comparators": [
                {"comparator": "contains", "value": "Windows 2012", "property": "name"},
                {"comparator": "notin", "value": "Windows 2012 Account Access Group", "property": "name"}
            ]
        },
        {
            "stig": "Network Security STIG",
            "comparators": [
                {"comparator": "startswith", "value": "Kubernetes", "property": "name"},
                {"comparator": "endswith", "value": "Security", "property": "name"}
            ]
        }
    ]
}

Available Comparators

ComparatorDescription
equalsExact string match
containsString contains value
startswithString starts with value
endswithString ends with value
notinString does not contain value
inString is present in value
ninString is not present in value
gt, lt, gte, lte, neComparison operators

Rules can match against any asset property including name, operatingSystem, manufacturer, description, and others.

📘

NOTE: See All Scanner Integrations for information about how this updates Issues/POAMs