Archived

This repository has been archived on 2026-08-04. You can view files and clone it, but cannot push or open issues or pull requests.

Adam Moussa 94ed6ea224

feat(secrev): Plane-1 Phase 3 — doc-drift + IAM artifacts (aws-posture gated) (#19 )

* feat(secrev): doc-drift Plane-1 Tier-1 checker (UNGATED)

Third Plane-1 checker on the Phase-0 shared substrate, mirroring
compliance-drift.sh / dependency-cve.sh conventions verbatim (set -euo pipefail,
sourced substrate, --canary/--dry-run/--no-api/--refresh/--targets, mode-600
reports under $REPORT_ROOT/doc-drift/<UTC-date>/, ALARM-only, finding.schema
spirit JSON, exit 0/2/3, dotgit->.git fixture trick).

Detects documentation drift deterministically (design §4 doc-drift row):
  - readme-omits-component: README omits an existing major component in the tree
    (top-level service dir, SAM/CDK stack, Lambda handler dir, openapi/docs spec)
  - readme-stale-vs-code: README last-touch far older than newest code commit
    (two-factor: >=DOC_DRIFT_STALE_DAYS AND >=DOC_DRIFT_STALE_COMMITS)
A repo with NO README is SKIPPED (compliance-drift owns readme-present; no
double-flag). Future Gemini large-context judge (§4) is an inert stub (maybe_judge),
off in canary/dry-run/offline.

Planted-drift fixture corpus + EXPECTED_DRIFT_COUNT=4, canary-asserted (exit 3 on
miss). shellcheck -x clean (only accepted SC1091 source-line info).

Does NOT touch checker_coordinator.sh, requirements.txt, or aws-posture.
Wiring/systemd is gated (PROVISIONING footer). Design refs §4, §7 Phase 3.

* feat(secrev): Phase-3 IAM artifacts for cross-review (aws-posture gated)

Authored FILES (not applied to AWS — provisioning gated behind the mandatory
GPT-4.1 IAM cross-review + Adam, design §7 B3) for the aws-posture checker's
read-only AWS identity. Decision D5: box stays read-only, auths via IAM Roles
Anywhere short-lived leaf certs from a new internal step-ca; NO long-lived AWS key.

  - aws-posture-readonly-policy.json  least-privilege read-only (ce:Get*,
      cloudwatch:GetMetric*/DescribeAlarms, ec2/elb/rds:Describe*, lambda list +
      GetFunctionConfiguration, s3:ListAllMyBuckets/GetBucketLocation). No write,
      no iam:* mutation, no s3:GetObject/secrets/kms/logs data reads, no wildcard
      actions. Resource:* only where AWS has no resource-level support.
  - aws-posture-readonly-policy.rationale.md  per-statement least-privilege rationale.
  - aws-posture-trust-policy.json  pins Roles Anywhere principal + leaf subject CN +
      issuer CN + trust-anchor SourceArn (three conditions, all required).
  - roles-anywhere-config.json  trust anchor (pins step-ca root) + profile (1h session).
  - step-ca-config-sketch.md  internal CA config + systemd-timer leaf auto-renewal.
  - CROSS-REVIEW-PACKET.md  end-to-end trust model, blast radius, EXERCISED rollback,
      reviewer scrutiny list.

Does NOT build aws-posture.sh, touch checker_coordinator.sh, or requirements.txt.

* fix(secrev): apply IAM cross-review FIXes

GPT-4.1 IAM cross-review 2026-06-18: APPROVE, no BLOCKs. Applied FIXes:
- trust policy: add aws:SourceAccount=328440206208 (confused-deputy guard)
  alongside the existing aws:SourceArn trust-anchor pin
- readonly policy: remove ec2:DescribeImages (data minimization — AMIs are
  not an idle-spend signal)
- aws:RequestedRegion NIT: deliberately SKIPPED — ce:* and s3:ListAllMyBuckets
  are global-endpoint services a blanket region condition could DENY; rationale
  recorded in aws-posture-readonly-policy.rationale.md
- rationale.md + CROSS-REVIEW-PACKET.md: record APPROVE + FIXes + NIT answers
  (snapshots=account-owned idle signal; s3 list=names-only; no logs:* needed)

* feat(secrev): aws-posture checker (Tier-2, provisioning-gated)

Read-only Tier-2 idle/anomalous-spend + idle-resource posture checker for the
R720 agent-team (design D5 / §4 / §6.3 / §7 Phase 3). Mirrors the Tier-1 checker
conventions verbatim (flags --canary/--dry-run/--no-api/--targets, mode-600
report under $REPORT_ROOT/aws-posture/<date>/, ALARM-only, finding.schema.json
spirit, exit 0/2/3, shared substrate redact/post_slack_alarm).

Detectors (complement GuardDuty/SecurityHub/Config, do not replace):
- anomalous Cost Explorer deltas (ce get-anomalies, $-impact threshold)
- stopped EC2 still paying for attached EBS
- unattached EBS volumes
- unassociated Elastic IPs
- idle NAT gateways (≈0 bytes out)
- idle load balancers (0 healthy targets)
- idle RDS (0 connections over window)

Live AWS calls are PROVISIONING-GATED: they run ONLY when Roles Anywhere creds
are available (STS identity probe) AND not --no-api/--canary. With no creds or
--no-api/--canary the checker SKIPS live calls and notes them — NEVER alarms on
missing data (memory feedback_cloudwatch_alarms). Roles Anywhere/step-ca are not
stood up (IAM cross-review PASSED 2026-06-18; see security-review/iam/).

Offline canary: fixtures of mocked AWS responses (cost/describe-* JSON) under
fixtures/aws-posture/ + EXPECTED_FINDING_COUNT=7, asserted fully offline (no aws,
no network). Identical detector code runs online and offline. shellcheck-clean
(only accepted SC1091), chmod +x.

* fix(secrev): doc-drift fixture py ruff-clean (root CI runs check + format --check)

The repo-root CI lint runs both 'ruff check .' and 'ruff format --check .' over
all fixtures. Fixed E701 one-liners and ruff-formatted the sample-service .py
files (handlers/*, feature_*.py). Fixture content is irrelevant to doc-drift
(keys on file/dir presence + git staleness).

2026-06-18 16:25:40 -04:00

6.3 KiB

Raw Blame History

aws-posture-readonly-policy.json — least-privilege rationale

This is the annotated companion to aws-posture-readonly-policy.json. The policy JSON itself is kept strictly valid (no inline Comment keys — IAM rejects those), so all rationale lives here. This policy is the permission set for the aws-posture checker (design D5 / §4): idle / anomalous-spend watch on the Sea Haven AWS account (328440206208, us-east-1).

Cross-review status (2026-06-18): GPT-4.1 IAM cross-review returned APPROVE, no BLOCKs. FIXes applied to the policy as a result:

Removed ec2:DescribeImages (data minimization — AMIs are not part of the idle-spend signal; orphan EBS snapshots already cover the storage-waste case via ec2:DescribeSnapshots).
The trust policy (aws-posture-trust-policy.json) gained aws:SourceAccount = 328440206208 as an extra confused-deputy guard alongside the existing aws:SourceArn trust-anchor pin (see that file).

aws-posture itself is built in Phase-3 (this change set) but stays PROVISIONING-GATED — the checker never calls AWS until step-ca + Roles Anywhere (this packet) are stood up. This file + the policy are the IAM cross-review inputs (design §7, B3).

Design principle

The box stays read-only. There is no write action, no iam:* mutating action, no Resource wildcard where AWS supports resource-level scoping. Idle-spend posture is an account-wide, list-oriented read: most of the actions below are AWS APIs that do not support resource-level ARNs at all (Cost Explorer, the CloudWatch metric-data calls, and the EC2/ELB/ RDS Describe* list operations). For those, least-privilege is enforced by the action allow-list (only the specific read verbs), not by narrowing Resource.

Statement-by-statement

Sid	Why aws-posture needs it	Why read-only / why `Resource: "*"`
`CostAndUsageReadOnly`	The core idle/anomalous-spend signal (the design flags ≈$330/mo). `GetCostAndUsage`, forecasts, dimensions, and the native CE anomaly detectors.	Cost Explorer is an account-scoped service; its API has no resource-level ARNs, so `Resource:` is the only valid form. Only `Get` verbs — no `ce:Update/Create/Delete*`, no budget mutation.
`CloudWatchMetricsReadOnly`	Correlate spend with utilization (an instance billing but at ~0% CPU is idle). `GetMetricData`/`GetMetricStatistics`/`ListMetrics`; `DescribeAlarms*` to see whether an idle resource is already alarmed.	These metric-read APIs do not support resource-level permissions. No `PutMetricData`, no alarm create/modify/delete.
`Ec2DescribeReadOnly`	The classic idle-spend inventory: stopped instances still paying for EBS, unattached volumes, unassociated Elastic IPs, idle NAT gateways, orphan snapshots. (`ec2:DescribeImages` was removed in cross-review — AMIs are not an idle-spend signal aws-posture acts on.)	`Describe` is read-only; these list calls don't take resource ARNs. No `Run/Start/Stop/Terminate/Modify/Create/Delete`.**
`ElbAndRdsDescribeReadOnly`	Idle load balancers (no healthy targets) and idle/oversized RDS are frequent waste. `Describe*` only.	List APIs without resource-level ARNs. *No `rds:Modify/Delete/Reboot`, no ELB mutation.**
`LambdaAndStorageInventoryReadOnly`	Inventory functions + buckets to correlate against CloudWatch idle metrics.	Deliberately excludes `s3:GetObject` — the role never reads object data, only `ListAllMyBuckets` + `GetBucketLocation` (existence/region). No `lambda:InvokeFunction`, no Lambda mutation. This is the tightest the inventory can be while still seeing what exists.

What is deliberately NOT here (blast-radius containment)

No iam:*, sts:AssumeRole onward-chaining, organizations:*, or account:*.
No s3:GetObject / s3:GetObjectVersion (no data-plane read of any bucket).
No secretsmanager:GetSecretValue / ssm:GetParameter* (no secret read).
No kms:Decrypt, no logs:GetLogEvents (no log/data exfil path).
No write/modify/delete verb in any service.

A leaked session from this role can enumerate and price the account, and nothing more — it cannot read application data, secrets, or change a single resource.

Cross-review NIT answers (2026-06-18)

ec2:DescribeSnapshots kept (NIT: is it needed?) — yes. Orphan EBS snapshots are a common idle-spend line item (snapshots of long-deleted volumes keep billing); the checker lists them to flag that waste. It returns only account-owned metadata (we query with OwnerIds=["self"]), no snapshot data. ec2:DescribeImages (AMIs) was the over-grant and was removed.
s3:ListAllMyBuckets kept (NIT: data exposure?) — it returns only bucket names you own, no object data and no bucket contents; s3:GetBucketLocation returns only the region. Both are account-owned inventory queries needed to correlate idle buckets/regions against cost. No s3:GetObject anywhere, so there is no data-plane read path.
No logs:* (NIT: do we need CloudWatch Logs?) — no. aws-posture reasons over metrics (cloudwatch:GetMetric*) and the cost/inventory describe calls; it never needs log events. Omitting logs:GetLogEvents/logs:FilterLogEvents keeps the role off the log-exfil path.
aws:RequestedRegion condition (NIT: optional region pin) — SKIPPED, deliberately. The reviewer flagged this as optional. It is NOT applied because Cost Explorer (ce:*) and s3:ListAllMyBuckets are global-endpoint services that resolve to us-east-1 with request contexts where aws:RequestedRegion does not reliably equal us-east-1 — a blanket region condition risks DENYing the core cost signal. Scoping it to a separate statement covering only the regional Describe* calls (ec2/rds/elb/cloudwatch) would add a fourth+ statement for marginal benefit (the action allow-list already bounds blast radius, and the box only ever runs in us-east-1). Per the task's guidance, we prefer SKIP over a region pin that could break the global-service statements.

Comparison to the AWS-managed alternatives

ReadOnlyAccess / ViewOnlyAccess are far broader (they include s3:GetObject, dynamodb:GetItem, secretsmanager list, etc.). This custom policy is intentionally a small fraction of those — only the cost + idle-inventory surface the checker actually queries.

6.3 KiB Raw Blame History