docs: security vulnerabilities

frontend/docs/metrics/security/index.md

@@ -1,5 +1,7 @@
 # Security & Best Practices
 
+## Controls Assessment
+
 The control assessments that we run for "Security & Best Practices" are powered by the [Open Source Project Security Baseline](https://baseline.openssf.org) by OpenSSF.
 
 Please note that Insights only runs control assessments that work without privileged access to a project's codebase.
@@ -9,3 +11,65 @@ Where supported (currently, only GitHub and Gitlab), it also ignores repositorie
 Additionally, some repositories may be marked as excluded, even if they are not archived. One example of this are `.github` repositories, which are automatically marked as excluded, but not archived. Repositories marked as excluded are also not taken into account in the security assesments.
 
 To improve security & best practices, we recommend maintainers to check out the Baseline project and validate all control assessments.
+
+## Vulnerabilities
+
+The Security Vulnerabilities section surfaces known vulnerabilities found in your project's dependencies, helping teams track and remediate security risks across their repositories.
+
+::: info
+This section is only available to logged-in users.
+:::
+
+### How It Works
+
+Insights scans repository dependencies using [OSV-Scanner](https://google.github.io/osv-scanner/), an open-source CLI tool maintained by Google. OSV-Scanner detects dependency manifests and lockfiles, then cross-references them against the [OSV.dev](https://osv.dev) vulnerability database — a platform that aggregates advisories from multiple authoritative sources including the CVE program.
+
+Vulnerability data covers the last 12 months and reflects findings across all repositories in the project.
+
+::: info
+Vulnerability data is sourced from the CVE program only. CWE (Common Weakness Enumeration) entries are not included.
+:::
+
+### Supported Ecosystems
+
+OSV-Scanner automatically detects a wide range of package managers and lockfile formats, including npm, Go modules, PyPI, Maven, Cargo, and more. For the full list of supported languages and lockfiles, see the [OSV-Scanner documentation](https://google.github.io/osv-scanner/supported-languages-and-lockfiles/).
+
+#### Vendored dependencies
+
+Some vulnerabilities appear with an ecosystem of **Vendored**. This happens when OSV-Scanner detects a vulnerability in a dependency that lacks package ecosystem, name, or version metadata, typically because it is a vendored dependency.
+
+Vendored dependencies are third-party libraries (commonly C/C++ code) that have been copied directly into a repository's source tree (for example, a `deps/` or `vendor/` directory) rather than installed through a package manager. Because no package manager is involved, OSV-Scanner cannot determine the ecosystem, so Insights labels these as **Vendored** to distinguish them from package-managed dependencies.
+
+### Metrics
+
+The top of the Vulnerabilities section displays four key indicators:
+
+| Metric | Description |
+|---|---|
+| **Open Vulnerabilities** | Total count of unresolved vulnerabilities across all scanned repositories |
+| **Median CVSS** | Median severity score across all open vulnerabilities, using the CVSS (Common Vulnerability Scoring System) scale |
+| **Fix Status** | Ratio of vulnerabilities that have a fix available in a newer package version (e.g., "6 of 8 fixable") |
+| **Time Since Last Vulnerability** | How long ago the most recent vulnerability was detected |
+
+### Charts
+
+**Vulnerabilities by Severity**
+A bar chart showing the distribution of vulnerabilities across severity levels: Critical, High, Medium, and Low. Severity is determined by the CVSS score associated with each CVE.
+
+**Vulnerabilities by Ecosystem**
+A breakdown of vulnerabilities grouped by package manager (e.g., npm, Go, PyPI). This helps identify which dependency ecosystems contribute most to your project's risk surface.
+
+### Remediating Vulnerabilities
+
+When a fix is available, upgrading the affected dependency to the patched version is the most direct remediation path. The Fix Status metric shows how many of your open vulnerabilities have a known fix, giving teams a clear starting point for triage.
+
+For vulnerabilities without an available fix, consider:
+- Monitoring the upstream package for a patch release
+- Evaluating whether the vulnerable code path is reachable in your project
+- Replacing the dependency with a maintained alternative
+
+### Known Limitations
+
+| Limitation | Details |
+|---|---|
+| **Bun lockfiles** | Repositories that use [Bun](https://bun.sh) with `bun.lock` files are not scanned. OSV-Scanner returns an error when processing this lockfile format. This is a [known OSV-Scanner bug](https://github.com/google/osv-scanner/issues/2683) and will be resolved once an upstream fix is available. |