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

Running Scans

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

What Happens During a Scan

When a scan is triggered, Certifai 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 Grype
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 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 + Grype
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.
• SBOM -- review your dependency inventory, check for vulnerable packages, and audit license compliance. See SBOM & Licenses.
• 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.