Welcome to the Code Scanning Java Tutorial! This tutorial will take you through how to set up Github Advanced Security: Code Scanning as well as interpret results that it may find. The following repository contains SQL injection vulnerability for demonstration purpose.
Code scanning is a feature that you use to analyze the code in a GitHub repository to find security vulnerabilities and coding errors. Any problems identified by the analysis are shown in GitHub.
You can use code scanning with CodeQL, a semantic code analysis engine. CodeQL treats code as data, allowing you to find potential vulnerabilities in your code with greater confidence than traditional static analyzers.
This tutorial with use CodeQL Analysis with Code Scanning in order to search for vulnerabilities within your code.
Create repository fork
Begin by creating a new repository from a fork (public) or cloning the repository.
Where creating the forked repository, make sure to
- Select the correct org / user account
- Create a name for your new repository
- Disable main branch only cloning
- Create the repository from the template
Enable Code Scanning
Click on the Security tab.
Click Set up code scanning.
Click the Setup dropdown and select the Default CodeQL Analysis.
This will trigger a CodeQL Scan without needing a workflow file. Since Java is a compiled language the file will use our out-of-the-box Autobuild action but if your application requires more customizable compilation steps, you can switch to the advanced setup and create a workflow file where you can input your desired steps. See the documentation if you would like to configure CodeQL Analysis with a 3rd party CI system instead of using GitHub Actions.
Actions Workflow file (No need to do anything!)
As we're going with the Default Setup, this file is not necessary but in case you're curious, here how it looks like:
The Actions Workflow file contains a number of different sections including:
- Checking out the repository
- Initializing the CodeQL Action
- Running Autobuilder (or code your own build steps if autobuild doesn't work)
- Running the CodeQL Analysis
Click Start Commit -> Commit this file to commit the changes to main branch.
Workflow triggers
There are a number of events that can trigger a GitHub Actions workflow.
In this example, with the default setup the triggers will be:
Whereas with the workflow, it will be triggered on:
- push to main branch
- pull request to merge to main branch
- on schedule, at 6:33 every Thursday
Setting up the new CodeQL workflow and committing it to main branch in the step above will trigger the scan.
GitHub Actions Progress
Click Actions tab -> CodeQL
Click the specific workflow run. You can view the progress of the Workflow run until the analysis completes.
Security Issues
Once the Workflow has completed, click the Security tab -> Code Scanning Alerts. An security alert "Query built from user-controlled sources" should be visible.
Clicking on the security alert will provide details about the security alert including:
- A description of the issue
- A tag to the CWE that it is connected to as well as the type of alert (Error, Warning, Note)
- The line of code that triggered the security alert
- The ability to dismiss the alert depending on certain conditions (`False positive`? `Won't fix`? `Used in tests`?)
Click Show more to view a full desciption of the alert including examples and links to additional information.
Show Paths
CodeQL Analysis is able to trace the dataflow path from source to sink and gives you the ability to view the path traversal within the alert.
Click show paths in order to see the dataflow path that resulted in this alert.
Fix the Security Alert (with Copilot)
In order to fix this specific alert, we will need to ensure parameters used in the SQL query is validated and sanitized. We will solve this with the power of Copilot!
Open the file [`IndexController.java`](./src/main/java/com/github/hackathon/advancedsecurityjava/Controllers/IndexController.java) in the `Controllers` folder and select line 40. Once highlighted, select `Shift` on your keyboard and click line 53. Finally, click on the Copilot icon that appears to the side of the highlighted code.
Ask Copilot the following prompt or feel free to try with a prompt of your own!
- English: Rewrite this method to prevent a SQL injection
- Spanish: Reescribe este método para prevenir SQL injection
Integrate the suggested code in your Index Controller. Make sure to click Edit on the file.
Click Create a new branch for this commit and start a pull request, name the branch fix-sql-injection, and create the Pull Request.
Fix the Security Alert (without Copilot)
In order to fix this specific alert, we will need to ensure parameters used in the SQL query is validated and sanitized.Click on the Code tab and Edit the file IndexController.java in the Controllers folder, replace the content with the file fixme.
Click Create a new branch for this commit and start a pull request, name the branch fix-sql-injection, and create the Pull Request.
Re-Scan your code after new changes
In the Pull Request, you will notice that the CodeQL Analysis has started as a status check. Wait until it completes.
After the Workflow has completed click on Details by the Code Scanning Results / CodeQL status check.
Notice that Code Scanning has detected that this Pull Request will fix the SQL injection vulnerability that was detected before.
Merge the Pull Request. After the Pull Request has been merged, another Workflow will kick off to scan the repository for any vulnerabilties.
After the final Workflow has completed, navigate back to the Security tab and click Closed. Notice that the Query built from user-controlled sources security alert now shows up as a closed issue.
Click on the security alert and notice that it details when the fix was made, by whom, and the specific commit. This provides full traceability to detail when and how a security alert was fixed and exactly what was changed to remediate the issue.
Prevent new Alerts in a Pull Request
Now that we have setup CodeQL Analysis and have fix a security alert, we can try to introduce an alert into a Pull Request.
Create a new Pull Request with the base branch as your main branch and the compare branch as the new-feature branch.
Make sure that the base branch is set to your own repositories main branch versus the original repository's main branch.
Once the Pull Request has been created, you will notice that the CodeQL Analysis has started as a status check. Wait until it completes.
After the Workflow has completed, the Code Scanning Results / CodeQL status check will have failed.
Notice that Code Scanning has detected that this Pull Request introduces a new security alert.
Directly in the Pull Request, you will notice that GitHub Code Scanning bot has left a review of the Pull Request with the security alert details. This will help developers to quickly identify security issues introduced in their Pull Requests.
This also allows for collaboration between developers and security teams to discuss the security alert and how to remediate it.
Click on Show more details by the new Code Scanning Alert to jump to the Security tab and view the security alert details.
Notice that the security alert was found In pull request and not in the main branch (production).
(Bonus) Enable Secret Scanning
Click on `Settings` and select `Code Security` from the menu on the left.
Find the options for Secret Scanning and Push Protection and make sure they are both Enabled. When they are it should say disabled, similar to this image:
(Bonus) Try to introduce a Secret
Find yourself a secret that matches any of the supported secrets and try to commit the value to the Repo. You could commit it to any file! Refer to the previous activities to refresh how Edit and Commit a change.
If you received an error, you've done it right!!
If you didn't receive an error, this may be why:
- The secret is not supported out-of-the-box. For secrets not in the supported secrets list, you will need to create a Custom Pattern first.
- The secret was already leaked and you already have an Open Alert in your Security page. Why cry over spilled milk?!
- Check again that Push Protection is enabled on your Repo!
No usar pero este un ejemplo de un secreto xxx
Ready to talk about advanced security features for GitHub Enterprise? Contact Sales for more information!
Check out GitHub's Security feature page for more security features embedded into GitHub.
Check out the Code Scanning documentation for additional configuration options and technical details.