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
| Field | Description | Default |
|---|---|---|
| Client ID | Service account client ID (~53 chars) | — |
| Client Secret | Service account client secret (~64 chars) | — |
| Region | Wiz data-center region: us1, us2, us3, eu1, eu2, eu3, eu4 | — |
| Endpoint | Full GraphQL endpoint URL override (replaces region) | — |
| Auth Flavor | OAuth2 backend: cognito or auth0 | cognito |
| Token URL | Token endpoint override | derived from auth flavor |
| Audience | OAuth2 audience override | derived 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, audiencewiz-api - Auth0 — token endpoint
https://auth.wiz.io/oauth/token, audiencebeyond-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
- Log in to the Wiz portal as an administrator
- Navigate to Settings → Service Accounts
- Click Add Service Account and choose type Custom Integration (GraphQL API)
- Assign the API scopes your workflows require (see scope table below)
- Copy the generated Client ID and Client Secret — the secret is shown only once
- 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):
| Scope | Unlocks |
|---|---|
read:issues | issue.list, issue.get, issue.getEvidence, issue.groupedCount, issue.severityCounts |
update:issues | issue.update, issue.clearDueAt, issue.createNote, issue.deleteNote |
read:resources (Read graph resource) | cloudResource.*, graphSearch.*, vulnerabilityFinding.list, versionControlResource.list |
read:projects | project.list, project.getTeam |
read:reports | (planned for future operations) |
admin:audit_logs | (planned for future operations) |
| WizDefend scope | detection.*, threat.* |
| Forensics scope | forensics.copyToExternalAccount |
Creating a Credential in NINA
- Navigate to Credentials → Add New Credential
- Select integration service: Wiz
- Auth type: Service Account (Client Credentials)
- Fill in Client ID, Client Secret, and Region (or Endpoint)
- Leave Auth Flavor as cognito unless you know your tenant requires auth0
- 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 OPEN → IN_PROGRESS → RESOLVED or REJECTED.
| Operation | Name | Description |
|---|---|---|
list | List Issues | Paginated list of issues, filterable by severity, status, type, creation date, and related entity |
get | Get Issue | Retrieve a single issue by Wiz issue ID |
getEvidence | Get Issue Evidence | Return the issue's evidenceQuery JSON and (for threat issues) threatDetectionDetails |
update | Update Issue | Patch issue status, due date, note, or resolution reason (cannot null fields) |
clearDueAt | Clear Issue Due Date | Null out the due date using override semantics — separate from update |
createNote | Create Issue Note | Attach a comment note to an issue |
deleteNote | Delete Issue Note | Permanently delete a note by note ID |
groupedCount | Get Issues Grouped Count | Count issue groups by STATUS, SEVERITY, or TYPE |
severityCounts | Get Issue Severity Counts | Aggregate counts broken down by severity |
Key parameters for list:
filterBy.severity— array ofCRITICAL,HIGH,MEDIUM,LOW,INFORMATIONALfilterBy.status— array ofOPEN,IN_PROGRESS,RESOLVED,REJECTEDfilterBy.type— array ofTOXIC_COMBINATION,CLOUD_CONFIGURATION,THREAT_DETECTIONfilterBy.createdAt.after/filterBy.createdAt.before— ISO-8601 rangefilterBy.relatedEntity.id/filterBy.relatedEntity.type— filter by associated cloud resourcefirst(max 500),after— Relay cursor paginationorderBy.field/orderBy.direction— sort bySEVERITY,CREATED_AT,RESOLVED_AT, orSTATUS_CHANGED_AT
Key parameters for update:
issueId(required) — Wiz issue UUIDpatch.status,patch.note,patch.resolutionReason,patch.dueAt— only provided fields are changed;patchcannot 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.
| Operation | Name | Description |
|---|---|---|
list | List Cloud Resources | Paginated list, filterable by search, type, subscription, and provider-unique ID |
get | Get Cloud Resource | Retrieve a single resource by search string or providerUniqueId |
listIDs | List Cloud Resource IDs | Return only the Wiz internal id field — lightweight query for chaining |
Key parameters for list and listIDs:
filterBy.search— free-text search on resource namefilterBy.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).
| Operation | Name | Description |
|---|---|---|
list | List Vulnerability Findings | Paginated list with severity, status, exploit indicators, fix version, and the vulnerable asset |
Key parameters for list:
filterBy.severity— array of CVSS severitiesfilterBy.status— array of finding statuses (e.g.OPEN,RESOLVED)first(max 500),after— paginationorderBy.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).
| Operation | Name | Description |
|---|---|---|
list | List Version Control Resources | Paginated list of VCS resources visible to the service account |
Key parameters for list:
filterBy.search— free-text searchfirst(max 500),after— pagination
Project
Wiz projects — logical groupings of cloud resources used for security posture management, access control, and team ownership.
| Operation | Name | Description |
|---|---|---|
list | List Projects | Paginated list, filterable by name search and archived status |
getTeam | Get Project Team | Find a project by name and return owners and security champions |
Key parameters for list:
filterBy.search— match against project namefilterBy.includeArchived— boolean, defaults to falseorderBy.field/orderBy.direction— e.g.SECURITY_SCOREASC/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.
| Operation | Name | Description |
|---|---|---|
copyToExternalAccount | Copy Resource Forensics to External Account | Async 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), usecloudResource.listIDsfirst 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.
| Operation | Name | Description |
|---|---|---|
list | List Detections | Paginated list of detections with rich filter options |
get | Get Detection | Retrieve a single detection by ID |
Key parameters for list:
filterBy.id.equals— array of detection IDsfilterBy.issueId— single associated issue ID (no equals wrapper)filterBy.type.equals— array ofGENERATED_THREAT,MATCH_ONLYfilterBy.cloudPlatform.equals— array of cloud platformsfilterBy.origin.equals— array of origins (e.g.AWS_CLOUDTRAIL,WIZ_SENSOR)filterBy.severity.equals— array of severitiesfilterBy.cloudAccountOrCloudOrganizationId.equals— array of cloud account/org IDsfilterBy.resource.id.equals— array of resource IDs (nested wrapper)filterBy.matchedRule.id— single rule IDfilterBy.matchedRuleName.equals— array of rule namesfilterBy.projectId— single project IDfilterBy.createdAt.after/filterBy.createdAt.before— date rangefilterBy.createdAt.inLast.amount+filterBy.createdAt.inLast.unit— relative duration (DurationFilterValueUnitDays/Hours/Minutes)first(default 250, max 1000),after— paginationorderBy.field(CREATED_AT) /orderBy.direction(ASC/DESC)includeTriggeringEvents— boolean, defaulttrue; 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.
| Operation | Name | Description |
|---|---|---|
list | List Threats | Paginated list of threat-detection issues |
get | Get Threat | Retrieve a single threat issue by ID |
Key parameters for list:
filterBy.id— single issue IDfilterBy.severity— array of severitiesfilterBy.status— array of statusesfilterBy.cloudAccountOrCloudOrganizationId— array (no equals wrapper for threats)filterBy.eventOrigin.equals— array (equals wrapper)filterBy.relatedEntity.cloudPlatform— array, nested underrelatedEntity(this differs from the cloud-sideissue.listfilter wherecloudPlatformis top-level)filterBy.threatResource.ids— array of resource IDsfilterBy.project— single project ID (no wrapper)filterBy.createdAt.after/filterBy.createdAt.before— date rangefirst(default 250, max 500),after— paginationorderBy.field(SEVERITY/CREATED_AT) /orderBy.direction
Graph Search
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.
| Operation | Name | Description |
|---|---|---|
run | Run Graph Search | Execute a GraphEntityQueryInput against the Security Graph |
resolveResourceGraphID | Resolve Resource Graph ID | Translate a providerUniqueId (e.g. AWS ARN) into a Wiz graph entity ID |
Key parameters for run:
query—GraphEntityQueryInputobject (parsed from JSON, often sourced fromissue.getEvidence'sevidenceQueryfield)projectId(required) — project scope, or*for all projectsfirst(max 500),after— paginationfetchTotalCount— includetotalCountandmaxCountReached(defaultfalse)quick— fast query path (defaulttrue); set tofalsefor exhaustive searchesfetchPublicExposurePaths,fetchInternalExposurePaths,fetchIssueAnalytics,fetchLateralMovement,fetchKubernetes— booleans to expand the response with extra context (default allfalse)
Key parameters for resolveResourceGraphID:
query—GraphEntityQueryInputfiltering byproviderUniqueIdornameprojectId(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
- Schedule Node — run every morning
severityCounts(issue) — get per-severity totals for statusOPEN/IN_PROGRESS- Conditional Node — if
criticalSeverityCount > 0, continue list(issue) — fetch critical issues withfilterBy.severity = [CRITICAL]- Slack / Teams Node — post a digest with Wiz portal links
- Optional:
update(issue) — bulk-assign or comment
Vulnerability Sweep on a Specific Asset
listIDs(cloudResource) — translate the asset ARN to a Wiz graph entity ID- Use the resolved ID as
filterBy.relatedEntity.idin subsequent calls list(issue) — fetch issues for that resourcelist(vulnerabilityFinding) — fetch CVEs for that resource (filter viarelatedEntityif supported)- Script Node — merge the two lists into a per-asset risk report
Threat Detection Auto-Response
- Schedule Node — every 5 minutes
list(detection) —createdAt.inLast = { amount: 5, unit: Minutes },severity.equals = [CRITICAL]- Loop Node — iterate over each detection
- Conditional / Switch — route by
cloudPlatform.equalsvalue - AWS / GCP / Azure Node — execute response action (isolate VM, revoke key, etc.)
update(issue) — set the linked issue status toIN_PROGRESSwith a note
Issue → Evidence → Graph Walk
get(issue) — fetch the issuegetEvidence(issue) — pullevidenceQueryandthreatDetectionDetails- Script Node — parse
evidenceQueryJSON run(graphSearch) — execute the query withprojectId = *- Output: the graph entities affected by the issue
MSSP Multi-Tenant Project Reporting
list(project) — enumerate all non-archived projects- Loop Node — iterate over each project
severityCounts(issue) — scoped to the project (via filter)getTeam(project) — fetch owners and security champions- Email / Slack Node — send per-project security digest to the project's owner
Forensics on Demand
- Webhook / Alert Node — incoming SOC alert with an asset ARN
listIDs(cloudResource) — translate ARN to Wiz resource IDcopyToExternalAccount(forensics) — initiate the snapshot copy- Script Node — record
systemActivityGroupIdfor tracking - Notify the IR team with the activity ID and Wiz portal link
Troubleshooting
| Issue | Resolution |
|---|---|
| 401 Unauthorized on token fetch | Client ID/secret invalid — verify in Settings → Service Accounts; rotate the secret if needed |
| Token endpoint connection failure | Wrong Auth Flavor — try switching between cognito and auth0 |
extensions.code: FORBIDDEN GraphQL error | Service account lacks the required API scope — add the scope in the Wiz portal and rotate credentials |
Cannot query field X on type Y | Wiz schema drifted — open an issue; this typically means a new field was renamed or removed in a recent Wiz release |
BAD_USER_INPUT on filter | Filter 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 operation | The ID does not exist or the service account lacks scope to see it — confirm in the Wiz portal |
Threat relatedEntity.cloudPlatform filter returns nothing | Threats 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 Requests | Tenant 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 page | Ensure 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 authenticate | Set the Endpoint field explicitly to your federal endpoint (.wiz.us suffix) and the matching Token URL |
Security Considerations
- Protect Credentials: Store client ID and secret exclusively through NINA credential management — never in workflow parameters, logs, or version control
- Token Handling: Access tokens are cached in memory for the token's lifetime — they are never written to disk or logs
- Scope Minimisation: Grant only the API scopes the workflow needs. Read-only workflows should not be granted
update:issuesor forensics scopes - Forensics Data Sensitivity: Forensics snapshots contain raw cloud resource state — restrict the external account configured to receive them and audit access regularly
- Threat Detection Data: WizDefend detections may include sensitive event payloads (raw API calls, network flows) — restrict workflow and credential visibility
- Issue Notes: Notes added via
createNoteare visible to all users with read access in the Wiz portal — do not include secrets, PII, or customer data - Service Account Rotation: Rotate client secrets at least every 90 days; rotate immediately if a workflow handler or NINA host is compromised
- 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
- Wiz Documentation Portal
- Wiz API Introduction
- Using the Wiz API
- Service Accounts Settings
- Wiz GraphQL API Explorer (in-portal)
- Wiz Public GitHub — including the Cortex XSOAR pack and Backstage plugin
Updated: 2026-05-05