Pulumi Blog: Erin Krengel

New Policy as Code Capabilities with CrossGuard

Erin Krengel — Tue, 05 May 2020 00:00:00 +0000

In a previous blog post, I introduced CrossGuard, Pulumi’s Policy as Code solution. As part of our 2.0 release, CrossGuard is now generally available and has some awesome new features to improve the user experience around managing Policy Packs.

General Availability

CrossGuard is enabled for enterprise organizations in the Pulumi Service, and as always, the open source offering is available for all to use.

Improved CLI support

We have added richer CLI support for CrossGuard. Organization administrators can now manage their Policy Packs from the CLI. In addition to being able to publish Policy Packs, you may now enable a Policy Pack by simply running:

$ pulumi policy enable <organization>/<pack-name> <version>

This same command can be used to upgrade a previously enabled Policy Pack.

Organization administrators may also disable a Policy Pack by running:

$ pulumi policy disable <organization>/<pack-name>

By default, the enable and disable commands use an organization’s default Policy Group. Using the --policy-group flag, you can specify another Policy Group. You can also specify latest instead of a specific Policy Pack version to enable the latest version of that Policy Pack.

Options, Parent, and Dependencies

Policies now have access to more information about the resources under review. With access to the options, parent, and dependencies of a resource, you can now write even more thorough policies.

You may access a resource’s options via the ResourceValidationArgs parameter. In the below example, we enforce that all DynamoDB tables be protected to prevent data loss.

new PolicyPack("aws-policies", {
 policies: [
 {
 name: "dyanmodb-table-protected",
 description: "DynamoDB tables must be protected.",
 enforcementLevel: "mandatory",
 validateResource: validateResourceOfType(aws.dynamodb.Table, (_, args, reportViolation) => {
 if (!args.opts.protect) {
 reportViolation(`DynamoDB tables must be protected to prevent data loss.`);
 }
 }),
 },
 ],
});

Access to the parent and dependencies of a resource allows you to author policies about the relationship between resources. For example, you may want to make sure that each DynamoDB table in a stack has an attached scaling policy.

new PolicyPack("aws-policies", {
 policies: [
 {
 name: "dyanmodb-table-protected",
 description: "DynamoDB tables should have an autoscaling policy.",
 enforcementLevel: "advisory",
 validateStack: (args, reportViolation) => {
 const tables = args.resources.filter(r => r.isType(aws.dynamodb.Table))

 for (const table of tables) {
 const scalingPolicies = table.dependencies.filter(r => r.isType(aws.appautoscaling.Policy));
 if (!scalingPolicies || scalingPolicies.length === 0) {
 reportViolation(`DynamoDB table ${table.name} is missing a scaling policy.`);
 }
 }
 }
 },
 ],
});

Python Support

As of our 2.0 launch, you can now author Policy Pack in Python. Our multi-language approach allows you to author a Policy Pack using our NodeJS or Python SDK and enforce the pack on a stack written in any language.

The Python-based Policy Pack prohibits public permission of Azure Storage Blob Containers.

def storage_container_no_public_read_validator(args: ResourceValidationArgs, report_violation: ReportViolation):
 if args.resource_type == "azure:storage/container:Container" and "containerAccessType" in args.props:
 access_type = args.props["containerAccessType"]
 if access_type == "blob" or access_type == "container":
 report_violation(
 "Azure Storage Container must not have blob or container access set. " +
 "Read more about read access here: " +
 "https://docs.microsoft.com/en-us/azure/storage/blobs/storage-manage-access-to-resources")

storage_container_no_public_read = ResourceValidationPolicy(
 name="storage-container-no-public-read",
 description="Prohibits setting the public permission on Azure Storage Blob Containers.",
 validate=storage_container_no_public_read_validator,
)

PolicyPack(
 name="azure-python",
 enforcement_level=EnforcementLevel.MANDATORY,
 policies=[
 storage_container_no_public_read,
 ],
)

Configuration

And lastly, the feature I am most excited to share with you all is Configurable Policy Packs. Using configuration, you can author Policy Packs that are reusable and flexible for your organization’s various needs.

For example, you may have a policy that restricts the allowed EC2 instance types. This set of instances may vary between your non-production stack and production stacks.

new PolicyPack("aws-policies", {
 policies: [
 {
 name: "allowed-ec2-instance-type",
 description: "EC2 instance type must be of an approved type.",
 enforcementLevel: "mandatory",
 configSchema: {
 properties: {
 allowedTypes: {
 type: "array",
 default: ["t2.nano", "t2.micro", "t2.small"]
 },
 },
 },
 validateResource: validateResourceOfType(aws.ec2.Instance, (instance, args, reportViolation) => {
 const config = args.getConfig<{ allowedTypes?: string[] }>();
 if (!config.allowedTypes) {
 reportViolation(`No EC2 instance types have been approved.`);
 return;
 }
 if (!config.allowedTypes.includes(instance.instanceType)) {
 reportViolation(`EC2 type must be an allowed instance type: ${config.allowedTypes}. ` +
 `${instance.instanceType} is not allowed type.`);
 }
 }),
 },
 ],
});

Using this configuration, you can make this deviation, allowing larger, more costly instances only in production. We can enable this configurable Policy Pack for our Policy Group prod-stacks using configuration that allows for other instance types.

{
 "allowed-ec2-instance-type": {
 "allowedTypes": ["t2.medium", "t2.large"]
 }
}

To enable the pack with this configuration, we can save the JSON to a file called prod-policy-config.json and then run:

pulumi policy enable aws-policies latest --policy-group prod-stacks --config prod-policy-config.json

Alternatively, we can enable the Policy Pack from the Pulumi Service.

Configuration allows organization administrators to quickly and easily tweak Policy Packs to meet a variety of use cases.

Wrapping Up

We’ve invested in improving the user experience for authoring and managing policy. Whether you’re an enterprise customer or an open source user, you can get started by taking CrossGuard for a spin.

The Getting Started with Policy as Code webinar recording is also a excellent resource for seeing these features in action.

Announcing CrossGuard Preview

Erin Krengel — Mon, 02 Dec 2019 00:00:00 +0000

This blog post discusses CrossGuard in “preview” status. CrossGuard is now fully released and integrated into Pulumi. For current information about Pulumi’s policy as code capabilities, please refer to the latest CrossGuard documentation.

Over the past few months, we have been hard at work on Pulumi CrossGuard, a Policy as Code solution. Using CrossGuard, you can express flexible business and security rules using code. CrossGuard enables organization administrators to enforce these policies across their organization or just on specific stacks. CrossGuard allows you to verify or enforce custom policies on changes before they are applied to your resources. CrossGuard is 100% open source and available to all users of Pulumi, including the Individual Edition. Advanced organization-wide policy management features are available to Enterprise customers.

You can run policies against any Pulumi stack, independent of the stack’s language. This means you can have policies written in TypeScript and run them against a Python-based stack. Policies are grouped in Policy Packs and run against a stack during both pulumi preview and pulumi up. Each resource in a stack is run through the Policy Pack prior to creation, meaning you can block the creation of out-of-compliance resources.

Why

Using Pulumi, developers and operators are empowered to self-provision their infrastructure and move quickly. One of our core goals is to allow you to codify best practices and share them with your team. We often hear from organization leaders that they are concerned about enforcing security and compliance best-practices. CrossGuard provides a way to automatically enforce compliance, allowing teams to operate self-sufficiently while still ensuring organization-wide requirements are met.

As an organization administrator, you may want to encourage use of smaller compute instances to optimize for cost. As a security engineer, you may want to ensure databases and other storage solutions are not publicly accessible. As a team lead, you may want to ensure your containers have reserved an appropriate amount of memory and CPU to meet your team’s requirements. Whether you’re an organization administrator, security engineer or team lead, CrossGuard provides you the capability to enforce best practice for cost, compliance, security, team practices, and much more.

Key Features

The key features available during the CrossGuard preview are:

Policy SDK to express custom policies using TypeScript or JavaScript
Run Policy Packs locally using the --policy-pack flag, available to all users
AWSGuard codifies best practices for AWS
Enforce Policy Packs across your organization or particular stacks in the Pulumi Service, for Team and Enterprise users
View policy errors and Policy Packs for an update in the Pulumi Service

Pulumi CrossGuard for Everyone

Pulumi CrossGuard has something to offer everyone in your organization.

For Organization Administrators

You want your organization to be able to move quickly and deliver business value. To do so, your team needs to be able to self-service their infrastructure. Pulumi CrossGuard gives you the peace of mind that you need to allow your team to work independently. Codify business and security policies to ensure your team meets the requirements you set forth.

For Security Engineers

There’s a lot of complexity to security and often the rest of your organization does not have all the knowledge they need to deliver software securely. Express security policies that allow you to share your knowledge and prevent issues from ending up in production.

For Developers and Operators

There are a ton of moving pieces in our ecosystems today. It is difficult to know everything about the cloud resources we use. Pulumi CrossGuard ensures you do not fall into the trap of insecure or unreasonable defaults.

CrossGuard in Action

With an understanding of what CrossGuard enables, let’s look at what that means in practice. The following is a policy pack definition that prohibits creating an AWS S3 bucket that is public readable. Our Policy Pack is not complicated. It uses a validateResourceOfType helper function to filter for the resource type we care about and reports a violation if present.

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

We initially run pulumi preview for an S3 bucket that will pass the policy.

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket("my-bucket");

We then modify the bucket to have its access control list (ACL) set to public-read, which will cause our bucket to be out-of-compliance.

// Create an AWS resource (S3 Bucket)
const bucket = new aws.s3.Bucket("my-bucket", {
 acl: "public-read",
});

While this is a simple demonstration of what you can do with Policy as Code, the framework is very flexible and supports much more complex policies. Our AWSGuard library is a great example of how you can use Policy as Code to write configurable policies.

Try it Today

Pulumi CrossGuard empowers everyone to build better, safer applications and infrastructure. Today, Pulumi CrossGuard is available to preview for all Pulumi users. For Enterprise organizations, administrators can opt-in to the preview via the “Policies” tab in the Pulumi Service. To get started with CrossGuard today, here are some resources:

If haven’t played around with Pulumi yet, here is Pulumi’s Getting Started tutorial.
Policy as Code Getting Started tutorial

We’ve initially released the capability to create policies with TypeScript or JavaScript (that work with Pulumi programs written in any supported language) and plan to add policy SDKs for other supported languages. We would love to hear any feedback you have! You can submit feedback via our Contact Us form or in our community slack.

Secure APIs with Auth0 Lambda Authorizers Using Pulumi & AWS

Erin Krengel — Wed, 24 Apr 2019 00:00:00 +0000

Creating serverless applications just got even easier! You can now protect your application APIs in just three easy steps. We’ve already posted about how easy it is to create serverless apps in Pulumi. Now, we’re helping you simplify protecting those apps with API Gateway and Lambda authorizers.

With Pulumi’s new AWSX package, you can quickly define a Lambda and an AWS Lambda authorizer to protect it. We’re once again harnessing the power of Lambdas as Lambdas to allow developers to focus on writing code.

Today, we will walkthrough creating a simple serverless app using AWS and Pulumi. We will simplify implementing the OAuth protocol by using Auth0 and AWS Lambda authorizers to authorize users. Auth0 provides a universal authentication and authorization platform for applications. It has become an extremely popular platform for user management because Auth0 makes OAuth easy.

Concepts

Before we get started, let’s go over some concepts we’ll be using.

API Gateway

An API Gateway takes clients requests and then re-routes them to the appropriate backend service. Typically, a gateway serves as the “front door” for an API and is used for traffic management as well as flexible security controls.

Using AWS API Gateway, you can build a fully managed collection of resources which integrate with AWS Lambda and various other AWS resources. To control who can call your API, you can use IAM permissions, an Amazon Cognito User Pool or set up custom logic using a Lambda authorizer.

OAuth

OAuth is an industry-standard for token-based authorization. Using OAuth, users can grant third-party applications or websites access to their information on another website without disclosing their password. Google and Facebook are two very common examples of sites that permit users to share their personal information with websites or applications using OAuth.

Lambda Authorizers

An AWS Lambda authorizer is a Lambda that provides access control to an API. It contains custom logic for authorizing requests to an endpoint. If a Lambda authorizer is configured, API Gateway routes a client’s call to the Lambda first. The Lambda authorizer runs its custom logic and returns a Policy and principal ID, which are used by API Gateway to determine if the call to the backend is allowed.

Step-by-Step Guide To Creating a Lambda Authorizer

Using a Lambda authorizer, we can implement the authorization flow using Auth0 to handle our Access Tokens.

API Gateway can be used to protect many different resources, and in the following example we will front an AWS Lambda. Users authenticate with Auth0 and then use the token they’ve obtained to make a request to our Lambda via our API Gateway, which authorizes the request by validating the token with Auth0. Some of the code examples have been stubbed or shortened for this blog post. The full code example can be found in our Pulumi examples repo.

Below is a diagram of the architecture we will set up. In Step 1, we will create our API Gateway and Hello World Lambda. In Step 2, we will set up the logic for our Lambda authorizer. And finally in Step 3, we will bring it all together by telling API Gateway to use our authorizer.

1 - Define Your Routes

Using Pulumi’s AWSX package, you can easily define routes to serverless apps as well as routes to static resources. We will create a very simple Hello world! backend Lambda, but in practice you can have this do much more interesting things.

import * as awsx from "@pulumi/awsx";

// Create our API and reference the Lambda authorizer
const api = new awsx.apigateway.API("myapi", {
    routes: [{
        path: "/hello",
        method: "GET",
        eventHandler: async () => {
            return {
                statusCode: 200,
                body: "<h1>Hello world!</h1>",
            };
        },
    }],
});

2 - Write Your Custom Auth Logic

Just as Pulumi allows you to define your Lambda inline, you can define your custom authorization code. We will define a small wrapper for our custom logic and write the rest of the code as a function called authenticate. Pulumi will package up all our runtime code and create an AWS Lambda for us.

import * as awsx from "@pulumi/awsx";
import * as pulumi from '@pulumi/pulumi';

import * as jwksClient from 'jwks-rsa';
import * as jwt from 'jsonwebtoken';
import * as util from 'util';

const config = new pulumi.Config();
const jwksUri = config.require("jwksUri");
const audience = config.require("audience");
const issuer = config.require("issuer");

const authorizerLambda = async (event: awsx.apigateway.AuthorizerEvent) => {
    try {
        return await authenticate(event);
    }
    catch (err) {
        console.log(err);
        // Tells API Gateway to return a 401 Unauthorized response
        throw new Error("Unauthorized");
    }
}

/**
 * Below is all code that gets added to the Authorizer Lambda. The code was copied and
 * converted to TypeScript from
 * [Auth0's GitHub Example](https://github.com/auth0-samples/jwt-rsa-aws-custom-authorizer)
 */

function getToken(event: awsx.apigateway.AuthorizerEvent): string {
    // Stubbed function to extract and return the Bearer Token from the Lambda event parameter
}

// Check if the Token is valid with Auth0
async function authenticate(event: awsx.apigateway.AuthorizerEvent): Promise<awsx.apigateway.AuthorizerResponse> {
    const token = getToken(event);

    const decoded = jwt.decode(token, { complete: true });
    if (!decoded || typeof decoded === "string" || !decoded.header || !decoded.header.kid) {
        throw new Error('invalid token');
    }

    const client = jwksClient({
        cache: true,
        rateLimit: true,
        jwksRequestsPerMinute: 10, // Default value
        jwksUri: jwksUri
    });

    const key = await util.promisify(client.getSigningKey)(decoded.header.kid);
    const signingKey = key.publicKey || key.rsaPublicKey;
    if (!signingKey) {
        throw new Error('could not get signing key');
    }

    const verifiedJWT = await jwt.verify(token, signingKey, { audience, issuer });
    if (!verifiedJWT || typeof verifiedJWT === "string" || !isVerifiedJWT(verifiedJWT)) {
        throw new Error('could not verify JWT');
    }
    return awsx.apigateway.authorizerResponse(verifiedJWT.sub, 'Allow', event.methodArn);
}

3 - All Together Now

Now let’s tie it all together! We will modify the route we created in Step 1 to include our authorizer.

import * as awsx from "@pulumi/awsx";

// Create our API and reference the Lambda authorizer
const api = new awsx.apigateway.API("myapi", {
    routes: [{
        path: "/hello",
        ...
        authorizers: awsx.apigateway.getTokenLambdaAuthorizer({
            authorizerName: "jwt-rsa-custom-authorizer",
            header: "Authorization",
            handler: authorizerLambda,
            identityValidationExpression: "^Bearer [-0-9a-zA-Z._]*$",
            authorizerResultTtlInSeconds: 3600,
        }),
    }],
});

The Finished Product

When we run pulumi up, Pulumi will create our resources and provide us with our protected endpoint.

$ pulumi up
...
     Type Name Status Info
 + pulumi:pulumi:Stack lambda-authorizer-dev created 1 message
 + ├─ aws:apigateway:x:API myapi created
 + │ ├─ aws:iam:Role myapifc45ff03 created
 + │ ├─ aws:iam:RolePolicyAttachment myapifc45ff03-32be53a2 created
 + │ ├─ aws:lambda:Function myapifc45ff03 created
 + │ ├─ aws:apigateway:RestApi myapi created
 + │ ├─ aws:apigateway:Deployment myapi created
 + │ ├─ aws:lambda:Permission myapi-62a1b306 created
 + │ └─ aws:apigateway:Stage myapi created
 + ├─ aws:iam:Role jwt-rsa-custom-authorizer-authorizer-role created
 + ├─ aws:iam:Role jwt-rsa-custom-authorizer created
 + ├─ aws:iam:RolePolicyAttachment jwt-rsa-custom-authorizer-32be53a2 created
 + ├─ aws:lambda:Function jwt-rsa-custom-authorizer created
 + └─ aws:iam:RolePolicy jwt-rsa-custom-authorizer-invocation-policy created
Outputs:
    url: "https://XXXXX.execute-api.us-west-2.amazonaws.com/stage/"
Resources:
    + 14 created
Duration: 28s

You’ll notice there’s a ton of resources we didn’t explicitly define. AWSX provisions the appropriate Lambdas, roles, and more for you. If required, all of these resources can be overridden in your Pulumi program by explicitly defining them.

Let’s give try out our new API.

We can now curl our endpoint without a token and should get a 401 Unauthorized response.

$ curl $(pulumi stack output url)hello
{"message":"Unauthorized"}

We can curl our endpoint with an invalid token and should once again get a 401 Unauthorized response.

$ curl $(pulumi stack output url)hello -H "Authorization: Bearer invalid"
{"message":"Unauthorized"}

Finally, we expect a 200 response when we obtain a token from Auth0 and use it to call our API. We can get a token by visiting the API Details page for our API and clicking the Test tab. This provides us with a valid token for testing purposes only. The way tokens are acquired by users or client apps will depend on the type of application (i.e. native mobile app, single-page app, web app, etc.) being developed. For more information on authenticating users, visit Auth0’s documentation.

Using the test access token, the API will return a 200 response: Hello world!

$ curl $(pulumi stack output url)hello -H "Authorization: Bearer <VALID_TOKEN>"
<h1>Hello world!</h1>

For the complete code example, visit our examples repo.

Keep It Going

While we used OAuth and Auth0 in this blog post, AWS Lambda authorizers are an extremely flexible tool that allow you to implement whatever custom authorization logic you require. AWS also supports Cognito Authorizers, which use AWS Cognito User Pools, and we will share even more examples soon.

There are a vast amount of resources for deploying your code into the cloud, and we want to make it easier for developers to make the most of those resources. Pulumi’s AWSX package provides reusable abstractions to enable developers to get their code production ready faster.

Get going with these resources: