Add GitHub Code Scanning Policy to Developer Space

Issue Description

Code Scanning Policy page to be added to GitHub documentation in Developer Space. This policy was announced on a Tech Tuesday call 1/16/24 and will affect developers on Platform.

Tasks

[x] Create draft from Clint Little approved language and links in comments.
[x] Format for Platform Website
[x] Determine location on IA for this page.
[x] Create follow up ticket to check in 3 months with Clint, for relevancy of content
[x] Schedule Slack reminder for follow up

Acceptance Criteria

[x] Final version approved by Clint Little
[x] Page is deployed

Relevant documentation

Original email text in comments below

How to configure this issue

[ ] Attached to a Milestone (when will this be completed?)
[ ] Attached to an Epic (what body of work is this a part of?)
[ ] Labeled with Team (product support, analytics-insights, operations, service-design, Console-Services, tools-fe)
[ ] Labeled with Practice Area (backend, frontend, devops, design, research, product, ia, qa, analytics, contact center, research, accessibility, content)
[ ] Labeled with Type (bug, request, discovery, documentation, etc.)

Some or all of this email announcement will be used to inform the page on Platform Website:

As we look to improve the state of software security across the agency and reduce the number of vulnerabilities that make it into production systems, as well as the time existing vulnerabilities live in production before remediation, leadership has made the decision to begin requiring the use of CodeQL for performing Static Application Security Testing (SAST) as part of your Software Development Lifecycle.

For those who were unable to attend the call yesterday, here is a summary of the changes that are going into effect.

On February 15th, 2024, as part of new tooling requirements sponsored by OCTO, AES, and OIS:

All repositories on https://github.com with a supported language will be required to use CodeQL as their SAST tool. The GitHub Admin team will create an organization policy requiring that all code changes to your default branch (master, main, etc.) be delivered through the GitHub Pull Request process. Repositories will be required to perform CodeQL scans of all pull requests targeting their default branch prior to merging the change. Repositories will be required to perform an additional CodeQL scan at least once weekly on their default branch to identify vulnerabilities in existing code during periods of inactivity. Repositories will be required to remediate all vulnerabilities of Critical severity within 30 days of identification. If a Critical vulnerability exceeds 30 days without remediation, a notification will be posted your pull requests until remediation of the vulnerability has occurred. For all vulnerabilities dismissed with a reason of Won’t Fix, Used in Tests, or False Positive a valid justification must be provided during the dismissal process of why these findings are being dismissed without remediation. On April 15th, 2024, the following policies will go into effect:

If a Critical vulnerability exceeds 30 days without remediation, you will be unable to merge your pull request until remediation of the vulnerability has occurred. For extenuating circumstances, the GitHub Admin team will provide an audited method for bypassing this policy in the event critical code changes need to be delivered to production. While this may seem like a lot of changes, our goal is to make this change as low lift as possible. To that end, the GitHub Admin team has enabled Default Code Scanning for all eligible repositories on GitHub.com. If your repository is currently performing CodeQL scans via Jenkins or GitHub Actions, this change will not affect your repository and you may continue using your existing method. For the vast majority of repositories, the enablement of Default Code Scanning means your repository is now covered by CodeQL scans.

How to configure CodeQL Source code written in Java If your repository contains Java code, we have enabled Default Code Scanning for repository. If you are not already performing CodeQL scans using GitHub Actions or Jenkins, Default Code Scanning will now be enabled on your repository. If your repository is now using Default Code Scanning, it is likely operating in buildless mode. Because most Java projects are dependent on internal Maven registries such as Nexus, it is likely that your Java scan is operating in buildless mode which does not call your build tool to compile your Java source code. You can check whether your scans are building in buildless mode or not by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directly there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If your repository is running in buildless mode, no additional configuration is technically necessary. However, Java source code benefits from increased precision when CodeQL can compile your source code. This will likely lead to fewer false positives. If you’d like to configure CodeQL to compile your source code, follow the instructions in the GitHub Handbook.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

Source code written in C# If your repository contains C# code, we have enabled Default Code Scanning for repository. Much of the C# code developed at the VA is written in .NET Framework and not .NET Core. Default Code Scanning only leverages Linux-based build systems for performing scans. .NET Framework applications do not support the Linux-based build tools for C#. At this time, CodeQL does not support buildless configurations for C#, so you will need instruct CodeQL to use Windows to build your .NET application on a Windows-based system. You may configure CodeQL to compile your source code using Windows by following the instructions in the GitHub Handbook and using windows-2019 as runs-on key. This will instruct CodeQL to build your application on a system with .NET Framework already configured.

In the near future C# will support buildless mode for applications unable to build their source code.

If your repository contains C# code written in .NET Core, we have enabled Default Code Scanning for repository. If you are not already performing CodeQL scans using GitHub Actions or Jenkins, Default Code Scanning will now be enabled on your repository. You can confirm your scans are working as intended by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directory there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

Source code not written in Java and C# For repositories that DO NOT contain Java or C# code, you likely won’t need to perform any additional configuration. You can confirm your scans are working as intended by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directly there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

What next Once CodeQL is configured on your repository, the only additional work you must do at this time is remediate any Code Scanning finding of Critical severity in your repository before April 15th. You can find information on how to remediate findings in the GitHub Handbook.

After February 15th, every time you open a new pull request against your repositories default branch, automation will run analyzing whether you have vulnerabilities approaching or exceeding the 30 day remediation period. If you do, a summary of this information will be posted to your pull request informing you what to do next to remain compliant. These results should be posted within a few seconds after opening your pull request or pushing updates to your pull request. After April 15th, if a vulnerability exceeds 30 days without remediation, you will be unable to merge your pull request until you remediate the vulnerability. At this time we are only looking at Critical vulnerabilities when blocking pull requests. If this policy changes to lower the severity threshold, sufficient notice will be provided to developers.

If your repository contains a Critical vulnerability older than 30 days, and you need to merge an urgent fix before remediating these vulnerabilities, you may request temporary bypass permissions allowing you to merge your change by following the instructions in the GitHub Handbook. In response to user feedback, we are also evaluating a custom security role that can be assigned to ISSO's and program responsible individuals who can merge pull requests in these critical situations. Again, policies blocking merging changes will not go into effect until April 15th, providing sufficient time to reach a compliant state.

@little-oddball which parts of the above email text do you feel should be used for the new page on Platform Website?

Announcement wise, I believe these would be important to call out/add:

On February 15th, 2024, as part of new tooling requirements sponsored by OCTO, AES, and OIS:

All repositories on https://github.com/ with a supported language will be required to use CodeQL as their SAST tool.
The GitHub Admin team will create an organization policy requiring that all code changes to your default branch (master, main, etc.) be delivered through the GitHub Pull Request process.
Repositories will be required to perform CodeQL scans of all pull requests targeting their default branch prior to merging the change.
Repositories will be required to perform an additional CodeQL scan at least once weekly on their default branch to identify vulnerabilities in existing code during periods of inactivity.
Repositories will be required to remediate all vulnerabilities of Critical severity within 30 days of identification.
If a Critical vulnerability exceeds 30 days without remediation, a notification will be posted your pull requests until remediation of the vulnerability has occurred.
For all vulnerabilities dismissed with a reason of Won’t Fix, Used in Tests, or False Positive a valid justification must be provided during the dismissal process of why these findings are being dismissed without remediation.

On April 15th, 2024, the following policies will go into effect:

If a Critical vulnerability exceeds 30 days without remediation, you will be unable to merge your pull request until remediation of the vulnerability has occurred.
For extenuating circumstances, the GitHub Admin team will provide an audited method for bypassing this policy in the event critical code changes need to be delivered to production.
While this may seem like a lot of changes, our goal is to make this change as low lift as possible. To that end, the GitHub Admin team has enabled Default Code Scanning for all eligible repositories on GitHub.com. If your repository is currently performing CodeQL scans via Jenkins or GitHub Actions, this change will not affect your repository and you may continue using your existing method. For the vast majority of repositories, the enablement of Default Code Scanning means your repository is now covered by CodeQL scans.

What next

Once CodeQL is configured on your repository, the only additional work you must do at this time is remediate any Code Scanning finding of Critical severity in your repository before April 15th. You can find information on how to remediate findings in the GitHub Handbook.

After February 15th, every time you open a new pull request against your repositories default branch, automation will run analyzing whether you have vulnerabilities approaching or exceeding the 30 day remediation period. If you do, a summary of this information will be posted to your pull request informing you what to do next to remain compliant. These results should be posted within a few seconds after opening your pull request or pushing updates to your pull request. After April 15th, if a vulnerability exceeds 30 days without remediation, you will be unable to merge your pull request until you remediate the vulnerability. At this time we are only looking at Critical vulnerabilities when blocking pull requests. If this policy changes to lower the severity threshold, sufficient notice will be provided to developers.

If your repository contains a Critical vulnerability older than 30 days, and you need to merge an urgent fix before remediating these vulnerabilities, you may request temporary bypass permissions allowing you to merge your change by following the instructions in the GitHub Handbook. In response to user feedback, we are also evaluating a custom security role that can be assigned to ISSO's and program responsible individuals who can merge pull requests in these critical situations. Again, policies blocking merging changes will not go into effect until April 15th, providing sufficient time to reach a compliant state.

I believe the below information is also good for developers but, if less announcement and more general information:

How to configure CodeQL

Source code written in Java

If your repository contains Java code, we have enabled Default Code Scanning for repository. If you are not already performing CodeQL scans using GitHub Actions or Jenkins, Default Code Scanning will now be enabled on your repository. If your repository is now using Default Code Scanning, it is likely operating in buildless mode. Because most Java projects are dependent on internal Maven registries such as Nexus, it is likely that your Java scan is operating in buildless mode which does not call your build tool to compile your Java source code. You can check whether your scans are building in buildless mode or not by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directly there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If your repository is running in buildless mode, no additional configuration is technically necessary. However, Java source code benefits from increased precision when CodeQL can compile your source code. This will likely lead to fewer false positives. If you’d like to configure CodeQL to compile your source code, follow the instructions in the GitHub Handbook.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

Source code written in C#

If your repository contains C# code, we have enabled Default Code Scanning for repository. Much of the C# code developed at the VA is written in .NET Framework and not .NET Core. Default Code Scanning only leverages Linux-based build systems for performing scans. .NET Framework applications do not support the Linux-based build tools for C#. At this time, CodeQL does not support buildless configurations for C#, so you will need instruct CodeQL to use Windows to build your .NET application on a Windows-based system. You may configure CodeQL to compile your source code using Windows by following the instructions in the GitHub Handbook and using windows-2019 as runs-on key. This will instruct CodeQL to build your application on a system with .NET Framework already configured. In the near future C# will support buildless mode for applications unable to build their source code.

If your repository contains C# code written in .NET Core, we have enabled Default Code Scanning for repository. If you are not already performing CodeQL scans using GitHub Actions or Jenkins, Default Code Scanning will now be enabled on your repository. You can confirm your scans are working as intended by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directory there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

Source code not written in Java and C#

For repositories that DO NOT contain Java or C# code, you likely won’t need to perform any additional configuration. You can confirm your scans are working as intended by checking the Security Tools status page of your repository. This page can be found by navigating to the Security tab in your repository, selecting Code Scanning and then Tool Status. Alternatively you may navigate directly there using this format: https://github.com/department-of-veterans-affairs/_/security/code-scanning/tools/CodeQL/status.

If you are unable to configure your repository for any reason, or have general questions, please feel free to open an issue in the GitHub User Requests repository.

@little-oddball Thank you! We will size this work and add it to a future sprint. We will send you the draft page for approval.

Hey team! Please add your planning poker estimate with Zenhub @BSmolensky @laucon @taylojill

@little-oddball we are beginning work on this page. We have a couple of questions regarding getting started:

Could you assist us in creating a brief intro sentence as to what this change is all about? Specifically, who will this policy change affect (All Platform developers, All VA frontend developers? etc.) - maybe we can sum up the policy change itself in 1 sentence?
Where in the IA should this document live? It will have a home in the Developer Docs space, but we need to determine where in Developer Docs: front end? Back end? QA? Code and Build? Infrastructure? Please let us know your thoughts. Thanks!

The change is to enable a level of code scanning / security at the repos level based on the VA.gov security policies they manage. This change potentially impacts everyone who uses a repos in the VA GH organization (in regards to potentially fixing issues, etc.).
This change reaches across all repos that have code thus could/would impact any of the engineers. From a where should this live, I believe we would live it to live in sort of a universal place that is associated with developers.

Created ticket 78278 for follow up, scheduled Slack reminder. All tasks complete, moving to Done

department-of-veterans-affairs / va.gov-team