All jobs

Add a Policy Pack to a Pulumi Program

Yes. An agent reads what your Pulumi program creates, writes a CrossGuard policy pack for those intentions, and proves it on previews with and without a violation.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the program before it writes a rule. In a program shaped like pulumi/examples' aws-ts-s3-folder, Pulumi.yaml names a nodejs runtime with an aws:region config defaulting to us-west-2, package.json is "type": "module" on @pulumi/pulumi 3.228.0 and @pulumi/aws 7.23.0 with mime for content types, and tsconfig.json compiles index.ts alone with module: nodenext and strict. index.ts creates one aws.s3.Bucket, a BucketWebsiteConfiguration with index.html as the index document, a BucketPublicAccessBlock with blockPublicAcls: false, one BucketObject per file in www with contentType from mime, and a BucketPolicy that grants s3:GetObject to Principal: "*" with dependsOn the access block. The stack exports bucketName and websiteUrl. So this is a bucket that is public on purpose, and a generic no-public-buckets rule would fail it on day one.

It also reads what a pack looks like in this repository, because the shape is already there to copy. policy-packs/aws-ts holds PulumiPolicy.yaml with runtime: nodejs, a package.json on @pulumi/policy 1.21.0 and the same @pulumi/aws version, and an index.ts that builds a PolicyPack with validateResourceOfType rules such as a mandatory Name tag on EC2 instances and VPCs and a mandatory ban on 0.0.0.0/0 ingress, with enforcementLevel set per rule. testing-pac-ts/tests shows the other kind, a StackValidationPolicy whose validateStack walks args.resources, filters with isType and reads fields with asType, and guards cloud lookups behind pulumi.runtime.isDryRun().

The pack it writes lives in a policy/ directory beside index.ts and says what this program means. A mandatory resource policy on aws.s3.BucketPolicy parses the policy document and refuses any statement whose principal is * and whose actions are anything but s3:GetObject, so a future edit cannot widen the public grant to s3:*. A mandatory policy on aws.s3.BucketObject requires a contentType, which the mime call supplies today and a copied loop might forget. An advisory policy on aws.s3.BucketPublicAccessBlock reports when blockPublicAcls is false and the stack has no BucketPolicy at all, which is the stack-level case, written as a validateStack that counts both resource types. Each rule has a description that reads as the sentence a reviewer would otherwise type.

Then it runs the pack. In the sandbox the agent uses a local backend with pulumi login --local, creates a throwaway stack with aws:region set and the provider's credential validation skipped, so pulumi preview --policy-pack policy evaluates the rules without AWS credentials and without creating anything. The first preview passes. It then widens the bucket policy's action to s3:* on a scratch copy, runs the preview again and keeps the output where the mandatory rule fails the preview with the rule's own message, restores the file, and runs tsc --noEmit in both the program and the pack. The README gains a Policy section showing the --policy-pack flag the repository's own tests already use.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a Pulumi CrossGuard policy pack to this program. Read Pulumi.yaml, package.json, tsconfig.json and index.ts first and list every resource the program creates with the properties that express an intention, such as a public-read bucket policy or a content type on each object. Write a policy pack in a policy/ directory with PulumiPolicy.yaml, its own package.json on @pulumi/policy and the same provider package version as the program, and an index.ts with one PolicyPack. Encode the program's own intentions as rules: mandatory rules for anything a future edit could silently widen, such as a wildcard-principal bucket policy granting more than read, and advisory rules for things worth a warning. Include at least one stack-level validation. Give each rule a description a reviewer would understand. Log in to a local backend, create a throwaway stack with the region set and provider credential validation skipped, and run pulumi preview --policy-pack policy; then introduce a violation on a scratch copy, show the mandatory rule failing the preview, and restore the file. Run tsc --noEmit in both directories. Add a Policy section to the README and open a pull request that lists each rule with its enforcement level and quotes both previews.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that adds policy/PulumiPolicy.yaml, policy/package.json, policy/tsconfig.json and policy/index.ts, and a Policy section in README.md. index.ts and Pulumi.yaml are unchanged, which the description points out, because the pack describes the program rather than altering it.

The description lists each rule with its enforcement level and its description string, then quotes the two previews from the sandbox: the clean one where every policy reports as passed, and the one on the widened bucket policy where the mandatory rule refuses the preview with its message. It names the config the throwaway stack used so a reviewer can repeat the run without AWS credentials.

Before merging, a reviewer decides which advisory rules should become mandatory, checks that the read-only principal rule parses the policy document rather than string-matching it, and chooses whether the pack runs from the program directory on every preview or is published to the organisation and enforced centrally. Adding a tagging rule or a region allow-list is a follow-up on the same session.

Run it on every program ready for guardrails

This is a change an engineer starts from the terminal and reads later: one POST /o/{org}/sessions with this prompt and the repository in resources, then the laptop closes. The run reads the program, writes the pack, runs both previews and opens the pull request with nobody watching. The sandbox parks with its disk when the turn ends, so a follow-up such as make the content-type rule advisory and add a Name tag rule for the bucket wakes it with the local backend and the stack still there.

A platform team with many Pulumi programs sends the same body once per repository, one run each, and each run writes rules for what that program actually creates. Give the API key a webhook_url and Rush posts run.completed or run.failed with the session_url when each turn ends, so the pull request links collect in one channel. Send a request_id so a retried POST returns the run it already started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A policy pack is only useful if it fails the right preview and passes the right one, and the way to know is to run both. That needs a backend, a stack, the provider configured to skip credential checks, and a deliberate violation to confirm the mandatory rule bites. The agent does that sequence in its own sandbox and keeps both outputs, so the pull request shows the rule working rather than describing what it should do.

Reading the program first is what keeps the rules honest. A generic pack would forbid the public bucket this program exists to create; the agent's rules say instead that public means read-only and every object carries a content type, which is what the author meant. The transcript shows where each rule came from in index.ts, so a reviewer can trace a rule to a line and tighten or loosen it in a follow-up.

Frequently asked questions

Why not just forbid public S3 buckets?

Because this program creates a static website, and the bucket is public by design. The pack encodes the narrower intention: a wildcard principal may be granted s3:GetObject and nothing else, and the public access block must be paired with a bucket policy. A blanket rule would fail the first preview and be disabled by lunchtime.

Does running the preview need AWS credentials?

No. The agent uses a local backend and a throwaway stack with the region set and the provider's credential validation skipped, so pulumi preview evaluates the resources and the policies without calling AWS or creating anything. The description names that config so you can repeat it.

Will the pack run on every pulumi up?

Only when you pass --policy-pack policy, or once the pack is published to your Pulumi organisation and enforced there. The README section documents the flag, and the pull request leaves the central enforcement choice to you.

What is the difference between mandatory and advisory here?

A mandatory rule fails the preview, so a widened bucket policy or an object without a content type never reaches pulumi up. An advisory rule prints a warning and lets the preview continue, which is how the pack starts for anything the team might legitimately change.

Can the same pack cover my other programs?

The rules are written against resource types, not resource names, so they apply to any program using the same provider. The agent writes them for what this program creates; a run on another repository reads that program and proposes rules for its resources.

More Pulumi jobs

More jobs like this: Hand off a long task

Keep reading