# Amazon Inspector policies Amazon Inspector policies allow you to centrally enable and manage Amazon Inspector across accounts in your Amazon organization. With an Amazon Inspector policy, you specify which organizational entities (root, OUs, or accounts) have Amazon Inspector automatically enabled and linked to the Amazon Inspector delegated administrator account. You can use Amazon Inspector policies to simplify service-wide onboarding and ensure consistent enablement of Amazon Inspector in all existing and newly created accounts. ## Key Features and Benefits Amazon Inspector policies let you define which scan types should be enabled for your organization or subsets of it, ensuring consistent coverage and reducing manual effort. When implemented, they help you onboard new accounts automatically and maintain your scanning baseline as your organization scales. ## How it works When you attach an Amazon Inspector policy to an organizational entity, the policy automatically enables Amazon Inspector for all member accounts within that scope. Also, if you have finalized Amazon Inspector setup by registering a delegated administrator for Amazon Inspector, that account will have centralized vulnerability visibility over accounts in the organization that have Amazon Inspector enabled. Amazon Inspector policies can be applied to the entire organization, to specific organizational units (OUs), or to individual accounts. Accounts that join the organization—or move into an OU with an attached Amazon Inspector policy—automatically inherit the policy and have Amazon Inspector enabled and linked to the Amazon Inspector delegated administrator. Amazon Inspector policies allow you to enable Amazon EC2 scanning, Amazon ECR scanning, or Lambda Standard and code scanning, as well as Code Security. Specific configuration settings and suppression rules can be managed via the delegated administrator account for the organization. When you attach an Amazon Inspector 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, Amazon Inspector will be disabled in that region. + When `ALL_SUPPORTED` is specified for enablement, Amazon Inspector is enabled in all current and future regions unless explicitly disabled. This allows you to maintain comprehensive 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 This topic uses the following terms when discussing Amazon Inspector policies. | 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 Amazon Inspector policies on behalf of the organization. | | Service-linked role | An IAM role that allows Amazon Inspector to interact with other Amazon services. | ### Use cases for Amazon Inspector policies Organizations launching large-scale workloads across multiple accounts can use this policy to ensure all accounts immediately enable the correct scan types and avoid gaps. Regulatory or compliance-driven environments can use child policies to override or limit scan-types by OU. Rapid growth environments can automate enablement for newly created accounts so they're always compliant with the baseline. ### Policy inheritance and enforcement 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 When creating Amazon Inspector policies, the following validations occur: + Region names must be valid Amazon region identifiers + Regions must be supported by Amazon Inspector + 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 Amazon Inspector policies apply only in Regions where Amazon Inspector and Amazon Organizations trusted access are available. 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 Amazon Inspector is available ### Detachment behavior If you detach an Amazon Inspector policy, Amazon Inspector remains enabled in previously covered accounts. However, future changes to the organizational structure (such as new accounts joining or existing accounts moving into the OU) will no longer automatically enable Amazon Inspector. Any further enablement must be performed manually or through re-attaching a policy. ## Additional details ### Delegated Administrator Only one delegated administrator can be registered for Amazon Inspector in an organization. You must configure this in the Amazon Inspector console or via APIs before attaching Amazon Inspector policies. ### Prerequisites You must enable trusted access for Amazon Organizations, have a delegated administrator for Amazon Inspector registered, and have service-linked roles available in all accounts. ### Supported Regions All Regions where Amazon Inspector is available. # Getting started with Amazon Inspector policies Getting started Before you configure Amazon Inspector 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. ## Learn about required permissions To enable or attach Amazon Inspector policies, you must have the following permissions in the management account: + `organizations:EnableAWSServiceAccess` for `inspector2.amazonaws.com` + `organizations:RegisterDelegatedAdministrator` for `inspector2.amazonaws.com` + `organizations:AttachPolicy`, `organizations:CreatePolicy`, `organizations:DescribeEffectivePolicy` + `inspector2:Enable` (for management account and delegated admin) ## Before you begin Review the following requirements before implementing Amazon Inspector policies: + Your account must be part of an Amazon organization + You must be signed in as either: + The management account for the organization + An Amazon Organizations delegated administrator with permissions to manage Amazon Inspector policies + You must enable trusted access for Amazon Inspector in your organization + You must enable the Amazon Inspector policy type in the root of your organization Additionally, verify that: + Amazon Inspector is supported in the Regions where you want to apply policies + You have the `AWSServiceRoleForInspectorV2` service-linked role configured in your management account. To verify this role exists, run `aws iam get-role --role-name AWSServiceRoleForInspectorV2`. If you need to create this role, you can either run `aws inspector2 enable` in any Region from your management account, or create it directly by running `aws iam create-service-linked-role --aws-service-name inspector2.amazonaws.com`. ## Implementation steps To implement Amazon Inspector 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 Amazon Inspector](orgs_integrate_services.md#orgs_how-to-enable-disable-trusted-access). 1. [Enable Amazon Inspector policies for your organization](enable-policy-type.md). 1. [Create an Amazon Inspector policy](orgs_manage_policies_inspector_syntax.md). 1. [Attach the Amazon Inspector policy to your organization's root, OU, or account](orgs_policies_attach.md). 1. [View the combined effective Amazon Inspector policy that applies to an account](orgs_manage_policies_effective.md). ## Create an Amazon Inspector policy ### Minimum permissions To create an Amazon Inspector policy, you need the following permission: + `organizations:CreatePolicy` ### Amazon Management Console **To create an Amazon Inspector policy** 1. Sign in to the [Amazon Organizations console](https://console.amazonaws.cn/organizations/v2). You must sign in as an 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. 1. Set a delegated administrator for the service in use within Amazon Inspector console. 1. Once the delegated administrator has been set up for Amazon Inspector, visit Amazon organization console to set up the policies. On Amazon organization console, visit the Amazon Inspector Policies page, choose **Create policy**. 1. On the **Create new Amazon Inspector policy** page, enter a **Policy name** and an optional **Policy description**. 1. (Optional) You can add one or more tags to the policy by choosing **Add tag** and then entering a key and an optional value. Leaving the value blank sets it to an empty string; it isn't `null`. You can attach up to 50 tags to a policy. For more information, see [Tagging Amazon Organizations resourcesConsiderations](orgs_tagging.md). 1. Enter or paste the policy text in the JSON code box. For information about the Amazon Inspector policy syntax, and example policies you can use as a starting point, see [Amazon Inspector policy syntax and examples](orgs_manage_policies_inspector_syntax.md). 1. When you're finished editing your policy, choose **Create policy** at the lower-right corner of the page. # Best practices for using Amazon Inspector policies Best practices When implementing Amazon Inspector policies across your organization, following established best practices helps ensure successful deployment and maintenance. ## Start simply and make small changes Begin by enabling Amazon Inspector policies at a limited organizational unit (for example, "Security Pilot") to validate expected behavior before rolling out to all accounts. This incremental approach allows you to identify and resolve potential issues in a controlled environment before broader deployment. ## Establish review processes Regularly monitor for new accounts joining your organization and confirm they inherit Amazon Inspector enablement automatically. Review policy attachment scopes quarterly to ensure your security coverage remains aligned with your organizational structure and security requirements. ## Validate changes using DescribeEffectivePolicy After attaching or modifying a policy, run `DescribeEffectivePolicy` for representative accounts to ensure that Amazon Inspector enablement is reflected properly. This validation step helps you confirm that your policy changes have the intended effect across your organization. ## Communicate and train Educate account owners that Amazon Inspector will be enabled automatically and findings may appear in their Security Hub or Amazon Inspector dashboards once they are linked to the Amazon Inspector delegated administrator. Clear communication helps ensure that account owners understand the security monitoring in place and can respond appropriately to findings. ## Plan your delegated administrator strategy Designate a security or compliance account as the delegated administrator for Amazon Inspector. Set the delegated administrator from the Amazon Inspector console or via Amazon Organizations APIs. This approach enables consistent security monitoring and management across your organization. ## Handle regional considerations Enable Amazon Inspector in Regions where your workloads run. Consider your compliance requirements and operational needs when determining which Regions require Amazon Inspector coverage. Document your region-specific requirements to maintain consistent security monitoring across your infrastructure. # Amazon Inspector policy syntax and examples Amazon Inspector policies follow a standardized JSON syntax that defines how Amazon Inspector is enabled and configured across your organization. An Amazon Inspector policy is a JSON document structured according to the Amazon Organizations management-policy syntax. It defines which organizational entities will have Amazon Inspector automatically enabled. ## Basic policy structure An Amazon Inspector policy uses this basic structure: ``` { "inspector": { "enablement": { "ec2_scanning": { "enable_in_regions": { "@@assign": ["us-east-1", "us-west-2"] }, "disable_in_regions": { "@@assign": ["eu-west-1"] } } } } } ``` ## Policy components Amazon Inspector policies contain these key components: `inspector` The top-level key for Amazon Inspector policy documents, which is required for all Amazon Inspector policies. `enablement` Defines how Amazon Inspector is enabled across the organization, and contains scan type configurations. `Regions (Array of Strings)` Specifies the Regions where Amazon Inspector should be auto-enabled. ## Amazon Inspector policy examples The following examples demonstrate common Amazon Inspector policy configurations. ### Example 1 – Enable Amazon Inspector organization-wide The following example enables Amazon Inspector in `us-east-1` and `us-west-2` for all accounts in the organization root. Create a file `inspector-policy-enable.json`: ``` { "inspector": { "enablement": { "lambda_standard_scanning": { "enable_in_regions": { "@@assign": [ "us-east-1", "us-west-2" ] }, "disable_in_regions": { "@@assign": [ "eu-west-1" ] }, "lambda_code_scanning": { "enable_in_regions": { "@@assign": [ "us-east-1", "us-west-2" ] }, "disable_in_regions": { "@@assign": [ "eu-west-1" ] } } }, "ec2_scanning": { "enable_in_regions": { "@@assign": [ "us-east-1", "us-west-2" ] }, "disable_in_regions": { "@@assign": [ "eu-west-1" ] } }, "ecr_scanning": { "enable_in_regions": { "@@assign": [ "us-east-1", "us-west-2" ] }, "disable_in_regions": { "@@assign": [ "eu-west-1" ] } }, "code_repository_scanning": { "enable_in_regions": { "@@assign": [ "us-east-1", "us-west-2" ] }, "disable_in_regions": { "@@assign": [ "eu-west-1" ] } } } } } ``` When attached to the root, all accounts in the organization automatically enable Amazon Inspector, and their scan findings are available to the Amazon Inspector delegated administrator. Create and attach the policy: ``` POLICY_ID=$(aws organizations create-policy \ --content file://inspector-policy-enable.json \ --name InspectorOrgPolicy \ --type INSPECTOR_POLICY \ --description "Inspector organization policy to enable all resources in IAD and PDX." \ --query 'Policy.PolicySummary.Id' \ --output text) aws organizations attach-policy --policy-id $POLICY_ID --target-id ``` Any new account joining the organization automatically inherits enablement. If detached, existing accounts remain enabled, but future accounts are not auto-enabled: ``` aws organizations detach-policy --policy-id $POLICY_ID --target-id ``` ### Example 2 – Enable Amazon Inspector for a specific OU Create a file `inspector-policy-eu-west-1.json`: ``` { "inspector": { "enablement": { "lambda_standard_scanning": { "enable_in_regions": { "@@assign": [ "eu-west-1" ] }, "disable_in_regions": { "@@assign": [ "eu-west-2" ] }, "lambda_code_scanning": { "enable_in_regions": { "@@assign": [ "eu-west-1" ] }, "disable_in_regions": { "@@assign": [ "eu-west-2" ] } } }, "ec2_scanning": { "enable_in_regions": { "@@assign": [ "eu-west-1" ] }, "disable_in_regions": { "@@assign": [ "eu-west-2" ] } }, "ecr_scanning": { "enable_in_regions": { "@@assign": [ "eu-west-1" ] }, "disable_in_regions": { "@@assign": [ "eu-west-2" ] } }, "code_repository_scanning": { "enable_in_regions": { "@@assign": [ "eu-west-1" ] }, "disable_in_regions": { "@@assign": [ "eu-west-2" ] } } } } } ``` Attach this to an OU to ensure all production accounts in `eu-west-1` will have Amazon Inspector enabled and linked to the Amazon Inspector delegated administrator: ``` aws organizations update-policy --policy-id $POLICY_ID --content file://inspector-policy-eu-west-1.json --description "Inspector organization policy - Enable all (eu-west-1)" aws organizations attach-policy --policy-id $POLICY_ID --target-id ou-aaaa-12345678 ``` Accounts outside the OU are unaffected.