ENTERPRISE-8875 assume role list

[gnyahay]

ENTERPRISE-8875

Summary

Adds an assume-role list so a single agent can inventory multiple AWS
account-regions, each via its own IAM role (optionally with an external ID) and
its own region. Zero entries preserves the previous behavior (inventory the
agent's own account using the top-level region). Includes a 50-entry limit and a
startup pre-flight that fails fast if any configured role cannot be assumed;
once the poll loop is running, per-cycle failures are logged and retried rather
than exiting.

Release notes

• --region / ANCHORE_ECS_INVENTORY_REGION is now ignored (with a warning)
  whenever assume-role entries are configured. Each entry supplies its own
  region; the top-level region applies only to the zero-entry (ambient) case.

Testing

make unit and make integration both pass. The integration suite runs against
a local moto server (STS + ECS) started by
test/integration/run.sh.

Coverage boundary: moto emulates STS and the ECS control plane but does
not populate a task's runtime Containers, so image extraction — the product's
actual output — is not exercised end to end over the wire. The integration tests
cover assume-role auth, multi-pass account/region isolation (each pass sees
only its own account's clusters), and report delivery to a stand-in Anchore API;
image-level extraction stays covered by the unit tests with a synthetic ECS API.

[gnyahay]

Please note that I have implemented an assumed role list limit of 50 and pre-flight checks that will fail startup if any configured roles cannot be assumed. If assumed roles stop working after the fact the agent continues to run.

[bradleyjones]

Posting a few findings from a review pass as inline comments (verified against a local build of this branch).

[bradleyjones]

Reviewed at 344c35d. Ran both suites locally: make unit passes (70.5%, above the gate) and make integration passes (moto starts, all 3 integration tests green). I also probed moto directly to work out what it can actually prove.

The feature code looks good — building the credentials cache once and reusing it, the asymmetric startup validation, and the exit-on-startup-failure / tolerate-runtime-failure split are all correct and unusually well documented. Most of what follows is about the tests.

Verdict on the integration tests

Keep the harness, rewrite the tests. The moto setup is sound and cheap, but the three tests as written barely exercise the feature. Two of them can't fail for the reason they claim, and the headline capability — multiple passes across multiple account-regions — is never tested.

The key thing I verified: moto enforces real account isolation for assumed sessions. Seeding a cluster with base credentials (account 123456789012) and then assuming arn:aws:iam::999999999999:role/other gives an empty ListClusters, while a same-account role sees all the seeded clusters. You can also seed into separate accounts through assumed roles:

A(111111111111/us-east-1): [arn:aws:ecs:us-east-1:111111111111:cluster/acct-a-cluster]
B(222222222222/eu-west-1): [arn:aws:ecs:eu-west-1:222222222222:cluster/acct-b-cluster]

So the exact scenario this PR exists for is fully expressible in moto. The tests just don't use it.

Test by test

TestIntegration_AssumeRoleThenInventory — tautological as written. The role ARN (123456789012) is in the same account as the base credentials that seeded the cluster. If configureAssumeRole were a complete no-op and the client silently used ambient credentials, this test would still pass. The comment's claim that it "proves the assumed role discovered the seeded service" isn't supported. Fix: seed via role A into 111111111111, then assert role B in 222222222222 sees only its own cluster and not A's. That version fails loudly if the wiring breaks.

TestIntegration_ExternalIDIsAccepted — suggest deleting. Its own comment concedes moto doesn't enforce external IDs. The assertions are a strict subset of the previous test, and the wiring is already covered by TestAssumeRoleOptionsCarryARNSessionAndExternalID in report_test.go. It's a passing test that can never fail.

TestIntegration_ReportDeliveredToAnchore — mostly duplicates pkg/reporter. TestPost already covers v2 path selection, headers, and gock. The unique signal here is "a report assembled from real ECS discovery survives the JSON round trip" — worth keeping, but the moto seeding is incidental to it, and the gock.EnableNetworking() dance against a globally installed transport is fragile.

Biggest gap: multi-pass fan-out is untested end to end. preparePasses is unit-tested with a fake builder and buildInventoryPasses is table-tested, but nothing runs two real passes and asserts each report contains only its account's clusters. That's the one regression that would actually hurt in production (all passes silently hitting the same account, or cross-account leakage), it's the whole point of the PR, and moto makes it nearly free. It needs to live in package pkg to reach preparePasses/readyPass.

Worth stating the coverage boundary in the PR description. moto doesn't populate task Containers, so image extraction — the actual product output — never goes over the wire. The suite covers auth plus control-plane listing only. The file comment says this; the PR description should too, so nobody reads "integration tests" as "end to end."

Harness

• run.sh runs go test -tags integration ./pkg/..., which re-runs the entire unit suite inside the integration job (reporter/connection/inventory unit tests all execute). Add -run 'TestIntegration' or move these into their own package.
• ${AWS_ACCESS_KEY_ID:-test} lets a developer's real credentials and AWS_PROFILE leak into the run. Force fixed dummies, unset AWS_PROFILE AWS_SESSION_TOKEN AWS_SHARED_CREDENTIALS_FILE, and set AWS_EC2_METADATA_DISABLED=true. Harmless against moto, but avoids SSO-resolution hangs on a dev box.
• The GO_BIN / asdf-shim fallback block reads as personal-environment scaffolding in a shared script — CI and other contributors just want go. (.tool-versions itself is fine as repo tooling.)
• Fixed container name means two parallel runs collide. Minor.

Non-test findings

pkg/lib.go:91 — logs report the wrong region for the ambient pass. readyPass{region: pass.region} stores the configured region, not the resolved one. When the region comes from AWS_REGION or IMDS (explicitly supported, and validated at pkg/lib.go:75 via cfg.Region != ""), every log line and tracker message from pkg/lib.go:174 onward reads region="". Store cfg.Region instead.

GetInventoryReportsForRegion(cfg, region, ...) takes a region used only for log text, which can disagree with cfg.Region. Dropping the parameter and reading cfg.Region fixes the above by construction.

Duplicate helpers: passLogAttrs (pkg/lib.go) and appendAssumedRole (pkg/inventory/report.go) are the same function.

Serial fan-out vs. polling interval. Up to 20 roles x full ECS listing, all sequential, against a 300s default. A slow account can push a cycle past the interval; the ticker then just fires immediately and reports go stale with no signal. Worth a warning when a cycle exceeds the interval, or bounded parallelism.

checkAWSCredentials removal is a UX regression for the ambient path. The friendly "check ~/.aws/credentials" message is gone, so the most common misconfiguration now surfaces as a recurring ECS API error. Deliberate and documented, but consider a startup credential check for the ambient pass that warns rather than fails — that keeps the diagnostic without reintroducing the exit-on-blip behavior you were avoiding.

Release-note worthy: --region / ANCHORE_ECS_INVENTORY_REGION is now ignored (with a warning) whenever assume-role entries exist.