> 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/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/branch-periodic-scan-workflow.md).

# Branch periodic scan workflow

The workflow proceeds from prevention through assurance to investigation and recovery. Configure coverage first — a scan that was never configured to run cannot be triaged.

```mermaid
flowchart TD
    A[Configure repository scan coverage] --> B[Periodic scan runs every 12 hours]
    B --> C{Scan health?}
    C -->|Completed| D[Investigate scan results by issue category]
    C -->|Partially Completed or Error| E[Triage the failed scan]
    D --> F[Route each issue to its issue inventory]
    F --> G[Remediate and verify on the next cycle]
    E --> H[Diagnose the cause in data source instance health]
    H --> I[Correct the cause, then rescan]
    I --> B
```

## Configure repository scan coverage

Scanner coverage determines what a periodic scan can detect. A scanner that is disabled produces no findings, and the absence of findings for that scanner category is indistinguishable from a clean result. Configure coverage before relying on scan results for any posture assessment.

**Prerequisites:** An active VCS integration with the repository onboarded, and permission to modify data source configuration.

1. Navigate to **Settings** → **Data Sources & Integrations**, and search for the provider.
2. Select the provider. The provider view displays all instances and the status of each instance.
3. Select an instance. The instance view displays the connected repositories, the status of each repository, and the scan coverage of each repository. Scan coverage identifies the scan engines that run against the repository, such as IaC, SCA, and Secrets.
4. Right-click the target repository and select **Scan Configuration**.
5. Configure **Active Scanners**:
   * Enable or disable the Code Security scanners (IaC, SCA, Secrets)
   * Enable **Git History Scan** to detect secrets present in past commits of the repository. Detecting exposed credentials in history allows you to address the exposure proactively, because a credential deleted from the working tree remains retrievable from history until the credential is rotated
   * Enable **Secrets Validation** to check the activity status of a detected secret through public APIs, so that triage prioritizes active, exposed secrets over inert strings. Secrets validation is available through the Cortex Cloud tenant and the IDE extensions
6. Configure **PR Scanning**:
   * **Scan PR:** Trigger security scans automatically on a pull request, identifying security risks and misconfigurations before the code merges
   * **Fail PR on scan error:** Fail the pull request automatically when a scan error occurs, preventing an unscanned change from merging on the strength of a scan that did not run
   * **Tagging Bot:** Append a unique `yor_trace` identifier to resource and module blocks when a pull request opens. The `yor_trace` identifier enables code-to-cloud tracing across the software development lifecycle, and without the identifier the deployment-dependent Urgency signals for IaC resources cannot be computed
7. **Verify the scanned branch**. The scanned branch determines which code the periodic scan evaluates, and a scan of the wrong branch produces a complete-looking result for code nobody ships. To review or change the branch selection, right-click the repository and select **Set Scanned Branches**. For the branch selection model, see [Repository as an asset](/application-security/application-security-posture-management-aspm/repository-as-an-asset.md).
8. Configure **Exclude Path** to specify the files and directories to omit from scanning:
   * **Exclude directories:** Enter folder names to exclude every file inside the folder, such as `node_modules/`, `tests/`, `dist/`
   * **Exclude files by pattern:** Use `*` for any number of characters and `?` for a single character. The pattern `*.log` excludes all log files; the pattern `*.min.js` excludes all minified JavaScript files
   * **Use a comma-separated list:** Separate multiple exclusions with commas, such as `node_modules/, dist/, docs/`
   * **Avoid leading slashes:** Enter `dist/`, not `/dist/`
9. Select **Save**.

**Result:** The updated scan configuration applies from the next scan of the repository. Enabling a scanner that was previously disabled produces a first scan that reports the accumulated backlog for that scanner category — treat the first scan after enablement as a discovery pass, not as a regression.

> **Caution:** Every path added to **Exclude Path** removes the matched files from scanning entirely. An excluded path produces no findings and no issues, and the exclusion is not visible in the scan results. Exclude build output and vendored dependencies; do not exclude application source directories to reduce finding volume.

> **Note:** For the complete scan configuration surface, see [Reference E: Scan configuration settings](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-e-scan-configuration-settings.md). For each setting's scanner category, see [Reference F: Scanner to issue category mapping](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-f-scanner-to-issue-category-mapping.md). Scan configuration is also available programmatically — see [Repository as an asset](/application-security/application-security-posture-management-aspm/repository-as-an-asset.md).

## Assess scan coverage and health across the portfolio

Establish which repositories never reported and which reported incompletely, before drawing any conclusion from the findings the scans produced. This assessment spans two pages: the **AppSec Coverage** page establishes the repositories that never reported, and the **Branch Periodic Scans** inventory assesses the repositories that did report.

**Prerequisites:** The `Application Security Periodic View` permission for the Branch Periodic Scans inventory, and access to the [AppSec Coverage](/application-security/application-security-posture-management-aspm/coverage.md) page.

> **Important:** Establish the never-scanned population from the **Last Scan Status** filter, not from the **Coverage by Status** widget. **Not Covered** on the widget counts assets with no scanner activated, which is a configuration state. **Not Scanned Yet** on the filter counts assets where no scan has executed, which is an execution state. An asset can be Fully Covered and Not Scanned Yet at the same time, so the widget value understates the population that produced no results.

1. Navigate to **Application Security** > **AppSec Coverage**.
2. Scope the asset coverage table to VCS repositories: Apply the **Asset Type** filter and select **Repository**. The Coverage page reports repositories, CI/CD pipelines, and container image repositories together, and without this filter the returned population cannot be compared to the repository rows in the scan inventory.
3. Filter the scoped table by **Last Scan Status** and select **Not Scanned Yet**. The returned repositories have scanners activated but have produced no scan result, so the repositories appear in no scan inventory row and contribute no findings. Record the count.
4. Triage the returned population before proceeding. Apply the **Business Application Names** filter to isolate the repositories belonging to business-critical applications, or select **Download** to export the population for assignment. A large population immediately after a bulk scanner activation is expected and resolves within one scan cycle — see[ Configure repository scan coverage](#configure-repository-scan-coverage) above. A population that persists across more than one cycle indicates a scan execution failure rather than a configuration gap.
5. Navigate to **Application Security** > **Scans** > **Branch Periodic Scans**, and use the filter bar to filter by repository name, organization, scanned branch, scan health status, and scan date range.
6. Filter **Scan Health** to **Error** and to **Partially** completed. The returned rows are the repositories whose reported results are incomplete and whose findings must not be treated as a full assessment.
7. Read the **Business Application Names** column to establish the business context of each returned row. Without business context the inventory ranks a revenue-critical service and an unused prototype identically. A repository that is not mapped to a business application returns an empty value in this column — treat an empty value as unknown criticality requiring mapping, not as low criticality. To map repositories to applications, see [Criteria](/application-security/application-security-posture-management-aspm/applications/defining-business-applications.md).
8. Filter **Business Application Names** to one business-critical application at a time, and address the returned failures before moving to the next application. The inventory carries application names but not application criticality, and the column supports neither sorting nor grouping because a repository can belong to several applications. Establish the criticality ordering outside this inventory first: navigate to **Application Security** → **Application Management** → **Business Applications**, sort the table by the Business Criticality column, and record the application names in descending criticality order. Return to the Branch Periodic Scans inventory and work the filtered populations in that order. The criticality tiers that qualify as business-critical are a governance decision — confirm the threshold with the AppSec Manager rather than setting the threshold at the filter.

**Result:** You hold two populations: the repositories that never reported, from step 3, and the repositories that reported incompletely, from step 6. You know which repositories in each population belong to critical applications.

**Verify the assessment is complete.** Confirm all three of the following before acting on any finding produced by a periodic scan:

* The **Asset Type** filter is set to **Repository**, so the never-scanned count covers repositories only.
* The **Last Scan Status** filter (on the Coverage page) reads **Not Scanned Yet**.
* Every repository returned in step 3 and step 6 is either assigned to an owner or recorded as an accepted gap.

A repository that appears in neither population reported a **Completed** scan. Do not count those repositories to derive coverage — the count rises when visibility degrades, for the reason given in [The inventory lists scan results, not repositories](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-branch-periodic-scan-concepts.md#inventory-results-and-repository-coverage).

> **Important:** The two populations above do not by themselves produce a coverage percentage, because neither is a denominator. To state repository scan coverage over a defined period, use the unscanned repositories endpoint described in [Public APIs for scan management](https://app.gitbook.com/o/r4DIGbR5VLvkZy3gAYsu/sites/site_gHT7E/s/ZuJbX2x7VQJhNovscCwE/aspm-cicd-and-application-security/scan-management). The endpoint returns the repositories not scanned within a specified number of days, which is a staleness measure rather than a never-scanned measure — a repository scanned once a year ago is returned, and a repository never scanned at all is also returned. Set the `days` parameter deliberately: the default of seven days reports the repositories that missed roughly the last fourteen scan cycles, not the repositories that have never been scanned.

> **Note:** For the inventory columns and underlying fields, see [Reference A: Inventory columns](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-a-inventory-columns.md).

## Investigate a scan result and route each issue category

Open a scan result to determine what the scan found and where each detection is resolved.

1. Select a scan row in the Branch Periodic Scans inventory. The side panel opens, titled with the repository name and the branch name in parentheses, such as `my-repo (main)`.
2. Review the **Overview** tab to establish the scope of the result:
   * **Organization**, **Repository**, and **Scanned Branch** identify the code context of the scan
   * **Scan Date** records when the scan started
   * **Scan Health** reports execution health, and presents a **Rescan** control when the health value is **Error** or **Partially Completed**
   * **Issues** and **Issues By Type** report the actionable records by severity and by scanner category
   * **Findings** and **Findings By Type** report the raw detections by severity and by scanner category
3. Select the issue category tab that matches the detection you are investigating — **Vulnerabilities**, **Configurations**, **Secrets**, or **Package Integrity**. Each tab opens with the **Issues** tab displayed by default. The issue categories do not correspond one-to-one with configurable scanners. See [Reference F: Scanner to issue category mapping](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-f-scanner-to-issue-category-mapping.md).
4. Select an issue in the table. The issue side card opens within the scan management context, so investigation does not require navigating to the dedicated issue page first.
5. Select the **Findings** tab to review the evidence underlying the issues — the name of the finding, the asset in which the finding was detected, and the repository hosting the asset. Select a finding to open the description of the finding, the asset type and asset group, the time of the last update, and the evidence for the finding.
6. Route the issue to the inventory that owns resolution for the issue category. See [Reference C: Issue category routing](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-c-issue-category-routing.md).

**Result:** Each detection is understood in the context of the scan that produced the detection, and each issue is routed to the surface where resolution occurs.

> **Important:** The scan side card presents issues and findings for investigation. Resolution actions — changing issue status, suppressing an issue, opening a fix pull request, and assigning ownership — are performed in the dedicated issue inventory for the issue category, not in the scan inventory. Use the scan context to understand and route; use the issue inventory to resolve.

## Triage a scan that failed or completed partially

A scan health value of **Error** or **Partially Completed** means the reported results are incomplete. Determine the coverage consequence before deciding whether to rescan.

1. Select the scan row with a health value of **Error** or **Partially Completed**.
2. Determine the coverage consequence from [Reference B: Scan health values](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-b-scan-health-values.md). For **Partially Completed**, at least one scanner did not complete, and the results for that scanner category are absent rather than empty.
3. Treat every enabled scanner on the repository as unverified for this scan. Do not attempt to identify the failed scanner from **Findings By Type**. A scanner that completed and detected nothing contributes no entry to the breakdown, and a scanner that failed contributes no entry either — the breakdown reports detections, not execution, and cannot distinguish the two cases.
4. Diagnose the underlying cause. Follow [Diagnose a scan failure through data source instance health](#diagnose-a-scan-failure-through-data-source-instance-health), which reports errors per repository with a specific error type. The error type identifies what to correct; a rescan repeats the failure when the cause is a revoked token, a missing permission, or a webhook subscription error.
5. Trigger a rescan once the cause is corrected, or immediately if the diagnosis indicates a transient failure. The **Rescan** action triggers a new scan for the same repository and branch, and is available only when the scan health is **Error** or **Partially Completed**. The **Rescan** action is not available for a scan with a health value of **Completed** or **In Progress**.
   * **From the inventory:** Right-click the periodic scan row and select **Rescan**.
   * **From the side panel:** Select the periodic scan row to open the side panel, then select **Rescan** next to the **Scan Health** property on the **Overview** tab
6. **Verify recovery**. Confirm that the scan health of the repository resolves to **Completed**. A health value of **Completed** is the only signal that every enabled scanner executed, and is therefore the only evidence that the coverage gap closed. A rescan that returns **Error** or **Partially Completed** again indicates that the underlying cause persists — return to step 4 rather than repeating the rescan.

> **Important:** Treat a **Partially Completed** result as unknown coverage for every enabled scanner on the repository, not as a clean result for any of them. A repository reporting zero secrets because the Secrets scanner failed is indistinguishable, in the scan results alone, from a repository with no secrets. Restore the scan to **Completed** before drawing any conclusion from the reported counts.

> **Caution:** A repository that returns to **Error** on every cycle silently consumes the 12-hour cadence without producing coverage. Escalate a repeatedly failing repository to the owner of the VCS integration rather than allowing the failure to persist across cycles. Identify a repeatedly failing repository with the unscanned repositories endpoint (`GET /public_api/appsec/v1/scans/unscanned-repositories`), which returns the repositories not successfully scanned within a specified number of days — a repository returned with `days` set to two or more has failed across consecutive cycles. The scan inventory presents individual scan results and does not aggregate failures across cycles, so recurring failure cannot be detected from the inventory alone. See [Public APIs for scan management](https://app.gitbook.com/o/r4DIGbR5VLvkZy3gAYsu/sites/site_gHT7E/s/ZuJbX2x7VQJhNovscCwE/aspm-cicd-and-application-security/scan-management).

> **Note:** Escalation is performed outside Cortex Cloud. The scan inventory carries no owner, assignee, or acknowledgement field, and triggering a rescan requires the **Application Security Periodic `View/Edit`** permission that a governance user may not hold. Record the handoff in the tracking system your organization uses, and verify closure by confirming that the scan health of the repository reaches **Completed** on a subsequent cycle.

## Diagnose a scan failure through data source instance health

Scan failures originate in the connection between Cortex Cloud and the version control system. The data source instance health view reports the specific cause per repository, which the scan inventory does not.

1. Navigate to **Settings** → **Data Sources & Integrations**.
2. Filter for the data source, such as GitHub (SaaS). The data source displays the number of connected instances and the status of each instance. Status values are **Connected**, **Error**, **Warning**, and **Disabled**.
3. Select the data source. A list of data source instances is displayed.
4. Select the instance, then select **Review health**. The health status page opens and displays:
   * A top card reporting the status of the instance, the connected repositories, and the instance type, such as cloud
   * A list of repositories connected to the instance, including the status, the scan coverage (the connected scanners such as SCA, Secrets, and IaC, and the scan status), the location (scanned branch, organization, repository), and the timestamp
5. Review instance-level issues. Select **Review Health** in the top bar to display the errors by repository and the errors related to the instance. Each entry reports:
   * **Classification:** **Warning** or **Error**
   * **Error Type:** **Permission**, **Clone**, **Connection**, **Webhook subscription**, or **Token**
   * **Repository:** The repository containing the issue
   * **Scope:** The scope of the issue
6. Review repository-level issues. Select a repository in the table with a status of **Error** or **Warning** to display the repository-related warnings and errors, including the description, the type, the location, and the timestamp.
7. Correct the cause identified by the **Error Type** value. See [Reference D: Instance health error types](/application-security/code-security/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/references/reference-d-instance-health-error-types.md).

**Result:** The scan failure is attributed to a specific, correctable cause. Return to Triage a scan that failed or completed partially and trigger the rescan once the cause is corrected.

> **Note:** Instance status aggregates repository status. An instance reports **Error** when more than 50 percent of the associated repositories have errors, when a token error exists for a repository, when permissions are missing at error severity, when a webhook subscription error occurs at error severity, or when at least one repository includes a warning. An instance reports **Warning** when fewer than 50 percent of the associated repositories have errors, when permissions are missing at warning severity, or when a webhook subscription error occurs at warning severity.


---

# 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/application-security-scans-management/manage-scans-through-the-tenant-ui/branch-periodic-scans/branch-periodic-scan-workflow.md?ask=<question>&goal=<endgoal>
```

`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.