Sharang Parnerkar
7e12d1433a
Co-authored-by: Sharang Parnerkar <parnerkarsharang@gmail.com> Reviewed-on: #4
84 lines
2.5 KiB
Markdown
84 lines
2.5 KiB
Markdown
# 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.
|