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.