зеркало из https://github.com/github/docs.git
GHAS adoption & onboarding (#21502)
* new article scaffolding * Add scaffolding * Migrate content for overview article * Add placeholder notes and migrate over some more content * First draft of updates to existing docs * Add H2 headers to the article * Draft of phase 0 content * Update phase 0 with more drafting * Fix subheaders and table formatting * Add unedited and slightly tweaked source material * Current draft of reworked content * Refactor everything * Add best practices and some partnership details * Touch-ups * Touch up intro and create a phased approaches reusable * Fix the intro * Move reusable * Add image for GHES versions * Fix links * Add HTML note around links that need to be versioned for GHEC once the GHEC version releases * Fix reusable * Tidy up session * Versioning around the links * migrate this content to another PR for easier reviewing * Add HTML note about versioning for GHEC * Revamp intro * Add product variables * Less is more in the intro * Fix the beginning * Copy-edits for first half * Add Markdown-friendly bullet points * unclear shift direction * Distinguish the rollout team roles * More active language & cut the note * Maybe too wordy * Edit facts section * Update the article path to fix tests * Add product variables for professional services * Another revision * More tidying * Fix spacing * Apply suggestions from code review Co-authored-by: Felicity Chapman <felicitymay@github.com> * Apply suggestions from code review Co-authored-by: Felicity Chapman <felicitymay@github.com> * Apply @felicitymay's input * Apply suggestions from code review Co-authored-by: Rachael Sewell <rachmari@github.com> * Fix link test by adding HTML note around GHEC only article for now * Apply @felicitymay's stellar input 🌠 Co-authored-by: Felicity Chapman <felicitymay@github.com> * Apply suggestions from code review * Apply suggestions from code review * GitHub Advanced Security "Deploying" guide (#22114) * Add draft content * Add gated features reusable * Revise draft * Revamp steps of phase 0 * Replace goals section with intro text * More revising * Standardize headers with sentence case & remove overview subheader * Phase 0 streamlined * Fix intro and GHAS Guidebook reference * Fix reusable * Phase 1 💖 * Phase 2 tightened * Standardize on subheaders * Update phase 3 * Add product variable * Fix some links to fix the tests * Apply @felicitymay's stellar input 🌠 Co-authored-by: Felicity Chapman <felicitymay@github.com> * Apply Felicity's input * Use more GHAS to ease the reading load * Update resusable * Replacing "organization" * Add dependency review verisoning Co-authored-by: “jmarlena” <“jmarlena@github.com”> Co-authored-by: Felicity Chapman <felicitymay@github.com> * Remove draft notes for appendix links * Fix subheader * Deploying before enabling GHAS * Replace organization * Fix variables * Add GHEC & GHES versioning * not sure why this space is a commit * Apply suggestions from code review Co-authored-by: Felicity Chapman <felicitymay@github.com> * Remove ghec versioning we don't need * Add repo reference * Remove versioning note ftw * Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> * Markdown, I love you Co-authored-by: Megan Christudas <meganchristudas@Megans-MBP.fios-router.home> Co-authored-by: jmarlena <jmarlena@github.com> Co-authored-by: “jmarlena” <“jmarlena@github.com”> Co-authored-by: jmarlena <6732600+jmarlena@users.noreply.github.com> Co-authored-by: Felicity Chapman <felicitymay@github.com> Co-authored-by: Rachael Sewell <rachmari@github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
This commit is contained in:
Megan Christudas
GitHub
Родитель
73e3647779
Коммит
14d80f1991
Двоичные данные
assets/images/enterprise/3.0/security/advanced-security-phased-approach-diagram.png
Normal file
Двоичные данные
assets/images/enterprise/3.0/security/advanced-security-phased-approach-diagram.png
Normal file
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 148 KiB |
Двоичные данные
assets/images/enterprise/3.1/advanced-security-phased-approach-diagram.png
Normal file
Двоичные данные
assets/images/enterprise/3.1/advanced-security-phased-approach-diagram.png
Normal file
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 148 KiB |
Двоичные данные
assets/images/enterprise/security/advanced-security-phased-approach-diagram.png
Normal file
Двоичные данные
assets/images/enterprise/security/advanced-security-phased-approach-diagram.png
Normal file
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 148 KiB |
|
|
@ -0,0 +1,426 @@
|
|||
---
|
||||
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 %}'
|
||||
miniTocMaxHeadingLevel: 3
|
||||
versions:
|
||||
ghes: '>=3.0'
|
||||
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 permission levels for an organization](/organizations/managing-access-to-your-organizations-repositories/repository-permission-levels-for-an-organization#permission-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, you can view, fix, dismiss, or delete alerts 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 removing and avoiding vulnerable dependencies.
|
||||
|
||||
| Dependency Management Tool | Description |
|
||||
|----|----|
|
||||
| Dependabot Alerts | You can track your repository's dependencies and receive Dependabot alerts when your enterprise detects vulnerable dependencies. For more information, see "[About alerts for vulnerable dependencies](/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 > 3.1 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 %}
|
||||
| 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 %}
|
||||
|
||||
{% note %}
|
||||
|
||||
**Note:** Dependabot security updates and version updates are currently only available for {% data variables.product.prodname_ghe_cloud %} and will be available for {% data variables.product.prodname_ghe_server %} as outlined in our [public roadmap](https://github.com/github/roadmap).
|
||||
|
||||
{% endnote %}
|
||||
|
||||
### 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.
|
||||
|
|
@ -24,6 +24,8 @@ When you enable {% data variables.product.prodname_GH_advanced_security %} for y
|
|||
When you enable {% data variables.product.prodname_GH_advanced_security %} for your enterprise, repository administrators in all organizations can enable the features. {% ifversion ghes = 3.0 %}For more information, see "[Managing security and analysis settings for your organization](/organizations/keeping-your-organization-secure/managing-security-and-analysis-settings-for-your-organization)" and "[Managing security and analysis settings for your repository](/github/administering-a-repository/managing-security-and-analysis-settings-for-your-repository)."{% endif %}
|
||||
{% endif %}
|
||||
|
||||
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)."
|
||||
|
||||
## Prerequisites for enabling {% data variables.product.prodname_GH_advanced_security %}
|
||||
|
||||
1. Upgrade your license for {% data variables.product.product_name %} to include {% data variables.product.prodname_GH_advanced_security %}.{% ifversion ghes > 3.0 %} For information about licensing, see "[About billing for {% data variables.product.prodname_GH_advanced_security %}](/billing/managing-billing-for-github-advanced-security/about-billing-for-github-advanced-security)."{% endif %}
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ redirect_from:
|
|||
- /admin/configuration/configuring-advanced-security-features
|
||||
versions:
|
||||
ghes: '*'
|
||||
ghec: '*'
|
||||
topics:
|
||||
- Enterprise
|
||||
children:
|
||||
|
|
@ -15,5 +16,6 @@ children:
|
|||
- /configuring-code-scanning-for-your-appliance
|
||||
- /configuring-secret-scanning-for-your-appliance
|
||||
- /viewing-your-github-advanced-security-usage
|
||||
- /overview-of-github-advanced-security-deployment
|
||||
- /deploying-github-advanced-security-in-your-enterprise
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,267 @@
|
|||
---
|
||||
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)."'
|
||||
miniTocMaxHeadingLevel: 3
|
||||
versions:
|
||||
ghes: '>=3.0'
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
|
@ -30,12 +30,12 @@ redirect_from:
|
|||
|
||||
{% data reusables.code-scanning.about-code-scanning %} For information, see "[About {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}](/code-security/secure-coding/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning-with-codeql)."
|
||||
|
||||
You can run {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} within {% data variables.product.product_name %} using {% data variables.product.prodname_actions %}. Alternatively, if you use a third-party continuous integration or continuous delivery/deployment (CI/CD) system, you can run {% data variables.product.prodname_codeql %} analysis in your existing system and upload the results to {% data variables.product.product_location %}.
|
||||
{% data reusables.code-scanning.codeql-context-for-actions-and-third-party-tools %}
|
||||
|
||||
{% ifversion fpt or ghes > 3.1 or ghae-next or ghec %}
|
||||
<!--Content for GitHub.com, GHAE next, and GHES 3.2 and onward. CodeQL CLI is the preferred method, and CodeQL runner is deprecated. -->
|
||||
|
||||
You add the {% data variables.product.prodname_codeql_cli %} to your third-party system, then call the tool to analyze code and upload the SARIF results to {% data variables.product.product_name %}. The resulting {% data variables.product.prodname_code_scanning %} alerts are shown alongside any alerts generated within {% data variables.product.product_name %}.
|
||||
{% data reusables.code-scanning.codeql-cli-context-for-third-party-tools %}
|
||||
|
||||
{% data reusables.code-scanning.upload-sarif-ghas %}
|
||||
|
||||
|
|
|
|||
|
|
@ -34,6 +34,16 @@ A {% data variables.product.prodname_GH_advanced_security %} license provides th
|
|||
|
||||
For information about {% data variables.product.prodname_advanced_security %} features that are in development, see "[{% data variables.product.prodname_dotcom %} public roadmap](https://github.com/github/roadmap)." For an overview of all security features, see "[{% data variables.product.prodname_dotcom %} security features](/code-security/getting-started/github-security-features)."
|
||||
|
||||
{% ifversion ghes > 2.22 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 %}](/admin/advanced-security/overview-of-github-advanced-security-deployment)."
|
||||
|
||||
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 ghes > 2.22 or ghae %}
|
||||
## Enabling {% data variables.product.prodname_advanced_security %} features on {% data variables.product.product_name %}
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
You add the {% data variables.product.prodname_codeql_cli %} to your third-party system, then call the tool to analyze code and upload the SARIF results to {% data variables.product.product_name %}. The resulting {% data variables.product.prodname_code_scanning %} alerts are shown alongside any alerts generated within {% data variables.product.product_name %}. 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)."
|
||||
|
|
@ -0,0 +1 @@
|
|||
You can run {% data variables.product.prodname_codeql %} {% data variables.product.prodname_code_scanning %} within {% data variables.product.product_name %} using {% data variables.product.prodname_actions %}. Alternatively, if you use a third-party continuous integration or continuous delivery/deployment (CI/CD) system, you can run {% data variables.product.prodname_codeql %} analysis in your existing system and upload the results to {% data variables.product.product_location %}.
|
||||
|
|
@ -0,0 +1 @@
|
|||
{% 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 {% data variables.product.prodname_GH_advanced_security %}](/get-started/learning-about-github/about-github-advanced-security)."
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
We’ve created a phased approach to {% data variables.product.prodname_GH_advanced_security %} (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 organization. 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 organization.
|
||||
|
||||
Based on our experience helping customers with a successful deployment of GHAS, we expect most customers will want to follow their rollout in our suggested phases.
|
||||
|
||||
Depending on the needs of your organization, you may need to modify this approach and alter or remove some phases or steps.
|
||||
|
||||
|
||||
|
|
@ -151,6 +151,10 @@ support_ticket_priority_high: 'High'
|
|||
support_ticket_priority_normal: 'Normal'
|
||||
support_ticket_priority_low: 'Low'
|
||||
|
||||
# GitHub Professional Services
|
||||
prodname_professional_services: 'GitHub Professional Services'
|
||||
prodname_professional_services_team: 'Professional Services'
|
||||
|
||||
# Security features / code scanning platform / Security Lab
|
||||
prodname_security: 'GitHub Security Lab'
|
||||
prodname_security_link: 'https://securitylab.github.com/'
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче