Ctrlk
BlogSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API workflows for Code Security issues

The Code Security public APIs enable programmatic access to security issues and findings generated by the scan engine. Automate issue triage, verify shift-left enforcement, build posture dashboards, and feed findings into ticketing systems, all through scan-scoped REST endpoints.

API reference: For request and response schemas, parameters, and errors, see Scan Management.

Scope: This guide covers issue and finding retrieval. For scan orchestration, see Manage scans through public APIs. For application summaries, see Manage applications via public APIs.

Base URL and authentication

Base URL: https://<your-tenant>.xdr.us.paloaltonetworks.com/public_api/appsec/v1

Replace <your-tenant> with your tenant identifier. The region-specific domain varies by deployment.

Authentication headers

Header
Value

x-xdr-auth-id

API Key ID

Authorization

API Key Secret

Generate an API key pair from Settings → Configurations → API Keys in the Cortex Cloud console. The API key role must grant read access to scan results and application resources in the ASPM module.

Available endpoints

Endpoint
Method
Returns
Granularity

/scans/periodic

GET

Periodic scan results with issue type breakdowns (issuesTypesBreakdown) and severity breakdowns

Scan-level summary

/scans/pr

GET

PR scan results with blocking policy details and issue type breakdowns (issuesTypesBreakdown)

Scan-level summary

/scans/ci

GET

CI/CD scan results with blocking status and issue type breakdowns (issuesTypesBreakdown)

Scan-level summary

/scans/{scanId}/issues

GET

Individual issue records found during the specific scan, including severity level, detection method (issue type), resolution status, and assignee

Issue-level detail

/scans/{scanId}/findings

GET

Raw scanner findings with finding category (issue type), detection method, file path, git user, suppression type, timestamps

Finding-level detail

/application/{applicationId}/issues/{issueType}/summary

GET

Issue count breakdown by severity for a specific application and issue type

Application-level count

/scans/unscanned-repositories

GET

Repositories without a recent scan

Repository-level summary

/scan/repository/{repositoryId}

POST

A rerun of a repository scan

Scan request

Issue retrieval pattern

issue-retrieval-workflow.png

Retrieve issues by scan type

All scan types follow the same two-step pattern: list scans with filters, then retrieve issues or findings by scanId.

Periodic scans

Periodic scans assess the security posture of your onboarded repositories. Use periodic scan issues for compliance reporting, posture trending, and remediation tracking.

Step 1: List periodic scans: GET /scans/periodic with filters for organization, repository, branch, scan health, and time range (days).

Step 2 — Retrieve issues: GET /scans/{scanId}/issues with optional severity filter.

Tip

Use the issuesTypesBreakdown and issuesFound fields in the scan list response to identify scans with Critical or High issues before drilling into individual records, thereby reducing API calls.

PR scans

PR scans execute when a pull request is opened or updated. PR scan results indicate whether prevention policies blocked the merge; the primary shift-left enforcement point.

Step 1 — List PR scans: GET /scans/pr with filters for organization, repository, branch, PR ID, PR status, and time range.

Step 2 — Retrieve issues from a blocked PR: Use the scanId from the PR scan result. Key response fields include pullRequestStatus, blockingPolicyName, blockingPolicyId, userEmail, and commitId.

Note

Use blockingPolicyId and blockingPolicyName to identify the policy associated with the result. Evaluate pullRequestStatus separately.

CI scans

CI scans execute during automated build pipelines. CI blocking is a second enforcement point after PR scans.

Step 1 — List CI scans: GET /scans/ci with filters for organization, repository, CI status, scan health, and time range.

Step 2 — Retrieve issues from a blocked build: Use the scanId from the CI scan result. Key response fields include ciStatus, blockingPolicyName, and blockingPolicyId.

Retrieve findings

Raw findings provide scanner-level detail not available in issue records — git author attribution, suppression status, first/last observed timestamps, and scan source identification. Use findings for false positive investigation, suppression pattern analysis, and detailed forensics.

Endpoint: GET /scans/{scanId}/findings with optional severity filter.

Key fields available in findings but not in issues: git_user, suppression_type, first_observed, last_observed, scan_source, first_hash, platform_id, and data_source.

Retrieve issues by type

The issue endpoint (/scans/{scanId}/issues) does not support server-side filtering by issue type or detection method. To retrieve issues of a specific type (for example, all IaC misconfigurations), use the issuesTypesBreakdown field to pre-filter scans, then apply client-side filtering on detection_method.

Note

The severity query parameter is the only server-side filter available on the issue endpoint. Filtering by detection method, resolution status, or assignee requires client-side processing.

Step
Action

1

List Scans: Send a GET /scans/periodic?days=7&scanHealth=COMPLETED to identify recent baseline scans.

2

Inspect Summary: Check the issuesTypesBreakdown field in the response. Skip scans where the target issue type count is zero.

3

Retrieve Issues: For scans with relevant findings, call GET /scans/{scanId}/issues to retrieve all issues from matching scans.

4

Filter Client-Side: Filter by the detection method field (such as IaC Security) to isolate specific types of scan results.

Mapping issuesTypesBreakdown keys to detection_method values

Use this mapping to match an issuesTypesBreakdown key with its detection_method value.

issuesTypesBreakdown key

(summary type)

detection_method value

(issue type)

Scanner category

Vulnerabilities

Cve Security

SCA: CVE vulnerability scanner

Secrets

Secrets Security

Secrets scanner

IaC

IaC Security

IaC misconfiguration scanner

Note

License compliance (License Security) and package operational risk (Operational Risk Security) are not represented as separate keys in issuesTypesBreakdown. To retrieve these issue types, filter client-side by detection_method from the full issue set.

All Code Security detection_method values

Value
Scanner

Cve Security

CVEs in open-source dependencies

Secrets Security

Hardcoded secrets, API keys, tokens, credentials

IaC Security

IaC misconfigurations (Terraform, CloudFormation, Kubernetes, ARM, Bicep)

Operational Risk Security

Deprecated, unmaintained, or low-adoption packages

License Security

Non-compliant open-source licenses

Application-level issue summaries

Application issue summaries provide issue counts by severity for a specific application and issue type, without iterating through individual scans. Use for executive dashboards and application-level posture monitoring.

Endpoint: GET /public_api/appsec/v1/application/{applicationId}/issues/{issueType}/summary.

Supported issue types:

Value
Category

Vulnerabilities

CVE — open-source dependency vulnerabilities

Secrets

Hardcoded secrets and credentials

Misconfigurations

IaC misconfigurations

CodeWeaknesses

Code weaknesses

Note

Application issue summaries return counts only, not individual issue records. To retrieve individual records, list periodic scans for the application's repositories, then use GET /scans/{scanId}/issues.

Common automation workflows

Automated triage

Use recent periodic scans to create tickets for Critical issues.

Step
Action

1

List completed periodic scans from the last day

2

Retrieve Critical issues for each scanId

3

Create tickets with the issue name, severity, file path, and asset name

Shift-left verification

Measure prevention by comparing blocked results with all PR and CI scan results.

Step
Action

1

List PR scans for the reporting period

2

Count results by pullRequestStatus

3

List CI scans and count results by ciStatus

4

Calculate the blocked proportion across both scan types

Posture trending

Track periodic scan results over time to identify remediation progress.

Step
Action

1

List periodic scans for the reporting period

2

Use issuesFound for summary trends

3

Retrieve issues when severity or detection-method detail is required

Coverage gap remediation

Identify repositories without recent scans, then request a repository scan.

Step
Action

1

Call GET /scans/unscanned-repositories?days=14

2

Call POST /scan/repository/{repositoryId} for each repository

3

Retrieve issues after the scan completes

Operational notes

  • Issue data is scan-scoped. Each issue belongs to a specific scan execution. Use issuesFound and issuesTypesBreakdown in scan list responses to pre-filter before retrieving individual records

  • Client-side filtering. The issue endpoint supports only severity as a server-side filter. Filter by detection method, resolution status, or assignee client-side

  • Issue lifecycle management. Resolution status updates and assignee changes are managed through the console. The APIs provide read access to current state

  • Urgency context. Urgency classification is displayed in the console. The API issue response includes severity. For Urgency-based prioritization, use the console issue tables. Refer to Urgency for more details

  • Pagination. Use limit and offset to paginate. Continue until the response returns fewer results than the requested limit

Related topics

PreviousIssue table attributes reference
NextManage Application Security scans

Last updated

Was this helpful?