jprdonnelly/docs
1
0
Fork 0
mirror of synced 2025-12-19 18:10:59 -05:00
Code Issues Projects Releases Wiki Activity

Add GHAS resources

Browse Source
This commit is contained in:
Steve Guntrip
2022-07-15 14:57:26 +01:00
committed by GitHub
parent 969a4bd906
commit 74d6918dae
17 changed files with 589 additions and 702 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
content/admin/code-security/index.md
View File

@@ -4,7 +4,6 @@ shortTitle: Manage code security
intro: 'You can build security into your developers'' workflow with features that keep secrets and vulnerabilities out of your codebase, and that maintain your software supply chain.'
versions:
ghes: '*'
ghec: '*'
ghae: '*'
topics:
- Enterprise

423
content/admin/code-security/managing-github-advanced-security-for-your-enterprise/deploying-github-advanced-security-in-your-enterprise.md
View File

@@ -1,423 +0,0 @@
---
title: Deploying GitHub Advanced Security in your enterprise
intro: 'Learn how to plan, prepare, and implement a phased approach for rolling out {% data variables.product.prodname_GH_advanced_security %} (GHAS) in your enterprise.'
product: '{% data reusables.gated-features.advanced-security %}'
redirect_from:
- /admin/advanced-security/deploying-github-advanced-security-in-your-enterprise
miniTocMaxHeadingLevel: 3
versions:
ghes: '*'
ghec: '*'
type: how_to
topics:
- Advanced Security
- Code scanning
- Enterprise
- Security
---
## Overview of the deployment process
{% data reusables.security.overview-of-phased-approach-for-ghas-rollout %}
For a high-level summary of these different phases, see "[Overview of {% data variables.product.prodname_GH_advanced_security %} Deployment](/admin/advanced-security/overview-of-github-advanced-security-deployment)."
Before starting your deployment, we recommend you review the prerequisites for installing GHAS and best practices for GHAS deployment in "[Overview of {% data variables.product.prodname_GH_advanced_security %} Deployment](/admin/advanced-security/overview-of-github-advanced-security-deployment)."
## {% octicon "milestone" aria-label="The milestone icon" %} Phase 0: Planning & kickoff
{% note %}
{% octicon "clock" aria-label="Clock" %} **Estimated timing:** We estimate that phase 0 may last roughly between 1-4 weeks. This range can vary depending on your release needs and any necessary approvals your company may need on the deployment plan.
{% endnote %}
The goal of the planning and kickoff phase is to ensure that you have all of your people, processes, and technologies set up and ready for implementing GHAS.
To help you reach buy-in from the executive sponsor, we recommend preparing and aligning on a rollout plan and goals before releasing GHAS in your enterprise.
As a part of a phased rollout strategy, we recommend that you identify high-impact and critical teams or applications that should be targeted to join GHAS before the rest of your enterprise.
If a phased rollout doesn't work for your enterprise, you can skip to the [pilot project phase](#--phase-1-pilot-projects).
If you’re working with {% data variables.product.prodname_professional_services %}, during this phase you will also establish a plan for how your teams will work together throughout the rollout and implementation process. The {% data variables.product.prodname_professional_services_team %} team can support you with the creation of the phased rollout plan and goals as needed.
### Step 1: Kickoff meeting with {% data variables.product.prodname_professional_services %} (optional)
If you signed up for {% data variables.product.prodname_professional_services %}, you’ll begin the rollout and implementation process by meeting with your Services representative.
If you haven't signed up for {% data variables.product.prodname_professional_services %}, you can skip to the next step.
The goal of this meeting is to align the two teams on the necessary information to begin crafting a rollout and implementation plan that will work best for your company. In preparation for this meeting, we have created a survey that will help us better prepare for the discussion. Your Services representative will send you this survey.
To help you prepare for this initial meeting, review these topics.
- Aligning on how your company and {% data variables.product.prodname_professional_services %} will work best together
- Setting expectations on how to best utilize service hours/days purchased
- Communications plans/frequency of meetings
- Roles and responsibilities
- Review of how GHAS works within the Software Development Life cycle (SDLC). Your {% data variables.product.prodname_professional_services %} representative will explain how GHAS works.
- Review of best practices for deploying GHAS. This is offered as a refresher if your team finds it valuable or if your enterprise did not participate in the Proof of Concept (POC) exercise. This review includes a discussion of your existing Application Security program and its level of maturity, against something like the DevSecOps maturity model.
- Alignment on next steps for your GHAS deployment. Your {% data variables.product.prodname_professional_services %} representative will outline your next steps and the support you can expect from your partnership.
To help you plan your rollout strategy, you can also expect to discuss these questions:
- How many teams will be enabled?
- What is the anatomy of the teams’ repositories? (Tech stack, current tooling, etc.)
- Some of this might have already been covered during the Proof of Concept exercise if your company participated. If not, this is a crucial time to discuss this.
- What level of adoption do we expect to be organic, assisted, or inorganic?
- What does assisted adoption look like from a resourcing and documentation perspective?
- How will you manage inorganic adoption down the line? (For example, using policy enforcement or centrally managed workflows.)
### Step 2: Internal kickoff at your company
Whether or not your company chooses to work with {% data variables.product.prodname_professional_services %}, we always recommend you hold your own kickoff meeting to align your own team(s).
During this kickoff meeting, it's important to ensure there is a clear understanding of goals, expectations, and that a plan is in place for how to move forward with your rollout and implementation.
In addition, this is a good time to begin thinking about training and preparations for your team to ensure they have the right tools and expertise to support the rollout and implementation of GHAS.
#### Topics for your internal kickoff meeting
We recommend you cover these topics in your internal kickoff meeting at your company if you haven't already covered these with the same group in your kickoff meeting with {% data variables.product.prodname_professional_services %}.
- What are your business success metrics, how do you plan to measure and report on those measures?
- If these have not been defined, please define them. If they have been defined, communicate them and talk about how you plan to provide data-driven progress updates.
- Review of how GHAS works within the SDLC (Software Development Life cycle) and how this is
expected to work for your company.
- Review of best practices if your company did not participate in the Proof of Concept exercise (or a refresher if your team finds value in this review)
- How does this compare/contrast with your existing Application Security Program?
- Discuss and agree how your internal team will work best together throughout rollout and
implementation.
- Align on your communications plans and frequency of meetings for your internal team
- Review tasks for rollout and implementation completion, defining roles and responsibilities. We have outlined the majority of the tasks in this article, but there may be additional tasks your company requires we have not included.
- Consider establishing a “Champions Program” for scaled enablement
- Begin discussing timing for the completion of tasks
- Begin working on ideal rollout approaches that will work best for your company. This will include understanding a few important items:
- How many teams will be enabled? Some of this might have already been covered during the POC (Proof of Concept) exercise if your company participated. If not, this is a crucial time to discuss this.
- Of the critical applications identified for the initial rollout, how many are built on a technology supported by GHAS?
- How much organizational preparation is needed? To learn more, see "[Phase 2](#--phase-2-organizational-buy-in--rollout-preparation)."
### Step 3: Prepare your rollout & implementation plan and goals
Before you can move forward with pilot project(s) for the first phase of the rollout, it’s crucial to ensure a rollout plan and business goals have been established for how your company plans to proceed.
If you’re working with {% data variables.product.prodname_professional_services %}, they can play a significant role in the creation of this plan.
If you’re working independently, this section outlines some things to ensure are included in your plan as you prepare to move forward.
Plans for process changes (if needed) and training for team members as needed:
- Documented team assignments for roles and responsibilities. For more information on the permissions required for each feature, see "[Repository roles for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#access-requirements-for-security-features)."
- Documented plan of tasks and timelines/timeframes where possible. This should include infrastructure changes, process changes/training, and all subsequent phases of enablement of GHAS, allowing for timeframes for remediations and configuration adjustments as needed. For more information, see "[Phase 1: Pilot projects(s)](/admin/advanced-security/deploying-github-advanced-security-in-your-enterprise#--phase-1-pilot-projects)" below.
- Prioritized plan for which projects/teams will have GHAS enabled first, and subsequent
plans for which projects/teams will come in following phases
- Success metrics based on business goals. This will be a crucial reference point following the Pilot Project(s) to gain buy-in for the full rollout.
{% note %}
**Note:** To ensure awareness, buy-in, and adoption comes from all groups in your company, it's important to set realistic expectations around the rollout timing and impact on your company's infrastructure, processes, and general day-to-day development workflows. For a smoother and more successful rollout, ensure your security and development teams understand the impact of GHAS.
{% endnote %}
{% ifversion ghes %}
For {% data variables.product.prodname_ghe_server %} customers, to help ensure your instance can support the rollout and implementation of GHAS, review the following:
- While upgrading to GHES 3.0 is not required, you must upgrade to GHES 3.0 or higher to take advantage of feature combinations such as code scanning and {% data variables.product.prodname_actions %}. For more information, see "[Upgrading {% data variables.product.prodname_ghe_server %}](/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server)."
- In a high availability configuration, a fully redundant secondary {% data variables.product.prodname_ghe_server %} appliance is kept in sync with the primary appliance through replication of all major datastores. For more information on setting up high availability, see "[Configuring High Availability](/admin/enterprise-management/configuring-high-availability)."
- To help support any discussions regarding potential changes to your company's set up, you can review the {% data variables.product.prodname_ghe_server %} system overview. For more information, see "[System overview](/admin/overview/system-overview)."
{% endif %}
### Step 4: Establish a baseline of organizational insights
As your company prepares to begin your pilot project(s), it’s crucial to ensure that you have set a baseline for where your enterprise is today and have defined clear success metrics to measure your pilot project(s) progress against.
There are likely key business goals your company has that will need to be measured
against, but there are other metrics we can identify to help gauge your pilot’s success.
As a starting point, some of these metrics might include:
- The mean time to remediation for GHAS vulnerabilities versus the previous tooling and
practices the pilot project(s) / team(s) utilized.
- The code scanning integration's findings for the top X most critical applications.
- The number of applications that have SAST (Static application security testing) integrated versus before the engagement.
If you participated in the POC exercise prior to purchasing GHAS, these objectives might look familiar. This success criteria includes several objectives for the following high-level roles:
- Implementation & Administration teams
- Security / CISO (Chief Information Security Officer)
- Application Development Teams
If you’d like to take things a step further, you can look at utilizing OWASP’s DevSecOps
Maturity Model (DSOMM) to work towards reaching a Level 1 maturity. There are four main
evaluation criteria in DSOMM:
- **Static depth:** How comprehensive is the static code scan that you’re performing within
the AppSec CI pipeline
- **Dynamic depth:** How comprehensive is the dynamic scan that is being run within the
AppSec CI pipeline
- **Intensity:** Your schedule frequency for the security scans running in AppSec CI pipeline
- **Consolidation:** Your remediation workflow for handling findings and process
completeness
To learn more about this approach and how to implement it in GHAS,
you can download our white paper "[Achieving DevSecOps Maturity with GitHub](https://resources.github.com/whitepapers/achieving-devsecops-maturity-github/)."
Based on your wider company’s goals and current levels of DevSecOps maturity, we can help you determine how to best measure your pilot’s progress and success.
## {% octicon "milestone" aria-label="The milestone icon" %} Phase 1: Pilot project(s)
{% note %}
{% octicon "clock" aria-label="Clock" %} **Estimated timing:** We estimate that phase 1 may last roughly between 2 weeks to 3+ months. This range can vary largely depending on your company’s infrastructure or systems complexity, internal processes to manage/approve these changes, as well as if larger organizational process changes are needed to move forward with GHAS.
{% endnote %}
To begin enabling GHAS across your company, we recommend beginning with a few
high-impact projects or teams to pilot an initial rollout. This will allow an initial
group within your company to get familiar with GHAS and build a solid foundation on GHAS before rolling out to the remainder of your company.
Before you start your pilot project(s), we recommend that you schedule some checkpoint meetings for your team(s), such as an initial meeting, midpoint review, and a wrap-up session when the pilot is complete. These checkpoint meetings will help you all make adjustments as needed and ensure your team(s) are prepared and supported to complete the pilot successfully.
These steps will help you enable GHAS on your enterprise, begin using its features, and review your results.
If you’re working with {% data variables.product.prodname_professional_services %}, they can provide additional assistance through this process through onboarding sessions, GHAS workshops, and troubleshooting as needed.
### Step 1: GHAS set-up & installation
{% ifversion ghes %}
If you haven't already enabled GHAS for your {% data variables.product.prodname_ghe_server %} instance, see "[Enabling GitHub Advanced Security for your enterprise](/admin/advanced-security/enabling-github-advanced-security-for-your-enterprise)."
{% endif %}
You need to enable GHAS for each pilot project, either by enabling the GHAS feature for each repository or for all repositories in any organizations taking part in the project. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)" or "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)"
The vast majority of GHAS set-up and installation is centered around enabling and configuring code scanning on your enterprise and in your repositories.
Code scanning allows you to analyze code in a {% data variables.product.prodname_dotcom %} repository to find security vulnerabilities and coding errors. Code scanning can be used to find, triage, and prioritize fixes for existing problems in your code, as well as help prevent developers from introducing new problems that may otherwise reach production. For more information, see "[About code scanning](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)."
### Step 2: Set up {% data variables.product.prodname_code_scanning_capc %}
{% ifversion ghes %}
To enable {% data variables.product.prodname_code_scanning %} on your {% data variables.product.prodname_ghe_server %} instance, see "[Configuring code scanning for your appliance](/admin/advanced-security/configuring-code-scanning-for-your-appliance)."
{% endif %}
To set up code scanning, you must decide whether you'll run code scanning with [{% data variables.product.prodname_actions %}](#using-github-actions-for-code-scanning) or your own [third-party CI system](#using-a-third-party-ci-system-with-the-codeql-cli-for-code-scanning).
#### Using {% data variables.product.prodname_actions %} for {% data variables.product.prodname_code_scanning %}
{% ifversion ghes %}
To set up code scanning with {% data variables.product.prodname_actions %} for {% data variables.product.prodname_ghe_server %}, you'll need to provision one or more self-hosted {% data variables.product.prodname_actions %} runners in your
environment. For more information, see "[Setting up a self-hosted runner](/admin/advanced-security/configuring-code-scanning-for-your-appliance#running-code-scanning-using-github-actions)."
{% endif %}
For {% data variables.product.prodname_ghe_cloud %}, you can start to create a {% data variables.product.prodname_actions %} workflow using the [CodeQL action](https://github.com/github/codeql-action/) to run code scanning on a repository. {% data variables.product.prodname_code_scanning_capc %} uses [GitHub-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners) by default, but this can be customized if you plan to host your own runner with your own hardware specifications. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners)."
For more information about {% data variables.product.prodname_actions %}, see:
- "[Learn GitHub Actions](/actions/learn-github-actions)"
- "[Understanding GitHub Actions](/actions/learn-github-actions/understanding-github-actions)"
- "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows)"
- "[Filter Pattern Cheat Sheet](/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)"
#### Using a third-party CI system with the CodeQL CLI for {% data variables.product.prodname_code_scanning %}
If you’re not using {% data variables.product.prodname_actions %} and have your own continuous integration system, you can use the CodeQL CLI to perform CodeQL code scanning in a third-party CI system.
For more information, see:
- "[About CodeQL code scanning in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system)"
### Step 3: Enable {% data variables.product.prodname_code_scanning_capc %} in repositories
If you’re using a phased approach to roll out GHAS, we recommend enabling {% data variables.product.prodname_code_scanning %} on a repository-by-repository basis as part of your rollout plan. For more information, see "[Setting up code scanning for a repository](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository)."
If you’re not planning on a phased rollout approach and want to enable code scanning for many repositories, you may want to script the process.
For an example of a script that opens pull requests to add a {% data variables.product.prodname_actions %} workflow to multiple repositories, see the [`jhutchings1/Create-ActionsPRs`](https://github.com/jhutchings1/Create-ActionsPRs) repository for an example using PowerShell, or [`nickliffen/ghas-enablement`](https://github.com/NickLiffen/ghas-enablement) for teams who do not have PowerShell and instead would like to use NodeJS.
### Step 4: Run code scans and review your results
With code scanning enabled in the necessary repositories, you're ready to help your
development team(s) understand how to run code scans and reports, view reports, and process results.
#### {% data variables.product.prodname_code_scanning_capc %}
With code scanning, you can find vulnerabilities and errors in your project's code on GitHub,
as well as view, triage, understand, and resolve the related {% data variables.product.prodname_code_scanning %} alerts.
When code scanning identifies a problem in a pull request, you can review the highlighted
code and resolve the alert. For more information, see "[Triaging {% data variables.product.prodname_code_scanning %} alerts in pull requests](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests)."
If you have write permission to a repository you can manage code scanning alerts for that
repository. With write permission to a repository, {% ifversion delete-code-scanning-alerts %}you can view, fix, dismiss, or delete alerts {% else %}you can view, fix, or dismiss alerts{% endif %} for potential vulnerabilities or errors in your repository's code. For more information, see "[Managing code scanning alerts for your repository](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository)."
#### Generate reports of {% data variables.product.prodname_code_scanning %} alerts
If you’d like to create a report of your code scanning alerts, you can use the {% data variables.product.prodname_code_scanning_capc %} API. For more information, see the "[{% data variables.product.prodname_code_scanning_capc %} API](/rest/reference/code-scanning)."
For an example of how to use the {% data variables.product.prodname_code_scanning_capc %} API, see the [`get-code-scanning-alerts-in-org-sample`](https://github.com/jhutchings1/get-code-scanning-alerts-in-org-sample) repository.
### Step 5: Configure {% data variables.product.prodname_code_scanning_capc %} to fine tune your results
When running initial code scans, you may find that no results are found or that an unusual number of results are returned. You may want to adjust what is flagged in future scans.
For more information, see "[Configuring code scanning](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning)."
If your company wants to use other third-party code analysis tools with GitHub code scanning, you can use actions to run those tools within GitHub. Alternatively, you can upload results, generated by third-party tools as SARIF files, to code scanning. For more information, see "[Integrating with code scanning](/code-security/code-scanning/integrating-with-code-scanning)."
### Step 6: Set up secret scanning
GitHub scans repositories for known types of secrets, to prevent fraudulent use of secrets that were committed accidentally.
{% ifversion ghes %}
To enable secret scanning for your {% data variables.product.prodname_ghe_server %} instance, see "[Configuring secret scanning for your appliance](/admin/advanced-security/configuring-secret-scanning-for-your-appliance)."
{% endif %}
You need to enable secret scanning for each pilot project, either by enabling the feature for each repository or for all repositories in any organizations taking part in the project. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)" or "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)"
To learn how to view and close alerts for secrets checked into your repository, see "[Managing alerts from secret scanning](/code-security/secret-scanning/managing-alerts-from-secret-scanning)."
### Step 7: Set up dependency management
GitHub helps you avoid using third-party software that contains known vulnerabilities. We provide the following tools for updating vulnerable dependencies{% ifversion GH-advisory-db-supports-malware %} and removing malware{% endif %}.
| Dependency Management Tool | Description |
|----|----|
| Dependabot Alerts | You can track your repository's dependencies and receive Dependabot alerts when your enterprise detects insecure dependencies. For more information, see "[About {% data variables.product.prodname_dependabot_alerts %}](/code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/about-alerts-for-vulnerable-dependencies)." |
| Dependency Graph | The dependency graph is a summary of the manifest and lock files stored in a repository. It shows you the ecosystems and packages your codebase depends on (its dependencies) and the repositories and packages that depend on your project (its dependents). For more information, see "[About the dependency graph](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-the-dependency-graph)." |{% ifversion ghes or ghec %}
| Dependency Review | If a pull request contains changes to dependencies, you can view a summary of what has changed and whether there are known vulnerabilities in any of the dependencies. For more information, see "[About dependency review](/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)" or "[Reviewing Dependency Changes in a Pull Request](/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-dependency-changes-in-a-pull-request)." | {% endif %} {% ifversion ghec or ghes > 3.2 %}
| Dependabot Security Updates | Dependabot can fix vulnerable dependencies for you by raising pull requests with security updates. For more information, see "[About Dependabot security updates](/code-security/supply-chain-security/managing-vulnerabilities-in-your-projects-dependencies/about-dependabot-security-updates)." |
| Dependabot Version Updates | Dependabot can be used to keep the packages you use updated to the latest versions. For more information, see "[About Dependabot version updates](/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates)." | {% endif %}
{% data reusables.dependabot.beta-security-and-version-updates-onboarding %}
### Step 8: Establish a remediation process
Once your team(s) have been able to run scans, identify vulnerabilities and dependencies, and can consume the results of each security feature, the next step is to ensure that they can remediate the vulnerabilities identified within their normal development processes without involving your security team.
This means that the development teams understand how to utilize the GHAS features throughout the development process, can run scans, read reports, consume the results, and remediate vulnerabilities within their normal development workflows, without having to have a separate security phase at the end of development, or have a need to involve your security team to understand reports/results.
### Step 9: Set up custom analysis if needed
Custom analysis is an optional deeper use of code scanning when custom CodeQL queries are needed beyond the available default (and community) set of queries. The need for custom queries is rare.
Custom queries are used to identify custom security alerts or help developers follow coding standards by detecting certain code patterns.
If your company is interested in writing custom CodeQL queries, there are certain requirements your company should meet.
If your team can provide some examples of existing vulnerabilities you'd like to find via CodeQL, please let the GitHub team know and we can schedule an introductory session to review the basics of the language and discuss how to tackle one of your problems. If you want to cover CodeQL in more depth, then we offer additional engagement options to cover more topics to enable your team to build their own queries.
You can learn more about [CodeQL queries](https://codeql.github.com/docs/writing-codeql-queries/codeql-queries/) in our [CodeQL documentation](https://codeql.github.com/docs/codeql-overview/), or reach out to your {% data variables.product.prodname_professional_services %} team or sales representative.
### Step 10: Create & maintain documentation
All throughout the pilot phase, it’s essential to create and maintain high-quality internal documentation of the infrastructure and process changes made within your company, as well as learnings from the pilot process and configuration changes made as your team(s) progress throughout the rollout and implementation process.
Having thorough and complete documentation helps make the remaining phases of your rollout more of a repeatable process.
Good documentation also ensures that new teams can be onboarded consistently throughout the rollout process and as new team members join your team(s).
Good documentation doesn’t end when rollout and implementation are complete. The most helpful documentation is actively updated and evolves as your teams expand their experience using GHAS and as their needs grow.
In addition to your documentation, we recommend your company provides clear channels to your team(s) for support and guidance all throughout rollout, implementation, and beyond. Depending on the level of change your company needs to take on in order to support the rollout and implementation of GHAS, having well-supported teams will help ensure a successful adoption into your development teams’ daily workflow.
## {% octicon "milestone" aria-label="The milestone icon" %} Phase 2: Organizational buy-in & rollout preparation
{% note %}
{% octicon "clock" aria-label="Clock" %} **Estimated timing:** We estimate that phase 2 may last roughly between 1 week to over a month. This range can vary largely depending on your company’s internal approval processes.
{% endnote %}
One of the main goals of this phase is to ensure you have the organizational buy-in to make the full deployment of GHAS successful.
During this phase, your company reviews the results of the pilot project(s) to determine if the pilot was successful, what adjustments may need to be made, and if the company is ready to continue forward with the rollout.
Depending on your company’s approval process, organizational buy-in from your executive sponsor may be necessary to continue forward. In most cases, organizational buy-in from your team(s) is necessary to begin utilizing the value of GHAS for your company.
Before moving forward to the next phase of rolling out GHAS more widely across your company, modifications are often made to the original rollout plan based on learnings from the pilot.
Any changes that may impact the documentation should also be made to ensure it is current for continued rollout.
We also recommend that you consider your plan to train any teams or team members that will be introduced to GHAS in the next phases of your rollout if you haven't already.
### Step 1: Organize results
At the completion of Phase 1, your team(s) should have {% ifversion ghes %} GHAS enabled on your {% data variables.product.prodname_ghe_server %} instance and have{% endif %} been able to utilize all of the key features of GHAS successfully, potentially with some configuration changes to optimize results. If your company clearly defined success metrics in Phase 0, you should be able to measure against these metrics to determine the success of your pilot.
It’s important to revisit your baseline metrics when preparing your results to ensure that incremental progress can be demonstrated based on metrics collected from the pilot against your original business goals. If you need assistance with this information, GitHub can help by ensuring that your company has the right metrics to measure your progress against. For more information on help available, see "[GitHub services and support](/admin/advanced-security/overview-of-github-advanced-security-deployment#github-services-and-support)."
### Step 2: Secure organizational buy-in
Organizational buy-in will vary depending on a variety of factors, including your company’s size, approval process, or even the level of change required to rollout GHAS to name a few.
For some companies, securing buy-in is a one-time meeting, but for others, this process can take quite some time (potentially weeks or months). Buy-in may require approval from your executive sponsor or may require the adoption of GHAS into your teams’ daily workflows.
This duration of this stage is entirely up to your company and how quickly you would like to proceed. We recommend seeking support or services from GitHub where possible to help answer questions and provide any recommendations that may be needed to help support this process. For more information on help available, see "[GitHub services and support](/admin/advanced-security/overview-of-github-advanced-security-deployment#github-services-and-support)."
### Step 3: Revise and update documentation
Review the results and findings from your pilot project(s) and the needs of the remaining teams at your company. Based on your findings and needs analysis, update/revise your documentation.
We've found that it’s essential to ensure that your documentation is up-to-date before continuing with the rollout to the remainder of your company's enterprise.
### Step 4: Prepare a full rollout plan for your company
Based on what you learned from your pilot project(s), update the rollout plan you designed in stage 0. To prepare for rolling out to your company, consider any training your teams will need, such as training on using GHAS, process changes, or migration training if your enterprise is migrating to GitHub.
## {% octicon "milestone" aria-label="The milestone icon" %} Phase 3: Full organizational rollout & change management
{% note %}
{% octicon "clock" aria-label="Clock" %} **Estimated timing:** We estimate that phase 3 may
last anywhere from 2 weeks to multiple months. This range can vary largely depending on
your company’s size, number of repositories/teams, level of change the GHAS rollout will be for your company, etc.
{% endnote %}
Once your company has aligned on the results and findings from your pilot project(s) and all rollout preparation steps have been completed from Phase 2, you can move forward with the full rollout to your company based on your plan.
### Step 1: Evaluate your rollout as you go
If you're using a phased approach to rolling out GHAS, we recommend taking a brief pause and completing a short evaluation after rolling out GHAS to a different segment of your company to ensure the rollout is moving forward smoothly. Your evaluation can ensure that teams are enabled and trained properly, that any unique GHAS configuration needs are met, and that plans and documentation can be adjusted as needed.
### Step 2: Set up any needed training
When rolling GHAS out to any teams beyond your pilot project team(s), it’s important to ensure teams are either trained or there are training resources available to provide additional support where needed.
These are the main areas where we see companies needing further support:
- training on GHAS
- training for customers new to GitHub
- training on how to migrate to GitHub
Our {% data variables.product.prodname_professional_services_team %} team provides a variety of training services, bootcamps, and just general advice to help support your team(s) throughout the rollout and implementation process. For more information, see "[GitHub services and support](/admin/advanced-security/overview-of-github-advanced-security-deployment#github-services-and-support)."
To help support your teams, here's a recap of relevant GitHub documentation.
For documentation on how to enable GHAS, see:
- "[Enabling Advanced Security features](/get-started/learning-about-github/about-github-advanced-security)"
- "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)"
- "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)"
For documentation on how to migrate to GitHub, see:
- "[Importing source code to GitHub](/github/importing-your-projects-to-github/importing-source-code-to-github)"
For documentation on getting started with GitHub, see:
- "[Get started](/get-started)"
### Step 3: Help your company manage change
In step 4 of phase 2, we recommended that you update the initial rollout plan based on your learnings from the pilot project(s). Ensure that you continue to update your plan as you implement any necessary organizational changes to successfully roll out GHAS to your company.
Successful GHAS rollouts and the adoption of best practices into daily workflows depend on ensuring that your teams understand why it’s necessary to include security in their work.
### Step 4: Continued customization
Configuration and customization of GHAS are not complete once it’s rolled out across your company's enterprise. Further custom configuration changes should continue to be made over time to ensure GHAS continues to support your company's changing needs.
As your team becomes more experienced and skilled with GHAS over time, this will create additional opportunities for further customization.

2
content/admin/code-security/managing-github-advanced-security-for-your-enterprise/enabling-github-advanced-security-for-your-enterprise.md
View File

@@ -27,7 +27,7 @@ When you enable {% data variables.product.prodname_GH_advanced_security %} for y
{% endif %}
{% ifversion ghes %}
For guidance on a phased deployment of GitHub Advanced Security, see "[Deploying GitHub Advanced Security in your enterprise](/admin/advanced-security/deploying-github-advanced-security-in-your-enterprise)."
For guidance on a phased deployment of GitHub Advanced Security, see "[Introduction to adopting GitHub Advanced Security at scale](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale)."
{% endif %}
## Checking whether your license includes {% data variables.product.prodname_GH_advanced_security %}

3
content/admin/code-security/managing-github-advanced-security-for-your-enterprise/index.md
View File

@@ -9,14 +9,11 @@ redirect_from:
- /admin/advanced-security
versions:
ghes: '*'
ghec: '*'
topics:
- Enterprise
children:
- /enabling-github-advanced-security-for-your-enterprise
- /configuring-code-scanning-for-your-appliance
- /configuring-secret-scanning-for-your-appliance
- /overview-of-github-advanced-security-deployment
- /deploying-github-advanced-security-in-your-enterprise
---

269
content/admin/code-security/managing-github-advanced-security-for-your-enterprise/overview-of-github-advanced-security-deployment.md
View File

@@ -1,269 +0,0 @@
---
title: Overview of GitHub Advanced Security deployment
intro: 'Help your company successfully prepare to adopt {% data variables.product.prodname_GH_advanced_security %} (GHAS) by reviewing and understanding these best practices, rollout examples, and our enterprise-tested phased approach.'
product: '{% data variables.product.prodname_GH_advanced_security %} is a set of security features designed to make enterprise code more secure. It is available for {% data variables.product.prodname_ghe_server %} 3.0 or higher, {% data variables.product.prodname_ghe_cloud %}, and open source repositories. To learn more about the features, included in {% data variables.product.prodname_GH_advanced_security %}, see "[About GitHub Advanced Security](/get-started/learning-about-github/about-github-advanced-security)."'
redirect_from:
- /admin/advanced-security/overview-of-github-advanced-security-deployment
miniTocMaxHeadingLevel: 3
versions:
ghes: '*'
ghec: '*'
type: how_to
topics:
- Advanced Security
- Code scanning
- Enterprise
- Security
---
{% data variables.product.prodname_GH_advanced_security %} (GHAS) helps teams build more secure code faster using integrated tooling such as CodeQL, the world’s most advanced semantic code analysis engine. GHAS is a suite of tools that requires active participation from developers across your enterprise. To realize the best return on your investment, you must learn how to use, apply, and maintain GHAS to truly protect your code.
One of the biggest challenges in tackling new software for an company can be the rollout and implementation process, as well as bringing about the cultural change to drive the organizational buy-in needed to make the rollout successful.
To help your company better understand and prepare for this process with GHAS, this overview is aimed at:
- Giving you an overview of what a GHAS rollout might look like for your
company.
- Helping you prepare your company for a rollout.
- Sharing key best practices to help increase your company’s rollout
success.
To understand the security features available through {% data variables.product.prodname_GH_advanced_security %}, see "[{% data variables.product.prodname_dotcom %} security features](/code-security/getting-started/github-security-features)."
## Recommended phased approach for GHAS rollouts
We’ve created a phased approach to GHAS rollouts developed from industry and GitHub best practices. You can utilize this approach for your rollout, either in partnership with {% data variables.product.prodname_professional_services %} or independently.
While the phased approach is recommended, adjustments can be made based on the needs of your company. We also suggest creating and adhering to a timeline for your rollout and implementation. As you begin your planning, we can work together to identify the ideal approach and timeline that works best for your company.
![Diagram showing the three phases of GitHub Advanced Security rollout and deployment, including Phase 0: Planning & Kickoff, Phase 1: Pilot projects, Phase 2: Org Buy-in and Rollout for early adopters, and Phase 3: Full org rollout & change management](/assets/images/enterprise/security/advanced-security-phased-approach-diagram.png)
Based on our experience helping customers with a successful deployment of {% data variables.product.prodname_GH_advanced_security %}, we expect most customers will want to follow these phases. Depending on the needs of your company, you may need to modify this approach and alter or remove some phases or steps.
For a detailed guide on implementing each of these phases, see "[Deploying {% data variables.product.prodname_GH_advanced_security %} in your enterprise](/admin/advanced-security/deploying-github-advanced-security-in-your-enterprise)." The next section gives you a high-level summary of each of these phases.
### {% octicon "milestone" aria-label="The milestone icon" %} Phase 0: Planning & kickoff
During this phase, the overall goal is to plan and prepare for your rollout, ensuring that you have your people, processes, and technologies in place and ready for your rollout. You should also consider what success criteria will be used to measure GHAS adoption and usage across your teams.
### {% octicon "milestone" aria-label="The milestone icon" %} Phase 1: Pilot project(s)
To begin implementing GHAS, we recommend beginning with a few high-impact projects/teams with which to pilot an initial rollout. This will allow an initial group within your company to get familiar with GHAS, learn how to enable and configure GHAS, and build a solid foundation on GHAS before rolling out to the remainder of your company.
### {% octicon "milestone" aria-label="The milestone icon" %} Phase 2: Organizational buy-in & rollout preparation
Phase 2 is a recap of previous phases and preparing for a larger rollout across the remainder of the company. In this phase, organizational buy-in can refer to your company’s decision to move forward after the pilot project(s) or the company’s use and adoption of GHAS over time (this is most common). If your company decides to adopt GHAS over time, then phase 2 can continue into phase 3 and beyond.
### {% octicon "milestone" aria-label="The milestone icon" %} Phase 3: Full organizational rollout & change management
Once your company is in alignment, you can begin rolling GHAS out to the remainder of the company based on your rollout plan. During this phase, it’s crucial to ensure that a plan has been made for any organizational changes that may need to be made during your rollout of GHAS and ensuring teams understand the need, value, and impact of the change on current workflows.
## Best practices for a successful GHAS rollout
We’ve found that companies that have completed successful GHAS rollouts have several similar characteristics that help drive their success. To help your company increase the success of your GHAS rollout, review these best practices.
### {% octicon "checklist" aria-label="The checklist icon" %} Set clear goals for your company’s rollout
Setting goals may seem obvious, but we do see some companies that begin GHAS rollouts with no clear goals in mind. It’s more difficult for these companies to gain the true organizational buy-in that’s needed to complete the rollout process and realize the value of GHAS within their company.
As you begin planning for your rollout and implementation, begin outlining goals for GHAS within your company and ensure these are communicated to your team. Your goals can be highly detailed or something simple, as long as there is a starting point and alignment. This will help build a foundation for the direction of your company’s rollout and can help you build a plan to get there. If you need assistance with your goals, {% data variables.product.prodname_professional_services %} can help with recommendations based on our experience with your company and prior engagements with other customers.
Here are some high-level examples of what your goals for rolling out GHAS might look like:
- **Reducing the number of vulnerabilities:** This may be in general, or because your company was recently impacted by a significant vulnerability that you believe could have been prevented by a tool like GHAS.
- **Identifying high-risk repositories:** Some companies may simply want to target repositories that contain the most risk, ready to begin remediating vulnerabilities and reducing risk.
- **Increasing remediation rates:** This can be accomplished by driving developer adoption of findings and ensuring these vulnerabilities are remediated in a timely manner, preventing the accumulation of security debt.
- **Meeting compliance requirements:** This can be as simple as creating new compliance requirements or something more specific. We find many healthcare companies use GHAS to prevent the exposure of PHI (Personal Health Information).
- **Preventing secrets leakage:** This is often a goal of companies that have had (or want to prevent) critical information leaked such as software keys, customer or financial data, etc.
- **Dependency management:** This is often a goal for companies that may have fallen victim due to hacks from unpatched dependencies, or those seeking to prevent these types of attacks by updating vulnerable dependencies.
### {% octicon "checklist" aria-label="The checklist icon" %} Establish clear communication and alignment between your teams
Clear communication and alignment are critical to the success of any project, and the rollout of GHAS is no different. We’ve found that companies that have clear communication and alignment between their security and development groups, as well as their executive sponsor (either CISO or VP) from the purchase of GHAS through rollout, often have more success with their rollouts.
In addition to ensuring these groups are aligned throughout your GHAS rollout, there are a few specific areas we recommend focusing on.
#### Rollout planning
How will you roll out GHAS to your company? There will likely be many ideas and opinions. Here are some questions you should consider answering and aligning on before moving forward:
- What teams will be included in the pilot?
- What projects are focused on in the pilot?
- How should projects be prioritized for rollout?
- How do you plan to measure success in the pilot and beyond?
- What is the level of daily change your teams will be taking on? How will that be communicated?
- How will your rollout plans be communicated across the company?
- How do you plan to train your teams?
- How do you plan to manage scan results initially? (For more information, see the next section on "Processing results")
#### Processing results
Before GHAS is rolled out to your teams, there should be clear alignment on how results should be managed over time. We recommend initially looking at results as more informative and non-blocking. It’s likely your company has a full CI/CD pipeline, so we recommend this approach to avoid blocking your company’s process. As you get used to processing these results, then you can incrementally increase the level of restriction to a point that feels more accurate for your company.
### {% octicon "checklist" aria-label="The checklist icon" %} Lead your rollout with both your security and development groups
Many companies lead their GHAS rollout efforts with their security group. Often, development teams aren’t included in the rollout process until the pilot has concluded. However, we’ve found that companies that lead their rollouts with both their security and development teams tend to have more success with their GHAS rollout.
Why? GHAS takes a developer-centered approach to software security by integrating seamlessly into the developer workflow. Not having key representation from your development group early in the process increases the risk of your rollout and creates an uphill path towards organizational buy-in.
When development groups are involved earlier (ideally from purchase), security and development groups can achieve alignment early in the process. This helps to remove silos between the two groups, builds and strengthens their working relationships, and helps shift the groups away from a common mentality of “throwing things over the wall.” All of these things help support the overall goal to help companies shift and begin utilizing GHAS to address security concerns earlier in the development process.
#### {% octicon "people" aria-label="The people icon" %} Recommended key roles for your rollout team
We recommend a few key roles to have on your team to ensure that your groups are well represented throughout the planning and execution of your rollout and implementation.
We highly recommend your rollout team include these roles:
- **Executive Sponsor:** This is often the CISO, CIO, VP of Security, or VP of Engineering.
- **Technical Security Lead:** The technical security lead provides technical support on behalf of the security team throughout the implementation process.
- **Technical Development Lead:** The technical development lead provides technical support and will likely lead the implementation effort with the development team.
We also recommend your rollout team include these roles:
- **Project Manager:** We’ve found that the earlier a project manager can be introduced into the rollout process the higher the likelihood of success.
- **Quality Assurance Engineer:** Including a member of your company’s Quality Assurance team helps ensure process changes are taken into account for the QA team.
### {% octicon "checklist" aria-label="The checklist icon" %} Understand key GHAS facts to prevent common misconceptions
Going into a GHAS implementation, it’s important to understand some key basic facts about what GHAS is and can do, to prevent many common misconceptions companies have going into their GHAS rollouts.
{% note %}
**Note:** If you’re interested in furthering your GHAS education, {% data variables.product.prodname_professional_services %} provides a variety of options for additional education and training, including topics that your company needs to prepare for GHAS. These offerings may take the form of workshops, demonstrations, and bootcamps. Topics can range from deploying GHAS and basic usage of GHAS to more advanced topics to continue to build your team’s skills. For more information on working with the {% data variables.product.prodname_professional_services_team %} team, see "[{% data variables.product.prodname_professional_services %}](#github-professional-services)."
{% endnote %}
#### Fact 1: GHAS is a suite of security tools that require action to protect your code.
It’s not security software that is installed and forgotten—just having GHAS on its own does not protect your code. GHAS is a suite of tools that increases with value when configured, maintained, used in daily workflows, and in combination with other tools.
#### Fact 2: GHAS will require adjustment out of the box.
Once GHAS is set up on your repositories, there are additional steps that need to be taken to ensure it works for your company’s needs. Code scanning in particular requires further configuration to fine-tune your results, for example, customizing what is flagged by the scans to adjust what is picked up in future scans. Many customers find that initial scans either pick up no results or results that are not relevant based on the application's threat model and need to be adjusted to their company’s needs.
#### Fact 3: GHAS tools are most effective when used together, but the most effective AppSec programs involve the use of additional tools/activities.
GHAS is most effective when all of the tools are used together. When companies integrate GHAS with other tools and activities, such as penetration testing and dynamic scans, it further improves the effectiveness of the AppSec program. We recommend always utilizing multiple layers of protection.
#### Fact 4: Not all companies will use/need custom {% data variables.product.prodname_codeql %} queries, but they can help you customize/target scan results.
Code scanning is powered by {% data variables.product.prodname_codeql %}—the world’s most powerful code analysis engine. While many companies are excited at the prospect of being able to write custom queries, for a large portion of our customers the base query set and additional queries available in the community are typically more than sufficient. However, many companies may find the need for custom {% data variables.product.prodname_codeql %} queries to help reduce false positives rates in results or crafting new queries to target results your company may need.
However, if your company is interested in writing custom {% data variables.product.prodname_codeql %} queries, we recommend you complete your rollout and implementation of GHAS before exploring custom queries.
{% note %}
**Note:** It’s crucial for your company to have a solid foundation on GHAS before diving deeper into deeper security practices.
{% endnote %}
When your company is ready, our Customer Success team can help you navigate the requirements that need to be met and can help ensure your company has good use cases for custom queries.
#### Fact 5: {% data variables.product.prodname_codeql %} scans the whole code base, not just the changes made in a pull request.
When code scanning is run from a pull request, the scan will include the full codebase and not just the changes made in the pull request. While this may seem unnecessary at times, this is an important step to ensure the change has been reviewed all against all interactions in the codebase.
## Examples of successful {% data variables.product.prodname_GH_advanced_security %} rollouts
Now that you have a better understanding of some of the keys to a successful GHAS rollout and implementation, here are some examples of how our customers made their rollouts successful. Even if your company is in a different place, {% data variables.product.prodname_dotcom %} can help you with building a customized path that suits the needs of your rollout.
### Example rollout for a mid-sized healthcare technology company
A mid-sized healthcare technology company based out of San Francisco completed a successful GHAS rollout process. While they may not have had a large number of repositories that needed to be enabled, this company’s keys to success included having a well-organized and aligned team for the rollout, with a clearly established key contact to work with {% data variables.product.prodname_dotcom %} to troubleshoot any issues during the process. This allowed them to complete their rollout within two months.
In addition, having an engaged development team allowed the company to have teams using code scanning at the pull request level following the completion of their rollout.
### Example rollout for a mid-sized data platform company
A global data platform company has had great success with GHAS to date. They’ve completed their initial implementation and are currently progressing through the rollout process. This company is mature in their security posture and tooling, and are well-aligned as an company. This allows them to operate very self-sufficiently and has enabled them to move quickly and smoothly through their rollout.
This company's strong alignment, efficient operations, and security tooling maturity allowed them to implement GHAS quickly and build a good foundation for {% data variables.product.prodname_codeql %}. Since their implementation, they can now automatically enable {% data variables.product.prodname_codeql %} across different repositories.
In addition to their security and technical maturity, another critical key to this company’s success is having a project owner and single point of contact from their team to drive the project forward. Not only is having this key contact crucial, but they are incredibly resourceful and skilled, and directly contribute to the success of the rollout.
## Prerequisites for your company before rolling out GHAS
{% data variables.product.prodname_professional_services %} can help to provide additional support to help your company break down and understand these prerequisites and help you get prepared for the GHAS implementation process.
### CI/CD systems and process
If your company has not yet invested in or implemented continuous integration or continuous delivery (CI/CD) systems and processes, we recommend taking this step in conjunction with moving forward with GHAS. This may be a significant shift for your company—we can work with you to provide recommendations and guidance for implementing a CI/CD system, as well as supporting any training that might be needed.
### Requirements to install {% data variables.product.prodname_GH_advanced_security %}
There are a few different paths that can be taken for your GHAS installation based on what combinations of technologies your company uses. This section outlines a quick breakdown of the different paths your company may need to take.
{% ifversion ghes %}
#### {% data variables.product.prodname_ghe_server %}
It’s important that you’re utilizing a version of {% data variables.product.prodname_ghe_server %} (GHES) that will support your company’s needs.
If you’re using an earlier version of GHES (prior to 3.0) and would like to upgrade, there are some requirements that you’ll need to meet before moving forward with the upgrade. For more information, see:
- "[Upgrading {% data variables.product.prodname_ghe_server %}](/enterprise-server@2.22/admin/enterprise-management/updating-the-virtual-machine-and-physical-resources/upgrading-github-enterprise-server)"
- "[Upgrade requirements](/enterprise-server@2.20/admin/enterprise-management/upgrade-requirements)"
If you’re using a third-party CI/CD system and want to use {% data variables.product.prodname_code_scanning %}, make sure you have downloaded the {% data variables.product.prodname_codeql_cli %}. For more information, see "[About CodeQL code scanning in your CI system](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system/about-codeql-code-scanning-in-your-ci-system)."
If you're working with {% data variables.product.prodname_professional_services %} for your GHAS rollout, please be prepared to discuss these items at length in your kickoff meeting.
{% endif %}
{% ifversion ghec %}
#### {% data variables.product.prodname_ghe_cloud %}
If you’re a {% data variables.product.prodname_ghe_cloud %} (GHEC) customer there are prerequisites that you’ll need to meet depending on what CI/CD you plan to utilize.
Using {% data variables.product.prodname_actions %} for your CI/CD:
- To ensure {% data variables.product.prodname_code_scanning %} can be integrated and utilized properly, you should have a basic understanding of {% data variables.product.prodname_actions %} before proceeding with your installation.
Using a third-party tool for CI/CD:
- To integrate the {% data variables.product.prodname_codeql_cli %}, you should have a basic understanding of the CI/CD system, as well as *nix and Windows—in particular how commands are executed and how success/failure is signaled. For more information about how to integrate a third-party tool, see "[Using CodeQL code scanning with your existing CI system ](/code-security/code-scanning/using-codeql-code-scanning-with-your-existing-ci-system)."
{% endif %}
## Partnering with GitHub for your rollout
As you prepare for your GHAS implementation, it’s important to consider what will be required from your company to make this project successful. Our most successful implementations of GHAS rely on shared responsibilities between both GitHub and our customers throughout the process with a clearly identified stakeholder from the customer owning the project.
#### Success model for customer and GitHub responsibilities
**Customer responsibilities**
- Completing infrastructure and process prerequisites
- Managing rollout and implementation, including planning and execution
- Internal training
- (Optional) Contributing {% data variables.product.prodname_codeql %} queries to the GitHub Community
**GitHub responsibilities**
- Maintenance and enhancements for features, such as {% ifversion ghes %}{% data variables.product.prodname_ghe_server %}{% endif %}, {% data variables.product.prodname_actions %}, {% data variables.product.prodname_GH_advanced_security %}
- Providing, maintaining, and delivering the following services: {% data variables.product.prodname_dotcom %} Docs, {% data variables.product.prodname_dotcom %} Community, {% data variables.product.prodname_dotcom %} Support
{% note %}
**Note:** {% data variables.product.prodname_professional_services %} can help support many of the customer responsibilities. To learn more, see "[GitHub services and support](#github-services-and-support)."
{% endnote %}
## {% data variables.product.prodname_dotcom %} services and support
### {% data variables.product.prodname_dotcom %} Support
If you run into any issues during your implementation, you can search our deep documentation for solutions or engage with {% data variables.product.prodname_dotcom %} Support, a team of highly technical engineers that can support you as issues arise. For more information, see "[GitHub Enterprise Support](https://enterprise.github.com/support).
In addition, you can also try our [ {% data variables.product.prodname_gcf %}](https://github.community/).
If you purchased a Premium Support plan, you can submit your ticket in the [Premium Support Portal](https://enterprise.github.com/support). If you’re unsure of which Support plan you purchased, you can reach out to your sales representative or review the plan options.
For more information the Premium support plan options, see:
- "[Premium Support](https://github.com/premium-support)" {% ifversion ghec %}
- "[About GitHub Premium Support for {% data variables.product.prodname_ghe_cloud %}](/github/working-with-github-support/about-github-premium-support-for-github-enterprise-cloud)"{% endif %}{% ifversion ghes %}
- "[About GitHub Premium Support for {% data variables.product.prodname_ghe_server %}](/admin/enterprise-support/overview/about-github-premium-support-for-github-enterprise-server)"{% endif %}
### {% data variables.product.prodname_professional_services %}
Our {% data variables.product.prodname_professional_services_team %} team can partner with you for a successful rollout and implementation of {% data variables.product.prodname_GH_advanced_security %}. We offer a variety of options for the type of guidance and support you expect to need for your implementation. We also have training and bootcamps available to help your company to optimize the value of GHAS.
If you’d like to work with our {% data variables.product.prodname_professional_services_team %} team for your implementation, we recommend you begin thinking about your system design and infrastructure, as well as the number of repositories that you want to set up with GHAS, to begin these conversations. In addition, begin thinking about goals for what you would like to achieve with this rollout.
Implementation is just one step in a successful security-driven journey where you’ll learn how to use GHAS. Once you’ve completed your implementation, there will be more to learn with the rollout throughout your infrastructure and codebases. Speak with your sales representative for more information about all the {% data variables.product.prodname_professional_services_team %} options available.
If you initially opted out of additional services, but find that additional support is needed as you begin your implementation, please reach out to your sales representative to discuss what services options may be needed to support your implementation.

21
content/code-security/adopting-github-advanced-security-at-scale/index.md Normal file
View File

@@ -0,0 +1,21 @@
---
title: Adopting GitHub Advanced Security at scale
shortTitle: Adopting GHAS at scale
intro: "A phased approach to rolling out GitHub Advanced Security at your company using industry and GitHub best practices."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Secret scanning
- Advanced Security
- Repositories
children:
- /introduction-to-adopting-github-advanced-security-at-scale
- /phase-1-align-on-your-rollout-strategy-and-goals
- /phase-2-preparing-to-enable-at-scale
- /phase-3-pilot-programs
- /phase-4-create-internal-documentation
- /phase-5-rollout-and-scale-code-scanning
- /phase-6-rollout-and-scale-secret-scanning
---

54
content/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale.md Normal file
View File

@@ -0,0 +1,54 @@
---
title: Introduction to adopting GitHub Advanced Security at scale
intro: 'You can adopt {% data variables.product.prodname_GH_advanced_security %} at scale in your company following industry and GitHub best practices.'
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: Introduction
redirect_from:
- /admin/advanced-security/overview-of-github-advanced-security-deployment
- /admin/code-security/managing-github-advanced-security-for-your-enterprise/overview-of-github-advanced-security-deployment
- /admin/advanced-security/deploying-github-advanced-security-in-your-enterprise
- /admin/code-security/managing-github-advanced-security-for-your-enterprise/deploying-github-advanced-security-in-your-enterprise
miniTocMaxHeadingLevel: 2
---
## About these articles
{% data variables.product.prodname_GH_advanced_security %} (GHAS) helps teams build more secure code faster using integrated tooling such as secret scanning and code scanning using CodeQL. To understand the security features available through {% data variables.product.prodname_GH_advanced_security %}, see "[About GitHub Advanced Security](/get-started/learning-about-github/about-github-advanced-security)."
GHAS is a suite of tools that requires active participation from developers across your enterprise. To realize the best return on your investment, you must learn how to use, apply, and maintain GHAS.
We’ve created a phased approach to GHAS rollouts developed from industry and GitHub best practices. We expect most customers will want to follow these phases, based on our experience helping customers with a successful deployment of {% data variables.product.prodname_GH_advanced_security %}, but you may need to modify this approach to meet the needs of your company.
Enabling GHAS across a large organization can be broken down into six core phases.
1. [**Align on your rollout strategy and goals**](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals): Think about what success will look like, and align on how GHAS will be implemented in your company. This phase may only take a few days or a week, but it lays a solid foundation for the rest of the rollout.
2. [**Preparing to enable at scale**](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale): Prepare developers, collect data about your repositories, and ensure you're ready for the next phase.
3. [**Pilot programs**](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs): Optionally, pilot an initial rollout to a few high-impact projects and teams. This will allow an initial group within your company to get familiar with GHAS before you roll out to the remainder of your company.
4. [**Create internal documentation**](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation): Create and communicate internal documentation for the consumers of GHAS. Without proper documentation provided to developers, security engineers, and others who will be using GHAS, the value will get lost in the rollout.
5. [**Rollout and scale {% data variables.product.prodname_code_scanning %}**](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning): Leveraging the available APIs, automatically rollout {% data variables.product.prodname_code_scanning %} by team and by language across your enterprise, using the repository data you collected earlier.
6. [**Rollout and scale {% data variables.product.prodname_secret_scanning %}**](/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning): Roll out {% data variables.product.prodname_secret_scanning %}, which involves less configuration and is therefore simpler to adopt than {% data variables.product.prodname_code_scanning %}. Still, it's critical to have a strategy for handling new and old results.
## {% data variables.contact.github_support %} and {% data variables.product.prodname_professional_services_team %}
If you encounter any issues or have any questions during your implementation, you can search our documentation for solutions or engage with {% data variables.contact.github_support %}. For more information, see "[About GitHub Support](/support/learning-about-github-support/about-github-support)."
If you prefer to have guidance throughout the rollout process, {% data variables.product.prodname_professional_services %} can partner with you for a successful rollout and implementation of {% data variables.product.prodname_GH_advanced_security %}. We offer a variety of options for guidance and support. We also have training and bootcamps available to help your company to optimize the value of {% data variables.product.prodname_GH_advanced_security %}.
Speak with your sales representative for more information about all the Professional Services options available. For more information, contact {% data variables.contact.contact_enterprise_sales %}.
{% note %}
For the first article in this series, see "[Phase 1: Align on your rollout strategy and goals](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals)."
{% endnote %}

71
content/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals.md Normal file
View File

@@ -0,0 +1,71 @@
---
title: 'Phase 1: Align on your rollout strategy and goals'
intro: "Before enabling {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}, plan how GHAS should be rolled out across your enterprise."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: 1. Align on strategy
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the introduction to this series, see "[Introduction to adopting {% data variables.product.prodname_GH_advanced_security %} at scale](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale)."
{% endnote %}
### Set clear goals for your company’s rollout
To build a foundation for the direction of your company's rollout, outline goals for GHAS within your company, and communicate those goals to your team. Your goals can be simple or complex, as long as your team is aligned. If you need assistance with your goals, {% data variables.product.prodname_professional_services %} can provide recommendations based on our experience with your company and other customers.
Here are some high-level examples of what your goals for rolling out GHAS might look like:
- **Reducing the number of vulnerabilities**: This may be in general, or because your company was recently impacted by a significant vulnerability that you believe could have been prevented by a tool like GHAS.
- **Identifying high-risk repositories**: Some companies simply want to target repositories that contain the most risk, enabling them to reduce risk by remediating vulnerabilities.
- **Increasing remediation rates**: To prevent the accumulation of security debt, you may wish to drive developer adoption of findings and ensure these vulnerabilities are remediated in a timely manner.
- **Meeting compliance requirements**: For example, many healthcare companies use GHAS to prevent the exposure of PHI (Personal Health Information).
- **Preventing secrets leakage**: Many companies want to prevent critical information from being leaked, such as software keys or financial data.
### Lead your rollout with both your security and development groups
Companies that involve both their security and development teams in their GHAS rollouts tend to be more successful than companies who only involve their security group, waiting to include development teams once the pilot has concluded.
GHAS takes a developer-centered approach to software security by integrating seamlessly into the developer workflow. Having key representation from your development group early in the process decreases the risk of your rollout and encourages organizational buy-in.
Involving development groups earlier, ideally from the time of purchase, helps companies utilize GHAS to address security concerns earlier in the development process. When both groups work together, they achieve alignment early in the process, remove silos, build and strengthen their working relationships, and take more responsibility for the rollout.
### Learn about GHAS
To set realistic expectations for the rollout, ensure that all stakeholders understand the following key facts about how GHAS works.
#### 1. GHAS is a suite of security tools that require action to protect your code
GHAS is a suite of tools that increases with value when configured, maintained, used in daily workflows, and in combination with other tools.
#### 2. GHAS will require adjustment out of the box
After GHAS is set up on your repositories, you'll need to configure GHAS to meet your company’s needs. Code scanning in particular requires further customization, such as evaluating initial results and making adjustments for future scans. Many customers find that initial scans return limited or irrelevant results until code scanning is adjusted based on the application's threat model.
#### 3. GHAS tools are most effective when used together and integrated into your application security program
GHAS is most effective when all of the tools are used together. The effectiveness of your application security program is further improved by integrating GHAS with other tools and activities, such as penetration testing and dynamic scans. We recommend always utilizing multiple layers of protection.
#### 4. Custom {% data variables.product.prodname_codeql %} queries are used by some companies to customize and target scan results
Code scanning is powered by {% data variables.product.prodname_codeql %}, the world’s most powerful code analysis engine. For many of our customers, the base query set and additional queries available in the community are more than sufficient. However, other companies may require custom {% data variables.product.prodname_codeql %} queries to target different results or reduce false positives.
If your company is interested in custom {% data variables.product.prodname_codeql %} queries, we recommend completing your rollout and implementation of GHAS first. Then, when your company is ready, {% data variables.product.prodname_professional_services %} can help you navigate your requirements and ensure your company needs custom queries.
#### 5. {% data variables.product.prodname_codeql %} scans the whole codebase, not just the changes made in a pull request
When code scanning is run from a pull request, the scan will include the full codebase and not just the changes made in the pull request. Scanning the entire codebase is an important step to ensure the change has been reviewed all against all interactions in the codebase.
{% note %}
For the next article in this series, see "[Phase 2: Preparing to enable at scale](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale)."
{% endnote %}

153
content/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale.md Normal file
View File

@@ -0,0 +1,153 @@
---
title: 'Phase 2: Preparing to enable at scale'
intro: "In this phase you will prepare developers and collect data about your repositories to ensure your teams are ready and you have everything you need for pilot programs and rolling out {% data variables.product.prodname_code_scanning %} and {% data variables.product.prodname_secret_scanning %}."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: 2. Preparation
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the previous article in this series, see "[Phase 1: Align on your rollout strategy and goals](/code-security/adopting-github-advanced-security-at-scale/phase-1-align-on-your-rollout-strategy-and-goals)."
{% endnote %}
## Preparing to enable {% data variables.product.prodname_code_scanning %}
{% data reusables.code-scanning.about-code-scanning %} For more information, see "[About code scanning](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)."
Rolling {% data variables.product.prodname_code_scanning %} out across hundreds of repositories can be difficult, especially when done inefficiently. Following these steps will ensure your rollout is both efficient and successful. As part of your preparation, you will work with your teams, use automation to collect data about your repositories, and enable {% data variables.product.prodname_code_scanning %}.
### Preparing teams for {% data variables.product.prodname_code_scanning %}
First, prepare your teams to use {% data variables.product.prodname_code_scanning %}. The more teams that use {% data variables.product.prodname_code_scanning %}, the more data you'll have to drive remediation plans and monitor progress on your rollout. During this phase, focus on leveraging APIs and running internal enablement events.
Your core focus should be preparing as many teams to use {% data variables.product.prodname_code_scanning %} as possible. You can also encourage teams to remediate appropriately, but we recommend prioritizing enablement and use of {% data variables.product.prodname_code_scanning %} over fixing issues during this phase.
### Collecting information about your repositories
You can programmatically gather information about the different programming languages used in your repositories and use that data to enable {% data variables.product.prodname_code_scanning %} on all repositories that use the same language, using {% data variables.product.product_name %}'s GraphQL API.
{% note %}
**Note:** To gather this data without manually running the GraphQL queries described in this article, you can use our publicly available tool. For more information, see the "[ghas-enablement tool](https://github.com/NickLiffen/ghas-enablement)" repository.
{% endnote %}
If you want to gather information from repositories belonging to multiple organizations in your enterprise, you can use the query below to obtain the names of your organizations and then feed those into repository query. Replace OCTO-ENTERPRISE with your enterprise name.
```graphql
query {
enterprise(slug: "OCTO-ENTERPRISE") {
organizations(first: 100) {
totalCount
nodes {
name
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
You can identify which repositories use which languages by collating repositories by language at the organization level. You can modify the sample GraphQL query below, replacing OCTO-ORG with the organization name.
```graphql
query {
organization(login: "OCTO-ORG") {
repositories(first: 100) {
totalCount
nodes {
nameWithOwner
languages(first: 100) {
totalCount
nodes {
name
}
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
For more information about running GraphQL queries, see "[Forming calls with GraphQL](/graphql/guides/forming-calls-with-graphql)."
Then, convert the data from the GraphQL query into a readable format, such as a table.
| Language | Number of Repos | Name of Repos |
|-------------------------|-----------------|-----------------------------------------|
| JavaScript (TypeScript) | 4212 | org/repo<br /> org/repo |
| Python | 2012 | org/repo<br /> org/repo |
| Go | 983 | org/repo<br /> org/repo |
| Java | 412 | org/repo<br /> org/repo |
| Swift | 111 | org/repo<br /> org/repo |
| Kotlin | 82 | org/repo<br /> org/repo |
| C | 12 | org/repo<br /> org/repo |
You can filter out the languages that are currently not supported by {% data variables.product.prodname_GH_advanced_security %} from this table.
If you have repositories with multiple languages, you can format the GraphQL results as shown in the table below. Filter out languages that are not supported, but retain all repositories with at least one supported language. You can enable {% data variables.product.prodname_code_scanning %} on these repositories, and all supported languages will be scanned.
| Language(s) | Number of Repos | Name of Repos |
|------------------------|-----------------|------------------------------------------|
| JavaScript/Python/Go | 16 | org/repo <br /> org/repo |
| Rust/TypeScript/Python | 12 | org/repo <br /> org/repo |
An understanding of which repositories are using which languages will help you identify candidate repositories for pilot programs in phase 3, and prepares you to enable {% data variables.product.prodname_code_scanning %} across all repositories, one language at a time, in phase 5.
{% ifversion ghes %}
### Enabling {% data variables.product.prodname_code_scanning %} for your appliance
Before you can proceed with pilot programs and rolling out {% data variables.product.prodname_code_scanning %} across your enterprise, you must first enable {% data variables.product.prodname_code_scanning %} for your appliance. For more information, see "[Configuring code scanning for your appliance](/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance)."
{% endif %}
## Preparing to enable {% data variables.product.prodname_secret_scanning %}
If a project communicates with an external service, it might use a token or private key for authentication. If you check a secret into a repository, anyone who has read access to the repository can use the secret to access the external service with your privileges. {% data variables.product.prodname_secret_scanning_caps %} will scan your entire Git history on all branches present in your {% data variables.product.prodname_dotcom %} repositories for secrets and alert you{% ifversion secret-scanning-push-protection %} or block the push containing the secret{% endif %}. For more information, see "[About secret scanning](/code-security/secret-scanning/about-secret-scanning)."
### Considerations when enabling {% data variables.product.prodname_secret_scanning %}
{% data variables.product.product_name %}’s {% data variables.product.prodname_secret_scanning %} capability is slightly different from {% data variables.product.prodname_code_scanning %} since it requires no specific configuration per programming language or per repository and less configuration overall to get started. This means enabling {% data variables.product.prodname_secret_scanning %} at the organizational level can be easy but clicking **Enable All** at the organization level and ticking the option **Automatically enable {% data variables.product.prodname_secret_scanning %} for every new repository** has some downstream effects that you should be aware of:
- **License consumption**
Enabling {% data variables.product.prodname_secret_scanning %} for all repositories will consume all your licenses, even if no one is using code scanning. This is fine unless you plan to increase the number of active developers in your organization. If the number of active developers is likely to increase in the coming months, you may exceed your license limit and then be unable to use {% data variables.product.prodname_GH_advanced_security %} on newly created repositories.
- **Initial high volume of detected secrets**
If you are enabling {% data variables.product.prodname_secret_scanning %} on a large organization, be prepared to see a high number of secrets found. Sometimes this comes as a shock to organizations and the alarm is raised. If you would like to turn on {% data variables.product.prodname_secret_scanning %} across all repositories at once, plan for how you will respond to multiple alerts across the organization.
{% data variables.product.prodname_secret_scanning_caps %} can be enabled for individual repositories. For more information, see "[Configuring {% data variables.product.prodname_secret_scanning %} for your repositories](/code-security/secret-scanning/configuring-secret-scanning-for-your-repositories)." {% data variables.product.prodname_secret_scanning_caps %} can also be enabled for all repositories in your organization, as described above. For more information on enabling for all repositories, see "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-security-and-analysis-settings-for-your-organization)."
### Custom patterns for {% data variables.product.prodname_secret_scanning %}
{% ifversion ghae %}
{% note %}
**Note:** Custom patterns for {% data variables.product.prodname_secret_scanning %} is currently in beta and is subject to change.
{% endnote %}
{% endif %}
{% data variables.product.prodname_secret_scanning_caps %} detects a large number of default patterns but can also be configured to detect custom patterns, such as secret formats unique to your infrastructure or used by integrators that {% data variables.product.product_name %}'s {% data variables.product.prodname_secret_scanning %} does not currently detect. For more information about supported secrets for partner patterns, see "[Secret scanning patterns](/code-security/secret-scanning/secret-scanning-patterns)."
As you audit your repositories and speak to security and developer teams, build a list of the secret types that you will later use to configure custom patterns for {% data variables.product.prodname_secret_scanning %}. For more information, see "[Defining custom patterns for secret scanning](/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)."
{% note %}
For the next article in this series, see "[Phase 3: Pilot programs](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs)."
{% endnote %}

86
content/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs.md Normal file
View File

@@ -0,0 +1,86 @@
---
title: 'Phase 3: Pilot programs'
intro: "You may benefit from beginning with a few high-impact projects and teams with which to pilot an initial rollout. This will allow an initial group within your company to get familiar with GHAS, learn how to enable and configure GHAS, and build a solid foundation on GHAS before rolling out to the remainder of your company."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: 3. Pilot programs
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the previous article in this series, see "[Phase 2: Preparing to enable at scale](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale)."
{% endnote %}
## About pilot programs
We recommend you identify a few high-impact projects or teams to use in a pilot rollout of GHAS. This allows an initial group within your company to get familiar with GHAS and builds a solid foundation for GHAS before you roll it out to the remainder of your company.
The steps in this phase will help you enable GHAS on your enterprise, begin using its features, and review your results. If you’re working with {% data variables.product.prodname_professional_services %}, they can provide additional assistance through this process through onboarding sessions, GHAS workshops, and troubleshooting as needed.
Before you start your pilot projects, we recommend that you schedule some meetings for your teams, such as an initial meeting, midpoint review, and a wrap-up session when the pilot is complete. These meetings will help you all make adjustments as needed and ensure your teams are prepared and supported to complete the pilot successfully.
{% ifversion ghes %}
If you haven't already enabled GHAS for your {% data variables.product.prodname_ghe_server %} instance, see "[Enabling GitHub Advanced Security for your enterprise](/admin/advanced-security/enabling-github-advanced-security-for-your-enterprise)."
{% endif %}
You need to enable GHAS for each pilot project, either by enabling the GHAS features for each repository or for all repositories in any organizations taking part in the pilot. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)" or "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)"
## Piloting {% data variables.product.prodname_code_scanning %}
{% ifversion ghes %}
To enable {% data variables.product.prodname_code_scanning %} on your {% data variables.product.prodname_ghe_server %} instance, see "[Configuring code scanning for your appliance](/admin/advanced-security/configuring-code-scanning-for-your-appliance)."
{% elsif ghae %}
To enable {% data variables.product.prodname_code_scanning %} using {% data variables.product.prodname_actions %} you must make runners available to run workflows in {% data variables.product.prodname_ghe_managed %}, see "[Getting started with {% data variables.product.prodname_actions %} for {% data variables.product.prodname_ghe_managed %}](/admin/github-actions/getting-started-with-github-actions-for-your-enterprise/getting-started-with-github-actions-for-github-ae)."
{% endif %}
You can run code scanning on a repository by creating a {% data variables.product.prodname_actions %} workflow to run the [CodeQL action](https://github.com/github/codeql-action/). {% ifversion ghec %}{% data variables.product.prodname_code_scanning_capc %} uses [GitHub-hosted runners](/actions/using-github-hosted-runners/about-github-hosted-runners) by default, but this can be customized if you plan to host your own runner with your own hardware specifications. For more information, see "[About self-hosted runners](/actions/hosting-your-own-runners)."{% endif %}
For more information about {% data variables.product.prodname_actions %}, see:
- "[Learn GitHub Actions](/actions/learn-github-actions)"
- "[Understanding GitHub Actions](/actions/learn-github-actions/understanding-github-actions)"
- "[Events that trigger workflows](/actions/learn-github-actions/events-that-trigger-workflows)"
- "[Filter Pattern Cheat Sheet](/actions/learn-github-actions/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet)"
We recommend enabling {% data variables.product.prodname_code_scanning %} on a repository-by-repository basis as part of your pilot program. For more information, see "[Setting up code scanning for a repository](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/setting-up-code-scanning-for-a-repository)."
If you want to enable code scanning for many repositories, you may want to script the process.
For an example of a script that opens pull requests to add a {% data variables.product.prodname_actions %} workflow to multiple repositories, see the [`jhutchings1/Create-ActionsPRs`](https://github.com/jhutchings1/Create-ActionsPRs) repository for an example using PowerShell, or [`nickliffen/ghas-enablement`](https://github.com/NickLiffen/ghas-enablement) for teams who do not have PowerShell and instead would like to use NodeJS.
When running initial code scans, you may find that no results are found or that an unusual number of results are returned. You may want to adjust what is flagged in future scans. For more information, see "[Configuring code scanning](/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning)."
If your company wants to use other third-party code analysis tools with GitHub code scanning, you can use actions to run those tools within GitHub. Alternatively, you can upload results, which are generated by third-party tools as SARIF files, to code scanning. For more information, see "[Integrating with code scanning](/code-security/code-scanning/integrating-with-code-scanning)."
## Piloting {% data variables.product.prodname_secret_scanning %}
GitHub scans repositories for known types of secrets, to prevent fraudulent use of secrets that were committed accidentally.
{% ifversion ghes %}
To enable secret scanning for your {% data variables.product.prodname_ghe_server %} instance, see "[Configuring secret scanning for your appliance](/admin/advanced-security/configuring-secret-scanning-for-your-appliance)."
{% endif %}
You need to enable secret scanning for each pilot project, either by enabling the feature for each repository or for all repositories in any organizations taking part in the project. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)" or "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)."
If you have collated any custom patterns specific to your enterprise, especially any related to the projects piloting {% data variables.product.prodname_secret_scanning %}, you can configure those. For more information, see "[Defining custom patterns for secret scanning](/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)."
To learn how to view and close alerts for secrets checked into your repository, see "[Managing alerts from secret scanning](/code-security/secret-scanning/managing-alerts-from-secret-scanning)."
{% note %}
For the next article in this series, see "[Phase 4: Create internal documentation](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation)."
{% endnote %}

32
content/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: 'Phase 4: Create internal documentation'
intro: "You will create internal documentation and then communicate this to the consumers of {% data variables.product.prodname_GH_advanced_security %}."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: 4. Create internal documentation
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the previous article in this series, see "[Phase 3: Pilot programs](/code-security/adopting-github-advanced-security-at-scale/phase-3-pilot-programs)."
{% endnote %}
Before enabling {% data variables.product.prodname_GH_advanced_security %}, you should create internal documentation that defines processes for teams to follow. Everyone needs to know what to do when they receive a security alert, even if the process simply asks the team to apply their best judgment. Documentation will also prevent developers from getting blocked when they have questions. You should put the documentation about GHAS with existing developer-focused documentation, such as your developer portal or custom knowledge base.
If you ran pilot programs, use the experiences and feedback from the teams involved in those pilots to influence your documentation. This is especially useful if you encountered issues that are specific to your company, that other teams will also likely encounter.
If you skip creating internal documentation, your rollout won’t go at your intended pace. Creating internal documentation may slow the initial rollout by a week or two, but that time will be made up when developers can answer their own questions instead of coming to your team.
Education is probably the most crucial part of the rollout as it teaches developers what to do in different situations. You should ensure developers are empowered to maintain the security of their repository and that the security team are authorized to verify both what developers are doing and that it's in the best interest of security. In additional to internal documentation, education can take the form of online sessions, Q&As, etc.
{% note %}
For the next article in this series, see "[Phase 5: Rollout and scale code scanning](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning)."
{% endnote %}

56
content/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning.md Normal file
View File

@@ -0,0 +1,56 @@
---
title: 'Phase 5: Rollout and scale code scanning'
intro: "You can leverage the available APIs to rollout {% data variables.product.prodname_code_scanning %} programmatically by team and by language across your enterprise using the repository data you collected earlier."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: '5. Rollout code scanning'
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the previous article in this series, see "[Phase 4: Create internal documentation](/code-security/adopting-github-advanced-security-at-scale/phase-4-create-internal-documentation)."
{% endnote %}
### Enabling code scanning
Using the data you collated in [Phase 2](/code-security/adopting-github-advanced-security-at-scale/phase-2-preparing-to-enable-at-scale), you can begin to enable GHAS and then {% data variables.product.prodname_code_scanning %} on your repositories, one language at a time. The step-by-step process for enabling GHAS should look like this:
1. Enable GHAS on the repository. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)."
1. Create a pull request against the repository's default branch with a `codeql-analysis.yml` file containing an example of how to run CodeQL for that language. For more information, see "[Creating a pull request](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)."
1. Create an issue in the repository to explain why a pull request has been raised. The issue you create can contain a link to the previous communication sent to all users, but can also explain what changes the pull request introduces, what next steps the team have to take, what the team's responsibilities are, and how the team should be using {% data variables.product.prodname_code_scanning %}. For more information, see "[Creating an issue](/issues/tracking-your-work-with-issues/creating-an-issue)."
There is a publicly available tool that completes the first two steps called the [ghas-enablement tool](https://github.com/NickLiffen/ghas-enablement). You can re-run the ghas-enablement tool in batches of languages where it makes sense. For example, JavaScript, TypeScript, Python, and Go likely have a similar build process and could therefore use a similar CodeQL analysis file. The ghas-enablement tool can also be used for languages such as Java, C, and C++, but due to the varied nature of how these languages build and compile you may need to create more targeted CodeQL analysis files.
{% note %}
**Note:** If you are intending to use {% data variables.product.prodname_actions %} to control {% data variables.product.prodname_code_scanning %} and you do not use the [ghas-enablement tool](https://github.com/NickLiffen/ghas-enablement), keep in mind that there is no API access to the `.github/workflow` directory. This means that you cannot create a script without a git client underlying the automation. The workaround is to leverage bash scripting on a machine or container which has a git client. The git client can push and pull files into the `.github/workflows` directory where the `codeql-analysis.yml` file is located.
{% endnote %}
It is important to not just push the `codeql-analysis.yml` file the repository's default branch. Using a pull request puts ownership on the development team to review and merge, allowing the development team to learn about {% data variables.product.prodname_code_scanning %} and involving the team in the process.
You should capture the pull request URLs created by automation, and check each week for any activity and see which ones are closed. After a few weeks, it may be worth creating another issue or sending internal emails if the pull request remains unmerged.
### Creating subject matter experts
You can then proceed to the next stage of enablement, which is creating internal subject matter experts (or SMEs) and arranging company meetings. Opening pull requests and issues in repositories will likely tackle a large percentage of your adoption, but this doesn’t tackle one-off use cases where a specific build process, framework, or library needs specific feature flags to be enabled. A more personalized and hands-on approach is required to push high adoption, especially for Java, C, and C++.
It’s a good idea to run regular company meetings on specific topics to educate and discuss the rollout with a larger group. This is much more time-efficient for an enterprise with thousands of repositories compared to working with one team at a time. Teams can come to sessions that are relevant to them. Some example sessions that have been run before include:
- {% data variables.product.prodname_code_scanning_capc %} in a container
- {% data variables.product.prodname_code_scanning_capc %} & Java Struts
- {% data variables.product.prodname_code_scanning_capc %} & JSP
You can use the data you have collected about the distribution of different languages among repositories to create targeted meetings.
{% note %}
For the next article in this series, see "[Phase 6: Rollout and scale secret scanning](/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning)."
{% endnote %}

106
content/code-security/adopting-github-advanced-security-at-scale/phase-6-rollout-and-scale-secret-scanning.md Normal file
View File

@@ -0,0 +1,106 @@
---
title: 'Phase 6: Rollout and scale secret scanning'
intro: "For the final phase, you will focus on the rollout of {% data variables.product.prodname_secret_scanning %}. {% data variables.product.prodname_secret_scanning_caps %} is a more straightforward tool to rollout than {% data variables.product.prodname_code_scanning %}, as it involves less configuration, but it's critical to have a strategy for handling new and old results."
versions:
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Advanced Security
shortTitle: '6. Rollout secret scanning'
miniTocMaxHeadingLevel: 3
---
{% note %}
This article is part of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. For the previous article in this series, see "[Phase 5: Rollout and scale code scanning](/code-security/adopting-github-advanced-security-at-scale/phase-5-rollout-and-scale-code-scanning)."
{% endnote %}
You can enable secret scanning for individual repositories or for all repositories in an organization. For more information, see "[Managing security and analysis settings for your repository](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)" or "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)."
This article explains a high-level process focusing on enabling {% data variables.product.prodname_secret_scanning %} for all repositories in an organization. The principles described in this article can still be applied even if you take a more staggered approach of enabling {% data variables.product.prodname_secret_scanning %} for individual repositories.
### 1. Focus on newly committed secrets
When you enable {% data variables.product.prodname_secret_scanning %}, you should focus on remediating any newly committed credentials detected by secret scanning. If you focus on cleaning up committed credentials, developers could continue to accidentally push new credentials, which means your total secret count will stay around the same level, not decrease as intended. This is why it is essential to stop new credentials being leaked before focusing on revoking any current secrets.
There are a few approaches for tackling newly committed credentials, but one example approach would be:
1. **Notify**: Use webhooks to ensure that any new secret alerts are seen by the right teams as quickly as possible. A webhook fires when a secret alert is either created, resolved, or reopened. You can then parse the webhook payload, and integrate it into any tools you and your team use such Slack, Teams, Splunk, or email. For more information, see "[About webhooks](/developers/webhooks-and-events/webhooks/about-webhooks)" and "[Webhook events and payloads](/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#secret_scanning_alert)."
2. **Follow Up**: Create a high-level remediation process that works for all secret types. For example, you could contact the developer who committed the secret and their technical lead on that project, highlighting the dangers of committing secrets to GitHub, and asking the them to revoke, and update the detected secret.
{% note %}
**Note:** You can automate this step. For large enterprises and organizations with hundreds of repositories, manually following up is unsustainable. You could incorporate automation into the webhook process defined in the first step. The webhook payload contains repository and organization information about the leaked secret. Using this information, you can contact the current maintainers on the repository and create a email/message to the responsible people or open an issue.
{% endnote %}
3. **Educate**: Create an internal training document assigned to the developer who committed the secret. Within this training document, you can explain the risks created by committing secrets and direct them to your best practice information about using secrets securely in development. If the a developer doesn't learn from the experience and continues to commit secrets, you could create an escalation process, but education usually works well.
Repeat the last two steps for any new secrets leaked. This process encourages developers to take responsibility for managing the secrets used in their code securely, and allows you to measure the reduction in newly committed secrets.
{% note %}
**Note:** More advanced organizations may want to perform auto-remediation of certain types of secrets. There is an open-source initiative called [GitHub Secret Scanner Auto Remediator](https://github.com/NickLiffen/GSSAR) which you can deploy into your AWS, Azure, or GCP environment and tailor to automatically revoke certain types of secrets based on what you define as the most critical. This is also an excellent way to react to new secrets being committed with a more automated approach.
{% endnote %}
### 2. Remediate previously committed secrets, starting with the most critical
After you have established a process to monitor, notify and remediate newly published secrets, you can start work on secrets committed before {% data variables.product.prodname_GH_advanced_security %} was introduced.
How you define your most critical secrets will depend on your organization's processes and integrations. For example, a company likely isn’t worried about a Slack Incoming Webhook secret if they don’t use Slack. You may find it useful to start by focusing on the top five most critical credential types for your organization.
Once you have decided on the secret types, you can do the following:
1. Define a process for remediating each type of secret. The actual procedure for each secret type is often drastically different. Write down the process for each type of secret in a document or internal knowledge base.
{% note %}
**Note:** When you create the process for revoking secrets, try and give the responsibility for revoking secrets to the team maintaining the repository instead of a central team. One of the principles of GHAS is developers taking ownership of security and having the responsibility of fixing security issues, especially if they have created them.
{% endnote %}
2. When you have created the process that teams will follow for revoking credentials, you can collate information about the types of secrets and other metadata associated with the leaked secrets so you can discern who to communicate the new process to.
{% ifversion not ghae %}
You can use the security overview to collect this information. For more information about using the security overview, see "[Filtering alerts in the security overview](/code-security/security-overview/filtering-alerts-in-the-security-overview)."
{% endif %}
Some information you may want to collect includes:
- Organization
- Repository
- Secret type
- Secret value
- Maintainers on repository to contact
{% note %}
**Note:** Use the UI if you have few secrets leaked of that type. If you have hundreds of leaked secrets, use the API to collect information. For more information, see "[Secret scanning REST API](/rest/reference/secret-scanning)."
{% endnote %}
3. After you collect information about leaked secrets, create a targeted communication plan for the users who maintain the repositories affected by each secret type. You could use email, messaging, or even create GitHub issues in the affected repositories. If you can use APIs provided by these tools to send out the communications in an automated manner, this will make it easier for you to scale across multiple secret types.
### 3. Expand the program to include more secret types and custom patterns
You can now expand beyond the five most critical secret types into a more comprehensive list, with an additional focus on education. You can repeat the previous step, remediating previously committed secrets, for the different secret types you have targeted.
You can also include more of the custom patterns collated in the earlier phases and invite security teams and developer teams to submit more patterns, establishing a process for submitting new patterns as new secret types are created. For more information, see "[Defining custom patterns for secret scanning](/code-security/secret-scanning/defining-custom-patterns-for-secret-scanning)."
{% ifversion secret-scanning-push-protection %}
You can also enable push protection with secret scanning. Once enabled, secret scanning checks pushes for high-confidence secrets and blocks the push. For more information, see "[Protecting pushes with secret scanning](/code-security/secret-scanning/protecting-pushes-with-secret-scanning#using-secret-scanning-as-a-push-protection-from-the-command-line)."
{% endif %}
As you continue to build your remediation processes for other secret types, start to create proactive training material that can be shared with all developers of GitHub in your organization. Until this point, a lot of the focus has been reactive. It is an excellent idea to shift focus to being proactive and encourage developers not to push credentials to GitHub in the first place. This can be achieved in multiple ways but creating a short document explaining the risks and reasons would be a great place to start.
{% note %}
This is the final article of a series on adopting {% data variables.product.prodname_GH_advanced_security %} at scale. If you have questions or need support, see the section on {% data variables.contact.github_support %} and {% data variables.product.prodname_professional_services_team %} in "[Introduction to adopting {% data variables.product.prodname_GH_advanced_security %} at scale](/code-security/adopting-github-advanced-security-at-scale/introduction-to-adopting-github-advanced-security-at-scale#github-support-and-professional-services)."
{% endnote %}

1
content/code-security/getting-started/index.md
View File

@@ -17,4 +17,3 @@ children:
- /securing-your-organization
- /adding-a-security-policy-to-your-repository
---

1
content/code-security/index.md
View File

@@ -50,6 +50,7 @@ topics:
- Vulnerabilities
children:
- /getting-started
- /adopting-github-advanced-security-at-scale
- /secret-scanning
- /code-scanning
- /repository-security-advisories

5
content/get-started/learning-about-github/about-github-advanced-security.md
View File

@@ -63,12 +63,11 @@ For information about {% data variables.product.prodname_advanced_security %} fe
{% data variables.product.prodname_GH_advanced_security %} features are enabled for all public repositories on {% data variables.product.prodname_dotcom_the_website %}{% ifversion ghec %}, except for the security overview{% endif %}. Organizations that use {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_advanced_security %} can additionally enable these features for private and internal repositories. They also have access to an organization-level security overview. {% ifversion fpt %}For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/get-started/learning-about-github/about-github-advanced-security#enabling-advanced-security-features).{% endif %}
{% endif %}
{% ifversion ghes or ghec %}
{% ifversion ghes > 3.1 or ghec %}
## Deploying GitHub Advanced Security in your enterprise
To learn about what you need to know to plan your {% data variables.product.prodname_GH_advanced_security %} deployment at a high level, see "[Overview of {% data variables.product.prodname_GH_advanced_security %} deployment](/admin/advanced-security/overview-of-github-advanced-security-deployment)."
To learn about what you need to know to plan your {% data variables.product.prodname_GH_advanced_security %} deployment at a high level and to review the rollout phases we recommended, see "[Adopting {% data variables.product.prodname_GH_advanced_security %} at scale](/code-security/adopting-github-advanced-security-at-scale)."
To review the rollout phases we recommended in more detail, see "[Deploying {% data variables.product.prodname_GH_advanced_security %} in your enterprise](/admin/advanced-security/deploying-github-advanced-security-in-your-enterprise)."
{% endif %}
{% ifversion not fpt %}

5
lib/redirects/static/redirect-exceptions.txt
View File

@@ -551,3 +551,8 @@
- /enterprise-server@3.3/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
- /enterprise-server@3.4/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
- /enterprise-server@3.5/organizations/managing-membership-in-your-organization/exporting-member-information-for-your-organization
# We moved GHEC content from these categories
/enterprise-cloud@latest/code-security/adopting-github-advanced-security-at-scale
- /enterprise-cloud@latest/admin/code-security/managing-github-advanced-security-for-your-enterprise
- /enterprise-cloud@latest/admin/code-security