Skip to main content

Create a Custom Policy Pack

In this step, we’ll create a policy pack to enforce the following rules for AWS resources:

  1. S3 buckets must be prefixed with the product name myproduct-.
  2. EC2 instances must use the t2.micro instance type.
  3. All AWS resources must have at least one tag defined.

Set up your policy pack project#

First, create a new directory for your policy pack project:

Terminal window
mkdir custom-policy-pack
cd custom-policy-pack

Then, initialize your project. Choose Python or TypeScript based on your preferred language.

Terminal window
pulumi policy new aws-typescript

This will create the following files and directories:

This will initialize your project, creating the necessary files for Pulumi to use as a policy, including module dependencies to the providers that will let us interact with AWS resources.

Define Policies#

Policies are written in Python or TypeScript. Like Pulumi Programs, you can use the full power of your preferred language, including standard features like leveraging third-party modules, using conditional logic and control flow, and can be validated with unit testing frameworks.

By default the template sets up an example resource policy that prevents S3 buckets from being publicly readable:

File: custom-policy-pack/index.ts

import * as aws from "@pulumi/aws";
import { PolicyPack, validateResourceOfType } from "@pulumi/policy";


new PolicyPack("aws-typescript", {
    policies: [{
        name: "s3-no-public-read",
        description: "Prohibits setting the publicRead or publicReadWrite permission on AWS S3 bucket ACLs.",
        enforcementLevel: "mandatory",
        validateResource: validateResourceOfType(aws.s3.BucketAcl, (bucketAcl, args, reportViolation) => {
            if (bucketAcl.acl === "public-read" || bucketAcl.acl === "public-read-write") {
                reportViolation(
                    "You cannot set public-read or public-read-write on an S3 bucket ACL. " +
                    "Read more about ACLs here: https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html");
            }
        }),
    }],
});

Here you can see the basic structure of a policy pack:

  • Some imports from the Pulumi Crossguard SDK
  • a function that implements the policy
  • a policy definition that wraps the implementation and describes the policy
  • a policy pack definition that packages the policies together

While this example is a useful policy, it’s not what we need right now. Let’s delete all of that code and create some new custom policies.

Replace the contents of index.ts with the following:

import * as aws from "@pulumi/aws";
import { PolicyPack, ReportViolation, ResourceValidationArgs, validateResourceOfType, ResourceValidationPolicy } from "@pulumi/policy";


export const REQUIRED_S3_PREFIX: string = "myproduct-";


// Policy: Ensure S3 buckets have product prefix enabled
export const s3ProductPrefixPolicy: ResourceValidationPolicy = {
    name: "s3-product-prefix",
    description: "Ensures S3 buckets have the correct product prefix.",
    enforcementLevel: "mandatory",
    validateResource: validateResourceOfType(aws.s3.Bucket, (bucket, args, reportViolation) => {
        const prefix = bucket.bucketPrefix || "";
        if (prefix != REQUIRED_S3_PREFIX) {
            reportViolation(`Invalid prefix: '${prefix}'. S3 buckets must use '${REQUIRED_S3_PREFIX}' prefix.`);
        }
    }),
};


export const REQUIRED_INSTANCE_TYPE: string = "t2.micro";


// Policy: Restrict EC2 instance types
export const ec2InstanceTypeRestrictedPolicy: ResourceValidationPolicy = {
    name: "ec2-instance-type-restricted",
    description: "Ensures EC2 instances use approved instance type.",
    enforcementLevel: "mandatory",
    validateResource: validateResourceOfType(aws.ec2.Instance, (instance, args, reportViolation) => {
        const instanceType = instance.instanceType || "";
        if (instanceType !== REQUIRED_INSTANCE_TYPE) {
            reportViolation(`Invalid instance type: '${instanceType}'. EC2 instances must use '${REQUIRED_INSTANCE_TYPE}' instance type.`);
        }
    }),
};


// Policy: Ensure all AWS resources have at least one tag
export const allAwsResourcesMustHaveTagsPolicy: ResourceValidationPolicy = {
    name: "all-aws-resources-must-have-tags",
    description: "Ensures all AWS resources have at least one tag.",
    enforcementLevel: "mandatory",
    validateResource: (args: ResourceValidationArgs, reportViolation: ReportViolation) => {
        if (args.type.startsWith("aws")) {
            const tags = args.props.tags || {};
            if (Object.keys(tags).length === 0) {
                reportViolation("All AWS resources must have at least one tag.");
            }
        }
    },
};


new PolicyPack("custom-policy-pack", {
    policies: [s3ProductPrefixPolicy, ec2InstanceTypeRestrictedPolicy, allAwsResourcesMustHaveTagsPolicy],
});

Here we define three different policies:

  • s3-product-prefix: Ensures S3 buckets are prefixed with the product name by checking the bucketPrefix property on all aws:s3:Bucket resources.
  • ec2-instance-type-restricted: Restricts EC2 instance types to only use the affordable t2.micro type, by checking the instanceType property on all aws:ec2/instance:Instance resources.
  • all-aws-resources-must-have-tags: Ensures all AWS resources have at least one tag by checking the tags property on all resources who’s type starts with aws.

Each of the policies uses the same pattern:

  1. Define a ResourceValidationPolicy with a bit of metadata and a validation function. Each policy can have an individual enforcement level, name, and description.
  2. The validation function is defined inline using the validateResourceOfType helper function. The way Crossguard resource policies work, each resource in the project will be passed to every policy in the pack. This strongly-typed helper function creates a filter that checks the resource type (e.g. aws.ec2.Instance from the pulumi-aws provider library) and will only run the validation function on resources that match the type.
  3. The validation functions take an instance of the resource, an args property bag, and a function for reporting policy violations. Inside the validation function, we can check one or more properties on the strongly-typed resource instance.
  4. If there is a problem with the property value, or some other aspect of the resource is out of compliance, we use the reportViolation function that was passed in to indicate that there’s a problem. The error message should be a full sentence and give useful information on how to remediate the problem.

What’s great about the strong typing in our SDK is that your IDE’s intellisense knows the type definition and can give you dot-completion for properties on the resource instance, so there’s no guessing about what the property is called, or what its type should be.

That said, sometimes you might need to write a policy that works against more than one resource type. For example, the all-aws-resources-must-have-tags policy checks every kind of AWS resource. In this case, instead of using the validateResourceOfType helper function, we just pass the anonymous function directly. Then, in the function we need to check the resource type as a string by inspecting the value of args.type.

If you’re not sure what the correct resource type string is for your particular set of resources, you can run pulumi stack to list the resources in your current stack. The TYPE column of the output contains the same resource types strings that you would use to filter on inside of a policy. In our above example, we apply the policy to any resource who’s type starts with aws.

Terminal window
pulumi stack
[...]
Current stack resources (5):
    TYPE                                    NAME
    pulumi:pulumi:Stack                     custom-policy-pack-integration-test-dev
    ├─ aws:s3:Bucket                        my-bucket
    ├─ aws:ec2/securityGroup:SecurityGroup  ssh-security-group
    ├─ aws:ec2/instance:Instance            web-server
    └─ pulumi:providers:aws                 default_6_65_0

Finally we assemble the policies into a policy pack object, giving it the name custom-policy-pack.

Next up, we’ll validate our custom policy pack by checking some cloud resources for compliance. Let’s go!

AWSTypeScriptPythonCrossGuardPolicy as CodeSecurity

Related

Blog PostDec 2019

Running AWS IAM Access Analyzer at Deployment Time

In this post, we will look at running AWS IAM Access Analyzer at deployment time.
Joe Duffy
WorkshopOn demand

AWS Immersion Day: Building an IDP with Pulumi

Learn best practices for platform engineering on AWS and how Pulumi makes it easier than ever to build an Internal Developer Platform (IDP) for your team.
Rob Smith and Josh Kodroff

The infrastructure as code platform for any cloud.

Contact usGet started