# Security Hub policies
<a name="orgs_manage_policies_security_hub"></a>

Amazon Security Hub policies provide security teams with a centralized approach to managing security configurations across their Amazon Organizations. By leveraging these policies, you can establish and maintain consistent security controls through a central configuration mechanism. This integration allows you to address security coverage gaps by creating policies that align with your organization's security requirements and centrally applying them across accounts and organizational units (OUs).

Security Hub policies are fully integrated with Amazon Organizations, allowing management accounts or delegated administrators to define and enforce security configurations. When accounts join your organization, they automatically inherit the applicable policies based on their location in the organizational hierarchy. This ensures that your security standards are consistently applied as your organization grows. The policies respect existing organizational structures and provide flexibility in how security configurations are distributed, while maintaining central control over critical security settings.

## Key features and benefits
<a name="security-hub-policies-features"></a>

Security Hub policies provide a comprehensive set of capabilities that help you manage and enforce security configurations across your Amazon organization. These features streamline security management while ensuring consistent control over your multi-account environment.
+ Centrally [enable Security Hub](https://docs.amazonaws.cn/securityhub/latest/userguide/security-hub-adv-getting-started-enable.html#security-hub-adv-getting-started-enable-org-account) across accounts and Regions in your organization
+ Create security policies that define your security configuration across accounts and OUs
+ Automatically apply security configurations to new accounts when they join your organization
+ Ensure consistent security settings across your organization
+ Prevent member accounts from modifying organization-level security configurations

## What are Security Hub policies?
<a name="security-hub-policies-what-are"></a>

Security Hub policies are Amazon Organizations policies that provide centralized control over security configurations across your organization's accounts. These policies work seamlessly with Amazon Organizations to help you establish and maintain consistent security standards throughout your multi-account environment.

When you implement Security Hub policies, you gain the ability to define specific security configurations that automatically propagate across your organization. This ensures that all accounts, including newly created ones, align with your organization's security requirements and best practices.

These policies also help you maintain compliance by enforcing consistent security controls and preventing individual accounts from modifying organization-level security settings. This centralized approach significantly reduces the administrative overhead of managing security configurations across large, complex Amazon environments.

## How Security Hub policies work
<a name="security-hub-policies-how-works"></a>

When you attach an Security Hub policy to your organization or organizational unit, Amazon Organizations automatically evaluates the policy and applies it based on the scope you define. The policy enforcement process follows specific conflict resolution rules:

When regions appear in both enable and disable lists, the disable configuration takes precedence. For example, if a region is listed in both enable and disable configurations, Security Hub will be disabled in that region.

When `ALL_SUPPORTED` is specified for enablement, Security Hub is enabled in all current and future regions unless explicitly disabled. This allows you to maintain comprehensive security coverage as Amazon expands into new regions.

Child policies can modify parent policy settings using inheritance operators, allowing for granular control at different organizational levels. This hierarchical approach ensures that specific organizational units can customize their security settings while maintaining baseline controls.

## Terminology
<a name="security-hub-policies-terminology"></a>

This topic uses the following terms when discussing Security Hub policies.


**Security Hub policy terminology**  

| Term | Definition | 
| --- | --- | 
| Effective policy | The final policy that applies to an account after combining all inherited policies. | 
| Policy inheritance | The process by which accounts inherit policies from parent organizational units. | 
| Delegated administrator | An account designated to manage Security Hub policies on behalf of the organization. | 
| Service-linked role | An IAM role that allows Security Hub to interact with other Amazon services. | 

## Use cases for Security Hub policies
<a name="security-hub-policies-use-cases"></a>

Security Hub policies address common security management challenges in multi-account environments. The following use cases demonstrate how organizations typically implement these policies to enhance their security posture.

### Example use case: Regional compliance requirements
<a name="security-hub-policies-use-case-1"></a>

A multinational corporation needs different Security Hub configurations for different geographical regions. They create a parent policy enabling Security Hub in all regions using `ALL_SUPPORTED`, then use child policies to disable specific regions where different security controls are required. This allows them to maintain compliance with regional regulations while ensuring comprehensive security coverage.

### Example use case: Development team security standards
<a name="security-hub-policies-use-case-2"></a>

A software development organization implements Security Hub policies that enable monitoring in production regions while keeping development regions unmanaged. They use explicit region lists in their policies rather than `ALL_SUPPORTED` to maintain precise control over security monitoring coverage. This approach allows them to enforce stricter security controls in production environments while maintaining flexibility in development areas.

## Policy inheritance and enforcement
<a name="security-hub-policies-inheritance"></a>

Understanding how policies are inherited and enforced is crucial for effective security management across your organization. The inheritance model follows the Amazon Organizations hierarchy, ensuring predictable and consistent policy application.
+ Policies attached at the root level apply to all accounts
+ Accounts inherit policies from their parent organizational units
+ Multiple policies can apply to a single account
+ More specific policies (closer to the account in the hierarchy) take precedence

## Policy validation
<a name="security-hub-policies-validation"></a>

When creating Security Hub policies, the following validations occur:
+ Region names must be valid Amazon region identifiers
+ Regions must be supported by Security Hub
+ Policy structure must follow Amazon Organizations policy syntax rules
+ Both `enable_in_regions` and `disable_in_regions` lists must be present, though they can be empty

## Regional considerations and supported Regions
<a name="security-hub-policies-regions"></a>

Security Hub policies operate across multiple Regions, requiring careful consideration of your global security requirements. Understanding regional behavior helps you implement effective security controls across your organization's global footprint.
+ Policy enforcement occurs in each Region independently
+ You can specify which Regions to include or exclude in your policies
+ New Regions are automatically included when using the `ALL_SUPPORTED` option
+ Policies only apply to Regions where Security Hub is available

## Next steps
<a name="security-hub-policies-next-steps"></a>

To get started with Security Hub policies:

1. Review the prerequisites in Getting started with Security Hub policies

1. Plan your policy strategy using our best practices guide

1. Learn about policy syntax and view example policies

# Getting started with Security Hub policies
<a name="orgs_manage_policies_security_hub_getting_started"></a>

Before you configure Security Hub policies, ensure you understand the prerequisites and implementation requirements. This topic guides you through the process of setting up and managing these policies in your organization.

## Before you begin
<a name="security_hub_getting_started-before-begin"></a>

Review the following requirements before implementing Security Hub policies:
+ Your account must be part of an Amazon Organizations organization
+ You must be signed in as either:
  + The management account for the organization
  + A delegated administrator account with permissions to manage Security Hub policies
+ You must enable trusted access for Security Hub in your organization
+ You must enable the Security Hub policy type in the root of your organization

Additionally, verify that:
+ Security Hub is supported in the Regions where you want to apply policies
+ You have the `AWSServiceRoleForSecurityHubV2` service-linked role configured in your management account. To verify this role exists, run `aws iam get-role --role-name AWSServiceRoleForSecurityHubV2`. If you need to create this role, you can either run `aws securityhub enable-security-hub-v2` in any Region from your management account, or create it directly by running `aws iam create-service-linked-role --aws-service-name securityhubv2.amazonaws.com`.

## Implementation steps
<a name="security_hub_getting_started-implementation"></a>

To implement Security Hub policies effectively, follow these steps in sequence. Each step ensures proper configuration and helps prevent common issues during setup. The management account or delegated administrator can perform these steps through the Amazon Organizations console, Amazon Command Line Interface (Amazon CLI), or Amazon SDKs.

1. [Enable trusted access for Security Hub](orgs_integrate_services.md#orgs_how-to-enable-disable-trusted-access).

1. [Enable Security Hub policies for your organization](enable-policy-type.md).

1. [Create a Security Hub policy](orgs_policies_create.md#create-security-hub-policy-procedure).

1. [Attach the Security Hub policy to your organization's root, OU, or account](orgs_policies_attach.md).

1. [View the combined effective Security Hub policy that applies to an account](orgs_manage_policies_effective.md).

For all of these steps, you sign in as an Amazon Identity and Access Management (IAM) user, assume an IAM role, or sign in as the root user ([not recommended](https://docs.amazonaws.cn/IAM/latest/UserGuide/best-practices.html#lock-away-credentials)) in the organization's management account.

**Other information**
+ [Learn policy syntax for Security Hub policies and see policy examples](orgs_manage_policies_security_hub_syntax.md)

# Best practices for using Security Hub policies
<a name="orgs_manage_policies_security_hub_best_practices"></a>

When implementing Security Hub policies across your organization, following established best practices helps ensure successful deployment and maintenance of your security configurations. These guidelines specifically address the unique aspects of Security Hub policy management and enforcement within Amazon Organizations.

## Policy design principles
<a name="policy-design-principles"></a>

Before creating Security Hub policies, establish clear principles for your policy structure. Keep policies simple and avoid complex cross-attribute or nested rules that make it difficult to determine the final outcome. Start with broad policies at the organization root level and refine them through child policies where needed.

Consider using empty region lists strategically. You can leave `enable_in_regions` empty when you only need to disable Security Hub in specific regions, or leave `disable_in_regions` empty to keep regions unmanaged by policy. This flexibility helps you maintain precise control over your security monitoring coverage.

## Region management strategies
<a name="region-management-strategies"></a>

When managing regions through Security Hub policies, consider these proven approaches. Use `ALL_SUPPORTED` when you want to automatically include future regions in your security coverage. For more granular control, explicitly list regions rather than relying on `ALL_SUPPORTED`, especially when different regions require different security configurations.

Document your region-specific requirements, particularly for:
+ Compliance-mandated regions that require specific configurations
+ Development versus production environment differences
+ Opt-in regions with special considerations
+ Regions where Security Hub must remain disabled

## Policy inheritance planning
<a name="policy-inheritance-planning"></a>

Carefully plan your policy inheritance structure to maintain effective security control while allowing necessary flexibility. Document which organizational units can modify inherited policies and what modifications are allowed. Consider restricting inheritance operators (@@assign, @@append, @@remove) at parent levels when you need to enforce strict security controls.

## Monitoring and validation
<a name="monitoring-validation"></a>

Implement regular monitoring practices to ensure your policies remain effective. Review policy attachments periodically, especially after organizational changes. Validate that region configurations match your intended security coverage, particularly when using `ALL_SUPPORTED` or when managing multiple region lists.

## Troubleshooting strategies
<a name="troubleshooting-strategies"></a>

When troubleshooting Security Hub policies, focus first on policy precedence and inheritance. Remember that disable configurations take precedence over enable configurations when regions appear in both lists. Check policy inheritance chains to understand how parent and child policies combine to create the effective policy for each account.

# Security Hub policy syntax and examples
<a name="orgs_manage_policies_security_hub_syntax"></a>

Security Hub policies follow a standardized JSON syntax that defines how Security Hub is enabled and configured across your organization. Understanding the policy structure helps you create effective policies for your security requirements.

## Considerations
<a name="security-hub-policy-considerations"></a>

Before creating Security Hub policies, understand these key points about policy syntax:
+ Both `enable_in_regions` and `disable_in_regions` lists are required in the policy, though they can be empty
+ When processing effective policies, `disable_in_regions` takes precedence over `enable_in_regions`
+ Child policies can modify parent policies using inheritance operators unless explicitly restricted
+ The `ALL_SUPPORTED` designation includes both current and future regions
+ Region names must be valid and available in Security Hub

## Basic policy structure
<a name="security-hub-basic-structure"></a>

A Security Hub policy uses this basic structure:

```
{
  "securityhub": {
    "enable_in_regions": {
      "@@append": ["ALL_SUPPORTED"],
      "@@operators_allowed_for_child_policies": ["@@all"]
    },
    "disable_in_regions": {
      "@@append": [],
      "@@operators_allowed_for_child_policies": ["@@all"]
    }
  }
}
```

## Policy components
<a name="security-hub-policy-components"></a>

Security Hub policies contain these key components:

`securityhub`  
The top-level container for policy settings  
Required for all Security Hub policies

`enable_in_regions`  
List of regions where Security Hub should be enabled  
Can contain specific region names or `ALL_SUPPORTED`  
Required field but can be empty  
When using `ALL_SUPPORTED`, includes future regions

`disable_in_regions`  
List of regions where Security Hub should be disabled  
Can contain specific region names or `ALL_SUPPORTED`  
Required field but can be empty  
Takes precedence over `enable_in_regions` when regions appear in both lists

Inheritance operators  
@@assign - Overwrites inherited values  
@@append - Adds new values to existing ones  
@@remove - Removes specific values from inherited settings

## Security Hub policy examples
<a name="security-hub-policy-examples"></a>

The following examples demonstrate common Security Hub policy configurations. 

The example below enables Security Hub in all current and future regions. By using `ALL_SUPPORTED` in the `enable_in_regions` list and leaving `disable_in_regions` empty, this policy ensures comprehensive security coverage as new regions become available.

```
{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            
         ]
      }
   }
}
```

This example disables Security Hub in all regions including any future regions since `disable_in_regions` list takes precedence over `enable_in_regions`.

```
{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "us-east-1",
            "us-west-2"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      }
   }
}
```

The following example demonstrates how child policies can modify parent policy settings using inheritance operators. This approach allows for granular control while maintaining the overall policy structure. The child policy adds a new region to `enable_in_regions` and removes a region from `disable_in_regions`.

```
{
   "securityhub":{
      "enable_in_regions":{
         "@@append":[
            "eu-central-1"
         ]
      },
      "disable_in_regions":{
         "@@remove":[
            "us-west-2"
         ]
      }
   }
}
```

This example shows how to enable Security Hub in multiple specific regions without using `ALL_SUPPORTED`. This provides precise control over which regions have Security Hub enabled, while leaving unspecified regions unmanaged by the policy.

```
{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "us-east-1",
            "us-west-2",
            "eu-west-1",
            "ap-southeast-1"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            
         ]
      }
   }
}
```

The following example demonstrates how to handle regional compliance requirements by enabling Security Hub in most regions while explicitly disabling it in specific locations. The `disable_in_regions` list takes precedence, ensuring Security Hub remains disabled in those regions regardless of other policy settings.

```
{
   "securityhub":{
      "enable_in_regions":{
         "@@assign":[
            "ALL_SUPPORTED"
         ]
      },
      "disable_in_regions":{
         "@@assign":[
            "ap-east-1",
            "me-south-1"
         ]
      }
   }
}
```