# Pike
[](https://GitHub.com/jameswoolfenden/pike/graphs/commit-activity)
[](https://github.com/JamesWoolfenden/pike/actions/workflows/ci.yml)
[](https://github.com/JamesWoolfenden/pike/releases/latest)
[](https://github.com/JamesWoolfenden/pike/releases/latest)
[](https://github.com/pre-commit/pre-commit)
[](https://www.checkov.io/)
[](https://github.com/JamesWoolfenden/pike/releases)
[](https://codecov.io/gh/JamesWoolfenden/pike)
[](https://www.bestpractices.dev/projects/7032)
Pike is a tool to determine the minimum IAM permissions required to run OpenTofu/Terraform infrastructure code.
**What's new?**
- JSON modules support.
- GCP compare, checks IAC permissions required versus a deployed role.
- Backend detection S3 and GCP.
Pike currently supports OpenTofu/Terraform and supports multiple providers (AWS, GCP and AZURE);
Azure is the newest with AWS having the most supported resources
<https://github.com/JamesWoolfenden/pike/tree/master/src/mapping>.
Feel free to submit PR or Issue if you find an issue or even better add new resources, and then I'll take a look at
merging it ASAP.
**Note on Placeholder Resources:** Some resources in the lookup maps (particularly GCP organization, folder, and billing-level resources) are marked with `placeholder` entries. These resources are recognized by Pike but do not have empirically validated IAM permissions because they require organization-level access or specialized account types that are difficult to test. When Pike encounters these resources, it will not error, but the permissions have not been validated through actual resource lifecycle testing.
**CAVEAT** The outputs of this tool are your first step, if you have AWS, you can now generate resources partially,
there are no conditions and even partial resources are wild-carded (for now).
(for AWS)minimum
**best practice** would go further (and I am working on it as well), you will need to modify these permissions to the
required in your environment by adding these
restrictions, you can also deploy using short-lived credentials (using this tool or Vault) (in AWS so far), generating
short-lived credentials for your build
and then remotely (REMOTE) supply and invoke your builds (INVOKE).
Ideally I would like to do this for you, but these policies are currently determined statically (QUICKER), and
unrecorded intentions can be impossible to infer.
## Quick Start
Get started with Pike in 3 steps:
1. **Install Pike**
```shell
# macOS
brew tap jameswoolfenden/homebrew-tap
brew install jameswoolfenden/tap/pike
# Windows (using Scoop)
scoop bucket add iac https://github.com/JamesWoolfenden/scoop.git
scoop install pike
# Or install from source
go install github.com/jameswoolfenden/pike@latest
```
2. **Scan your OpenTofu/Terraform code**
```shell
pike scan -d ./path/to/your/terraform
```
This outputs the minimum IAM permissions required as JSON.
3. **Generate as Terraform/OpenTofu code**
```shell
pike scan -o terraform -d ./path/to/your/terraform
```
This creates an `aws_iam_policy` resource you can deploy.
**Next steps:** Use `pike make` to deploy the policy directly, or `pike compare` to validate against existing policies. See [Usage](#usage) for all commands.
## Table of Contents
<!--toc:start-->
- [Pike](#pike)
- [Quick Start](#quick-start)
- [Table of Contents](#table-of-contents)
- [Install](#install)
- [MacOS](#macos)
- [Windows](#windows)
- [Docker](#docker)
- [Usage](#usage)
- [Scan](#scan)
- [Output](#output)
- [Make](#make)
- [Invoke](#invoke)
- [Apply](#apply)
- [Remote](#remote)
- [Readme](#readme)
- [Pull](#pull)
- [Runtime](#runtime)
- [Watch](#watch)
- [Parse](#parse)
- [Compare](#compare)
- [Audit](#audit)
- [Help](#help)
- [Building](#building)
- [Inspect](#inspect)
- [Extending](#extending)
- [Add Import mapping file](#add-import-mapping-file)
- [Add to provider Scan](#add-to-provider-scan)
- [Related Tools](#related-tools)
<!--toc:end-->
## Install
Download the latest binary here:
<https://github.com/JamesWoolfenden/pike/releases>
Install from code:
- Clone repo
- Run `go install`
Install remotely:
```shell
go install github.com/jameswoolfenden/pike@latest
```
### MacOS
```shell
brew tap jameswoolfenden/homebrew-tap
brew install jameswoolfenden/tap/pike
```
### Windows
I'm now using Scoop to distribute releases, it's much quicker to update and easier to manage than previous methods,
you can install scoop from <https://scoop.sh/>.
Add my scoop bucket:
```shell
scoop bucket add iac https://github.com/JamesWoolfenden/scoop.git
```
Then you can install a tool:
```bash
scoop install pike
```
### Docker
```shell
docker pull jameswoolfenden/pike
docker run --tty --volume /local/path/to/tf:/tf jameswoolfenden/pike scan -d /tf
```
<https://hub.docker.com/repository/docker/jameswoolfenden/pike>
## Usage
### Scan
To scan a directory containing OpenTofu/Terraform files:
```shell
./pike scan -d .\terraform\
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"ec2:MonitorInstances",
"ec2:UnmonitorInstances",
"ec2:DescribeInstances",
"ec2:DescribeTags",
"ec2:DescribeInstanceAttribute",
"ec2:DescribeVolumes",
"ec2:DescribeInstanceTypes",
"ec2:RunInstances",
"ec2:DescribeInstanceCreditSpecifications",
"ec2:StopInstances",
"ec2:StartInstances",
"ec2:ModifyInstanceAttribute",
"ec2:TerminateInstances",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:CreateSecurityGroup",
"ec2:DescribeSecurityGroups",
"ec2:DescribeAccountAttributes",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteSecurityGroup",
"ec2:RevokeSecurityGroupEgress"
],
"Resource": "*"
}
}
```
You can also generate the policy as OpenTofu/Terraform instead:
```bash
$pike scan -o terraform -d ../modules/aws/terraform-aws-activemq
resource "aws_iam_policy" "terraformXVlBzgba" {
name = "terraformXVlBzgba"
path = "/"
description = "Add Description"
policy = jsonencode({
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DeleteSecurityGroup",
"ec2:DeleteTags",
"ec2:DescribeAccountAttributes",
"ec2:DescribeInternetGateways",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DetachNetworkInterface",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress"
],
"Resource": "*"
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"kms:CreateKey",
"kms:DescribeKey",
"kms:EnableKeyRotation",
"kms:GetKeyPolicy",
"kms:GetKeyRotationStatus",
"kms:ListResourceTags",
"kms:ScheduleKeyDeletion",
"kms:TagResource",
"kms:UntagResource"
],
"Resource": "*"
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"mq:CreateBroker",
"mq:CreateConfiguration",
"mq:CreateTags",
"mq:CreateUser",
"mq:DeleteBroker",
"mq:DeleteTags",
"mq:DeleteUser",
"mq:DescribeBroker",
"mq:DescribeConfiguration",
"mq:DescribeConfigurationRevision",
"mq:DescribeUser",
"mq:RebootBroker",
"mq:UpdateBroker",
"mq:UpdateConfiguration",
"mq:UpdateUser"
],
"Resource": "*"
}
]
})
}
```
And I am working on further enhancements to policy generation, if you have AWS auth installed:
```shell
e:\pike scan -d . -i -e
9:13AM DBG terraform init at E:\Code\modules\aws\terraform-aws-activemq
9:13AM DBG downloaded ip
resource "aws_iam_policy" "terraform_pike" {
name_prefix = "terraform_pike"
path = "/"
description = "Pike Autogenerated policy from IAC"
policy = jsonencode({
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:DeleteNetworkInterface",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DeleteSecurityGroup",
"ec2:DeleteTags",
"ec2:DescribeAccountAttributes",
"ec2:DescribeInternetGateways",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ec2:DetachNetworkInterface",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress"
],
"Resource": [
"arn:aws:ec2:eu-west-2:680235478471:*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"kms:CreateGrant"
],
"Resource": [
"arn:aws:kms:eu-west-2:680235478471:*"
]
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"mq:CreateBroker",
"mq:CreateConfiguration",
"mq:CreateTags",
"mq:CreateUser",
"mq:DeleteBroker",
"mq:DeleteTags",
"mq:DeleteUser",
"mq:DescribeBroker",
"mq:DescribeConfiguration",
"mq:DescribeConfigurationRevision",
"mq:DescribeUser",
"mq:RebootBroker",
"mq:UpdateBroker",
"mq:UpdateConfiguration",
"mq:UpdateUser"
],
"Resource": [
"arn:aws:mq:eu-west-2:680235478471:*"
]
}
]
})
}
```
### Escalation-class permissions
When a Terraform config manages its own IAM (`google_project_iam_*`, `aws_iam_role_policy*`, `azurerm_role_assignment`), the minimum-sufficient role pike computes is also owner-equivalent — the holder can grant themselves anything. Pike always warns about these on stderr:
```text
WARNING: escalation-class permissions detected — holder can grant themselves additional access.
Consider the two-role pattern: planner SA (read-only) on all branches,
applier SA (full) on protected branches only.
aws: iam:PassRole, iam:PutRolePolicy
```
No flag is needed to enable this; it fires whenever escalation-class permissions are present.
The same warning also fires for dangerous *combinations* of otherwise-unremarkable permissions — e.g. `iam:PassRole` paired with `lambda:CreateFunction` or `ec2:RunInstances` lets you choose which compute resource receives that role, and `iam:CreateAccessKey` paired with `iam:ListUsers` lets you mint credentials for any user:
```text
Dangerous combinations (no single permission above reveals this; together they do):
aws: iam:PassRole + lambda:CreateFunction
```
Pass `--strict` to `pike scan` to exit non-zero when either kind of escalation-class permission is present, even though scan still succeeds in producing output (`pike compare --strict` does the same for the live-vs-IaC comparison). Pass `--no-lint` to suppress the warning (and the `--strict` check) entirely — useful if you're piping scan's policy output somewhere and don't want lint noise on stderr.
```bash
pike scan --strict -d ./terraform
pike scan --no-lint -o json -d ./terraform | some-other-tool
```
### Split output
Use `--output split` (or `-o split`) to emit two permission sets — `base` (safe to distribute broadly) and `escalation` (owner-equivalent, restrict to protected branches) — instead of a single flat policy:
```bash
pike scan -o split -d ./terraform
```
```json
{
"aws": {
"base": [
"firehose:CreateDeliveryStream",
"firehose:DeleteDeliveryStream",
"iam:GetRole",
"iam:ListAttachedRolePolicies"
],
"escalation": [
"iam:AttachRolePolicy",
"iam:PassRole",
"iam:PutRolePolicy"
]
}
}
```
The `base` set is the planner SA role (safe for `terraform plan` on every branch). The `escalation` set is the additional permissions the applier SA needs — bind this role only on protected branches.
With `--write` / `-w`, the split JSON is saved to `.pike/pike.generated_policy.split.json`.
### Deletion-sensitive permissions
Pike also warns when your Terraform manages stateful or expensive resources (GKE/EKS clusters, Cloud SQL/RDS databases, storage buckets, KMS keys) where accidental deletion is costly:
```text
WARNING: deletion-sensitive permissions detected — granting destroy on stateful/expensive resources.
GCP:
[HIGH] google_container_cluster
GKE clusters take 10+ minutes to recreate; workloads experience downtime
→ deletion_protection = true
[HIGH] google_sql_database_instance
Cloud SQL instances contain stateful data; point-in-time recovery may be lost
→ deletion_protection_enabled = true
```
Use `--sensitive` to generate a three-role split that separates high-risk delete permissions into a break-glass role:
```bash
pike scan -d ./terraform --sensitive
```
This outputs three Terraform roles:
- `terraform_pike_safe` — day-to-day operations (create, read, update) without high-risk deletes
- `terraform_pike_delete` — high-risk destruction permissions only (break-glass, requires approval)
- `terraform_pike_plan` — read-only permissions for `terraform plan`
Grant the delete role only to:
- Break-glass principals requiring approval workflows
- Decommissioning pipelines with manual gates
- Disaster recovery automation with audit logging
### Output
If you select the -w flag, pike will write out the role/policy required to build your project into the .pike folder:
```bash
$pike scan -w -i -d .
2022/09/17 13:50:51 terraform init at .
2022/09/17 13:50:51 downloaded ip
```
The .pike folder will contain:
``` shell
aws_iam_role.terraform_pike.tf
pike.generated_policy.tf
```
Which you can deploy using OpenTofu/Terraform to create the role/policy to build your infrastructure project.
### Make
You can now deploy the policy you need directly (AWS only so far):
```bash
$pike make -d ../modules/aws/terraform-aws-apigateway/
2022/09/18 08:53:41 terraform init at ..\modules\aws\terraform-aws-apigateway\
2022/09/18 08:53:41 modules not found at ..\modules\aws\terraform-aws-apigateway\
2022/09/18 08:53:49 aws role create/updated arn:aws:iam::680235478471:role/terraform_pike_20220918071439382800000002
arn:aws:iam::680235478471:role/terraform_pike_20220918071439382800000002
```
This new verb returns the ARN of the role created, and you can find the Terraform used in your .pike folder.
### Invoke
Invoke is currently for triggering GitHub actions, if supplied with the workflow (defaults to main.yaml), repository and
branch (defaults to main) flags, it will trigger the dispatch event.
You'll need to include the dispatch event in your workflow:
```yaml
on:
workflow_dispatch:
push:
branches:
- master
```
To authenticate with the GitHub API, you will need to set your GitHub Personal Access Token, as the environment variable
*GITHUB_TOKEN*
To Invoke a workflow, it is then:
```shell
pike invoke -workflow master.yml -branch master -repository JamesWoolfenden/terraform-aws-s3
```
I created Invoke to be used in tandem with the new remote command which supplies temporary credentials to a workflow.
**Note The GitHub API is rate-limited, usually 5000 calls per hour.
```shell
pike make -d ./module/aws/terraform-aws-s3/example/examplea
```
### Apply
Apply is an extension to make and will apply the policy and role and use that role to create your infrastructure:
```shell
pike apply -d ./module/aws/terraform-aws-s3/example/examplea -region eu-west-2
```
It is intended for testing and developing the permissions for Pike itself
### Remote
Remote uses the core code of make and apply, to write temporary AWS credentials(only so far) into your workflow.
```shell
pike remote -d ./module/aws/terraform-aws-s3/example/examplea -region eu-west-2 -repository terraform-aws-s3
```
### Readme
Pike can now be used to update a projects README.md file:
./pike readme -o terraform -d ..\modules\aws\terraform-aws-activemq\
This looks in the README for the delimiters:
```html
<!-- BEGINNING OF PRE-COMMIT-PIKE DOCS HOOK -->
<!-- END OF PRE-COMMIT-PIKE DOCS HOOK -->
```
and replaces is either with JSON or Terraform like so:
```markdown
This is the policy required to build this project:
The Policy required is
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": [
"mq:CreateTags",
"mq:DeleteTags",
"ec2:DescribeInternetGateways",
"ec2:DescribeAccountAttributes",
"ec2:DescribeVpcs",
"ec2:DescribeSubnets",
"ec2:DescribeSecurityGroups",
"ec2:CreateNetworkInterface",
"ec2:CreateNetworkInterfacePermission",
"ec2:DeleteNetworkInterfacePermission",
"ec2:DetachNetworkInterface",
"ec2:DeleteNetworkInterface",
"mq:CreateBroker",
"mq:DescribeBroker",
"mq:DescribeUser",
"mq:UpdateBroker",
"mq:DeleteBroker",
"mq:CreateConfiguration",
"mq:UpdateConfiguration",
"mq:DescribeConfiguration",
"mq:DescribeConfigurationRevision",
"mq:RebootBroker",
"ec2:CreateTags",
"ec2:DeleteTags",
"ec2:CreateSecurityGroup",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteSecurityGroup",
"ec2:RevokeSecurityGroupEgress",
"kms:TagResource",
"kms:UntagResource",
"kms:EnableKeyRotation",
"kms:CreateKey",
"kms:DescribeKey",
"kms:GetKeyPolicy",
"kms:GetKeyRotationStatus",
"kms:ListResourceTags",
"kms:ScheduleKeyDeletion"
],
"Resource": "*"
}
}
```
You can see an example here <https://github.com/jamesWoolfenden/terraform-aws-activemq#policy>.
## Compare
Want to check your deployed IAM policy against your infrastructure code requirement?
This works for AWS and GCP.
>$./pike compare -d ../modules/aws/terraform-aws-appsync -a arn:aws:iam::680235478471:policy/basic
```markdown
IAM Policy arn:aws:iam::680235478471:policy/basic versus Infrastructure Code ../modules/aws/terraform-aws-appsync
{
"Statement": [
0: {
"Action": [
- 0: "kinesisvideo:CreateStream"
+ 0: "firehose:CreateDeliveryStream"
+ 0: "firehose:CreateDeliveryStream"
+ 1: "firehose:DeleteDeliveryStream"
+ 2: "firehose:DescribeDeliveryStream"
+ 3: "firehose:ListTagsForDeliveryStream"
+ 4: "iam:AttachRolePolicy"
+ 5: "iam:CreateRole"
+ 6: "iam:DeleteRole"
+ 7: "iam:DetachRolePolicy"
+ 8: "iam:GetRole"
+ 9: "iam:ListAttachedRolePolicies"
+ 10: "iam:ListInstanceProfilesForRole"
+ 11: "iam:ListRolePolicies"
+ 12: "iam:PassRole"
+ 13: "iam:TagRole"
+ 14: "kms:CreateKey"
+ 15: "kms:DescribeKey"
+ 16: "kms:EnableKeyRotation"
+ 17: "kms:GetKeyPolicy"
+ 18: "kms:GetKeyRotationStatus"
+ 19: "kms:ListResourceTags"
+ 20: "kms:ScheduleKeyDeletion"
+ 21: "logs:AssociateKmsKey"
+ 22: "logs:CreateLogGroup"
+ 23: "logs:DeleteLogGroup"
+ 24: "logs:DeleteRetentionPolicy"
+ 25: "logs:DescribeLogGroups"
+ 26: "logs:DisassociateKmsKey"
+ 27: "logs:ListTagsLogGroup"
+ 28: "logs:PutRetentionPolicy"
+ 29: "s3:CreateBucket"
+ 30: "s3:DeleteBucket"
+ 31: "s3:GetAccelerateConfiguration"
+ 32: "s3:GetBucketAcl"
+ 33: "s3:GetBucketCORS"
+ 34: "s3:GetBucketLogging"
+ 35: "s3:GetBucketObjectLockConfiguration"
+ 36: "s3:GetBucketPolicy"
+ 37: "s3:GetBucketPublicAccessBlock"
+ 38: "s3:GetBucketRequestPayment"
+ 39: "s3:GetBucketTagging"
+ 40: "s3:GetBucketVersioning"
+ 41: "s3:GetBucketWebsite"
+ 42: "s3:GetEncryptionConfiguration"
+ 43: "s3:GetLifecycleConfiguration"
+ 44: "s3:GetObject"
+ 45: "s3:GetObjectAcl"
+ 46: "s3:GetReplicationConfiguration"
+ 47: "s3:ListAllMyBuckets"
+ 48: "s3:ListBucket"
+ 49: "s3:PutBucketAcl"
+ 50: "s3:PutBucketPublicAccessBlock"
+ 51: "s3:PutEncryptionConfiguration"
+ 52: "wafv2:CreateWebACL"
+ 53: "wafv2:DeleteWebACL"
+ 54: "wafv2:GetWebACL"
],
"Effect": "Allow",
"Resource": "*",
- "Sid": ""
+ "Sid": "VisualEditor0"
}
],
"Version": "2012-10-17"
}
```
Pike always warns to stderr when the computed policy contains escalation-class permissions (see [Escalation-class permissions](#escalation-class-permissions)). Pass `--strict` to also exit non-zero in that case, even if the policies otherwise match — useful in CI to enforce the two-role pattern:
```bash
pike compare --strict -d ./terraform -a arn:aws:iam::680235478471:policy/terraform_pike
```
### Comparing against a file instead of a live policy
`--target-file` reads the baseline policy from a local file instead of calling the live AWS/GCP API, so CI can diff against a committed snapshot with no cloud credentials at all. `--write-baseline` writes the freshly generated IaC policy to a file, to seed or refresh that snapshot. `-a`/`--arn` is still required (its format is how pike picks AWS vs GCP), but with `--target-file` set it's never used to make a live call.
```bash
# One-off, with live credentials: seed the baseline and confirm it matches deployed today.
pike compare -d ./terraform -a arn:aws:iam::680235478471:policy/terraform_pike --write-baseline ./policy-baseline.json
# Every CI run after that: no credentials needed.
pike compare -d ./terraform -a arn:aws:iam::680235478471:policy/terraform_pike --target-file ./policy-baseline.json
```
## Audit
`pike audit` runs a set of deterministic rules over the IAM-relevant resources in your Terraform — wildcard actions, escalation-class permissions granted without a scoping Condition, public principals, admin-class managed policy attachments, risky trust-policy principals, and more — without needing any cloud credentials at all.
```bash
pike audit -d ./terraform
```
Exits non-zero when any finding is present, so it's CI-friendly as a gate. Pass `-o json` for machine-readable output, or `--min-severity` to filter noise.
### Attachment and policy-data reference graphs
A policy's own findings are generated where the policy is *defined* — but the risk is really about who ends up *holding* it. When a customer-managed `aws_iam_policy` is attached via `aws_iam_role_policy_attachment`/`_user_`/`_group_`/`aws_iam_policy_attachment`, or a GCP `data.google_iam_policy`'s bindings are applied via a `google_project_iam_policy`/`_folder_`/`_organization_` resource's `policy_data`, pike resolves that reference and re-attributes the policy's findings to whoever ends up holding it — on top of (not instead of) the standalone finding on the policy/data source itself:
```text
129 HIGH AWS001 aws_iam_policy.wide — statement[0] allows Action "*"
full-wildcard action grants every API call
136 HIGH AWS001 aws_iam_role_policy_attachment.wide_to_ci — role aws_iam_role.ci ends up with (via aws_iam_policy.wide): statement[0] allows Action "*"
full-wildcard action grants every API call
```
```text
19 CRITICAL GCP001 google_project_iam_policy.authoritative — authoritative policy ends up with (via data.google_iam_policy.x): grants primitive role roles/owner
owner is project-admin equivalent; use a least-privilege predefined or custom role
24 CRITICAL GCP001 data.google_iam_policy.x — grants primitive role roles/owner
owner is project-admin equivalent; use a least-privilege predefined or custom role
```
Resolution is scoped to resources parsed in a single `pike audit` run (one directory) — a policy defined in a module with the attachment at the root call site, or vice versa, won't be traced, since each is a separate pass over that location's `.tf` files.
## Pull
Pull adds the ability to work with Git repositories (thanks to **go-git**),
to output the required permissions in JSON or OpenTofu/Terraform:
```bash
./pike pull
NAME:
pike pull - Clones remote repo and scans it using pike
USAGE:
pike pull [command options] [arguments...]
OPTIONS:
--directory value, -d value Directory to scan (defaults to .) (default: ".")
--destination value, --dest value Where to clone repository (default: ".destination")
--output json, -o json Policy Output types e.g. json terraform (default: "terraform") [%OUTPUT%]
--repository value, -r value Repository url
--init, -i Run Terraform init to download modules (default: false)
--write, -w Write the policy output to a file at .pike (default: false)
--help, -h show help
```
Like so:
```hcl
$ ./pike.exe pull -r https://github.com/JamesWoolfenden/terraform-aws-codebuild -i -d .
10:31PM INF .destination was not empty, removing
10:31PM INF git clone https://github.com/JamesWoolfenden/terraform-aws-codebuild .destination --recursive
10:31PM DBG terraform init at E:\Code\pike\.destination
10:31PM DBG modules not found at .destination
resource "aws_iam_policy" "terraform_pike" {
name_prefix = "terraform_pike"
path = "/"
description = "Pike Autogenerated policy from IAC"
policy = jsonencode({
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"codebuild:BatchGetProjects",
"codebuild:CreateProject",
"codebuild:DeleteProject",
"codebuild:UpdateProject"
],
"Resource": [
"*"
]
},
{
"Sid": "VisualEditor1",
"Effect": "Allow",
"Action": [
"events:DeleteRule",
"events:DescribeRule",
"events:ListTagsForResource",
"events:ListTargetsByRule",
"events:PutRule",
"events:PutTargets",
"events:RemoveTargets"
],
"Resource": [
"*"
]
},
{
"Sid": "VisualEditor2",
"Effect": "Allow",
"Action": [
"iam:AttachRolePolicy",
"iam:CreatePolicy",
"iam:CreateRole",
"iam:DeletePolicy",
"iam:DeleteRole",
"iam:DeleteRolePolicy",
"iam:DetachRolePolicy",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:ListAttachedRolePolicies",
"iam:ListInstanceProfilesForRole",
"iam:ListPolicyVersions",
"iam:ListRolePolicies",
"iam:PassRole",
"iam:PutRolePolicy",
"iam:TagRole"
],
"Resource": [
"*"
]
},
{
"Sid": "VisualEditor3",
"Effect": "Allow",
"Action": [
"kms:Decrypt"
],
"Resource": [
"*"
]
},
{
"Sid": "VisualEditor4",
"Effect": "Allow",
"Action": [
"s3:CreateBucket",
"s3:DeleteBucket",
"s3:GetAccelerateConfiguration",
"s3:GetBucketAcl",
"s3:GetBucketCORS",
"s3:GetBucketLogging",
"s3:GetBucketObjectLockConfiguration",
"s3:GetBucketPolicy",
"s3:GetBucketPublicAccessBlock",
"s3:GetBucketRequestPayment",
"s3:GetBucketTagging",
"s3:GetBucketVersioning",
"s3:GetBucketWebsite",
"s3:GetEncryptionConfiguration",
"s3:GetLifecycleConfiguration",
"s3:GetObject",
"s3:GetObjectAcl",
"s3:GetReplicationConfiguration",
"s3:ListAllMyBuckets",
"s3:ListBucket",
"s3:PutBucketAcl",
"s3:PutBucketLogging",
"s3:PutBucketPublicAccessBlock",
"s3:PutBucketVersioning",
"s3:PutEncryptionConfiguration",
"s3:PutLifecycleConfiguration"
],
"Resource": [
"*"
]
},
{
"Sid": "VisualEditor5",
"Effect": "Allow",
"Action": [
"ssm:AddTagsToResource",
"ssm:DeleteParameter",
"ssm:DescribeParameters",
"ssm:GetParameter",
"ssm:GetParameters",
"ssm:ListTagsForResource",
"ssm:PutParameter"
],
"Resource": [
"*"
]
}
]
})
}
```
### Runtime
`runtime` inspects IAC for permissions that only matter at runtime — for example, a GCP Cloud Run service account that needs to read from a Pub/Sub topic at request time rather than at `terraform apply` time.
```shell
pike runtime -d ./path/to/your/terraform -p gcp
```
Only GCP is supported today. Passing `--provider aws` or `--provider azure` returns an "not yet implemented" error rather than misleading stub output.
### Watch
`watch` polls IAM to block until a named policy's changes have propagated - useful immediately after `pike make` or `pike apply`, where AWS eventual consistency otherwise forces you to add ad-hoc sleeps in CI.
```shell
pike watch --arn arn:aws:iam::ACCOUNT_ID:policy/my-policy --wait 100
```
`--wait` is in tenths of seconds.
### Parse
`parse` walks a cloned Terraform provider repository and extracts its resources and data sources into a `<name>-members.json` lookup file. It is how Pike's provider mapping tables are regenerated (see `.github/workflows/resources.yml`) and is mainly useful to contributors adding provider coverage.
```shell
pike parse -d /path/to/terraform-provider-aws -name aws
```
Supported names today: `aws`, `azurerm`, `google`.
### Deprecated
`deprecated` lists the resources and datasources flagged as deprecated in the latest provider schemas Pike has embedded. It's a quick way to audit your Terraform before bumping a provider major — anything listed here will either already be warning on `pike scan` or is queued to be removed in a future provider release.
```shell
pike deprecated # all providers, text output
pike deprecated -n google # google only
pike deprecated -o json # machine-readable
```
The data is refreshed weekly by the `Resources` GitHub workflow and baked into each release binary; running `pike deprecated` offline works because no network call is made.
## Help
```bash
./pike -h
NAME:
pike - Generate IAM policy from your IAC code
USAGE:
pike [global options] command [command options]
VERSION:
9.9.9
AUTHOR:
James Woolfenden <james.woolfenden@gmail.com>
COMMANDS:
apply, a Create a policy and use it to instantiate the IAC
compare, c policy comparison of deployed versus IAC
inspect, x policy comparison of environment versus IAC
invoke, i Triggers a gitHub action specified with the workflow flag
make, m make the policy/role required for this IAC to deploy
parse, p Triggers a gitHub action specified with the workflow flag
pull, l Clones remote repo and scans it using pike
readme, r Looks in dir for a README.md and updates it with the Policy required to build the code
remote, o Create/Update the Policy and set credentials/secret for Github Action
scan, s scan a directory for IAM code
version, v Outputs the application version
watch, w Waits for policy update
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--help, -h show help
--version, -v print the version
```
## Building
```shell
go build
```
or
```Make
Make build
```
## Inspect
This new feature is in *beta* and is not yet fully supported and currently only for AWS.
When Pike is run with inspect, it will scan your code and output a policy that is required to deploy the code, as normal,
but it will also detect the running IAM credentials.
It will then report on the overlap between the running credentials and the minimum policy.
This works with AWS IAM user, group and role/assumed role credentials.
```bash
./pike inspect -d terraform/aws
The following are over-permissive:
s3:*
s3-object-lambda:*
*
account:GetAccountInformation
aws-portal:*Billing
aws-portal:*PaymentMethods
aws-portal:*Usage
billing:GetBillingData
billing:GetBillingDetails
billing:GetBillingNotifications
billing:GetBillingPreferences
```
`inspect` uses the ambient AWS session (whatever `aws sts get-caller-identity` would resolve to — env vars, `AWS_PROFILE`, instance role, etc.), so it does not need a dedicated profile. The identity does need read access to IAM so it can enumerate the attached policies:
```hcl
statement {
effect = "Allow"
actions = [
"iam:ListUserPolicies",
"iam:ListAttachedUserPolicies",
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:ListGroupPolicies",
"iam:ListAttachedGroupPolicies",
"iam:GetPolicy",
"iam:GetPolicyVersion",
"iam:GetUserPolicy",
"iam:GetRolePolicy",
"iam:GetGroupPolicy",
"iam:ListGroupsForUser",
]
resources = ["*"]
}
```
## Extending
Determine and create IAM mapping files ("./src/mapping") by
working out the permissions required for your resource.
For example, *aws_security_group.json*:
```json
[
{
"apply": [
"ec2:CreateSecurityGroup",
"ec2:DescribeSecurityGroups",
"ec2:DescribeAccountAttributes",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteSecurityGroup",
"ec2:RevokeSecurityGroupEgress"
],
"attributes": {
"ingress": [
"ec2:AuthorizeSecurityGroupIngress",
"ec2:AuthorizeSecurityGroupEgress"
],
"tags": [
"ec2:CreateTags",
"ec2:DeleteTags"
]
},
"destroy": [
"ec2:DeleteSecurityGroup"
],
"modify": [],
"plan": []
}
]
```
### How
Datasources are the easiest to start with. There's a script (resource.ps1 - requires pwsh: **brew install --cask powershell**)
that creates a blank mapping file and .tf resource file, but you've seen the example JSON file - make one without any entries.
You also need to create a minimal resource/datasource that you are trying to figure out the permissions for, and place
it in the correct directory (e.g., ../terraform/aws). There's a script for making a profile in the role directory.
You can then run OpenTofu/Terraform using the empty role against the resource/datasource with no permissions.
The debug output from the run will help you figure out the permissions you need to add to your basic role.
You then update your "basic" role.
Issues?
The providers, don't always tell you what you need to add,
you will need to check the IAM docs and the online IAM policymakers.
Not all resources are as easy as others, anything that make/scripts CF internally.
Some roles require *Passrole* and *CreateLinkedRole* but won't say so. Trail and error
#### What about "attributes"?
Some cloud providers require extra permissions depending on the attributes you add; this is how this is handled.
Build out your .tf resources to cover all reasonable scenarios.
#### Eventual consistency
Some cloud providers follow this model which means your test IAM role will take time after you change it to be
changed, how long? This seems to vary on time of day and the resource. Whilst other providers like
Azure just take a long time for the TF to change.
### Add Import mapping file
Update **files.go** with:
```txt
//go:embed aws_security_group.json
var securityGroup []byte
```
### Add to provider Scan
Once you have added the JSON import, as above, you then need to update the lookup table,
so we can read it and get the permissions:
```txt
func GetAWSResourcePermissions(result template) []interface{} {
TFLookup := map[string]interface{}{
"aws_s3_bucket": awsS3Bucket,
"aws_s3_bucket_acl": awsS3BucketACL,
+ "aws_security_group": awsSecurityGroup,
```
Also add an example .tf file into the folder **terraform/<cloud>/backups**. This helps test that all your
new code is picked up by pike.
## Related Tools
<https://github.com/iann0036/iamlive>
## Star History
[](https://star-history.com/#jameswoolfenden/pike&Date)