Running a Scan

The New Scan screen (Administration → Operations → New Scan) is where you configure and launch a posture scan. This guide covers every control.

Prerequisites

Requirement	Description	Why it’s needed
scans.run permission	Your role can launch scans	The Launch button is gated by it
A connected cloud account	GCP / AWS / Azure / M365 / Workspace	Provides the scan target and credentials
Valid license	Plan covers the scan you’re running	Scanning is blocked while the license is invalid

Step-by-step

1. Choose a cloud provider

Select GCP, AWS, Azure, or All Clouds. A quick-scan template selector can pre-fill the provider and profile for common cases.

2. Select a connected account

Pick from Connected Accounts (populated from your saved connections) to auto-fill the target. If you haven’t connected the cloud yet, use Add / Connect Provider to jump to Deployments.

3. Set the scope

Use the scope tabs:

Scope	Target
Project	One or more project IDs
Folder	A folder ID (all projects beneath it)
Org	An organization ID
Custom	A free-form multi-line list (up to 20 entries)

4. Pick a profile

Profiles select which checks run. Common choices:

Profile	Use it for
mvp15	A fast 15-check baseline (good first run)
full	Comprehensive coverage
iam / networking / storage / compute / gke	Domain-focused scans
cis	CIS benchmark compliance
audit	The audit collector
red_team / blue_team	Offensive / defensive emphasis (Red Team needs Simulate mode or higher)
web_security / host_security	Web app / host-OS hardening
🔥 EVERYTHING	Everything at once — all clouds, host, Web PT, audit, and SARIF

Note

Some profiles are gated by operation mode. For example, red_team is only available once you’re in Simulate mode or higher. See Core Concepts.

5. Set options

Option	Effect
Mock Mode	Use demo data instead of calling the cloud (great for trials/demos)
SARIF Output	Also emit a SARIF report (for code-scanning pipelines)
Host Security Scan	Add OS/host hardening checks; choose an SSH method (IAP Tunnel / Direct SSH / Metadata Only)
Audit Collector	Run the audit engine alongside the scan (shown for full/EVERYTHING)
Web PT	Active HTTP penetration testing against supplied target URLs

6. Run the Pre-scan Permission Check

Click Pre-scan Permission Check (POST /preflight) to see, per service, exactly which permissions are granted or missing — with a copyable report. Fix any gaps before launching.

7. Name and launch

Enter a Client / scan name (it appears in reports), then click Launch (POST /scans). The scan starts asynchronously and appears in Scan History.

Verification

• The scan shows Completed in Scan History.
• Findings appear under Findings & Risk → Issues.
• The Dashboard updates with the new posture.

API alternative

curl -X POST "https://<your-host>/scans" \
  -H "X-API-Key: cspm_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{
    "projects": ["my-gcp-project-id"],
    "profile": "full",
    "run_audit": true,
    "sarif": true
  }'

Returns 202 Accepted with a scan_id; poll GET /scans/{scan_id}. Provider-specific launchers also exist (/scans/gcp, /scans/aws, /scans/azure, /scans/m365, /scans/workspace). The optional Idempotency-Key header prevents duplicate launches. See the API Reference.

Troubleshooting

Issue	Cause	Resolution
Launch is disabled	Missing scans.run or a required field	Check your permissions and that scope + profile are set
Preflight shows denied permissions	Connected account lacks read roles	Grant the listed roles, then re-check
Scan errors immediately	Expired credentials	Re-authenticate the account; see Troubleshooting

Next steps

• Findings & Severity
• Remediation