docs: security vulnerabilities

[joanagmaia]

This pull request enhances the documentation for the Security & Best Practices metrics by adding detailed explanations about the controls assessment process and introducing a comprehensive section on vulnerability scanning and reporting. These updates clarify how security metrics are generated and give users actionable information on interpreting and remediating vulnerabilities.

Additions to security documentation:

• Added a new "Controls Assessment" section to explain the source and scope of security control assessments, referencing the OpenSSF Baseline project.

Vulnerability reporting and metrics:

• Introduced a "Vulnerabilities" section that explains how Insights surfaces known vulnerabilities in project dependencies, including data sources, scanning methodology (using OSV-Scanner), and limitations (CVE-only coverage).
• Described the supported ecosystems and lockfile formats detected by OSV-Scanner, with a link to the official documentation for further details.
• Documented the key vulnerability metrics displayed, such as open vulnerabilities count, median CVSS score, fix status, and time since last vulnerability.
• Added descriptions of the vulnerability charts (by severity and by ecosystem) and guidance for remediating vulnerabilities, including how to interpret fix status and next steps for unresolved issues.

[Copilot]

Pull request overview

This PR updates the Security & Best Practices metric documentation to better explain how Insights produces security-related results, adding an explicit Controls Assessment section and a new Vulnerabilities section describing dependency vulnerability scanning, metrics, charts, and remediation guidance.

Changes:

• Added documentation describing how control assessments are sourced (OpenSSF Baseline) and what repositories are included/excluded.
• Added end-user documentation for dependency vulnerability scanning (OSV-Scanner), including supported ecosystems, surfaced metrics, charts, and remediation steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The docs call this metric "Median CVSS", but the backend type returned by the vulnerabilities summary endpoint is avgCvssScore (average). Please align the documentation (and any UI label) with what’s actually computed (median vs average) to avoid misleading users.

Suggested change

	| **Median CVSS** | Median severity score across all open vulnerabilities, using the CVSS (Common Vulnerability Scoring System) scale |
	| **Average CVSS** | Average severity score across all open vulnerabilities, using the CVSS (Common Vulnerability Scoring System) scale |