Cross-account discovery in ZopNight

ALL THREE PATTERNS:
  1. ONE source-of-truth credential (managed centrally)
  2. EACH child account trusts the source credential
  3. ZOPNIGHT exchanges short-lived credentials for each access
  4. NO long-lived per-account credentials stored anywhere

STEP 1: ZOPNIGHT's source credential
  The ZopNight-Discovery IAM role in the management account
  (or external IAM user with assume-role-only permission)

STEP 2: PER-CHILD-ACCOUNT trust
  In each child account, deploy an IAM role with this trust policy:

  trust_policy:
    Principal: <ZopNight source role ARN>
    Action: sts:AssumeRole
    Condition: { StringEquals: { sts:ExternalId: "<customer-specific>" } }

STEP 3: ZOPNIGHT discovers via assume-role
  sts.AssumeRole(
    RoleArn = arn:aws:iam::<child-account>:role/ZopNight-Discovery,
    ExternalId = <customer-specific external ID>
  )
  → returns temporary credentials (default 1-hour lifetime)
  → ZopNight uses them for discovery in that account
  → credentials expire automatically; next discovery re-issues

DEPLOYMENT VEHICLE: CloudFormation StackSet
  Deploy the IAM role to all accounts in the AWS Organization
  in one operation. New accounts auto-receive the role.

LEGACY: Service-account JSON key
  Generate a JSON key for a service account
  Grant organization-viewer role to the service account
  Upload the JSON key to ZopNight

  Pros: simple
  Cons: long-lived secret; rotation manual; key compromise = full
        read of GCP estate

PREFERRED: Workload Identity Federation (WIF)
  Create a WIF pool in your GCP project
  Configure the pool to trust ZopNight's identity
  Grant organization-viewer to the WIF identity
  ZopNight authenticates via short-lived federated tokens

  Pros: no long-lived secret; rotation automatic; revocation instant
  Cons: slightly more setup

STEP 1: REGISTER an Azure AD application
  Portal → Azure AD → App registrations → New registration
  Note: tenant_id, application (client) ID

STEP 2: GRANT permissions
  Azure RBAC → Reader role at the tenant or root MG level
  Inherits to all subscriptions

STEP 3: CREATE a credential
  Option A: Client secret (long-lived; manual rotation)
  Option B: Certificate (long-lived; rotation via cert pipeline)
  Option C: Workload Identity Federation (short-lived; recommended)

STEP 4: ZOPNIGHT authenticates via OAuth client-credentials flow
  tenant_id + app_id + credential
  → returns access token (default 1-hour lifetime)
  → ZopNight uses token for ARM API calls (discovery, cost data)

WITHOUT ExternalId (insecure):
  Attacker says to ZopNight: "Assume role X for me"
  ZopNight (a trusted service) calls sts.AssumeRole(X)
  Returns credentials; attacker's instructions were honored

  PROBLEM: ZopNight is acting on attacker's behalf with stolen role

WITH ExternalId:
  Attacker says to ZopNight: "Assume role X for me"
  ZopNight calls sts.AssumeRole(X, ExternalId=<ZopNight's per-customer ID>)
  AWS checks the role's trust policy: requires ExternalId = <Y>
  If the attacker did not know Y to inject: AWS rejects

  PROTECTION: ExternalId acts as a shared secret between
              ZopNight + the legitimate customer account

T+0       ZopNight scheduled discovery task begins
T+10ms    Loads management-account credentials (long-lived, secured)

For each child account in the customer's estate:
T+11ms    Calls sts.AssumeRole(child_role_arn, ExternalId=customer_eid)
T+50ms    AWS returns temporary credentials (1-hour validity)
T+51ms    ZopNight begins discovery API calls:
            EC2: DescribeInstances, DescribeVolumes, ...
            S3:  ListBuckets, GetBucketLocation, ...
            RDS: DescribeDBInstances, ...
            (parallel calls; rate-limited per AWS guidance)
T+800ms   Discovery complete for this account
T+810ms   Resources persisted to ZopNight's database
T+810ms   Temporary credentials abandoned (no need to revoke;
          they expire automatically)
T+811ms   Next child account; repeat

For an 8-account AWS estate:
  Total cycle: ~3-5 minutes for full discovery (parallelism reduces
  wall-clock time well below 8× single-account time)

AWS:           ExternalId can be rotated by updating both ZopNight
              config and each child account's trust policy. Cross-
              account roles themselves do not need rotation if
              ExternalId is in place.

GCP (JSON):    Service-account keys must be rotated periodically.
              Recommended: every 90 days. WIF eliminates this need.

GCP (WIF):     No rotation needed; tokens are ephemeral.

Azure:         Client secrets rotate per Azure's expiration policy
              (default 1 year, configurable). Certificates rotate
              per the certificate's lifecycle. WIF eliminates need.

RESOURCE INVENTORY      EC2, RDS, S3, Lambda, EKS, ECS, EBS, ELB,
                        ALB, NLB, Route53, CloudFront, ...
                        (similar surfaces for GCP and Azure)

COST DATA              CUR (AWS), Cloud Billing (GCP), Cost
                        Management (Azure): typically daily refresh

TAG DATA                All resource tags + their values

USAGE METRICS           CloudWatch / Monitoring / Insights: for
                        recommendations (idle detection, right-sizing)

AUDIT/EVENT             CloudTrail / Audit Logs / Activity Log:
                        for activity-driven recommendations

SETUP TIMELINE:

Step 1: Management-account preparation (30 min)
  - Create ZopNight-Source IAM role in management account
  - Trust policy: trust ZopNight's AWS account
  - Permission policy: sts:AssumeRole on child-account roles

Step 2: Per-child-account role (StackSet: 15 min once, 0 min per account)
  - Deploy CloudFormation StackSet from management account
  - StackSet template defines ZopNight-Discovery role
  - Trust: management account principal + ExternalId condition
  - Permissions: read-only IAM policies for discovery

  Deploy to:
    - All 8 current accounts (1 deploy operation)
    - Auto-deploy to any new accounts added later

Step 3: ZopNight configuration (5 min)
  - In ZopNight: Settings → Cloud Accounts → Add AWS Organization
  - Provide: management account credentials,
             AWS Organizations ID, ExternalId
  - ZopNight discovers all 8 accounts; adds each to its inventory

Step 4: First discovery cycle (3-5 min)
  - ZopNight begins discovery; per-account assume-role calls
  - Each account: 1-hour temporary credentials; discovery API calls
  - Results: ~3,400 resources across the 8 accounts
  - Cost data: 30-90 day backfill begins

TOTAL ELAPSED: ~50 minutes from first IAM role to first dashboard.
ONGOING: discovery refreshes hourly; cost refreshes nightly.

PROVIDER:                __________ (AWS / GCP / Azure)
ACCOUNT COUNT:           _____
HIERARCHY-LEVEL CONNECTION POINT: __________ (org / folder / MG / etc.)

CREDENTIAL STRATEGY:
  □ Cross-account assume-role (AWS) with ExternalId
  □ Service account + org-viewer (GCP, legacy)
  □ Workload Identity Federation (GCP / Azure, preferred)
  □ Service principal with Reader role (Azure)

DEPLOYMENT VEHICLE for per-account IAM roles:
  □ CloudFormation StackSet (AWS)
  □ Terraform module (cloud-agnostic)
  □ Manual (small estates only)

ESTIMATED SETUP TIME:    _____ hours
  (Larger estates with multiple BUs may have political coordination
   overhead beyond the technical work)

CREDENTIAL ROTATION:
  Current rotation cadence: __________
  Target cadence: __________
  Migration to short-lived credentials (WIF / assume-role)? __________