Skip to main content

Wiz Integration Guide

Overview

The Wiz integration connects NINA workflows to the Wiz cloud security platform (CNAPP) and WizDefend threat detection product across 9 resources and 23 operations:

Cloud Security Posture (Wiz):

  • Issue — List, retrieve, update, comment on, and aggregate Wiz security issues (toxic combinations, vulnerabilities, misconfigurations, threat detections)
  • Cloud Resource — Search and inventory cloud resources across connected accounts (VMs, buckets, databases, container images, etc.)
  • Vulnerability Finding — List vulnerability findings with CVE details, exploit indicators, and the affected workload
  • Version Control Resource — Inventory repositories from connected VCS integrations (GitHub, GitLab, Bitbucket, AzureDevOps)
  • Project — Manage Wiz projects (logical groupings of cloud resources) and inspect project ownership

Threat Detection (WizDefend):

  • Detection — List and retrieve individual threat detection signals from connected cloud accounts
  • Threat — List and retrieve threat-detection issues raised by WizDefend rules (issues of type THREAT_DETECTION)

Forensics & Graph:

  • Forensics — Copy a cloud resource snapshot to an external account for deep investigation
  • Graph Search — Execute ad-hoc Security Graph queries and resolve provider-unique IDs to Wiz graph entity IDs

Authentication uses OAuth2 client credentials (client_id + client_secret). The Wiz API is GraphQL-based; NINA exposes each operation as a discrete request and handles the GraphQL details internally. Tokens are fetched automatically and cached for the duration of their validity.


Credential Configuration

Authentication

FieldDescriptionDefault
Client IDService account client ID (~53 chars)
Client SecretService account client secret (~64 chars)
RegionWiz data-center region: us1, us2, us3, eu1, eu2, eu3, eu4
EndpointFull GraphQL endpoint URL override (replaces region)
Auth FlavorOAuth2 backend: cognito or auth0cognito
Token URLToken endpoint overridederived from auth flavor
AudienceOAuth2 audience overridederived from auth flavor

Either Region or Endpoint must be set. For most tenants, set the Region and leave Endpoint blank — NINA will derive https://api.<region>.app.wiz.io/graphql automatically.

The two auth flavors exist because Wiz operates two OAuth backends:

  • Cognito (default) — token endpoint https://auth.app.wiz.io/oauth/token, audience wiz-api
  • Auth0 — token endpoint https://auth.wiz.io/oauth/token, audience beyond-api

If your tenant predates the Cognito migration or you've been told to use Auth0 explicitly, set Auth Flavor to auth0. Otherwise leave it as default.

How to Get Your Wiz Service Account Credentials

  1. Log in to the Wiz portal as an administrator
  2. Navigate to SettingsService Accounts
  3. Click Add Service Account and choose type Custom Integration (GraphQL API)
  4. Assign the API scopes your workflows require (see scope table below)
  5. Copy the generated Client ID and Client Secret — the secret is shown only once
  6. Note the GraphQL endpoint URL on the service account detail page; use it to derive your region or paste it directly into the Endpoint field

Common API scopes (assign only what you need):

ScopeUnlocks
read:issuesissue.list, issue.get, issue.getEvidence, issue.groupedCount, issue.severityCounts
update:issuesissue.update, issue.clearDueAt, issue.createNote, issue.deleteNote
read:resources (Read graph resource)cloudResource.*, graphSearch.*, vulnerabilityFinding.list, versionControlResource.list
read:projectsproject.list, project.getTeam
read:reports(planned for future operations)
admin:audit_logs(planned for future operations)
WizDefend scopedetection.*, threat.*
Forensics scopeforensics.copyToExternalAccount

Creating a Credential in NINA

  1. Navigate to CredentialsAdd New Credential
  2. Select integration service: Wiz
  3. Auth type: Service Account (Client Credentials)
  4. Fill in Client ID, Client Secret, and Region (or Endpoint)
  5. Leave Auth Flavor as cognito unless you know your tenant requires auth0
  6. Click Test Connection then Save

Supported Resources and Operations

Issue

Wiz security issues — the core surface for cloud security posture management. Issues represent rule violations across four types: TOXIC_COMBINATION, CLOUD_CONFIGURATION, VULNERABILITY, and THREAT_DETECTION. Lifecycle status moves through OPENIN_PROGRESSRESOLVED or REJECTED.

OperationNameDescription
listList IssuesPaginated list of issues, filterable by severity, status, type, creation date, and related entity
getGet IssueRetrieve a single issue by Wiz issue ID
getEvidenceGet Issue EvidenceReturn the issue's evidenceQuery JSON and (for threat issues) threatDetectionDetails
updateUpdate IssuePatch issue status, due date, note, or resolution reason (cannot null fields)
clearDueAtClear Issue Due DateNull out the due date using override semantics — separate from update
createNoteCreate Issue NoteAttach a comment note to an issue
deleteNoteDelete Issue NotePermanently delete a note by note ID
groupedCountGet Issues Grouped CountCount issue groups by STATUS, SEVERITY, or TYPE
severityCountsGet Issue Severity CountsAggregate counts broken down by severity

Key parameters for list:

  • filterBy.severity — array of CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL
  • filterBy.status — array of OPEN, IN_PROGRESS, RESOLVED, REJECTED
  • filterBy.type — array of TOXIC_COMBINATION, CLOUD_CONFIGURATION, THREAT_DETECTION
  • filterBy.createdAt.after / filterBy.createdAt.before — ISO-8601 range
  • filterBy.relatedEntity.id / filterBy.relatedEntity.type — filter by associated cloud resource
  • first (max 500), after — Relay cursor pagination
  • orderBy.field / orderBy.direction — sort by SEVERITY, CREATED_AT, RESOLVED_AT, or STATUS_CHANGED_AT

Key parameters for update:

  • issueId (required) — Wiz issue UUID
  • patch.status, patch.note, patch.resolutionReason, patch.dueAt — only provided fields are changed; patch cannot null fields

Why clearDueAt is separate: the Wiz API uses patch semantics for partial updates and override semantics to null fields. To clear a due date you must send override: { dueAt: null }, not patch: { dueAt: null }. NINA exposes this as a dedicated operation so the right semantic is selected automatically.

getEvidence chaining: for non-threat issues, evidenceQuery is a serialised GraphEntityQueryInput JSON. Pass it (parsed) to graphSearch.run to retrieve the affected graph entities. Threat issues already include the full evidence in threatDetectionDetails.


Cloud Resource

Cloud resources discovered by Wiz across all connected accounts — virtual machines, storage buckets, databases, container images, serverless functions, and every other entity type Wiz inventories.

OperationNameDescription
listList Cloud ResourcesPaginated list, filterable by search, type, subscription, and provider-unique ID
getGet Cloud ResourceRetrieve a single resource by search string or providerUniqueId
listIDsList Cloud Resource IDsReturn only the Wiz internal id field — lightweight query for chaining

Key parameters for list and listIDs:

  • filterBy.search — free-text search on resource name
  • filterBy.type — array of resource type strings (e.g. VIRTUAL_MACHINE, STORAGE_BUCKET, CONTAINER_IMAGE)
  • filterBy.subscriptionExternalId — array of cloud account / subscription external IDs (e.g. AWS account ID, Azure subscription ID)
  • filterBy.providerUniqueId — array of provider-unique IDs (e.g. AWS ARNs)
  • first (max 500), after — pagination

When to use listIDs: operations like forensics.copyToExternalAccount require a Wiz internal resource ID. If you only have a provider-unique ID (such as an AWS ARN), call listIDs first with filterBy.providerUniqueId to translate.


Vulnerability Finding

Per-asset vulnerability findings with CVE details, exploit indicators, and the affected workload. Each finding ties a CVE to a specific cloud workload (VM, container, serverless function, or container image).

OperationNameDescription
listList Vulnerability FindingsPaginated list with severity, status, exploit indicators, fix version, and the vulnerable asset

Key parameters for list:

  • filterBy.severity — array of CVSS severities
  • filterBy.status — array of finding statuses (e.g. OPEN, RESOLVED)
  • first (max 500), after — pagination
  • orderBy.field / orderBy.direction — sort order

Each finding node includes vulnerabilityExternalId (CVE ID), CVSSSeverity, hasExploit, hasCisaKevExploit, firstDetectedAt, lastDetectedAt, fixedVersion, and a polymorphic vulnerableAsset (one of VulnerableAssetVirtualMachine, VulnerableAssetServerless, VulnerableAssetContainerImage, VulnerableAssetContainer, or VulnerableAssetBase).


Version Control Resource

Repositories and other version control resources connected to Wiz via VCS integrations (GitHub, GitLab, Bitbucket, AzureDevOps).

OperationNameDescription
listList Version Control ResourcesPaginated list of VCS resources visible to the service account

Key parameters for list:

  • filterBy.search — free-text search
  • first (max 500), after — pagination

Project

Wiz projects — logical groupings of cloud resources used for security posture management, access control, and team ownership.

OperationNameDescription
listList ProjectsPaginated list, filterable by name search and archived status
getTeamGet Project TeamFind a project by name and return owners and security champions

Key parameters for list:

  • filterBy.search — match against project name
  • filterBy.includeArchived — boolean, defaults to false
  • orderBy.field / orderBy.direction — e.g. SECURITY_SCORE ASC/DESC

Key parameters for getTeam:

  • filterBy.search (required) — project name to look up

Forensics

Cloud resource forensics — initiate a copy of a resource snapshot to an externally configured account for deep investigation.

OperationNameDescription
copyToExternalAccountCopy Resource Forensics to External AccountAsync copy; returns a systemActivityGroupId for tracking

Key parameters:

  • input.id (required) — Wiz cloud resource ID (UUID). If you only have a provider-unique ID (ARN), use cloudResource.listIDs first to translate.

The operation is asynchronous — it returns immediately with a systemActivityGroupId that can be used to monitor copy progress through the Wiz portal or other API endpoints.


Detection

WizDefend detections — individual threat signals raised by detection rules. Each detection is associated with one or more threat issues. Detections power runtime threat detection across cloud accounts.

OperationNameDescription
listList DetectionsPaginated list of detections with rich filter options
getGet DetectionRetrieve a single detection by ID

Key parameters for list:

  • filterBy.id.equals — array of detection IDs
  • filterBy.issueId — single associated issue ID (no equals wrapper)
  • filterBy.type.equals — array of GENERATED_THREAT, MATCH_ONLY
  • filterBy.cloudPlatform.equals — array of cloud platforms
  • filterBy.origin.equals — array of origins (e.g. AWS_CLOUDTRAIL, WIZ_SENSOR)
  • filterBy.severity.equals — array of severities
  • filterBy.cloudAccountOrCloudOrganizationId.equals — array of cloud account/org IDs
  • filterBy.resource.id.equals — array of resource IDs (nested wrapper)
  • filterBy.matchedRule.id — single rule ID
  • filterBy.matchedRuleName.equals — array of rule names
  • filterBy.projectId — single project ID
  • filterBy.createdAt.after / filterBy.createdAt.before — date range
  • filterBy.createdAt.inLast.amount + filterBy.createdAt.inLast.unit — relative duration (DurationFilterValueUnitDays / Hours / Minutes)
  • first (default 250, max 1000), after — pagination
  • orderBy.field (CREATED_AT) / orderBy.direction (ASC / DESC)
  • includeTriggeringEvents — boolean, default true; includes up to 10 triggering events per detection

Note on filter wrappers: the WizDefend API uses an equals wrapper on most filter fields (e.g. severity: { equals: ["HIGH"] }). NINA exposes this as nested parameters — pass values inside the .equals sub-field for any filter that documents one. Plain scalars like issueId, projectId, and matchedRule.id skip the wrapper.


Threat

WizDefend threat-detection issues — issues of type THREAT_DETECTION raised by WizDefend rules. The query automatically scopes to filterScope=ALL_ISSUE_DETECTIONS and forces type=[THREAT_DETECTION] so only threats are returned.

OperationNameDescription
listList ThreatsPaginated list of threat-detection issues
getGet ThreatRetrieve a single threat issue by ID

Key parameters for list:

  • filterBy.id — single issue ID
  • filterBy.severity — array of severities
  • filterBy.status — array of statuses
  • filterBy.cloudAccountOrCloudOrganizationId — array (no equals wrapper for threats)
  • filterBy.eventOrigin.equals — array (equals wrapper)
  • filterBy.relatedEntity.cloudPlatform — array, nested under relatedEntity (this differs from the cloud-side issue.list filter where cloudPlatform is top-level)
  • filterBy.threatResource.ids — array of resource IDs
  • filterBy.project — single project ID (no wrapper)
  • filterBy.createdAt.after / filterBy.createdAt.before — date range
  • first (default 250, max 500), after — pagination
  • orderBy.field (SEVERITY / CREATED_AT) / orderBy.direction

Wiz Security Graph search — execute ad-hoc graph entity queries to explore relationships between cloud resources, and translate provider-unique IDs to Wiz graph entity IDs.

OperationNameDescription
runRun Graph SearchExecute a GraphEntityQueryInput against the Security Graph
resolveResourceGraphIDResolve Resource Graph IDTranslate a providerUniqueId (e.g. AWS ARN) into a Wiz graph entity ID

Key parameters for run:

  • queryGraphEntityQueryInput object (parsed from JSON, often sourced from issue.getEvidence's evidenceQuery field)
  • projectId (required) — project scope, or * for all projects
  • first (max 500), after — pagination
  • fetchTotalCount — include totalCount and maxCountReached (default false)
  • quick — fast query path (default true); set to false for exhaustive searches
  • fetchPublicExposurePaths, fetchInternalExposurePaths, fetchIssueAnalytics, fetchLateralMovement, fetchKubernetes — booleans to expand the response with extra context (default all false)

Key parameters for resolveResourceGraphID:

  • queryGraphEntityQueryInput filtering by providerUniqueId or name
  • projectId (required) — project scope, or *

Examples

List High-Severity Open Issues

{
"integration_service": "wiz",
"resource": "issue",
"operation": "list",
"parameters": {
"filterBy": {
"severity": ["CRITICAL", "HIGH"],
"status": ["OPEN", "IN_PROGRESS"]
},
"first": 100,
"orderBy": {
"field": "SEVERITY",
"direction": "DESC"
}
}
}

Get a Single Issue

{
"integration_service": "wiz",
"resource": "issue",
"operation": "get",
"parameters": {
"filterBy": {
"id": "abcd1234-5678-90ab-cdef-1234567890ab"
}
}
}

Update an Issue's Status

{
"integration_service": "wiz",
"resource": "issue",
"operation": "update",
"parameters": {
"issueId": "abcd1234-5678-90ab-cdef-1234567890ab",
"patch": {
"status": "IN_PROGRESS",
"note": "Investigating with platform team"
}
}
}

Resolve an Issue with Reason

{
"integration_service": "wiz",
"resource": "issue",
"operation": "update",
"parameters": {
"issueId": "abcd1234-5678-90ab-cdef-1234567890ab",
"patch": {
"status": "RESOLVED",
"resolutionReason": "False positive — internal-only resource"
}
}
}

Clear an Issue's Due Date

{
"integration_service": "wiz",
"resource": "issue",
"operation": "clearDueAt",
"parameters": {
"issueId": "abcd1234-5678-90ab-cdef-1234567890ab"
}
}

Add a Note to an Issue

{
"integration_service": "wiz",
"resource": "issue",
"operation": "createNote",
"parameters": {
"input": {
"issueId": "abcd1234-5678-90ab-cdef-1234567890ab",
"text": "Confirmed remediation in PR #1234"
}
}
}

Get Issue Severity Counts (Dashboard)

{
"integration_service": "wiz",
"resource": "issue",
"operation": "severityCounts",
"parameters": {
"filterBy": {
"status": ["OPEN", "IN_PROGRESS"]
}
}
}

Get Issue Evidence

{
"integration_service": "wiz",
"resource": "issue",
"operation": "getEvidence",
"parameters": {
"filterBy": {
"id": "abcd1234-5678-90ab-cdef-1234567890ab"
}
}
}

Search Cloud Resources by Type

{
"integration_service": "wiz",
"resource": "cloudResource",
"operation": "list",
"parameters": {
"filterBy": {
"type": ["VIRTUAL_MACHINE"],
"subscriptionExternalId": ["123456789012"]
},
"first": 200
}
}

Resolve a Cloud Resource by ARN

{
"integration_service": "wiz",
"resource": "cloudResource",
"operation": "listIDs",
"parameters": {
"filterBy": {
"providerUniqueId": ["arn:aws:ec2:us-east-1:123456789012:instance/i-0abc1234"]
}
}
}

List Critical Vulnerability Findings with Active Exploits

{
"integration_service": "wiz",
"resource": "vulnerabilityFinding",
"operation": "list",
"parameters": {
"filterBy": {
"severity": ["CRITICAL"],
"status": ["OPEN"]
},
"first": 100,
"orderBy": {
"direction": "DESC"
}
}
}

Get Project Team

{
"integration_service": "wiz",
"resource": "project",
"operation": "getTeam",
"parameters": {
"filterBy": {
"search": "Production - EU West"
}
}
}

Trigger Forensics Copy

{
"integration_service": "wiz",
"resource": "forensics",
"operation": "copyToExternalAccount",
"parameters": {
"input": {
"id": "wiz-resource-uuid-from-listIDs"
}
}
}

List WizDefend Detections in the Last 24 Hours

{
"integration_service": "wiz",
"resource": "detection",
"operation": "list",
"parameters": {
"filterBy": {
"severity": {
"equals": ["CRITICAL", "HIGH"]
},
"createdAt": {
"inLast": {
"amount": 24,
"unit": "DurationFilterValueUnitHours"
}
}
},
"first": 250,
"orderBy": {
"field": "CREATED_AT",
"direction": "DESC"
}
}
}

List Threats Filtered by Cloud Platform

{
"integration_service": "wiz",
"resource": "threat",
"operation": "list",
"parameters": {
"filterBy": {
"severity": ["CRITICAL", "HIGH"],
"status": ["OPEN"],
"relatedEntity": {
"cloudPlatform": ["AWS"]
}
},
"first": 100
}
}

Translate ARN to Wiz Graph Entity ID

{
"integration_service": "wiz",
"resource": "graphSearch",
"operation": "resolveResourceGraphID",
"parameters": {
"projectId": "*",
"query": {
"type": ["VIRTUAL_MACHINE"],
"where": {
"providerUniqueId": {
"EQUALS": ["arn:aws:ec2:us-east-1:123456789012:instance/i-0abc1234"]
}
}
}
}
}

Common Workflow Patterns

Daily Critical Issue Triage

  1. Schedule Node — run every morning
  2. severityCounts (issue) — get per-severity totals for status OPEN/IN_PROGRESS
  3. Conditional Node — if criticalSeverityCount > 0, continue
  4. list (issue) — fetch critical issues with filterBy.severity = [CRITICAL]
  5. Slack / Teams Node — post a digest with Wiz portal links
  6. Optional: update (issue) — bulk-assign or comment

Vulnerability Sweep on a Specific Asset

  1. listIDs (cloudResource) — translate the asset ARN to a Wiz graph entity ID
  2. Use the resolved ID as filterBy.relatedEntity.id in subsequent calls
  3. list (issue) — fetch issues for that resource
  4. list (vulnerabilityFinding) — fetch CVEs for that resource (filter via relatedEntity if supported)
  5. Script Node — merge the two lists into a per-asset risk report

Threat Detection Auto-Response

  1. Schedule Node — every 5 minutes
  2. list (detection) — createdAt.inLast = { amount: 5, unit: Minutes }, severity.equals = [CRITICAL]
  3. Loop Node — iterate over each detection
  4. Conditional / Switch — route by cloudPlatform.equals value
  5. AWS / GCP / Azure Node — execute response action (isolate VM, revoke key, etc.)
  6. update (issue) — set the linked issue status to IN_PROGRESS with a note

Issue → Evidence → Graph Walk

  1. get (issue) — fetch the issue
  2. getEvidence (issue) — pull evidenceQuery and threatDetectionDetails
  3. Script Node — parse evidenceQuery JSON
  4. run (graphSearch) — execute the query with projectId = *
  5. Output: the graph entities affected by the issue

MSSP Multi-Tenant Project Reporting

  1. list (project) — enumerate all non-archived projects
  2. Loop Node — iterate over each project
  3. severityCounts (issue) — scoped to the project (via filter)
  4. getTeam (project) — fetch owners and security champions
  5. Email / Slack Node — send per-project security digest to the project's owner

Forensics on Demand

  1. Webhook / Alert Node — incoming SOC alert with an asset ARN
  2. listIDs (cloudResource) — translate ARN to Wiz resource ID
  3. copyToExternalAccount (forensics) — initiate the snapshot copy
  4. Script Node — record systemActivityGroupId for tracking
  5. Notify the IR team with the activity ID and Wiz portal link

Troubleshooting

IssueResolution
401 Unauthorized on token fetchClient ID/secret invalid — verify in Settings → Service Accounts; rotate the secret if needed
Token endpoint connection failureWrong Auth Flavor — try switching between cognito and auth0
extensions.code: FORBIDDEN GraphQL errorService account lacks the required API scope — add the scope in the Wiz portal and rotate credentials
Cannot query field X on type YWiz schema drifted — open an issue; this typically means a new field was renamed or removed in a recent Wiz release
BAD_USER_INPUT on filterFilter shape is wrong — check whether the filter expects a plain scalar, a bare list, or an { equals: [...] } wrapper (Detection filters use the wrapper extensively)
Empty nodes[] for a get operationThe ID does not exist or the service account lacks scope to see it — confirm in the Wiz portal
Threat relatedEntity.cloudPlatform filter returns nothingThreats nest cloudPlatform under relatedEntity (different from cloud-side issues where it would be top-level) — make sure the filter is nested correctly
429 Too Many RequestsTenant rate limit exceeded — Wiz typically allows ~100 req/s per tenant; reduce request rate or batch via larger first page sizes
Pagination returns the same pageEnsure you're forwarding after from pageInfo.endCursor and that hasNextPage was true
Update fails with "cannot null field"Use clearDueAt (override semantics) instead of update (patch semantics) when nulling a field
forensics.copyToExternalAccount returns "resource not found"The id must be a Wiz internal resource UUID, not a providerUniqueId — call cloudResource.listIDs first to translate
Federal tenant fails to authenticateSet the Endpoint field explicitly to your federal endpoint (.wiz.us suffix) and the matching Token URL

Security Considerations

  1. Protect Credentials: Store client ID and secret exclusively through NINA credential management — never in workflow parameters, logs, or version control
  2. Token Handling: Access tokens are cached in memory for the token's lifetime — they are never written to disk or logs
  3. Scope Minimisation: Grant only the API scopes the workflow needs. Read-only workflows should not be granted update:issues or forensics scopes
  4. Forensics Data Sensitivity: Forensics snapshots contain raw cloud resource state — restrict the external account configured to receive them and audit access regularly
  5. Threat Detection Data: WizDefend detections may include sensitive event payloads (raw API calls, network flows) — restrict workflow and credential visibility
  6. Issue Notes: Notes added via createNote are visible to all users with read access in the Wiz portal — do not include secrets, PII, or customer data
  7. Service Account Rotation: Rotate client secrets at least every 90 days; rotate immediately if a workflow handler or NINA host is compromised
  8. Multi-Region: If your tenant spans regions, use a separate service account and credential per region rather than sharing one secret across regions

Additional Resources

Updated: 2026-05-05