compliance-scanner-agent/docs/guide/scanning.md

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.