Skip to content

Ad-Hoc Scans

Ad-hoc scans let you trigger a security scan on demand for any asset in your organization. Use them for one-off assessments, scanning specific branches, or investigating a suspected vulnerability.

Triggering an Ad-Hoc Scan

From the Assets Page

  1. Navigate to the Assets page from the left sidebar
  2. Locate the asset you want to scan (use the search bar to find it quickly)
  3. Click the Scan button on the asset's row
  4. The scan configuration modal opens

From the Asset Detail Page

  1. Navigate to any asset's detail page by clicking its name
  2. Click the Run Scan button in the header area
  3. The scan configuration modal opens

The Scan Configuration Modal

The scan modal collects three pieces of information before launching the scan:

Scanner Selection

Choose which scanner to run from the dropdown menu:

Scanner Type Best For
OpenGrep SAST Code vulnerability patterns across many languages
Semgrep SAST Custom rules and framework-specific checks
Trivy SCA Dependency vulnerabilities and license checks
Grype SCA CVE matching against package manifests
Gitleaks Secrets Detecting hardcoded secrets and credentials

Not Sure Which Scanner?

Start with Trivy for a quick dependency check or OpenGrep for a broad code scan. See Scanner Reference for detailed guidance on choosing the right scanner.

Rules Dropdown

After selecting a scanner, the Rules dropdown populates with available rule sets for that scanner:

For SAST scanners (OpenGrep, Semgrep):

Rule Set Description
Default The scanner's built-in rule set — a good balance of coverage and noise
OWASP Top 10 Rules targeting the OWASP Top 10 vulnerability categories
Security Audit Comprehensive rule set for thorough security reviews
Custom Organization-specific rules (if configured)

For SCA scanners (Trivy, Grype):

Rule Set Description
Default Full vulnerability database scan
Critical + High Only Only report critical and high severity CVEs

For Gitleaks:

Rule Set Description
Default Standard secret detection patterns
Extended Includes generic high-entropy string detection

Branch Field

The branch field specifies which branch of the repository to scan. It defaults to the asset's configured default branch (e.g., main).

You can override this to scan any branch:

main
develop
feature/auth-refactor
release/v2.1
hotfix/cve-2024-1234

Branch Must Exist

The branch you specify must exist in the repository. If the branch does not exist, the scan will fail with a clone error.

What Happens During a Scan

Once you click Start Scan in the modal, the following sequence occurs:

1. Scan Queued

The scan request is submitted to the scan queue. If scanner capacity is available, execution begins immediately. If all scanner slots are occupied, the scan waits in the queue (first-in-first-out).

You will see a notification:

Scan queued for org/repo-name using OpenGrep

2. Repository Cloned

The scanner service clones the repository at the specified branch into an isolated temporary directory. For private repositories (integration assets), the clone uses the GitHub App credentials. For public assets, a standard unauthenticated clone is performed.

3. Scanner Executes

The selected scanner runs against the cloned repository with the chosen rule set. During execution:

  • The scan appears in the Running Scans section of the Scan Queue page
  • A progress timer shows elapsed time
  • The scanner processes files matching its supported language extensions

4. Results Parsed

After the scanner completes, Mayo ASPM parses the raw output (typically JSON or SARIF) and normalizes each result into the unified findings format:

  • Severity is mapped to Critical / High / Medium / Low
  • File paths and line numbers are extracted
  • Rule IDs and descriptions are preserved
  • CWE and CVE identifiers are linked where applicable

5. Deduplication

Each finding is assigned a fingerprint based on:

  • Scanner type
  • Rule ID
  • File path
  • Relevant code snippet

If a finding with the same fingerprint already exists for this asset, the existing finding is updated rather than creating a duplicate. New fingerprints create new findings.

6. Scan Completed

The scan record is marked as completed with:

  • Total findings count (new + existing)
  • New findings count
  • Scan duration
  • Scanner version and rule set used

Viewing Results After Completion

From the Notification

When a scan completes, a notification appears with a link to view the results. Click it to navigate directly to the scan results.

From the Scan Queue

Navigate to Scan Queue from the sidebar. Completed scans appear in the recent history. Click a scan to view its results.

From the Asset Detail Page

Navigate to the asset and scroll to the Scan History section. The most recent scan appears at the top with:

  • Scanner name and rule set
  • Completion timestamp
  • Findings count
  • Status badge (Completed / Failed)

Click a scan to view the detailed results.

From the Findings Page

All findings from the scan are immediately available on the Findings page, filtered and searchable alongside findings from all other scans.

Scan Failures

If a scan fails, the scan record includes an error message explaining what went wrong. Common failure reasons:

Error Cause Resolution
Clone failed Branch does not exist or repository is inaccessible Verify the branch name and repository access
Scanner timeout Scan exceeded the maximum duration for your tier Try scanning with a narrower rule set or split into smaller scans
Scanner error The scanner process crashed or returned invalid output Retry the scan; if persistent, contact support
Capacity exceeded Queue depth limit reached Wait for running scans to complete, then retry

Failed Scans and Quotas

Failed scans do count toward your daily scan quota but do not consume the full duration allocation. If a scan fails quickly, the capacity is released immediately.

Best Practices

  1. Start broad, then narrow down — Run a default rule set first. If too noisy, switch to a focused rule set like "OWASP Top 10" or "Critical + High Only"

  2. Scan feature branches before merge — Use the branch field to scan feature branches that are not yet covered by PR scanning

  3. Use the right scanner for the job — Run Trivy or Grype for dependency checks, OpenGrep or Semgrep for code analysis, and Gitleaks for secrets

  4. Check the queue first — If you are running many scans, check the Scan Queue to understand current capacity before queuing more

Next Steps