Skip to main content

BYOC Setup Guide

BYOC (Bring Your Own Cloud) allows you to run Shadow Executor simulations in your own AWS account, giving you complete control over your infrastructure while benefiting from Shadow Executor's policy enforcement and simulation capabilities.

Overview​

BYOC mode deploys a CloudFormation stack in your AWS account that creates:

  • IAM Role with least-privilege permissions for Shadow Executor to assume
  • S3 Bucket for simulation artifacts and logs
  • CloudWatch Log Group for audit trail
  • External ID for secure cross-account role assumption

Shadow Executor never stores your AWS credentials. Instead, it assumes the IAM role in your account using STS (Security Token Service) with temporary credentials.

Prerequisites​

  • AWS account with administrative access
  • AWS CLI configured with credentials
  • Shadow Executor CLI installed (npm install -g shadow-exec)

Setup Steps​

1. Generate CloudFormation Template​

npx shadow-exec byoc init

This generates shadow-exec-byoc-template.json in your current directory.

Options:

  • --format <json|yaml> - Template format (default: json)
  • --output <path> - Output file path
  • --account-id <id> - Shadow Executor AWS account ID (provided during onboarding)
  • --external-id <id> - External ID for role assumption (auto-generated if not provided)

Example with custom options:

npx shadow-exec byoc init --format yaml --output my-template.yaml

2. Deploy CloudFormation Stack​

Option A: Using Shadow Executor CLI (recommended)

npx shadow-exec byoc deploy --wait

This deploys the stack and waits for completion.

Option B: Using AWS CLI directly

aws cloudformation create-stack \
  --stack-name shadow-exec-byoc \
  --template-body file://shadow-exec-byoc-template.json \
  --capabilities CAPABILITY_NAMED_IAM \
  --region us-east-1

Wait for stack creation:

aws cloudformation wait stack-create-complete --stack-name shadow-exec-byoc

3. Test Cross-Account Access​

npx shadow-exec byoc test

This verifies that Shadow Executor can successfully assume the role in your account.

Expected output:

Shadow Executor BYOC - Test Access

Testing access to role: arn:aws:iam::123456789012:role/ShadowExecutorBYOCRole

✅ Cross-account access successful!

Connection details:
  Role ARN: arn:aws:iam::123456789012:role/ShadowExecutorBYOCRole
  Region: us-east-1
  Credentials expire: 2026-05-06T14:30:00.000Z

Shadow Executor can now run simulations in your AWS account.

4. Configure Shadow Executor to Use BYOC​

Create or update your Shadow Executor configuration file (~/.shadow-exec/config.json):

{
  "mode": "byoc",
  "roleArn": "arn:aws:iam::YOUR_ACCOUNT_ID:role/ShadowExecutorBYOCRole",
  "externalId": "YOUR_EXTERNAL_ID",
  "region": "us-east-1"
}

The roleArn and externalId values are automatically saved after deployment if you use byoc deploy --wait.

Permissions Granted​

The BYOC IAM role has least-privilege permissions scoped to simulation operations only:

S3 Permissions​

  • Create/delete buckets with shadow-exec-byoc-* prefix only
  • Put/get/delete objects within those buckets
  • No access to your existing S3 buckets

RDS Permissions​

  • Create/delete snapshots with shadow-exec-sim-* prefix only
  • Describe DB instances and snapshots (read-only)
  • No permission to modify or delete actual DB instances

CloudWatch Logs Permissions​

  • Create log groups/streams under /shadow-executor/byoc prefix only
  • Put log events for audit trail
  • No access to your existing logs

Security Best Practices​

1. External ID​

The External ID provides additional security when assuming cross-account roles. It prevents the "confused deputy" problem.

  • Keep it secret: Never commit the External ID to version control
  • Rotate regularly: Regenerate every 90 days (update CloudFormation stack)
  • Use unique IDs: Each customer should have a unique External ID

2. Role Session Duration​

By default, assumed role sessions last 1 hour. You can adjust this in the CloudFormation template:

{
  "Type": "AWS::IAM::Role",
  "Properties": {
    "MaxSessionDuration": 3600  // 1 hour (3600 seconds)
  }
}

3. Resource Tagging​

All resources created by Shadow Executor are tagged:

ManagedBy: ShadowExecutor
Purpose: BYOC-Simulation

Use these tags to track costs and set up monitoring.

4. CloudTrail Monitoring​

Enable CloudTrail in your account to audit all Shadow Executor operations:

aws cloudtrail lookup-events --lookup-attributes AttributeKey=Username,AttributeValue=ShadowExecutorBYOCRole

Cost Estimation​

BYOC mode incurs AWS costs in your account. Estimated monthly costs for typical usage:

ResourceUsageEstimated Cost
S3 Storage1 GB simulation artifacts$0.023/month
S3 Requests10,000 requests/month$0.05/month
RDS Snapshots5 snapshots @ 20 GB each$10/month
CloudWatch Logs1 GB logs/month$0.50/month
Total~$10.60/month

Actual costs vary based on:

  • Number of simulations
  • Size of data being simulated
  • Snapshot retention period
  • Region pricing

Troubleshooting​

"Access Denied" when testing​

Symptoms:

❌ Cross-account access failed
Error: User is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::123456789012:role/ShadowExecutorBYOCRole

Solutions:

  1. Verify the CloudFormation stack deployed successfully:

    aws cloudformation describe-stacks --stack-name shadow-exec-byoc

  2. Check the External ID matches:

    cat ~/.shadow-exec/byoc-config.json

  3. Verify the Shadow Executor account ID in trust policy:

    aws iam get-role --role-name ShadowExecutorBYOCRole --query 'Role.AssumeRolePolicyDocument'

CloudFormation stack creation failed​

Symptoms:

❌ Stack deployment failed: CREATE_FAILED

Solutions:

  1. Check stack events for detailed error:

    aws cloudformation describe-stack-events --stack-name shadow-exec-byoc --max-items 10

  2. Common issues:

    • Bucket name conflict: S3 bucket names must be globally unique. The template uses your account ID to ensure uniqueness, but conflicts can still occur.
    • Insufficient permissions: Ensure your AWS credentials have iam:CreateRole, s3:CreateBucket, and logs:CreateLogGroup permissions.
    • Region mismatch: Some resources (like S3 buckets) are global. Ensure you're deploying in the correct region.

  3. Delete failed stack and retry:

    aws cloudformation delete-stack --stack-name shadow-exec-byoc
    aws cloudformation wait stack-delete-complete --stack-name shadow-exec-byoc
    npx shadow-exec byoc deploy --wait

Simulations failing in BYOC mode​

Symptoms:

Simulation failed: Service s3 operation CreateBucket returned error: Access Denied

Solutions:

  1. Verify IAM role permissions:

    aws iam get-role-policy --role-name ShadowExecutorBYOCRole --policy-name ShadowExecutorBYOCPolicy

  2. Check resource naming conventions:

    • S3 buckets must start with shadow-exec-byoc-
    • RDS snapshots must start with shadow-exec-sim-

  3. Verify session hasn't expired:

    • Sessions last 1 hour by default
    • Check credentials expiration: npx shadow-exec byoc test

Teardown​

When you no longer need BYOC mode, delete the CloudFormation stack:

Using Shadow Executor CLI​

npx shadow-exec byoc teardown --wait

Using AWS CLI​

aws cloudformation delete-stack --stack-name shadow-exec-byoc
aws cloudformation wait stack-delete-complete --stack-name shadow-exec-byoc

⚠️ Warning: This deletes all simulation artifacts and logs. Download any logs you need before teardown.

Manual Cleanup (if teardown fails)​

If CloudFormation teardown fails, manually delete resources:

  1. Empty S3 bucket:

    aws s3 rm s3://shadow-exec-byoc-artifacts-YOUR_ACCOUNT_ID --recursive

  2. Delete S3 bucket:

    aws s3 rb s3://shadow-exec-byoc-artifacts-YOUR_ACCOUNT_ID

  3. Delete RDS snapshots:

    aws rds describe-db-snapshots --query "DBSnapshots[?starts_with(DBSnapshotIdentifier, 'shadow-exec-sim-')].DBSnapshotIdentifier" --output text | xargs -n1 aws rds delete-db-snapshot --db-snapshot-identifier

  4. Delete log group:

    aws logs delete-log-group --log-group-name /shadow-executor/byoc/audit

  5. Delete IAM role:

    aws iam delete-role-policy --role-name ShadowExecutorBYOCRole --policy-name ShadowExecutorBYOCPolicy
    aws iam delete-role --role-name ShadowExecutorBYOCRole

FAQ​

Q: Can I use BYOC with multiple AWS accounts?​

A: Yes. Generate separate CloudFormation stacks for each account and switch between them using different configuration files:

# Deploy to account 1
npx shadow-exec byoc deploy --stack-name shadow-exec-prod --region us-east-1

# Deploy to account 2
npx shadow-exec byoc deploy --stack-name shadow-exec-staging --region us-west-2

Q: Can I restrict BYOC to specific VPCs or subnets?​

A: Yes. Add VPC endpoint conditions to the IAM policy in the CloudFormation template:

{
  "Condition": {
    "StringEquals": {
      "aws:SourceVpce": "vpce-1234567890abcdef0"
    }
  }
}

Q: How do I audit Shadow Executor operations in my account?​

A: Use CloudTrail to monitor all API calls made by the ShadowExecutorBYOCRole:

aws cloudtrail lookup-events \
  --lookup-attributes AttributeKey=Username,AttributeValue=ShadowExecutorBYOCRole \
  --max-results 50

Q: Can I use BYOC with GovCloud or China regions?​

A: Yes, but you must deploy the stack in the GovCloud/China region and ensure the Shadow Executor service principal is authorized for that partition.

Q: What happens if my AWS credentials expire?​

A: Shadow Executor uses STS temporary credentials that auto-refresh before expiration. If your long-term AWS credentials (used to initially deploy the stack) expire, BYOC will continue working as long as the IAM role exists.

Next Steps​