AWSGuard policies
Overview
AWSGuard codifies best practices for AWS. It is an open source library that you can configure and use to enforce these best practices for your own Pulumi stacks or organization.
For more information on Pulumi’s Policy as Code solution, visit our docs.
Trying AWSGuard
In this guide, we’ll show you how to create a Policy Pack that configures and uses the policies available in AWSGuard.
Prerequisites
Verify your version of the Pulumi CLI
pulumi version # should be v1.14.0 or later
Authoring a Policy Pack that uses AWSGuard policies
To use AWSGuard policies, you must create a Policy Pack that references the @pulumi/awsguard
npm package and creates a new instance of the AwsGuard
class.
Create a directory for your new Policy Pack, and change into it.
mkdir awsguard && cd awsguard
Run the
pulumi policy new
command.$ pulumi policy new awsguard-typescript
Tweak the code in the
index.ts
file as desired. The default implementation provided by theawsguard-typescript
template creates a new instance ofAwsGuard
with all policies set to have an enforcement level of advisory.new AwsGuard({ all: "advisory" });
From here, you can change the enforcement level for all policies or configure individual policies.
For example:
To make all policies mandatory rather than advisory:
new AwsGuard({ all: "mandatory" });
To make all policies mandatory, but change certain policies to be advisory:
new AwsGuard({ all: "mandatory", ec2InstanceNoPublicIP: "advisory", elbAccessLoggingEnabled: "advisory", });
To disable a particular policy:
new AwsGuard({ ec2InstanceNoPublicIP: "disabled", });
To disable all policies except ones explicitly enabled:
new AwsGuard({ all: "disabled", ec2InstanceNoPublicIP: "mandatory", elbAccessLoggingEnabled: "mandatory", });
To specify additional configuration for policies that support it:
new AwsGuard({ ec2VolumeInUseCheck: { checkDeletion: false }, encryptedVolumes: { enforcementLevel: "mandatory", kmsId: "id" }, redshiftClusterMaintenanceSettingsCheck: { preferredMaintenanceWindow: "Mon:09:30-Mon:10:00" }, acmCheckCertificateExpiration: { maxDaysUntilExpiration: 10 }, });
Test the new Policy Pack
Policy Packs can be tested on a user’s local workstation to facilitate rapid development and testing of policies.
Run
npm install
in the Policy Pack directory.Use the
--policy-pack
flag withpulumi preview
orpulumi up
to specify the path to the directory containing your Policy Pack when previewing/updating a Pulumi program.If you don’t have a Pulumi program readily available, you can create a new project for testing by running
pulumi new aws-typescript
in an empty directory. This AWS example will create an S3 bucket, which is perfect for testing our Policy.$ mkdir test-program && cd test-program $ pulumi new aws-typescript
In the Pulumi project’s directory run:
$ pulumi preview --policy-pack <path-to-policy-pack-directory>
If the stack is not in compliance, the policy violation will be displayed. Since the enforcement level for all policies are set to advisory, a warning is shown for any resources that are not in compliance with the AWSGuard policies. In this case, logging must be defined for S3 buckets.
Previewing update (dev): Type Name Plan Info + pulumi:pulumi:Stack test-dev create + └─ aws:s3:Bucket my-bucket create 1 warning Diagnostics: aws:s3:Bucket (my-bucket): advisory: [s3-bucket-logging-enabled] Checks whether logging is enabled for your S3 buckets. Bucket logging must be defined. Resources: + 2 to create
If you had wanted the preview to fail for any policy violations, the Policy Pack can be modified to configure all policies to be mandatory.
new AwsGuard({ all: "mandatory" });
Running the
pulumi preview
command again will now fail the preview operation.Previewing update (dev): Type Name Plan Info + pulumi:pulumi:Stack test-dev create 1 error + └─ aws:s3:Bucket my-bucket create 1 error Diagnostics: pulumi:pulumi:Stack (test-dev): error: preview failed aws:s3:Bucket (my-bucket): mandatory: [s3-bucket-logging-enabled] Checks whether logging is enabled for your S3 buckets. Bucket logging must be defined.
If you do not want to enforce this particular policy, you can modify the Policy Pack to disable it.
new AwsGuard({ all: "mandatory", s3BucketLoggingEnabled: "disabled", });
Next Steps
Once you’ve validated the behavior of the AWSGuard policies you’ve configured in your Policy Pack, an organization administrator can publish the Policy Pack to the Pulumi Cloud to be enforced across your organization. To learn more see Enforcing a Policy Pack Across an Organization.
Now that you’ve seen how to configure and use AWSGuard policies, you may want to write your own policies. See the Getting Started tutorial to get started.
Thank you for your feedback!
If you have a question about how to use Pulumi, reach out in Community Slack.
Open an issue on GitHub to report a problem or suggest an improvement.