> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/application-security/code-security/api-workflows-for-code-security-issues.md). # 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 detailed request/response schemas, field definitions, and parameter specifications, refer to [Cortex Cloud platform APIs](https://cortex-docs.paloaltonetworks.com/cortex-cloud-api/). ### Base URL and authentication **Base URL**: `https://.xdr.us.paloaltonetworks.com/public_api/appsec/v1` Replace ` with your tenant identifier. The region-specific domain varies by deployment. #### Authentication headers | Header | Valus | | --------------- | -------------- | | `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 | ### Issue retrieval pattern ![issue-retrieval-workflow.png](/files/F7PCoJhl1ryX27xs3t0X) ### 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 run every 12 hours against the default branch 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`). ````programlisting ```bash curl -X GET "https://.xdr.us.paloaltonetworks.com/public_api/appsec/v1/scans/periodic?organizationName=my-org&scanHealth=COMPLETED&days=7&limit=50" \ -H "x-xdr-auth-id: " \ -H "Authorization: " ``` ```` **Step 2 — Retrieve issues**: `GET /scans/{scanId}/issues` with optional `severity` filter. {% hint style="info" %} ### 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. {% endhint %} #### 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: `pullRequestStatus` (Blocked or Passed), `blockingPoliciesNames`, `userEmail`, `commitId`. {% hint style="info" %} ### Note When `blockingPoliciesIds` is non-empty, the PR was blocked, preventing vulnerable code from merging into the protected branch. {% endhint %} #### CI/CD scans CI/CD scans execute during automated build pipelines. I blocking is the second enforcement point after PR scans. **Step 1 — List CI/CD 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: `ciStatus` (Blocked or Passed), `blockingPoliciesNames`. ### 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. ````programlisting ```bash curl -X GET "https://.xdr.us.paloaltonetworks.com/public_api/appsec/v1/scans/scan-a1b2c3d4/findings?severity=High&limit=100" \ -H "x-xdr-auth-id: " \ -H "Authorization: " ``` ```` **Key fields available in findings but not in issues**: `git_user`, `suppression_type`, `first_observed`, `last_observed`, `scan_source`, `first_hash`, `platform_id, 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`. {% hint style="info" %} ### 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. {% endhint %} | 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** To filter the results in Step 4, use the table below to match each issues`TypesBreakdown` key with its corresponding `detection_method` value. This mapping lets you isolate the relevant scan results. |

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 | {% hint style="info" %} ### 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. {% endhint %} **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 | {% hint style="info" %} ### 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`. {% endhint %} ### 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](/application-security/application-security-posture-management-aspm/urgency.md) for more details * **Pagination.** Use `limit` and `offset` to paginate. Continue until the response returns fewer results than the requested `limit` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/application-security/code-security/api-workflows-for-code-security-issues.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.