docs: rewrite user docs, fix modal scroll, webhook URL, and sccache
Some checks failed
CI / Clippy (push) Failing after 2m49s
CI / Security Audit (push) Has been skipped
CI / Tests (push) Has been skipped
CI / Detect Changes (push) Has been skipped
CI / Format (pull_request) Successful in 3s
CI / Clippy (pull_request) Failing after 2m52s
CI / Security Audit (pull_request) Has been skipped
CI / Tests (pull_request) Has been skipped
CI / Format (push) Successful in 3s
CI / Deploy Agent (push) Has been skipped
CI / Deploy Dashboard (push) Has been skipped
CI / Deploy Docs (push) Has been skipped
CI / Deploy MCP (push) Has been skipped
CI / Detect Changes (pull_request) Has been skipped
CI / Deploy Agent (pull_request) Has been skipped
CI / Deploy Dashboard (pull_request) Has been skipped
CI / Deploy Docs (pull_request) Has been skipped
CI / Deploy MCP (pull_request) Has been skipped
Some checks failed
CI / Clippy (push) Failing after 2m49s
CI / Security Audit (push) Has been skipped
CI / Tests (push) Has been skipped
CI / Detect Changes (push) Has been skipped
CI / Format (pull_request) Successful in 3s
CI / Clippy (pull_request) Failing after 2m52s
CI / Security Audit (pull_request) Has been skipped
CI / Tests (pull_request) Has been skipped
CI / Format (push) Successful in 3s
CI / Deploy Agent (push) Has been skipped
CI / Deploy Dashboard (push) Has been skipped
CI / Deploy Docs (push) Has been skipped
CI / Deploy MCP (push) Has been skipped
CI / Detect Changes (pull_request) Has been skipped
CI / Deploy Agent (pull_request) Has been skipped
CI / Deploy Dashboard (pull_request) Has been skipped
CI / Deploy Docs (pull_request) Has been skipped
CI / Deploy MCP (pull_request) Has been skipped
Rewrite all public documentation to be user-facing only: - Remove deployment, configuration, and self-hosting sections - Add guide pages for SBOM, issues, webhooks & PR reviews - Add reference pages for glossary and tools/scanners - Add 12 screenshots from live dashboard - Explain MCP, LLM triage, false positives, human-in-the-loop Fix edit repository modal not scrollable (max-height + overflow-y). Show full webhook URL using window.location.origin instead of path. Unset RUSTC_WRAPPER in agent cargo commands to avoid sccache errors. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -1,20 +1,22 @@
|
||||
# Running Scans
|
||||
|
||||
Scans are the primary workflow in Compliance Scanner. Each scan analyzes a repository for security vulnerabilities, dependency risks, and code structure.
|
||||
Scans are the primary workflow in Certifai. Each scan analyzes a repository for security vulnerabilities, dependency risks, and code structure.
|
||||
|
||||
## Scan Types
|
||||
## What Happens During a Scan
|
||||
|
||||
A full scan consists of multiple phases, each producing different types of findings:
|
||||
When a scan is triggered, Certifai runs through these phases in order:
|
||||
|
||||
| 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 |
|
||||
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
|
||||
|
||||
## Triggering a Scan
|
||||
Each phase produces results that are visible in the dashboard as soon as they complete.
|
||||
|
||||
## How Scans Are Triggered
|
||||
|
||||
### Manual Scan
|
||||
|
||||
@@ -24,60 +26,54 @@ A full scan consists of multiple phases, each producing different types of findi
|
||||
|
||||
### Scheduled Scans
|
||||
|
||||
Scans run automatically based on the `SCAN_SCHEDULE` cron expression. The default scans every 6 hours:
|
||||
|
||||
```
|
||||
SCAN_SCHEDULE=0 0 */6 * * *
|
||||
```
|
||||
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
|
||||
|
||||
Configure GitHub or GitLab webhooks to trigger scans on push events. Set the webhook URL to:
|
||||
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.
|
||||
|
||||
```
|
||||
http://<agent-host>:3002/webhook/github
|
||||
http://<agent-host>:3002/webhook/gitlab
|
||||
```
|
||||
## Scan Phases and Statuses
|
||||
|
||||
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
|
||||
Each scan progresses through these statuses:
|
||||
|
||||
| Status | Meaning |
|
||||
|--------|---------|
|
||||
| `queued` | Waiting to start |
|
||||
| `running` | Currently executing |
|
||||
| `completed` | Finished successfully |
|
||||
| `failed` | Stopped due to an error |
|
||||
| **Queued** | Scan is waiting to start |
|
||||
| **Running** | Currently executing scan phases |
|
||||
| **Completed** | All phases finished successfully |
|
||||
| **Failed** | Stopped due to an error |
|
||||
|
||||
## Deduplication
|
||||
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.
|
||||
|
||||
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.
|
||||
## 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](/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).
|
||||
|
||||
Reference in New Issue
Block a user