# Running Scans

Scans are the primary workflow in Prüfwerk. Each scan analyzes a repository for security vulnerabilities, dependency risks, and code structure.

## What Happens During a Scan

When a scan is triggered, Prüfwerk runs through these phases in order:

1. **Clone** -- pulls the latest code from the Git remote (or clones it for the first time)
2. **SAST** -- runs static analysis using Semgrep with rules covering OWASP, GDPR, OAuth, secrets, and general security patterns
3. **SBOM** -- extracts all dependencies using Syft, identifying packages, versions, licenses, and known vulnerabilities via OSV.dev + NVD
4. **CVE Check** -- cross-references dependencies against the NVD database for known CVEs
5. **Graph Build** -- parses the codebase to construct a code knowledge graph of functions, classes, and their relationships
6. **AI Triage** -- new findings are reviewed by an LLM that assesses severity, considers blast radius using the code graph, and generates remediation guidance
7. **Issue Sync** -- creates or updates issues in connected trackers (GitHub, GitLab, Gitea, Jira) for new findings

Each phase produces results that are visible in the dashboard as soon as they complete.

## How Scans Are Triggered

### Manual Scan

1. Go to **Repositories**
2. Click **Scan** on the repository you want to scan
3. The scan starts immediately in the background

### Scheduled Scans

Repositories are scanned automatically on a recurring schedule. By default, scans run every 6 hours and CVE monitoring runs daily. Your administrator controls these schedules.

### Webhook-Triggered Scans

When you configure a webhook in your Git hosting provider, scans are triggered automatically on push events. You can also get automated PR reviews. See [Webhooks & PR Reviews](/guide/webhooks) for setup instructions.

## Scan Phases and Statuses

Each scan progresses through these statuses:

| Status | Meaning |
|--------|---------|
| **Queued** | Scan is waiting to start |
| **Running** | Currently executing scan phases |
| **Completed** | All phases finished successfully |
| **Failed** | Stopped due to an error |

You can monitor scan progress on the Overview page, which shows the most recent scan runs across all repositories, including the current phase, finding count, and duration.

## Scan Types

A full scan runs multiple analysis engines, each producing different types of findings:

| Scan Type | What It Detects | Scanner |
|-----------|----------------|---------|
| **SAST** | Code-level vulnerabilities (injection, XSS, insecure crypto, etc.) | Semgrep |
| **SBOM** | Dependency inventory, outdated packages, known vulnerabilities | Syft + OSV.dev/NVD |
| **CVE** | Known CVEs in dependencies cross-referenced against NVD | NVD API |
| **GDPR** | Personal data handling issues, consent violations | Custom rules |
| **OAuth** | OAuth/OIDC misconfigurations, insecure token handling | Custom rules |
| **Secrets** | Hardcoded credentials, API keys, tokens in source code | Custom rules |
| **Code Review** | Architecture and security patterns reviewed by AI | LLM-powered |

## Deduplication and Fingerprinting

Findings are deduplicated using a fingerprint hash based on the scanner, file path, line number, and vulnerability type. This means:

- **Repeated scans** will not create duplicate findings for the same issue
- **Tracker issues** are only created once per unique finding
- **Resolved findings** that reappear in a new scan are flagged for re-review

The fingerprint is also used to match findings to existing tracker issues, preventing duplicate issues from being created in GitHub, GitLab, Gitea, or Jira.

## Interpreting Results

After a scan completes, you can explore results in several ways:

- **Findings** -- browse all discovered vulnerabilities with filters for severity, type, and status. See [Understanding Findings](/guide/findings).
- **SBOM** -- review your dependency inventory, check for vulnerable packages, and audit license compliance. See [SBOM & Licenses](/guide/sbom).
- **Overview** -- check the dashboard for a high-level summary of your security posture across all repositories.
- **Issues** -- see which findings have been pushed to your issue tracker. See [Issues & Tracking](/guide/issues).
