diff --git a/docs/development-infrastructure/continuous-integration/docker.md b/docs/development-infrastructure/continuous-integration/docker.md index 014e83cc..1fe65d79 100644 --- a/docs/development-infrastructure/continuous-integration/docker.md +++ b/docs/development-infrastructure/continuous-integration/docker.md @@ -191,7 +191,7 @@ Finally, the image gets published to Docker Hub using the tags determined earlie A `docker-compose.yml` can be optionally used for using images locally and testing. This isn't required for deploying to Docker Hub. -Here's an [example `docker-compose.yml` from GitProxy](https://github.com/finos/git-proxy/blob/main/docker-compose.yml) for reference. +Here's an [example `docker-compose.yml` from GitProxy](https://github.com/finos/git-proxy/edit/main/test/e2e/docker-compose.yml) for reference. ## Verification diff --git a/docs/governance/Software-Projects/Security-Vulnerabilities-Responsible-Disclosure-Policy.md b/docs/governance/Software-Projects/Security-Vulnerabilities-Responsible-Disclosure-Policy.md index 89031259..50301c10 100644 --- a/docs/governance/Software-Projects/Security-Vulnerabilities-Responsible-Disclosure-Policy.md +++ b/docs/governance/Software-Projects/Security-Vulnerabilities-Responsible-Disclosure-Policy.md @@ -1,97 +1,163 @@ --- id: cve-responsible-disclosure -title: FINOS Security Vulnerabilities Responsible Disclosure Policy +title: Vulnerability Disclosure Policy description: "Responsible disclosure for FINOS security issues: how reporters, maintainers, and users coordinate fixes, embargoes, and public communication about CVEs." --- :::caution -Right now, FINOS does not operate a bug bounty program, and does not offer rewards or compensations of any kind in exchange for submitting potential bugs, issues or vulnerabilities. +Currently, FINOS does not operate a bug bounty program, and does not offer rewards or compensations of any kind in exchange for submitting potential bugs, issues or vulnerabilities. ::: -This document defines a **set of rules and policies established by FINOS to manage the lifecycle of potential vulnerabilities and security incidents within FINOS projects**, aimed to guarantee... +FINOS defines a **set of rules to manage the lifecycle of potential vulnerabilities and security incidents within FINOS projects**. Our goal is to guarantee: -1. Discretion for new and ongoing development activity around security vulnerabilities that haven't been published yet +1. Discretion for new and ongoing development activity around undisclosed security vulnerabilities 2. Transparency and guidance around security vulnerabilities that have been identified, patched and released as new versions -It includes step-by-step guides on [how contributors can setup a process to manage security vulnerabilities](#for-finos-open-source-contributors) and [how anyone can privately submit an undisclosed security vulnerability](#for-finos-open-source-consumers) to a FINOS project. +We have step-by-step guides on [how contributors can manage security vulnerabilities](#for-finos-open-source-contributors) and [how anyone can privately submit an undisclosed security vulnerability](#for-finos-open-source-consumers) to a FINOS project. ## What are Common Vulnerabilities and Exposures The **Common Vulnerabilities and Exposures** (or [CVE](https://cve.mitre.org/cve/)) is a dictionary that provides definitions for publicly disclosed cybersecurity [vulnerabilities](https://cve.mitre.org/about/terminology.html#vulnerability) and [exposures](https://cve.mitre.org/about/terminology.html#exposure), although the term is normally used to identify CVE entries; each entry is comprised of an identification number, a description, and at least one public reference, you can check [an example on the cla-bot project](https://github.com/finos/cla-bot/issues/157). Please note that the term security vulnerability also comprises undisclosed ones, as opposed to CVEs, which only refer to publicly disclosed entries. ## For FINOS Open Source Consumers -**IMPORTANT!** No information should be made public about the vulnerability until it is formally announced at the end of this process. That means, for example that a GitHub Issue must NOT be created to track the issue since that will make the issue public. Also the messages associated with any commits should not make ANY reference to the security nature of the commit. +**IMPORTANT!** No information should be made public about the vulnerability until it is formally announced at the end of this process. Do NOT create a GitHub Issue to track the vulnerability, since that will make the issue public. Commit messages should not make ANY reference to the security nature of the commit. -An overview of the vulnerability handling process is: -1. The reporter reports the vulnerability privately to a FINOS Lead Maintainer. -2. The appropriate project's team members works privately with the reporter to resolve the vulnerability. -3. A new release of the FINOS product concerned is made that includes the fix. -4. The vulnerability is publicly announced. +### Reporting a Vulnerability -### Browse security vulnerabilities for a project and release -Security vulnerabilities are published as GitHub Issues marked with the label security vulnerability. You can easily browse through the open and closed ones using the GitHub web UI. +In order to report a vulnerability in a FINOS project, follow these steps: -### Submit a new security vulnerability -To submit a new vulnerability, please follow these steps: -1. Identify the FINOS Project (project) related to the security vulnerability. -2. If you cannot find her personal email, please ask [security@finos.org](mailto:security@finos.org) -3. Email the Lead Maintainer privately with the description - and screenshots, if useful - of the vulnerability. +1. Visit the "Security and quality" tab of the project repository, available at `github.com/finos//security`: -**Sharing information. ** Information may be shared with domain experts (e.g. colleagues at your employer) at the discretion of the project's security team providing that it's made clear the information is not for public disclosure and that [security@finos.org](mailto:security@finos.org) or the Lead Maintainer must be copied on any communication regarding the vulnerability. + ![Security and quality tab](security-and-quality-tab.png) + +2. Carefully read the project's `SECURITY.md` policy, in case any processes override what's described on this page: + + ![Security Policy](security-policy.png) + +3. Follow the submission steps in the project's security policy. Usually, this means clicking the "Report a vulnerability" button and filling in the [requested details](#details-to-include). +4. If the project doesn't have a SECURITY.md policy available, submit the vulnerability via email to a project Maintainer (ideally, the Lead Maintainer). You can find contact emails in the project's `MAINTAINERS.md` file. Also, CC the email to [security@finos.org](mailto:security@finos.org). +5. If the project doesn't provide a contact email for a maintainer, submit the report directly to [security@finos.org](mailto:security@finos.org). + +**Important: Do NOT make a GitHub issue or discuss the vulnerability through public channels.** + +### Details to include + +When reporting a vulnerability, it's very helpful to provide as many details as possible, including: + +- **Impact:** _What kind of vulnerability is it? Who is impacted?_ +- **Patches:** _Has the problem been patched? What versions should users upgrade to?_ +- **Workarounds:** _Is there a way for users to fix or remediate the vulnerability without upgrading?_ +- **References:** _Are there any links users can visit to find out more?_ +- **Screenshots (if applicable):** _Which user flows demonstrate the problem?_ + +### Vulnerability Remediation Process + +1. The project's team members work privately with the reporter to resolve the vulnerability. +2. The affected FINOS project releases a new version including the fix. +3. The vulnerability is publicly announced. + +For more details, see how maintainers [Manage new vulnerabilities](#managing-new-vulnerabilities) and how you can contribute to patching the issue. + +### Browse security vulnerabilities for a project + +Published security vulnerabilities are available in the "Security and quality" tab at the repository's main page, accessible via `github.com/finos//security`. + +### Information Sharing + +If you would like to share vulnerability information with domain experts (e.g. co-workers), you must first ask the project's Security Team (maintainers, etc.) for permission. It should be made clear that the information is not for public disclosure and that [security@finos.org](mailto:security@finos.org) or the Lead Maintainer must be kept in the loop on any communication regarding the vulnerability. ## For FINOS Open Source Contributors -**IMPORTANT!** No information should be made public about the vulnerability until it is formally announced at the end of this process. That means, for example that a GitHub Issue must NOT be created to track the issue since that will make the issue public. Also the messages associated with any commits should not make ANY reference to the security nature of the commit. +**IMPORTANT!** No information should be made public about the vulnerability until it is formally announced at the end of this process. Do NOT create a GitHub Issue to track the vulnerability, since that will make the issue public. Commit messages should not make ANY reference to the security nature of the commit. + +### Reporting a Vulnerability + +Submitting a vulnerability report is identical to the process followed by project Consumers. See [the guide above](#for-finos-open-source-consumers) for reference. + +### Setting up responsible disclosure + +To start leveraging GitHub's native disclosure and remediation process, you must add a `SECURITY.md` file describing the disclosure process. + +This is a sample `SECURITY.md` file that you may edit as appropriate and add to your project; just replace `PROJECT_NAME` and `PROJECT_URL` with the actual project name and GitHub URL: + +```markdown +# Security Policy + +{PROJECT_NAME} supports responsible disclosure of security vulnerabilities and adheres to the [FINOS Security Vulnerabilities Policy](https://community.finos.org/docs/governance/Software-Projects/cve-responsible-disclosure). If you find something you believe to be a security issue in {PROJECT_NAME}, we encourage and appreciate your report. Please report the issue privately to the [project maintainers]({PROEJCT_URL}/blob/main/MAINTAINERS.md) using one of the following methods: -### FINOS lifecycle -The responsible disclosure ties into [FINOS Project Lifecycle](/docs/governance/project-lifecycle) in the following items: +## Reporting a Vulnerability -- All [Incubating projects](/docs/governance/lifecycle-stages/incubating) **MUST** have an automated way to manage security vulnerabilities, see below -- All [Graduated projects](/docs/governance/lifecycle-stages/graduated) **MUST** have WhiteSource enabled -- All projects **publishing artefacts under FINOS package registries MUST** have WhiteSource enabled +- **GitHub Security Reports:** In order for the vulnerability reports to reach maintainers as soon as possible, the preferred way is to use the ["Report a vulnerability"]({PROJECT_URL}/security) button under our "Security and quality" tab. This creates a private communication channel between you and the maintainers. +- **Email:** If you are unable to or have strong reasons not to use the GitHub Security vulnerability reporting feature, please email the maintainers directly and CC: [security@finos.org](mailto:security@finos.org) with a description of the vulnerability, along with relevant details (Impact, Patches, Workarounds, References and Screenshots). + +## Vulnerability Process + +1. **Report the vulnerability privately** using one of the methods above. Do not create a public GitHub Issue or make any public reference to the vulnerability. +2. The project team will acknowledge receipt of your report and triage the issue. If a vulnerability is confirmed, the team will work with you to investigate and resolve it. +3. Once a fix is available, a release will be made and the vulnerability will be publicly disclosed in accordance with the [FINOS policy](https://community.finos.org/docs/governance/Software-Projects/cve-responsible-disclosure). +``` + +Once a `SECURITY.md` file is added, you must enable private vulnerability reporting in your repository by going to **Settings** > **Advanced Security** > **Private Vunlerability Reporting** and clicking on "Enable": + +![Private Vulnerability Reporting](private-vulnerability-reporting.png) + +If you don't have access to this menu, email [security@finos.org](mailto:security@finos.org) to request private vulnerability reporting to be activated. ### Collecting project CVE list -Since all CVE entries are labeled as security vulnerability, it is possible to use GitHub Issues UI to browse them. + +Since all CVE entries are labeled as security vulnerability, it is possible to use GitHub Issues UI to browse them. Alternatively, check the Advisories tab under the "Security and quality" tab of the project repository, also accessible at `github.com/finos//security/advisories`. ### Managing new vulnerabilities + A typical process for handling a new security vulnerability is as follows. Projects that wish to use other processes MAY do so, but **MUST** clearly and publicly document their process and have FINOS team review it ahead of time. #### Accepting a new vulnerability -1. The person discovering the issue, the reporter, reports the vulnerability privately to the Lead Maintainer and cc's [security@finos.org](mailto:security@finos.org) (or sends the email directly to security@finos.org). -2. The project team sends an e-mail to the original reporter to acknowledge the report, cc to [security@finos.org](mailto:security@finos.org). -3. The project team investigates report and either rejects it or accepts it. + +1. The person discovering the issue, the reporter, reports the vulnerability privately via GitHub's native disclosure process. This automatically notifies the maintainers and [security@finos.org](mailto:security@finos.org), +2. The project team sends an e-mail to the original reporter to acknowledge the report +3. The project team investigates the report and either rejects it or accepts it. +4. Optionally, the project team can edit the report if appropriate, and fill in or amend details including the affected/patched versions, severity and [CWE weaknesses](https://cwe.mitre.org/). #### Working on a fix -1. The project team agrees the fix, the announcement and the release schedule with the reporter. The level of detail to include in the report is a matter of judgement. Generally, reports should contain enough information to enable people to assess the risk associated with the vulnerability for their system and no more. Steps to reproduce the vulnerability are not normally included. -2. The project team commits the fix. No reference should be made to the commit being related to a security vulnerability. -3. The project team creates a release that includes the fix. + +The reporter and maintainer team collaborate on a fix via GitHub's native vulnerability management system. As part of the process, they must: + +1. Create a temporary private fork by clicking on the "Create private fork" button in the draft advisory page +2. Clone the fork, make a branch and commit a fix to the vulnerability **without referencing the security nature of the commits** +3. Open a PR on the private fork, which will automatically show on the advisory page +4. Review, approve and merge the PR +5. Request a CVE from GitHub + +Once all of these have been completed, GitHub will assign a CVE and it will be officially published, and merged to the `main` branch. If no automated release tooling is available, the team must manually make a new release, and backport the fixes to previous release lines if appropriate. #### Apply fixes to all supported versions + As soon as the project team finds and implements a fix for the vulnerability, all supported versions (most likely GitHub branches) can be patched and released. +We highly recommend setting up release automation (Release Drafter, automatic version bumping) to simplify the process of backporting fixes to all active release branches. See [GitProxy's release-related workflows](https://github.com/finos/git-proxy/tree/main/.github/workflows) examples you can use in your own project. + +Here's an [example of a detailed release policy](https://git-proxy.finos.org/docs/development/releases/) that enabled maintainers to speed up their release process and spread the load across the team. + #### Publishing -1. The project team announces the release. -2. The project team announces the vulnerability. The vulnerability announcement should be sent after, or at the same time as, the release announcement to the following destinations: - a. GitHub Issues, reporting the following info: - i. CVE ID in the title - ii. Apply label security vulnerability - iii. Specify which library is affected, if any - iv. Specify code line/block that causes the vulnerability - v. Specify vulnerability details, including link to CVE description - vi. Specify fix (high level) - vii. Specify affected and fixed released versions - b. The same destinations as the release announcement. - c. The vulnerability reporter. - d. [security@finos.org](mailto:security@finos.org) -3. Additional requirements for the emails sent to the above lists are: - a. The subject must contain the name of the project and the CVE name(s), and should contain a short description of the issue(s), for example `Subject: [CVE-2007-5648] Apache Tomcat information disclosure vulnerability` - b. The message body must contain details of the vulnerability, similar to what will be sent to The Mitre Corporation in the next step (not just a URL link to the details) -4. Any relevant project documentation page must be updated -5. The log for the Git commit that applied the fix is updated to include the CVE number. Projects that use git as their primary source code control system should not do this as editing a pushed commit causes all sorts of problems. + +First, the team must release the patched version(s). Then, the following optional actions must be done **before** the vulnerability is published (via the GitHub Advisories UI): + +1. Emailing [security@finos.org](mailto:security@finos.org) about the public disclosure +2. Notifying the original reporter about the disclosure +3. Relevant documentation must be updated (though it's highly recommended to do this *within* the private fork) + +Note that FINOS and the original reporter are automatically notified by GitHub on any changes on the report status. + +The following optional actions must be done **after** the vulnerability is published: + +1. Creating follow-up issues to solve bugs that are out-of-scope for the original vulnerability +2. Creating any issue that referencing the vulnerability directly (via links, name, etc.) or indirectly ## Automating security vulnerabilities + FINOS provides multiple tools that adapt to languages and build platforms adopted by the project's codebase, please visit the [code validation page](https://community.finos.org/docs/development-infrastructure/code-validation/intro/). ## Responsible Disclosure at Apache Software Foundation + We took great inspiration from the work that the Apache Software Foundation have done; we started from there, then adapted processes and contents around our requirements; below the links describing the ASF responsible disclosure. - https://www.apache.org/security/ - https://www.apache.org/security/committers.html diff --git a/docs/governance/Software-Projects/private-vulnerability-reporting.png b/docs/governance/Software-Projects/private-vulnerability-reporting.png new file mode 100644 index 00000000..d4f43501 Binary files /dev/null and b/docs/governance/Software-Projects/private-vulnerability-reporting.png differ diff --git a/docs/governance/Software-Projects/security-and-quality-tab.png b/docs/governance/Software-Projects/security-and-quality-tab.png new file mode 100644 index 00000000..2c71abe0 Binary files /dev/null and b/docs/governance/Software-Projects/security-and-quality-tab.png differ diff --git a/docs/governance/Software-Projects/security-policy.png b/docs/governance/Software-Projects/security-policy.png new file mode 100644 index 00000000..705ce677 Binary files /dev/null and b/docs/governance/Software-Projects/security-policy.png differ