# 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 Rush](https://cloud.getrush.ai/run/add-policy-pack/pulumi/). Opens 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`

```json
{
  "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.

## 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

- [Post Pulumi Previews on Pull Requests](https://getrush.ai/run/add-preview-comments-to-pr/pulumi/)
- [Tag Every Resource in a Pulumi Program](https://getrush.ai/run/add-resource-tags/pulumi/)
- [Split a Pulumi Program Into Stacks Linked by StackReference](https://getrush.ai/run/add-stack-references/pulumi/)

## More jobs like this: Hand off a long task

- [Add Pools to Limit Concurrent Tasks in Airflow](https://getrush.ai/run/add-pools/airflow/)
- [Add a Post-Deploy Smoke Test to a Fly.io Workflow](https://getrush.ai/run/add-post-deploy-smoke-test/fly/)
- [Add pre-commit Hooks to an Ansible Role](https://getrush.ai/run/add-pre-commit-hooks/ansible/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
