@aaa-sentinel/iac-cost 0.3.1 → 0.4.1

package/README.md

@@ -7,6 +7,10 @@ internet is caught in review instead of after the deploy. With `iac-cost fix`, t
 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.4.0:** the `posture` subcommand prints how the security posture of an account changed
+> over 30, 90 or 365 days, with an optional gate on new findings (see
+> [Posture over time](#posture-over-time)). Nothing changes for `fix` or the existing command.
+
 > **Changed in 0.3.1:** the pull requests of `fix` pass `terraform fmt -check`: an added attribute is
 > aligned with its group (also around heredocs and after removing a block), as `terraform fmt` does.
 
@@ -171,19 +175,19 @@ value from the plan: a variable is named (`DB_PASSWORD`), its value is not read.
 
 | 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_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; database ports (SQL Server, Oracle, MySQL, PostgreSQL, Redis, Elasticsearch, MongoDB) open to the internet over TCP |
 | 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_db_instance`, `aws_rds_cluster_instance` (+ `aws_rds_cluster`) | Unencrypted storage; publicly accessible |
 | 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_network_security_group`, `azurerm_network_security_rule` | Admin ports open to the internet; database ports open to the internet over TCP |
 | 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_compute_firewall` | Admin ports open to the internet; database ports open to the internet over TCP |
+| Google Cloud | `google_sql_database_instance` | Authorized from 0.0.0.0/0; no CMEK; unencrypted connections accepted (`ssl_mode`; not judged while the provider still has to compute it) |
 | 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 |
 
@@ -543,6 +547,61 @@ pipelines:
 
 The commit is created through the Bitbucket API (`POST /src`), so the clone needs no push access.
 
+## Posture over time
+
+`iac-cost posture` reads `GET /v1/security/posture-history` and prints, for one account and a
+period of 30, 90 or 365 days:
+
+- the Security Score from the first to the last day with a scan (the last scan of each day), or
+  why it is **not comparable** (the rule catalog or what could be evaluated changed in between);
+- distinct findings **resolved** (gone in a scan that fully evaluated their rule) and **new**
+  (from rules that were already fully evaluated before);
+- findings that cannot be compared (their rule was not fully evaluated in the previous scan, or
+  they come from an external tool) and findings gone without confirmation;
+- the mean time to fix critical and high findings.
+
+```bash
+export IAC_SECURITY_CLIENT_ID=…       # OAuth2 app with the security:read scope
+export IAC_SECURITY_CLIENT_SECRET=…
+npx --yes @aaa-sentinel/iac-cost posture --account acc_01j… --days 90
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `--account <id>` | `IAC_SECURITY_ACCOUNT_ID` | AAA Sentinel account id |
+| `--days <30\|90\|365>` | `90` | Period |
+| `--format <markdown\|text\|json>` | `markdown` | `json` prints the API response as is |
+| `--fail-on-new <severity>` | — | Exit 1 when new findings at this severity or worse appeared in the period |
+
+Exit codes: `1` only when `--fail-on-new` trips; `2` for a usage error (an option without a value,
+a stray argument), missing credentials or, with the gate, a 4xx from the API (wrong scope or
+account); `0` otherwise, also when the API does not answer (a warning explains why). Findings that
+cannot be compared with the previous scan do not count for the gate.
+
+A weekly job that writes the summary to the run page:
+
+```yaml
+name: Security posture
+on:
+  schedule:
+    - cron: '0 7 * * 1'
+  workflow_dispatch:
+
+jobs:
+  posture:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Posture over the last 90 days
+        env:
+          IAC_SECURITY_CLIENT_ID: ${{ secrets.IAC_SECURITY_CLIENT_ID }}
+          IAC_SECURITY_CLIENT_SECRET: ${{ secrets.IAC_SECURITY_CLIENT_SECRET }}
+        run: |
+          npx --yes @aaa-sentinel/iac-cost posture --account ${{ vars.AAA_SENTINEL_ACCOUNT_ID }} --days 90 --fail-on-new critical >> "$GITHUB_STEP_SUMMARY"
+```
+
 ## Why there is no comment
 
 | What you see | Why |