Skip to content

PR Scanning

PR scanning brings security checks directly into your development workflow. When a pull request is opened or updated, Mayo ASPM automatically scans the changes and posts findings as comments and check runs on the PR — giving developers immediate feedback before code reaches the default branch.

What PR Scanning Does

When PR scanning is enabled for a repository and a developer opens (or pushes to) a pull request:

  1. GitHub sends a webhook to Mayo ASPM via the GitHub App
  2. Mayo ASPM clones the PR branch and runs the configured scanners
  3. Results are analyzed against your alert and block severity thresholds
  4. A comment is posted on the PR with a formatted findings table
  5. A check run is reported as pass or fail based on your block configuration

The entire flow completes in minutes, giving developers actionable security feedback without leaving their pull request.

How It Works: The Webhook Flow

Developer pushes to PR
        │
        ▼
GitHub sends webhook ──────▶ webhooks.mayoaspm.com
                                    │
                                    ▼
                            Validates webhook signature
                                    │
                                    ▼
                            Queues scan job ──────▶ scanner.mayoaspm.com
                                                          │
                                                          ▼
                                                   Clones PR branch
                                                          │
                                                          ▼
                                                   Runs configured scanners
                                                          │
                                                          ▼
                                                   Parses findings
                                                          │
                                                          ▼
                            Posts comment + check run ◀───┘
                                    │
                                    ▼
                            Developer sees results on PR

Webhook Security

All webhook payloads are cryptographically verified using the GitHub App's webhook secret. Invalid signatures are rejected immediately.

Alert vs. Block Behavior

PR scanning supports two distinct response behaviors based on finding severity:

Alert Severities

Findings at alert severity levels are reported in the PR comment but do not cause the check run to fail. The PR can still be merged.

  • Developers see the findings and can address them proactively
  • No merge is blocked
  • Informational — helps build security awareness

Block Severities

Findings at block severity levels cause the check run to fail. If your repository requires the Mayo ASPM check to pass before merging (via GitHub branch protection rules), these findings effectively block the PR.

  • The check run status is set to "failure"
  • The PR comment highlights blocked findings
  • Developers must fix the blocking findings (or have an admin override) to merge

Example Configuration

Severity Behavior
Critical Block
High Block
Medium Alert
Low Alert

This configuration blocks PRs that introduce critical or high severity findings while informing developers about medium and low findings without blocking their workflow.

Simple Mode vs. OPA Advanced Mode

Mayo ASPM offers two modes for configuring PR scanning behavior:

Simple Mode (Default)

In simple mode, you configure PR scanning using the straightforward UI controls:

  • Select which severities to alert on
  • Select which severities to block on
  • Choose which scanners to run
  • Configure per repository or in bulk

Simple mode is ideal for teams that want clear, severity-based rules without complexity.

OPA Advanced Mode

For teams that need more sophisticated logic, OPA (Open Policy Agent) advanced mode lets you write Rego policies that control PR scanning behavior:

  • Block based on specific rule IDs, not just severity
  • Allow exceptions for known patterns or specific file paths
  • Implement custom logic (e.g., block secrets in production directories but alert in test directories)
  • Combine multiple conditions for nuanced decision-making
# Example: Block critical/high findings except in test files
package mayo.pr_scan

block {
    input.finding.severity in ["critical", "high"]
    not startswith(input.finding.file_path, "test/")
    not startswith(input.finding.file_path, "__tests__/")
}

Start Simple

We recommend starting with simple mode and graduating to OPA advanced mode only when you need conditional logic that severity-based rules cannot express. Most teams find simple mode sufficient.

See OPA Policies for details on writing and managing Rego policies.

Requirements

PR scanning requires:

Requirement Why
GitHub App installed The app must be installed on the repository's organization to receive webhook events
Integration asset The repository must be an integration asset (not a public asset)
PR scanning enabled PR scanning must be toggled on for the specific repository
Branch protection (optional) To enforce blocking, configure GitHub branch protection to require the Mayo ASPM check

Public Assets

PR scanning is not available for public assets (manually added repositories). The GitHub App must have webhook access to detect pull request events. See Adding Public Repos for details on this limitation.

What Gets Scanned

When a PR scan runs, it scans the full PR branch — not just the diff. This means:

  • Existing vulnerabilities in unchanged files are detected
  • New vulnerabilities introduced in the PR are detected
  • The finding report covers the complete security posture of the branch

Why Full Branch?

Scanning only the diff would miss vulnerabilities that span multiple files or that exist in unchanged code that interacts with the changed code. Full-branch scanning provides a complete picture.

Next Steps