Skip to main content

BYOC Setup Guide

BYOC (Bring Your Own Cloud) allows you to run Visus Agent Sandbox simulations in your own AWS account, giving you complete control over your infrastructure while benefiting from Visus Agent Sandbox'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 Visus Agent Sandbox to assume
  • S3 Bucket for simulation artifacts and logs
  • CloudWatch Log Group for audit trail
  • External ID for secure cross-account role assumption

Visus Agent Sandbox 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
  • Visus Agent Sandbox CLI installed (npm install -g visus-sandbox)

Setup Steps​

1. Generate CloudFormation Template​

npx visus-sandbox byoc init

This generates visus-sandbox-byoc-template.json in your current directory.

Options:

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

Example with custom options:

npx visus-sandbox byoc init --format yaml --output my-template.yaml

2. Deploy CloudFormation Stack​

Option A: Using Visus Agent Sandbox CLI (recommended)

npx visus-sandbox byoc deploy --wait

This deploys the stack and waits for completion.

Option B: Using AWS CLI directly

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

Wait for stack creation:

aws cloudformation wait stack-create-complete --stack-name visus-sandbox-byoc

3. Test Cross-Account Access​

npx visus-sandbox byoc test

This verifies that Visus Agent Sandbox can successfully assume the role in your account.

Expected output:

Visus Agent Sandbox 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

Visus Agent Sandbox can now run simulations in your AWS account.

4. Configure Visus Agent Sandbox to Use BYOC​

Create or update your Visus Agent Sandbox configuration file (~/.visus-sandbox/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 visus-sandbox-byoc-* prefix only
  • Put/get/delete objects within those buckets
  • No access to your existing S3 buckets

RDS Permissions​

  • Create/delete snapshots with visus-sandbox-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 /visus-sandboxutor/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 Visus Agent Sandbox 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 Visus Agent Sandbox 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 visus-sandbox-byoc

  2. Check the External ID matches:

    cat ~/.visus-sandbox/byoc-config.json

  3. Verify the Visus Agent Sandbox 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 visus-sandbox-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 visus-sandbox-byoc
    aws cloudformation wait stack-delete-complete --stack-name visus-sandbox-byoc
    npx visus-sandbox 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 visus-sandbox-byoc-
    • RDS snapshots must start with visus-sandbox-sim-

  3. Verify session hasn't expired:

    • Sessions last 1 hour by default
    • Check credentials expiration: npx visus-sandbox byoc test

Teardown​

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

Using Visus Agent Sandbox CLI​

npx visus-sandbox byoc teardown --wait

Using AWS CLI​

aws cloudformation delete-stack --stack-name visus-sandbox-byoc
aws cloudformation wait stack-delete-complete --stack-name visus-sandbox-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://visus-sandbox-byoc-artifacts-YOUR_ACCOUNT_ID --recursive

  2. Delete S3 bucket:

    aws s3 rb s3://visus-sandbox-byoc-artifacts-YOUR_ACCOUNT_ID

  3. Delete RDS snapshots:

    aws rds describe-db-snapshots --query "DBSnapshots[?starts_with(DBSnapshotIdentifier, 'visus-sandbox-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 /visus-sandboxutor/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 visus-sandbox byoc deploy --stack-name visus-sandbox-prod --region us-east-1

# Deploy to account 2
npx visus-sandbox byoc deploy --stack-name visus-sandbox-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 Visus Agent Sandbox 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 Visus Agent Sandbox service principal is authorized for that partition.

Q: What happens if my AWS credentials expire?​

A: Visus Agent Sandbox 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​