# Running Scans

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

## Scan Types

A full scan consists of multiple phases, 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 |
| **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 |

## Triggering a Scan

### 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

Scans run automatically based on the `SCAN_SCHEDULE` cron expression. The default scans every 6 hours:

```
SCAN_SCHEDULE=0 0 */6 * * *
```

### Webhook-Triggered Scans

Configure GitHub or GitLab webhooks to trigger scans on push events. Set the webhook URL to:

```
http://<agent-host>:3002/webhook/github
http://<agent-host>:3002/webhook/gitlab
```

And configure the corresponding webhook secret:

```
GITHUB_WEBHOOK_SECRET=your-secret
GITLAB_WEBHOOK_SECRET=your-secret
```

## Scan Phases

Each scan progresses through these phases in order:

1. **Queued** — Scan is waiting to start
2. **Cloning** — Repository is being cloned or updated
3. **Scanning** — Static analysis and SBOM extraction are running
4. **Analyzing** — CVE cross-referencing and graph construction
5. **Reporting** — Creating tracker issues for new findings
6. **Completed** — All phases finished successfully

If any phase fails, the scan status is set to **Failed** with an error message.

## Viewing Scan History

The Overview page shows the 10 most recent scan runs across all repositories, including:

- Repository name
- Scan status
- Current phase
- Number of findings discovered
- Start time and duration

## Scan Run Statuses

| Status | Meaning |
|--------|---------|
| `queued` | Waiting to start |
| `running` | Currently executing |
| `completed` | Finished successfully |
| `failed` | Stopped due to an error |

## Deduplication

Findings are deduplicated using a fingerprint hash based on the scanner, file path, line number, and vulnerability type. Repeated scans will not create duplicate findings for the same issue.