@aaa-sentinel/iac-cost 0.1.1 → 0.3.0

package/README.md

@@ -1,7 +1,19 @@
 # @aaa-sentinel/iac-cost
 
 Comments the **monthly cost delta of a Terraform plan** on the pull request that introduces it,
-so the price of a change is visible while it is still cheap to change.
+so the price of a change is visible while it is still cheap to change — and checks the same plan
+against the **security rules of the AAA Sentinel posture scan**, so an SSH port open to the
+internet is caught in review instead of after the deploy. With `iac-cost fix`, the findings of
+your last scan on resources this Terraform manages come back to you as **pull requests**, not as
+console changes (see [Fixes as pull requests](#fixes-as-pull-requests)).
+
+> **New in 0.3.0:** the `fix` subcommand. Nothing changes for the existing command: same output,
+> same exit codes.
+
+> **Changed in 0.2.0:** stdout now carries a `### 🔒 Security` section after the cost estimate
+> (or alone, under the same comment marker, when there is no cost estimate), so a plan with no
+> billable change can still produce a comment. Pass `--no-security` to get exactly the 0.1 output.
+> The exit code stays 0 unless you add `--fail-on`.
 
 > ### 💲 Infrastructure cost estimate
 >
@@ -18,12 +30,17 @@ so the price of a change is visible while it is still cheap to change.
 
 ## Requirements
 
-- Node.js 20 or newer.
-- An OAuth2 application with the `iac:estimate` scope, created in the
+- Node.js 20 or newer. That is all the **security check** needs: it runs offline.
+- For the **cost estimate**, an OAuth2 application with the `iac:estimate` scope, created in the
   [developer portal](https://app.aaa-sentinel.com/developer/apps).
   That scope grants **nothing else** — it cannot read your accounts, findings or reports —
-  which is what makes it safe to paste into a CI that third parties can trigger.
-- A **Pro** or **Business** plan.
+  which is what makes it safe to paste into a CI that third parties can trigger. The cost
+  estimate needs a **Pro** or **Business** plan.
+- For the optional **drift check**, a second application with `security:read` and the security
+  add-on on the account (see [Drift](#drift-plan-vs-cloud)).
+- For **`iac-cost fix`**, an application with the `security:fix` scope, the security add-on on the
+  account, and a CI token that can push a branch and open a pull request (see
+  [Fixes as pull requests](#fixes-as-pull-requests)).
 
 ## Usage
 
@@ -39,15 +56,41 @@ npx @aaa-sentinel/iac-cost plan.json          # or: … | npx @aaa-sentinel/iac-
 | `IAC_COST_CLIENT_ID` | yes | Client ID of the OAuth2 application |
 | `IAC_COST_CLIENT_SECRET` | yes | Client secret. Store it as an encrypted CI secret |
 | `IAC_COST_BASE_URL` | no | Defaults to `https://api.aaa-sentinel.com`. Must be `https` — the secret is never sent over plain HTTP |
+| `IAC_SECURITY_FAIL_ON` | no | Same as `--fail-on` |
+| `IAC_SECURITY_ACCOUNT_ID` | no | Same as `--drift-account` |
+| `IAC_SECURITY_CLIENT_ID` / `IAC_SECURITY_CLIENT_SECRET` | for drift | An OAuth2 application with the `security:read` scope |
 
 The Markdown comment goes to **stdout**; warnings go to **stderr**. If there is nothing to
 say, stdout is empty.
 
-### It never fails your build
+| Option | Meaning |
+| --- | --- |
+| `--format markdown` | The pull request comment (default) |
+| `--format text` | Plain lines for a terminal or a CI log |
+| `--format json` | `{ formatVersion, cost, security, warnings }`, with the full evidence of each finding. It is evidence for you, not for a pull request: it keeps the Terraform addresses as written (for_each keys included) and the evidence as the rules see it — ARNs, subscription ids, emails or internal CIDRs of resources that already exist. Do not post it as a comment |
+| `--fail-on <critical\|high\|medium\|low>` | Exit 1 when a security finding or toxic combination is at that severity or worse. Also `IAC_SECURITY_FAIL_ON` |
+| `--no-security` | Cost only, exactly as in 0.1 |
+| `--no-cost` | Security only and no credentials needed. Nothing leaves your machine unless you also pass `--drift-account` explicitly: with `--no-cost`, `IAC_SECURITY_ACCOUNT_ID` in the environment is ignored |
+| `--drift-account <accountId>` | Compare with the last scan of that account (see [Drift](#drift-plan-vs-cloud)). Also `IAC_SECURITY_ACCOUNT_ID`, except with `--no-cost`. It puts what the scan found in your cloud into the PR comment: **never on a public repository** |
+
+### It never fails your build — unless you ask for a gate
+
+Without `--fail-on` the exit code is **always 0**. A missing credential, a network error, an
+unreadable plan or an outage on our side prints a one-line warning and stops. A cost comment is
+not a quality gate, and our availability must not become a dependency of your deployments.
 
-The exit code is **always 0**. A missing credential, a network error, an unreadable plan or an
-outage on our side prints a one-line warning and stops. A cost comment is not a quality gate, and
-our availability must not become a dependency of your deployments.
+With `--fail-on high` you are asking for a gate, and the exit code becomes:
+
+| Code | When |
+| --- | --- |
+| `0` | No finding or combination at `high` or worse |
+| `1` | At least one — block the merge |
+| `2` | The input is not a readable plan (unreadable JSON, the state instead of a plan, `errored: true`) or `--fail-on` has a value that is not a severity. A gate that cannot read its input does not open by itself |
+
+Any other unknown or malformed argument only prints a warning, with or without a gate.
+
+Only the plan decides the code. The cost estimate and the drift check go over the network, and
+neither can change it. A check that **could not be decided** (see below) never blocks.
 
 ## What actually leaves your machine
 
@@ -57,6 +100,19 @@ whitelist: resource type, action (`create`/`update`/`delete`/`replace`), how man
 block produces, and the handful of attributes that move the price (instance size, region, OS).
 Everything else is dropped before serialising, and the projection is never written to the CI log.
 
+The security check sends nothing: it runs entirely on your machine. The drift check sends only
+the account id you give it, and receives the findings of your last scan. With `--no-cost`, the
+only way to make a network call is to pass `--drift-account` on the command line.
+
+`iac-cost fix` reads the open findings of the account (rule, cloud id, region) and sends back, per
+finding it matched: the Terraform address, the `.tf` path relative to the repository, the attribute,
+the repository name and the pull request link and number. Never the plan, the code or your git
+token: the branch, the commit and the pull request are created by your CI against your git host.
+
+The PR comment and the text output name each resource by its Terraform address, with the key of a
+`for_each` replaced by a short hash (`aws_s3_bucket.b[#3fa2c19d]`), because keys are often emails
+or account ids. The JSON output does not: it is the complete evidence (see `--format json`).
+
 ## Reading the number
 
 - **List price.** Neither AWS, Azure nor Google returns what *you* pay. Enterprise agreements
@@ -79,6 +135,144 @@ Everything else is dropped before serialising, and the projection is never writt
 Currently priced: **AWS** (EC2 on demand) and **Azure** (virtual machines). Anything else is
 reported as not priced, never as free.
 
+## Security before deploy
+
+The plan is checked **on your machine** with the rules of the AAA Sentinel posture scan — the
+same code, bundled into this package, not a copy. A rule that flags an open security group in
+your cloud flags it in the plan that would create it, with the same severity. The security part
+sends nothing anywhere and needs no credentials.
+
+> ### 🔒 Security
+>
+> **Findings: 2 critical, 1 high, 0 medium, 0 low** on 6 resources checked.
+>
+> | Severity | Rule | Resource | Change | Detail |
+> |---|---|---|---|---|
+> | 🔴 critical | Admin ports open to the internet | `aws_security_group.bastion` | new | ports 22 |
+> | 🔴 critical | Lambda invocable from the internet | `aws_lambda_function.api` | new | function URL without auth |
+> | 🟠 high | Secret in a Lambda environment variable | `aws_lambda_function.api` | new | variables DB_PASSWORD |
+>
+> **Toxic combinations** — findings that are worse together, fix these first:
+>
+> | Severity | Combination | Resource |
+> |---|---|---|
+> | 🔴 critical | Public function with secrets in its configuration | `aws_lambda_function.api` |
+>
+> <details><summary>Not evaluable before apply (1)</summary> … </details>
+
+The comment names the **Terraform address** of each resource, which is already in your
+repository (with `for_each` keys hashed), and never a cloud identifier, an account number or a
+value from the plan: a variable is named (`DB_PASSWORD`), its value is not read.
+
+### What is checked
+
+| Cloud | Terraform resources | Rules |
+| --- | --- | --- |
+| AWS | `aws_security_group`, `aws_default_security_group`, `aws_security_group_rule`, `aws_vpc_security_group_ingress_rule` (+ `aws_ec2_managed_prefix_list`) | Admin ports (22/3389) open to the internet, directly or through a prefix list |
+| AWS | `aws_s3_bucket` + `aws_s3_bucket_public_access_block`, `aws_s3_account_public_access_block`, `aws_s3_bucket_acl`, `aws_s3_bucket_policy` | Public bucket |
+| AWS | `aws_db_instance`, `aws_rds_cluster_instance` (+ `aws_rds_cluster`) | Unencrypted storage |
+| AWS | `aws_lambda_function` + `aws_lambda_function_url`, `aws_lambda_permission` | Invocable from the internet; secret-looking environment variable names |
+| AWS | `aws_cloudtrail` | Trail stopped; management events excluded |
+| AWS | `aws_kms_key` | Key rotation off |
+| AWS | `aws_vpc`, `aws_default_vpc` + `aws_flow_log` (+ `aws_subnet`) | VPC without flow logs; flow logs that miss part of the traffic |
+| Azure | `azurerm_network_security_group`, `azurerm_network_security_rule` | Admin ports open to the internet |
+| Azure | `azurerm_storage_account` | Public blobs allowed; weak TLS or HTTP |
+| Azure | `azurerm_mssql_server` + `azurerm_mssql_firewall_rule` | Public network access open to 0.0.0.0–255.255.255.255; weak TLS |
+| Azure | `azurerm_role_assignment` | Owner or User Access Administrator at any scope; Contributor at subscription scope (a Contributor at a management group or at `/` is not flagged, neither here nor in the live scan) |
+| Google Cloud | `google_compute_firewall` | Admin ports open to the internet |
+| Google Cloud | `google_sql_database_instance` | Authorized from 0.0.0.0/0; no CMEK |
+| Google Cloud | `google_cloudfunctions_function`, `google_cloudfunctions2_function` | Secret-looking environment variable names |
+| Google Cloud | `google_project_iam_member`, `_binding`, `_policy`; `google_service_account_key` | Primitive Owner/Editor role; user-managed key |
+
+**Toxic combinations** are reported when the plan holds every part: an unencrypted database with
+a public endpoint, a public function with secrets in its configuration, public SQL or storage with
+weak TLS, an Owner/Editor service account with a downloadable key.
+
+### What a plan cannot tell — "not evaluable"
+
+A plan is not the cloud. When a rule needs something the plan does not have, the resource is
+listed as **not evaluable, with the reason**, and is never counted as passing:
+
+| Reason | Example |
+| --- | --- |
+| `value only known after apply` | A CIDR taken from another resource, an encryption flag set from a variable, Lambda environment variables when any value comes from another resource (Terraform then hides the whole map, names included) |
+| `depends on configuration outside this plan` | An S3 bucket when the account-level public access block is not in the plan; an existing Lambda function whose URL or resource policy are not managed here |
+| `needs the cloud to evaluate it` | A bucket policy open to `*` under a condition; CloudTrail advanced event selectors |
+| `the plan does not carry this setting` | An attribute the adapter does not translate |
+
+Defaults are applied only to what the plan **creates**: a new S3 bucket is created with every
+public access block on, a new bucket has no policy unless the plan adds one. An existing resource
+may carry configuration made outside Terraform, so the same absence proves nothing about it — and
+`aws_default_security_group` / `aws_default_vpc` adopt something that already exists, so they are
+never treated as new.
+
+**S3 buckets are often "not evaluable".** The account-level public access block decides as much
+as the bucket's own, and it is only read from the plan when `aws_s3_account_public_access_block`
+is in it **and** belongs to the same account: a single `aws` provider configuration, or the same
+provider alias as the bucket. Without it the bucket is not evaluable: the account block could be
+the one that closes it. With it, a bucket is reported as public as soon as one path is proven open
+(a public ACL or a public policy, with both blocks off for that path), even if the other path
+cannot be read. Likewise, a Lambda function is reported as public as soon as one path is proven
+open (a URL without auth, or `*` in its resource policy).
+
+Also not checked before deploy, and said so in the comment:
+
+- **Account-wide rules** (is there a multi-region trail at all? an Activity Log export? the CIS
+  alarm set?) need the whole account and are only checked by the live scan.
+- Resource types with a live rule that the plan check does not translate yet (IAM users and
+  access keys, load balancers, Lightsail, snapshots, the legacy `azurerm_sql_server` and its
+  firewall rules, GCP disks and firewall policies, log sinks and diagnostic settings) are named
+  when they appear in the plan.
+- Something declared on a Lambda alias or version (`qualifier`) is not what the live rule reads,
+  and is not counted.
+- A child written as `bucket = each.value.id` is joined to the parent through its `for_each`
+  (`for_each = aws_s3_bucket.b`), by instance key. Terraform does not expose the expression, only
+  what it references, so a `for_each` that renames the keys so that they still collide with the
+  parent's (`{ for k, v in aws_s3_bucket.b : f(k) => v }`) can join the wrong instance.
+- A `dynamic` block (`dynamic "restore_to_point_in_time"`) is not visible in the plan's
+  configuration: a restore declared that way is read as absent, which can only add a finding.
+- Public Google Cloud Storage buckets (`google_storage_bucket_iam_*`) have no rule yet, neither
+  before nor after deploy.
+- Delivery health (a flow log or a trail that stops writing) only exists in the cloud.
+
+### Drift: plan vs. cloud
+
+With `--drift-account <accountId>` (the AAA Sentinel account id, `acc_…`) the CLI reads the
+findings of your last scan through the public API (`GET /v1/security/findings`) and lists the
+resources of the plan where the scan has a finding that the plan, for the same rule, does not.
+
+What that means depends on what the plan does with the resource. `terraform plan` refreshes
+existing resources first, so drift in what Terraform manages — a port opened by hand on a security
+group whose inline rules live in the code — shows up as an **update** that reverts it:
+
+| Shown as | When | Read it as |
+| --- | --- | --- |
+| re-check after apply | The plan changes the resource | The scan saw the problem and the plan changes the resource: the next scan will tell whether it is gone |
+| the scan differs | The plan leaves the resource unchanged | The scan may predate a fix, or the cause is something Terraform does not manage on that resource |
+
+Rules whose cause only exists in the cloud (flow log delivery) are left out, and a Lambda function
+or an RDS instance is only matched when the region of the plan resource is known (from its ARN):
+their names are unique only within a region.
+
+It needs a **separate** OAuth2 application with the `security:read` scope, in
+`IAC_SECURITY_CLIENT_ID` / `IAC_SECURITY_CLIENT_SECRET`, and the security add-on on that account.
+Keep `iac:estimate` and `security:read` in two applications: the first one is safe in a CI that
+third parties can trigger, the second one reads your findings.
+
+Limits, all from what the API exposes:
+
+- only findings are published, not resources that pass, so only one direction is reported
+  (flagged by the scan, passing in the plan);
+- the API returns the 500 most severe findings of the **last scan**; the comment says when the
+  list was truncated;
+- resources are matched by their cloud identifier, which a plan only knows for resources that
+  already exist;
+- reading the account directly with your own cloud credentials is not supported: it would bring a
+  cloud SDK into this package.
+
+> The drift section tells readers of the pull request what your last scan found **in your
+> cloud**. Do not enable it on a public repository.
+
 ## GitHub Actions
 
 Posts one comment per pull request and **updates it in place** on later pushes instead of
@@ -86,7 +280,7 @@ stacking a new one each time. The token is the one the run already injects — n
 token, no app installation.
 
 ```yaml
-name: Infrastructure cost
+name: Infrastructure cost and security
 on: pull_request
 
 permissions:
@@ -107,7 +301,7 @@ jobs:
       - run: terraform plan -out=plan.tfplan
       - run: terraform show -json plan.tfplan > plan.json
 
-      - name: Estimate cost
+      - name: Estimate cost and check security
         env:
           IAC_COST_CLIENT_ID: ${{ secrets.IAC_COST_CLIENT_ID }}
           IAC_COST_CLIENT_SECRET: ${{ secrets.IAC_COST_CLIENT_SECRET }}
@@ -128,8 +322,16 @@ jobs:
           else
             gh api -X POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@comment.md
           fi
+
+      # Optional: block the merge on critical or high findings. Runs after the comment, so the
+      # review shows why it failed. Local only: no credentials, nothing sent.
+      - name: Security gate
+        run: npx --yes @aaa-sentinel/iac-cost plan.json --no-cost --format text --fail-on high
 ```
 
+Make the `Security gate` job a **required status check** in the branch protection rules to
+actually block the merge.
+
 > `continue-on-error` is not decoration: without it, a GitHub API hiccup while posting the comment
 > would fail the job, and a cost comment must never be able to do that.
 
@@ -148,7 +350,7 @@ pipelines:
   pull-requests:
     '**':
       - step:
-          name: Infrastructure cost
+          name: Infrastructure cost and security
           image: hashicorp/terraform:latest
           script:
             - apk add --no-cache nodejs npm curl jq
@@ -157,32 +359,191 @@ pipelines:
             - terraform show -json plan.tfplan > plan.json
             - npx --yes @aaa-sentinel/iac-cost plan.json > comment.md
             - |
-              set +e
-              [ -s comment.md ] || exit 0
-              API="https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pullrequests/$BITBUCKET_PR_ID/comments"
-              BODY=$(jq -Rs . < comment.md)
-              ID=$(curl -sf -H "Authorization: Bearer $BB_TOKEN" "$API?pagelen=100" \
-                    | jq -r '[.values[] | select((.content.raw // "") | contains("<!-- aaa-sentinel:iac-cost -->"))][0].id // empty')
-              if [ -n "$ID" ]; then
-                curl -sf -X PUT -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
-                  -d "{\"content\":{\"raw\":$BODY}}" "$API/$ID"
-              else
-                curl -sf -X POST -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
-                  -d "{\"content\":{\"raw\":$BODY}}" "$API"
-              fi
-              exit 0
+              (
+                set +e
+                [ -s comment.md ] || exit 0
+                API="https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pullrequests/$BITBUCKET_PR_ID/comments"
+                BODY=$(jq -Rs . < comment.md)
+                ID=$(curl -sf -H "Authorization: Bearer $BB_TOKEN" "$API?pagelen=100" \
+                      | jq -r '[.values[] | select((.content.raw // "") | contains("<!-- aaa-sentinel:iac-cost -->"))][0].id // empty')
+                if [ -n "$ID" ]; then
+                  curl -sf -X PUT -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
+                    -d "{\"content\":{\"raw\":$BODY}}" "$API/$ID"
+                else
+                  curl -sf -X POST -H "Authorization: Bearer $BB_TOKEN" -H 'Content-Type: application/json' \
+                    -d "{\"content\":{\"raw\":$BODY}}" "$API"
+                fi
+                exit 0
+              ) || true
+            # Optional gate, after the comment so the review shows why: fails on critical or high findings.
+            - npx --yes @aaa-sentinel/iac-cost plan.json --no-cost --format text --fail-on high
 ```
 
-> The `set +e` and the final `exit 0` are there for the same reason as `continue-on-error` on
-> GitHub: a failure while commenting must not fail the pipeline. A deleted comment has a null
+> The `set +e`, the subshell and the final `exit 0` are there for the same reason as
+> `continue-on-error` on GitHub: a failure while commenting must not fail the pipeline, and the
+> `exit` must not end the script before the optional gate. A deleted comment has a null
 > `content.raw`, hence the `// ""` — without it `jq` aborts and the comment is posted again
 > instead of updated.
 
+## Fixes as pull requests
+
+If a resource is managed by Terraform, fixing it in the console creates drift: the next
+`terraform apply` puts the problem back. `iac-cost fix` turns the open findings of your last scan
+into pull requests against the code that manages each resource, and tells AAA Sentinel, so the app
+shows the pull request and stops offering the console change for that finding while a pull request
+is open or merged, or about to be opened. A suggestion without pull request, a closed pull request or
+a public repository leave the console change available.
+
+```bash
+terraform plan -out=plan.tfplan
+terraform show -json plan.tfplan > plan.json
+npx @aaa-sentinel/iac-cost fix plan.json --account acc_…
+```
+
+Run it on the branch you deploy from (a push to `main`, a schedule), not on a pull request: the
+pull requests target that branch, and the plan has to describe what is deployed. For each open
+finding (the 500 most severe, accepted risks excluded) it:
+
+1. finds the resource of the finding in the plan by its cloud id, like the [drift check](#drift-plan-vs-cloud),
+   and checks that the plan puts it in the same AWS account, GCP project or Azure subscription as the
+   AAA Sentinel account. Findings on resources that are not in this plan are left alone: they belong
+   to other code;
+2. finds its `resource` block in the `.tf` files of its module directory (following local module
+   `source`s), and edits **only the attribute that causes the finding**, and only if its value is a
+   literal written in that block;
+3. commits the change to a new branch `aaa-sentinel/fix-<id>` and opens one pull request per
+   finding, at most `--max-prs` (default 5) per run;
+4. records the result in AAA Sentinel. On later runs it updates the state of its pull requests
+   (open, merged, closed) instead of opening new ones. A closed pull request is not reopened; a
+   merged one whose change is no longer in the code gets a new pull request on a new branch; a branch
+   of its own left without a pull request (the token could not open it yet) gets one.
+
+Before committing, it checks that each file in the CI checkout is the file at the deployed commit,
+ignoring only a byte order mark and line endings: if an earlier step changed it (generated files,
+substituted secrets), the fix stays pending with `working_copy_changed`. The commit keeps the BOM
+and line endings of the file at the deployed commit, not those of the runner's checkout. On a **public
+repository** it opens nothing unless you pass `--allow-public-repo`: the pull request would tell
+anyone where your live finding is.
+
+| Rule | Change in the code |
+| --- | --- |
+| `SEC_AWS_NETWORK_ADMIN_ABIERTO` | Removes `0.0.0.0/0` / `::/0` from the rule that opens **only** port 22 or 3389 (inline `ingress`, `aws_security_group_rule`, `aws_vpc_security_group_ingress_rule`); removes the rule if it has no other source, and writes `ingress = []` when the last inline rule goes, so Terraform deletes it instead of leaving it unmanaged |
+| `SEC_AWS_EXPOSURE_S3_PUBLICO` | Sets the four flags of the bucket's `aws_s3_bucket_public_access_block` to `true` |
+| `SEC_AWS_ENCRYPTION_KMS_SIN_ROTACION` | `enable_key_rotation = true` |
+| `SEC_AWS_EXPOSURE_LAMBDA_PUBLICA` | `authorization_type = "AWS_IAM"` on the function URL (callers then have to sign requests) |
+| `SEC_AZURE_EXPOSURE_BLOB_PUBLICO` | `allow_nested_items_to_be_public = false` (`allow_blob_public_access` on azurerm 2.x) |
+| `SEC_AZURE_ENCRYPTION_STORAGE_TLS` | `min_tls_version = "TLS1_2"` and HTTPS only, where the code sets them weaker |
+| `SEC_AZURE_ENCRYPTION_SQL_TLS` | `minimum_tls_version = "1.2"` (also when the code says `"Disabled"`, which azurerm 3.x accepts and means no minimum) |
+| `SEC_GCP_NETWORK_ADMIN_ABIERTO` | Removes `0.0.0.0/0` from `source_ranges` of a firewall that allows only 22/3389, when another range, tag or service account remains |
+
+Everything else is recorded as a **suggested change in the code, without a pull request**, with
+the reason, and the app shows it that way:
+
+| Reason | Why it is not edited |
+| --- | --- |
+| `value_from_expression` | The value comes from a variable, a local, a function or a reference: the same code may serve another environment with another value |
+| `module_not_local` | The resource is in a module from the registry or git, not in this repository |
+| `multiple_instances` | `count` / `for_each` on the resource or its module, or a local module called more than once: the block is shared by several instances |
+| `dynamic_block` | The rules come from a `dynamic` block |
+| `other_ports` | The open rule also opens other ports (or all of them): closing it would cut that traffic too |
+| `only_source` | The internet range is the only source; on GCP, a firewall without sources applies to `0.0.0.0/0` |
+| `no_public_access_block` | The bucket has no `aws_s3_bucket_public_access_block` to edit |
+| `replacement_required` | The fix forces a new resource (RDS encryption, Cloud SQL CMEK) |
+| `ignore_changes` | `lifecycle { ignore_changes }` covers the attribute (or has a comment inside the list): Terraform would not apply the change |
+| `unsupported_host` | GitHub Enterprise Server (`GITHUB_API_URL` is not `https://api.github.com`): not supported yet, the app only links pull requests on github.com and bitbucket.org |
+| `cause_not_in_code` | The open value is not in the code (added by hand, or a provider default) |
+| `block_not_found` | The `resource` block could not be read (`.tf.json`, or a layout the editor does not handle) |
+| `rule_not_automated` | No deterministic code fix for that rule |
+
+The rest of the file is kept byte for byte, comments and line endings included (a removed block takes
+the comment lines right above it, up to the first blank line); run `terraform fmt`
+in review if the alignment of `=` matters to you. The pull request says what changed and why;
+review its `terraform plan` before merging. The finding closes after `terraform apply` and the next scan.
+
+| Option | Meaning |
+| --- | --- |
+| `--account <accountId>` | AAA Sentinel account id. Also `IAC_FIX_ACCOUNT_ID` |
+| `--dir <path>` | Directory where `terraform plan` ran (default: current). The repository root is the nearest `.git` above it |
+| `--max-prs <n>` | Pull requests opened per run (default 5, `0` records without opening) |
+| `--host <github\|bitbucket>` | Git host. Detected from the CI by default |
+| `--dry-run` | Prints the changes; opens nothing and records nothing. Works without a git host |
+| `--allow-public-repo` | Opens pull requests on a public repository too |
+| `--format <text\|json>` | Output format |
+
+Exit code: `2` for a usage error (no account, no git host, the run is a pull request build, the input
+is not a plan); otherwise `0`, also when the API or the git host fails — the step prints a warning
+and the findings stay `pending`.
+
+### GitHub Actions
+
+The workflow token can open the pull request with `contents: write` and `pull-requests: write`. In
+the repository (or organization) settings, **Actions → General → Workflow permissions** must allow
+*GitHub Actions to create and approve pull requests*. Pull requests opened with that token do not
+trigger other workflows (a GitHub rule), so the cost and security comment will not run on them
+until someone pushes to the branch.
+
+```yaml
+name: Security fixes
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '0 7 * * 1-5'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  fix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hashicorp/setup-terraform@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: terraform init
+      - run: terraform plan -out=plan.tfplan
+      - run: terraform show -json plan.tfplan > plan.json
+      - name: Open security fixes as pull requests
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          IAC_FIX_CLIENT_ID: ${{ secrets.IAC_FIX_CLIENT_ID }}
+          IAC_FIX_CLIENT_SECRET: ${{ secrets.IAC_FIX_CLIENT_SECRET }}
+        run: npx --yes @aaa-sentinel/iac-cost fix plan.json --account ${{ vars.AAA_SENTINEL_ACCOUNT_ID }}
+```
+
+### Bitbucket Pipelines
+
+Bitbucket Pipelines does not inject a token that can open pull requests. Create a **Repository
+Access Token** with `repository:write` and `pullrequest:write` (the comment step's `BB_TOKEN` works
+if it has both) and store it as a secured variable `BB_TOKEN`.
+
+```yaml
+pipelines:
+  branches:
+    main:
+      - step:
+          name: Security fixes
+          image: hashicorp/terraform:latest
+          script:
+            - apk add --no-cache nodejs npm
+            - terraform init
+            - terraform plan -out=plan.tfplan
+            - terraform show -json plan.tfplan > plan.json
+            - npx --yes @aaa-sentinel/iac-cost fix plan.json --account "$AAA_SENTINEL_ACCOUNT_ID" || true
+```
+
+The commit is created through the Bitbucket API (`POST /src`), so the clone needs no push access.
+
 ## Why there is no comment
 
 | What you see | Why |
 | --- | --- |
-| No comment at all | The plan changes no billable resource, or the credentials are missing — check the step log, the reason is always printed |
+| No comment at all | The plan changes no billable resource and has no resource the security rules cover, or the credentials are missing — check the step log, the reason is always printed |
+| A security section but no cost estimate | `IAC_COST_CLIENT_ID`/`IAC_COST_CLIENT_SECRET` are not set: the security check needs no credentials and still runs |
 | A breakdown with no total | Fewer than half of the billable resources could be priced |
 | `region could not be resolved from the plan` | The region comes from a variable or an aliased provider, so the plan does not say which one applies |
 | `provider recognized, pricing not connected yet` | A cloud we support but whose catalogue is not connected yet (Google) |