Skip to main content

AWS Org-Mode Bootstrap

This is the first-class onboarding path for SecurityV0 AWS integration.

Goal:

  • no manual per-account role creation
  • no console-driven member-account setup
  • one delegated-admin/security-account flow
  • automatic rollout to target OUs/accounts through StackSets

Bootstrap topology​

Management Account
  -> registers delegated admin for CloudFormation StackSets
  -> optionally grants read path for Organizations metadata

Security / Delegated Admin Account
  -> owns StackSet administration
  -> hosts SecurityV0 registration stack
  -> deploys SecurityV0 read-only spoke role to member accounts

Member Accounts
  -> receive SecurityV0 read-only role via StackSets
  -> trust SecurityV0 hub principal with ExternalId condition

Included artifacts​

Two templates are involved. The first lives under ./templates; the second is the canonical member role template, maintained in sv0-connectors:

  1. securityv0-org-bootstrap.yaml (this repo, ./templates)
    • deploy in the delegated-admin/security account
    • creates StackSet administration roles/config and registration outputs
  2. securityv0-readonly-role.yaml (sv0-connectors/integrations/aws/cfn/)
    • canonical member-account read-only role template
    • deployed by StackSets into target member accounts
    • single source of truth for the IAM permission set — see AWS Access — Customer Summary for the plain-English version

Parameters you must provide​

For the bootstrap stack (this repo):

  • SecurityV0PrincipalArn — the hub principal allowed to assume member roles
  • ExternalId — tenant/customer-specific ExternalId
  • RoleName — default SecurityV0ReadOnly

For the canonical member role StackSet (sv0-connectors):

  • ExternalId — same value used in the bootstrap stack
  • SecurityV0AccountId — 12-digit AWS account ID where the SecurityV0 connector runs
  • RoleName — default SecurityV0ReadOnly (must match what the connector resolves to)
  • TargetOuIds or target account set at StackSet deployment time

Deployment flow​

Step 1 — deploy bootstrap stack in delegated-admin/security account​

Example CLI:

aws cloudformation deploy \
  --stack-name SecurityV0-OrgBootstrap \
  --template-file docs/integrations/aws/templates/securityv0-org-bootstrap.yaml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    SecurityV0PrincipalArn=arn:aws:iam::111122223333:role/SecurityV0HubAssumer \
    ExternalId=sv0-customer-example \
    RoleName=SecurityV0ReadOnly

Step 2 — create/update the StackSet using the canonical member template​

The member-account role template is canonical in sv0-connectors. Pull it directly from GitHub for deployment:

curl -fsSL \
  https://raw.githubusercontent.com/SecurityV0/sv0-connectors/main/integrations/aws/cfn/securityv0-readonly-role.yaml \
  -o /tmp/securityv0-readonly-role.yaml

aws cloudformation create-stack-set \
  --stack-set-name SecurityV0-MemberReadOnlyRole \
  --template-body file:///tmp/securityv0-readonly-role.yaml \
  --permission-model SERVICE_MANAGED \
  --auto-deployment Enabled=true,RetainStacksOnAccountRemoval=false \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters \
    ParameterKey=ExternalId,ParameterValue=sv0-customer-example \
    ParameterKey=SecurityV0AccountId,ParameterValue=111122223333 \
    ParameterKey=RoleName,ParameterValue=SecurityV0ReadOnly

Step 3 — deploy stack instances to target OUs​

Example CLI:

aws cloudformation create-stack-instances \
  --stack-set-name SecurityV0-MemberReadOnlyRole \
  --deployment-targets OrganizationalUnitIds=ou-abcd-12345678 \
  --regions us-east-1

Validation​

Validation should also be scripted. Minimum checks:

  • StackSet exists and is ACTIVE
  • stack instances succeed in target accounts
  • target role exists in a sample member account
  • trust policy contains the expected principal + ExternalId condition
  • assume-role succeeds from the SecurityV0 hub principal

Example verification commands:

aws cloudformation describe-stack-set --stack-set-name SecurityV0-MemberReadOnlyRole
aws cloudformation list-stack-instances --stack-set-name SecurityV0-MemberReadOnlyRole
aws iam get-role --role-name SecurityV0ReadOnly

Teardown​

Teardown must also be scripted:

  1. delete stack instances
  2. delete StackSet
  3. delete bootstrap stack

Example:

aws cloudformation delete-stack-instances \
  --stack-set-name SecurityV0-MemberReadOnlyRole \
  --deployment-targets OrganizationalUnitIds=ou-abcd-12345678 \
  --regions us-east-1 \
  --retain-stacks false

aws cloudformation delete-stack-set --stack-set-name SecurityV0-MemberReadOnlyRole
aws cloudformation delete-stack --stack-name SecurityV0-OrgBootstrap

Notes​

  • This is the org-mode baseline, not the full connector implementation.
  • The IAM permissions in the member role are intentionally read-only and should evolve with connector scope.
  • Terraform support can be layered on later, but this StackSets path is the first required fully automated bootstrap.