GitHub code scanning policy
This document explains a new GitHub Code Scanning policy change for software developers. The change has been made 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 repo in the VA GH organization.
Policies and dates
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 http://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.
How to configure CodeQL
Source code written in Java
If your repository contains Java code, Default Code Scanning has been enabled 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. To find this page:
Navigate to the Security tab in your repository.
Then select Code Scanning.
Then select Tool 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#.
As of March 2024, 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, Default Code Scanning has been enabled 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. To find this page:
Navigate to the Security tab in your repository.
Then select Code Scanning.
Then select Tool 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. To find this page:
Navigate to the Security tab in your repository.
Then select Code Scanning.
Then select Tool 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.
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.