How to try GitHub Advanced Security

What is GitHub Advanced Security?

GitHub Advanced Security is a developer-first application security solution that modernizes and transforms how application security is perceived and implemented across organizations. Within the GitHub Advanced Security ecosystem, there are three core capabilities.

The matrix below illustrates which features are available for free during your trial, depending on whether you’re using a private or public repository.

As you can see from above, code scanning and dependency review are entirely free for use across public repositories! Primarily, we see customers wanting to trial code scanning. So let's go ahead and test out code scanning's capabilities and features. If you wish to trial the complete feature set offered by secret scanning, don't hesitate to contact us using the form at the bottom.

How to enable code scanning and CodeQL

Code scanning is a developer-first, GitHub-native approach to easily find security vulnerabilities. Powered by the world’s most powerful code analysis engine—CodeQL—it scans code as it’s created and surfaces actionable security reviews within pull requests.

There are two ways to try it out: in a public repository you already use or a sample repository based on your programming language.

Option 1: If you want to test code scanning on an open source repository you maintain.

Code scanning is for free for all public GitHub repositories. Maintain an open source library or any other active public repository with used code? Here’s how to set it up now.

• Go to the repository's Settings

• Choose the Code security & analysis tab

• In the "Code scanning" section, next to "CodeQL analysis", click the Set up dropdown menu, then select Default"

• Click Enable CodeQL

• After a successful run, click the Security tab, then click View alerts next to "Code scanning alerts" to see if CodeQL found any vulnerabilities in your code."

Figure 1: Image showing how to enable code scanning in a repository.

Note: You will need to have administrator permissions to fully test code scanning.

Option 2: If you want to test code scanning on a sample repository built by GitHub.

Don’t have any public repositories? That’s okay. GitHub maintains five repositories that can walk you through a simple code scanning example. Keep in mind, CodeQL will handle compiled languages slightly differently from interpreted ones. Extraction works by monitoring the standard build process for compiled languages.

Sample repositories by language

• Code scanning tutorial for JavaScript

• Code scanning tutorial for Java

• Code scanning tutorial for C#

• Code scanning tutorial for Python

• Code scanning tutorial for Go

Want to try more?

The above options should give you a basic feel for code scanning, but there’s still much more to learn! Carry on reading below to test out more features and see more complex use-cases.

Code scanning in action with Juice Shop

Running your first scan is just the start. Code scanning also integrates with GitHub Actions workflows—or your existing CI/CD environment—to maximize flexibility for your team. You can see data flows of vulnerabilities, quickly dismiss false positives, and complete other day-to-day security tasks all within a single repository.

Let’s explore how using the Juice Shop repository as an example.

Step 1: Fork the repository

Fork the Juice Shop repository into your account and configure code scanning by following the previous tutorial.

Step 2: Enable Actions

Since the workflows are in a forked repository, they won’t run until you specifically enable them. Go to the Actions tab, then turn on workflows by clicking the button shown in the below screenshot.

Figure 2: Image showing how to enable Actions on a forked repository

Step 3: Run a scan

Test the workflow by making a minor change to your repository’s README.md file, then commit the change to the default branch. After the scan is completed, you should see about 50 new notifications in the Security tab.

Step 4: Check your alerts

Next, go to the code scanning alerts page by clicking the Security tab and then Code scanning alerts.

You can use this API to disable or enable code scanning programmatically. For large enterprises, this API comes in handy when you’re adopting code scanning at scale.

Figure 3: Image showing how to find the code scanning alerts

Once you click into alerts, you should see the following page.

Figure 4: Image showing code scanning alerts page

There are three core sections within this page: Latest scan data, the search function, and the alerts view.

• Latest scan data - The card at the top has data on the latest scan. It’s a quick and easy way to find data on the last run.

• Search - An easy filterable search mechanism for looking for specific alerts based on metadata.

• Alerts view - A list format of all the results found within the default branch of the repository.

Understanding code scanning results

While security scan results are generated by automated tools, it’s still up to developers to address and fix them. That’s why developer-first tooling is essential—and it’s why GitHub code scanning results are built with developers in mind. The information you see prioritizes what needs to be addressed first, and then shows you how to remediate the vulnerability.

Searching and filtering results

The default view shows all alerts found within the default branch of your repository (which is normally main). You can use the search or the filter options provided within the header to narrow down the results to suit your needs.

Deep diving into specific alerts

To find out more information about a specific alert, you can click on the alert name to see a detailed view of what it is and how to fix it. You’ll also see a timeline view of where the alert was first found, where it has been found, and where it is now.

How GitHub Advanced Security impacts your workflow

Security is a team responsibility. Often known as “shifting security left,” protecting your code from vulnerabilities requires input from teams involved at every stage of the software development lifecycle. With code scanning and GitHub Advanced Security, developers, security personnel, and admins can all learn from and act on the results in meaningful ways.

Below you can explore code scanning’s many features by carrying out tasks designed for certain roles in your organization, from a member of the security team to a developer or product owner. Take a look at the different use-cases—even if they don’t relate to your current role—you may be surprised what you can learn.

Code scanning examples for security teams

As a security auditor, I want to filter all code scanning alerts to just SQL injections. Then, I want to deep-dive into a specific SQL injection, looking at the timeline history of that alert. The data I’m looking for is when it was committed, who committed it, and any places the vulnerability was alerted or changed, so that I can assess the possible impact over time. - Security Auditor

Let’s start with the search function. Click on Rule and search for 'code injection.'

Figure 5: Image showing how to filter by rule

Click on one of the alerts returned, and this screen should appear.

Figure 6: Image showing a specific alert

This is the page that shows you everything about an alert. For this step, the critical information is at the bottom.

Figure 7: Image showing the timeline/alert audit history

This feature offers a timeline view or audit history of where the vulnerability was first detected and who committed it. (This allows you to track the history and committers of vulnerabilities.) If you or anyone else takes this vulnerability, alters it within a branch, or pushes it up, the timeline will update accordingly.

As a security engineer reviewing an alert, I want to see the data flow of the user-provided value from source to sink, so I can understand the true (positive or negative) nature of this vulnerability. - Security Engineer

You can find the source, sink, and user-provided path from the single alert page. Click the Show paths button to get started.

Figure 8: Image showing how to find the show path button.

A pop up should appear, which looks like the following.

Figure 9: Image showing the source/sink pathway

Done! From here, you can see the source at the top, where the data is coming in, and the sink, where the data is executed. Scroll through the different steps to see the pathway to execution. This allows you to see if the SQL injection is something to be concerned about. This step will also show you the exact user input. Within Figure 9, click the User-provided value hyperlink. It should show you exactly where the input value is.

Code scanning examples for developers

As a junior developer, I would like to know more about SQL injections, so I can get a better understanding of how to fix them. Junior Developer

Staying on the detailed single-alert page, let’s try and find out more information about an SQL injection.

Click Show more.

Figure 10: Image showing user how to see more information about an alert

Done. That’s all you need to do. The whole purpose of this is to help developers learn more about a potential vulnerability. If it’s the first time a developer comes across one, they would like to know:

• Summary of vulnerability

• Recommendation of how to approach the vulnerability

• Example of how to fix it

• External references

All of that detail is provided in the overview shown in the expanded image above.

As a developer, I want to quickly find out which results are alerts from tests, so I can mark them as closed and focus on alerts that are source code–related. - Developer

This topic comes up all the time. “Vulnerabilities” found, but within test files. First, head back to the home screen for all alerts. It should look like this.

Figure 11: Image showing code scanning alerts page

Run a filter by Rule, but this time, filter for hard-coded credentials. You should now get a list of all vulnerabilities that show hard-coded credentials. Immediately, we know which ones are found in tests because there is a (Test) prefix on the vulnerability. You can see an example below.

Figure 12: Image showing a vulnerability found in a test.

Click on one of these vulnerabilities. Then click the Dismiss -> Used in tests button(s). The vulnerability should automatically close.

Figure 13: Image showing how a developer can mark a code scanning result as closed.

It’s as easy as that: Developers can come here to see if a vulnerability is a test and then close it up. You can also take a similar approach to mark a vulnerability as Won’t fix or False positive.

Note:

• After clicking Used in tests, look at the timeline/audit history at the bottom of the alert page. It should be updated with information about the event.

• When you click the Used in tests button, a code scanning alert webhook fires. What does this mean? Well, if you only want certain people to close code scanning alerts, you can have code running on that webhook event that checks to see who closed it—and if it wasn’t a GitHub handle on an approved list, you could automatically reopen it. (This will also update on the timeline.)

Extra steps

• Doing the above manually across a large mono repository may be a little tedious. So use the API instead! Use the code scanning API to get all results. Filter the ones that match the rule ID Hard-Coded Credentials, then look at the file name. If it has “tests/” at the start, you can automatically close them by hitting Update Code Scanning API.

• Since this is a JavaScript project, you can create a codeql-analysis.yml file and add an ignore paths section to that file. This will ignore the test directory. Push up that file and watch the findings within that folder not get flagged.

As a developer, I want to adjust the type of scan to the risk level of a repository, so that my high-risk and low-risk repositories don’t run the same level. - Developer

Within the .github/workflows/codeql-analysis.yml file, specifically at the github/codeql-action/init@v1 action, if no configuration is provided, then the default set of the queries will run. What does this mean?

Every supported language of CodeQL comes with a standard set of three packs: standard (security), security-extended, and security and quality.

• Standard

  If nothing else is specified, the standard pack runs high precision, high-accuracy queries. This means the results you get back will be extremely precise, actionable, and something you would likely want to review. However, it will not run all queries available.

• Security-extended 

  This contains a broader set of queries (which still focus on security), but may return results that are not as applicable to you. The queries run in this pack are still precise and accurate with the aim of returning actionable results, but they cover scenarios that not all teams would find relevant.

• Security and quality

  The security and quality pack runs all the queries within security-extended, with some additional code quality queries similar to what you would see out of a linting tool. This pack would only be relevant to teams interested in code quality results, not just security. The purpose is to be able to diversify the type of queries being run to the repository needs, and no longer running the same type of scans for completely different projects.

Note: There are lots of benefits for creating query packs. You can create a query pack specific for a type of application (SPA, API, for example) or one that only includes queries from SANS 25 or OWASP Top 10. For this step, we will use the built-in query packs based on the accuracy and precision of the queries.

As a developer, I want to configure my workflow to run security scans on changes to markdown files and to only run on the main and qa branches, so I don’t waste time waiting for results I don’t need. - Developer

The most frustrating aspect of standard security tooling is unnecessary scans. This slows down a release or a merge of a pull request. This is where GitHub Actions comes in. GitHub Actions easily integrates with GitHub Advanced Security, meaning we can easily configure a scan to, for example, ignore certain file types. So, let’s go ahead and modify the ..github/workflows/codeql-analysis.yml file to not run a scan on markdown files, which is a common ask from developers.

Follow the steps for avoiding unnecessary scans of files. After you finish, it should resemble this.

Figure 15: Image showing how you can configure GitHub Actions to ignore paths/file types.

Go to the README.md and make a file change. No workflow is kicked off—meaning scans only run on relevant changes. Additionally, as changes are only on the main branch, if you go and make a change in a branch called feature/123, again, a workflow won’t be triggered.

See the GitHub Actions Syntax for more configurations

As a developer and security advocate, I would like to enable and enforce security policies so that my code meets my organization's requirements. Developer

After the initial configuration of code scanning, users can configure third-party integrations to extend the standard functionality, like Advanced-Security-Compliance Action / Tool, which allows users to define policies as code.

Take a look at adding the above action to the .github/workflows/codeql-analysis.yml. An example policy that you may want to add is to block pull requests that introduce a specific license. Get creative—this will allow you to specify what passes or fails a build due to a policy from a code perspective.

Code scanning examples for product owners

As a product owner, I want to generate a PDF report showing a release’s security posture, so I can attach it as supporting evidence in my internal release documentation. Product Owner

PDFs are practical for larger enterprises because their security overviews can go alongside official documentation as supporting evidence. To make a PDF using the GitHub Security Report Action, create a new workflow in the repository that runs off a release, create a release, and see the new report that gets introduced. From there, you can get the supporting documentation you need, which will show whether or not you’re in compliance with certain security requirements.

Code scanning examples for product owners

As a product owner, I want to generate a PDF report showing a release’s security posture, so I can attach it as supporting evidence in my internal release documentation. Product Owner

PDFs are practical for larger enterprises because their security overviews can go alongside official documentation as supporting evidence. To make a PDF using the GitHub Security Report Action, create a new workflow in the repository that runs off a release, create a release, and see the new report that gets introduced. From there, you can get the supporting documentation you need, which will show whether or not you’re in compliance with certain security requirements.

Code scanning examples for DevSecOps architects

As a third-party security tool administrator/architect, I want to upload results from my current third-party tool into GitHub Advanced Security, so that developers can stay in GitHub to find all results and not have to switch between multiple tools. - DevSecOps Architect

For this example, you can use any third-party security scanning or code quality tool you like, as long as it supports SARIF. This means you can have three or four current tools along with GitHub code scanning.

Have a tool already in mind? Generate the SARIF and export it your standard way, and use the Upload SARIF API to upload the data. Check out how it looks in the GUI.

If you aren’t using a specific tool, there are plenty of tools within the GitHub Actions Marketplace. You can use the Aqua Security Trivy action as an example if you can’t find any others. Trivy is a third-party container tool that easily integrates with code scanning.

When the scan finishes and the data is uploaded, you can filter the results by the tool. Just head back to the Code Scanning Alerts tab within Security and filter by Tool, as shown in the screenshot below:

Figure 16: Image showing how you can filter results by tools.