From d353009f77179bb909fbd10d7c2636f4f825d029 Mon Sep 17 00:00:00 2001 From: Felicity Chapman Date: Wed, 27 Nov 2024 22:19:38 +0000 Subject: [PATCH] Update docs for Organization security manager role expansion and GA (#53276) Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ...security-settings-for-your-organization.md | 14 +++-- ...out-enabling-security-features-at-scale.md | 2 +- ...-security-managers-in-your-organization.md | 26 +++++++-- .../roles-in-an-organization.md | 57 ------------------- data/features/org-sec-manager-update.yml | 6 ++ .../organizations/about-security-managers.md | 10 +++- .../pre-defined-organization-roles.md | 1 + .../security-manager-beta-note.md | 4 ++ 8 files changed, 53 insertions(+), 67 deletions(-) create mode 100644 data/features/org-sec-manager-update.yml diff --git a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md index 0f4b75fc3179..8ff637eeed67 100644 --- a/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md +++ b/content/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization.md @@ -1,7 +1,7 @@ --- title: Configuring global security settings for your organization shortTitle: Configure global settings -intro: 'Customize {% data variables.product.prodname_GH_advanced_security %} features and create security managers to strengthen the security of your organization.' +intro: 'Customize {% data variables.product.prodname_GH_advanced_security %} features to strengthen the security of your organization.' permissions: '{% data reusables.permissions.security-org-enable %}' versions: feature: security-configurations @@ -13,7 +13,7 @@ topics: ## About {% data variables.product.prodname_global_settings %} -Alongside {% data variables.product.prodname_security_configurations %}, which determine repository-level security settings, you should also configure {% data variables.product.prodname_global_settings %} for your organization. {% data variables.product.prodname_global_settings_caps %} apply to your entire organization, and can customize {% data variables.product.prodname_GH_advanced_security %} features based on your needs. You can also create security managers on the {% data variables.product.prodname_global_settings %} page to monitor and maintain your organization's security. +Alongside {% data variables.product.prodname_security_configurations %}, which determine repository-level security settings, you should also configure {% data variables.product.prodname_global_settings %} for your organization. {% data variables.product.prodname_global_settings_caps %} apply to your entire organization, and can customize {% data variables.product.prodname_GH_advanced_security %} features based on your needs. {% ifversion ghes < 3.16 %}You can also create a team of security managers to monitor and maintain your organization's security.{% endif %} ## Accessing the {% data variables.product.prodname_global_settings %} page for your organization @@ -131,6 +131,12 @@ You can define custom patterns for {% data variables.product.prodname_secret_sca ## Creating security managers for your organization -The security manager role grants members of your organization the ability to manage security settings and alerts across your organization. To grant all members of a team the security manager role, in the "Search for teams" text box, type the name of the desired team. In the dropdown menu that appears, click the team, then click **I understand, grant security manager permissions**. +The security manager role grants members of your organization the ability to manage security settings and alerts across your organization. Security managers can view data for all repositories in your organization through security overview. -Security managers can view data for all repositories in your organization through security overview. To learn more about the security manager role, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)." +To learn more about the security manager role, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)." + +{% ifversion ghes < 3.16 %} + +To grant all members of a team the security manager role, in the "Search for teams" text box, type the name of the desired team. In the dropdown menu that appears, click the team, then click **I understand, grant security manager permissions**. + +{% endif %} diff --git a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md b/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md index 76775a55374d..cd1050584536 100644 --- a/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md +++ b/content/code-security/securing-your-organization/introduction-to-securing-your-organization-at-scale/about-enabling-security-features-at-scale.md @@ -48,7 +48,7 @@ You can also create and manage security configurations using the REST API. For m ## About {% data variables.product.prodname_global_settings %} -While {% data variables.product.prodname_security_configurations %} determine repository-level security settings, {% data variables.product.prodname_global_settings %} determine your organization-level security settings, which are then inherited by all repositories. With {% data variables.product.prodname_global_settings %}, you can customize how security features analyze your organization, as well as create security managers with permission to manage security alerts and settings across your organization. +While {% data variables.product.prodname_security_configurations %} determine repository-level security settings, {% data variables.product.prodname_global_settings %} determine your organization-level security settings, which are then inherited by all repositories. With {% data variables.product.prodname_global_settings %}, you can customize how security features analyze your organization{% ifversion ghes < 3.16 %}, as well as grant a team permission to manage security alerts and settings across your organization{% endif %}. ## Next steps diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md index 14cdd849cec3..a2d600e2ef3b 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization.md @@ -1,8 +1,10 @@ --- title: Managing security managers in your organization -intro: You can give your security team the least access they need to configure and monitor code security for your organization by assigning a team to the security manager role. +intro: You can give your security experts the least access they need to configure and monitor code security for your organization using the security manager role. versions: - feature: security-managers + fpt: '*' + ghec: '*' + ghes: '*' topics: - Organizations - Teams @@ -16,7 +18,7 @@ permissions: Organization owners can assign the security manager role. ## Permissions for the security manager role -Members of a team with the security manager role have only the permissions required to effectively manage code security for the organization. +Organization members {% ifversion org-sec-manager-update %} and members of teams {% elsif ghes < 3.16 %}in a team {% endif %}assigned the security manager role have only the permissions required to effectively manage code security for the organization. * Read access on all repositories in the organization, in addition to any existing repository access * Write access on all security alerts in the organization {% ifversion not fpt %} @@ -25,11 +27,25 @@ Members of a team with the security manager role have only the permissions requi * The ability to configure code security settings at the repository level{% ifversion not fpt %}, including the ability to enable or disable {% data variables.product.prodname_GH_advanced_security %}{% endif %} {% ifversion fpt %} -Additional functionality, including a security overview for the organization, is available in organizations that use {% data variables.product.prodname_ghe_cloud %} with {% data variables.product.prodname_advanced_security %}. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). +Additional functionality, including a security overview for the organization, is available in organizations that use {% data variables.product.prodname_ghe_cloud %}. For more information, see the [{% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization). {% endif %} If a team has the security manager role, people with admin access to the team and a specific repository can change the team's level of access to that repository but cannot remove the access. For more information, see "[AUTOTITLE](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/managing-team-access-to-an-organization-repository)" and "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository)." +{% ifversion org-sec-manager-update %} + +## Managing security managers in your organization + +You can assign the pre-defined security manager role to either an organization team or directly to an organization member. Larger organizations may want to create a dedicated team for security management. This approach is especially useful if you want to assign additional permissions to your security experts. + +For information about assigning roles to users and teams, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/using-organization-roles)." + +## Creating a custom security role + +You can create custom security roles for your organization with reduced or increased access, as needed. For example, you might create a security role limited to managing secret scanning results and bypass requests, or you might create a combined security and audit log role. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-custom-organization-roles)." + +{% else %} + ## Assigning the security manager role to a team in your organization You can assign the security manager role to a maximum of 10 teams in your organization. @@ -53,3 +69,5 @@ You can assign the security manager role to a maximum of 10 teams in your organi {% data reusables.organizations.security-and-analysis %} {% endif %} 1. Under **Security managers**, next to the team you want to remove as security managers, click {% octicon "x" aria-label="Remove TEAM" %}. + +{% endif %} diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md index 022eeb18b75a..45e853db33d8 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md @@ -68,8 +68,6 @@ Billing managers are users who can manage the billing settings for your organiza {% endif %} -{% ifversion security-managers %} - ### Security managers {% data reusables.organizations.security-manager-beta-note %} @@ -77,7 +75,6 @@ Billing managers are users who can manage the billing settings for your organiza {% data reusables.organizations.about-security-managers %} If your organization has a security team, you can use the security manager role to give members of the team the least access they need to the organization. For more information, see "[AUTOTITLE](/organizations/managing-peoples-access-to-your-organization-with-roles/managing-security-managers-in-your-organization)." -{% endif %} ### {% data variables.product.prodname_github_app %} managers @@ -278,60 +275,6 @@ Some of the features listed below are limited to organizations using {% data var {% endrowheaders %} -{% else %} - - -{% rowheaders %} - -| Organization action | Owners | Members | -|:--------------------|:------:|:-------:| -| Invite people to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Edit and cancel invitations to join the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Remove members from the organization | {% octicon "check" aria-label="Yes" %} |{% octicon "x" aria-label="No" %} | -| Reinstate former members to the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Add and remove people from **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Promote organization members to _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Configure code review assignments (see "[AUTOTITLE](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)")) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Add collaborators to **all repositories** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Access the organization audit log | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Edit the organization's profile page (see "[AUTOTITLE](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghes %} | -| Verify the organization's domains (see "[AUTOTITLE](/organizations/managing-organization-settings/verifying-or-approving-a-domain-for-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Restrict email notifications to verified or approved domains (see "[AUTOTITLE](/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/restricting-email-notifications-for-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Delete **all teams** | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Delete the organization account, including all repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Create teams (see "[AUTOTITLE](/organizations/managing-organization-settings/setting-team-creation-permissions-in-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| See all organization members and teams | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| @mention any visible team | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Can be made a _team maintainer_ | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| Transfer repositories | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Manage an organization's SSH certificate authorities (see "[AUTOTITLE](/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion projects-v1 %} | -| Create {% data variables.projects.projects_v1_boards %} (see "[AUTOTITLE](/organizations/managing-access-to-your-organizations-project-boards/project-board-permissions-for-an-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| {% ifversion team-discussions %} | -| View and post public team discussions to **all teams** (see "[AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| View and post private team discussions to **all teams** (see "[AUTOTITLE](/organizations/collaborating-with-your-team/about-team-discussions)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Edit and delete team discussions in **all teams** (for more information, see "[AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments)) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Hide comments on commits, pull requests, and issues (see "[AUTOTITLE](/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment)") | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | {% octicon "check" aria-label="Yes" %} | -| {% ifversion team-discussions %} | -| Disable team discussions for an organization (see "[AUTOTITLE](/organizations/organizing-members-into-teams/disabling-team-discussions-for-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| Set a team profile picture in **all teams** (see "[AUTOTITLE](/organizations/organizing-members-into-teams/setting-your-teams-profile-picture)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% ifversion ghes %} | -| Manage the publication of {% data variables.product.prodname_pages %} sites from repositories in the organization (see "[AUTOTITLE](/organizations/managing-organization-settings/managing-the-publication-of-github-pages-sites-for-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| {% endif %} | -| [Move teams in an organization's hierarchy](/organizations/organizing-members-into-teams/moving-a-team-in-your-organizations-hierarchy) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Pull (read), push (write), and clone (copy) _all repositories_ in the organization | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Convert organization members to {% ifversion repository-collaborators %}[outside collaborators or repository collaborators](#outside-collaborators-or-repository-collaborators){% else %}[outside collaborators](#outside-collaborators){% endif %} | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| [View people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| [Export a list of people with access to an organization repository](/organizations/managing-user-access-to-your-organizations-repositories/managing-repository-roles/viewing-people-with-access-to-your-repository#exporting-a-list-of-people-with-access-to-your-repository) | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | -| Manage default labels (see "[AUTOTITLE](/organizations/managing-organization-settings/managing-default-labels-for-repositories-in-your-organization)") | {% octicon "check" aria-label="Yes" %} | {% octicon "x" aria-label="No" %} | - -{% endrowheaders %} - {% endif %} ## Further reading diff --git a/data/features/org-sec-manager-update.yml b/data/features/org-sec-manager-update.yml new file mode 100644 index 000000000000..096698351e42 --- /dev/null +++ b/data/features/org-sec-manager-update.yml @@ -0,0 +1,6 @@ +# Issue #1115697 +# Documentation for updates to the organization-level security manager role +versions: + fpt: '*' + ghec: '*' + ghes: '>=3.16' diff --git a/data/reusables/organizations/about-security-managers.md b/data/reusables/organizations/about-security-managers.md index 8693206fc965..282c8f4db5c5 100644 --- a/data/reusables/organizations/about-security-managers.md +++ b/data/reusables/organizations/about-security-managers.md @@ -1 +1,9 @@ -Security manager is an organization-level role that organization owners can assign to any team in an organization. When applied, it gives every member of the team permissions to view security alerts and manage settings for code security across your organization, as well as read permissions for all repositories in the organization. +{% ifversion org-sec-manager-update %} + +The security manager role is an organization-level role that organization owners can assign to any member or team in the organization. When applied, it gives permission to view security alerts and manage settings for code security across your organization, as well as read permission for all repositories in the organization. + +{% elsif ghes < 3.16 %} + +Security manager is an organization-level role that organization owners can assign to any team in an organization. When applied, it gives every member of the team permission to view security alerts and manage settings for code security across your organization, as well as read permission for all repositories in the organization. + +{% endif %} diff --git a/data/reusables/organizations/pre-defined-organization-roles.md b/data/reusables/organizations/pre-defined-organization-roles.md index 6981b8661440..78312499147a 100644 --- a/data/reusables/organizations/pre-defined-organization-roles.md +++ b/data/reusables/organizations/pre-defined-organization-roles.md @@ -9,4 +9,5 @@ The current set of pre-defined roles are: * **All-repository admin**: Grants admin access to all repositories in the organization. {%- ifversion fpt or ghec or ghes > 3.15 %} * **CI/CD admin**: Grants admin access to manage Actions policies, runners, runner groups, hosted compute network configurations, secrets, variables, and usage metrics for an organization. +* **Security manager**: Grants the ability to manage security policies, security alerts, and security configurations for an organization and all its repositories. {%- endif %} diff --git a/data/reusables/organizations/security-manager-beta-note.md b/data/reusables/organizations/security-manager-beta-note.md index 3051050b714f..2121edbc9726 100644 --- a/data/reusables/organizations/security-manager-beta-note.md +++ b/data/reusables/organizations/security-manager-beta-note.md @@ -1,2 +1,6 @@ +{% ifversion ghes < 3.16 %} + > [!NOTE] > The security manager role is in {% data variables.release-phases.public_preview %} and subject to change. + +{% endif %}