AWS Connector

The AWS connector is how Outbound discovers and manages egress in your account. You deploy a single CloudFormation stack; it creates a scoped cross-account IAM role that Outbound’s control plane assumes, plus a small set of supporting resources. This page walks through the setup and documents every permission we request and why we need it.

What the onboarding stack creates

Resource	Purpose
IAM role cloudphilosnetworks	The cross-account role Outbound’s control plane assumes to discover your networks and manage gateways. Trust is restricted to CloudPhilos’s AWS account and a per-customer External ID.
IAM role & instance profile outbound-ec2-instance-role	Attached to gateway instances so they can fetch their reporting API key and be managed via AWS Systems Manager.
Discovery Lambda + EventBridge rules	Listens for EC2 instance and ECS task state changes and registers new private IPs with Outbound, so flows are attributed to the right application within seconds of a workload starting.
Secrets Manager secret /cloudphilos/outbound/api-key	Holds the API key gateways use to report flow telemetry. The key stays in your account; Outbound pushes and rotates it.

Deploy the stack in each region you want Outbound to manage. For multi-region accounts, use CloudFormation StackSets.

Setup steps

1. In the Outbound dashboard, go to Integrations → Add integration → AWS. The wizard generates your External ID and the CloudFormation template.
2. Deploy the stack in your account (console, CLI, or StackSets for multiple regions).
3. Back in the wizard, enter your account ID, the created role’s ARN, the External ID, an account name, and the regions to manage.
4. Outbound assumes the role, verifies access, and starts a read-only network scan. Continue with Your First Gateway.

Confused-deputy protection

The role can only be assumed by CloudPhilos’s AWS account when it presents your unique External ID. This is the standard AWS pattern for third-party access and prevents any other party — including another Outbound customer — from using your role.

Permissions reference

Cross-account role (cloudphilosnetworks)

This is the role Outbound’s control plane uses. Its permissions fall into two groups: read-only discovery, and scoped writes for the gateway lifecycle. Write permissions are constrained to Outbound-tagged resources or specific ARNs wherever the IAM action supports it.

Discovery (read-only)

Permission	Why we need it
ec2:DescribeVpcs	Discover the VPCs in your account so you can choose which ones Outbound manages.
ec2:DescribeSubnets	Classify subnets as public or private, and pair private subnets with a public subnet for gateway placement.
ec2:DescribeRouteTables	Find each subnet’s route table and its current default route — the basis of route table management.
ec2:DescribeNatGateways	Find the AWS NAT Gateways a gateway will replace, and read their configuration.
ec2:DescribeInstances	Track the state of gateway instances we launch, and attribute traffic to your EC2 workloads by private IP.
ec2:DescribeNetworkInterfaces	Map private IP addresses to network interfaces for traffic attribution.
ec2:DescribeAddresses	Discover Elastic IPs, including the ones Outbound allocates and pools for the static IP guarantee.
ec2:DescribeSecurityGroups	Find or reuse the Outbound gateway security group in each VPC.
ecs:ListClusters, ecs:ListTasks	Enumerate ECS clusters and tasks so container workloads can be attributed.
ecs:DescribeTasks, ecs:DescribeTaskDefinition	Resolve an ECS task’s private IP and service name for per-application attribution.
cloudwatch:GetMetricData	Read your existing NAT Gateway’s traffic metrics (bytes, packets, connections) to recommend a gateway size.
sts:GetCallerIdentity	Verify the role assumption and confirm which account we’re operating in.

Gateway lifecycle (scoped writes)

Permission	Resource scope	Why we need it
ec2:RunInstances	Instance, volume, ENI, subnet, security group, AMI resources	Launch the Outbound gateway instance in your public subnet.
ec2:TerminateInstances	Only instances tagged Name=cloudphilos-gateway	Remove a gateway during an upgrade/replacement or offboarding. Cannot touch your workloads.
ec2:ModifyInstanceAttribute	Only instances tagged Name=cloudphilos-gateway	Disable source/destination checking on the gateway — required for any instance that forwards traffic (NAT).
ec2:CreateSecurityGroup	VPC / security group	Create the gateway’s security group (one per VPC, ingress limited to your VPC CIDR).
ec2:AuthorizeSecurityGroupIngress	Only groups tagged cloudphilos-gateway-*	Allow your VPC’s private subnets to send traffic to the gateway.
ec2:CreateTags	Outbound-created instances, security groups, Elastic IPs	Tag gateway resources so they’re identifiable — and so the scoped permissions above apply to them and nothing else.
ec2:CreateRoute, ec2:ReplaceRoute	Route tables	Point the 0.0.0.0/0 route of private subnets at the gateway. Only the default route is ever touched — see Route Table Management.
ec2:AllocateAddress, ec2:AssociateAddress, ec2:ReleaseAddress	Elastic IPs	Allocate and attach the gateway’s static Elastic IP, maintain the spare-IP pool that preserves your egress IP across replacements, and release IPs at offboarding.
ec2:DeleteNatGateway	NAT gateways	Remove your old AWS NAT Gateway after traffic has been cut over to the Outbound gateway, so you stop paying for both.
secretsmanager:UpdateSecret	Only /cloudphilos/outbound/api-key*	Push and rotate the telemetry API key stored in your account.
iam:PassRole	Only the outbound-ec2-instance-role, and only to ec2.amazonaws.com	Attach the instance profile to gateway instances at launch. Cannot pass any other role, or to any other service.

Gateway instance role (outbound-ec2-instance-role)

Attached to the gateway EC2 instances themselves.

Permission	Why we need it
secretsmanager:GetSecretValue on /cloudphilos/outbound/api-key	The gateway’s sensor fetches the API key it uses to report flow telemetry over HTTPS.
AmazonEC2RoleforSSM (AWS managed policy)	Lets you and CloudPhilos manage the gateway via AWS Systems Manager (patching, session access for support) without opening SSH.

Discovery Lambda execution role

Permission	Why we need it
ec2:DescribeInstances, ec2:DescribeTags	When an EC2 instance starts, look up its private IP, VPC, and name tags to register it for attribution.
ecs:DescribeTasks, ecs:DescribeTaskDefinition	Same, for ECS tasks.
secretsmanager:GetSecretValue	Authenticate to Outbound’s registration endpoint.
sts:GetCallerIdentity	Include the account ID in registrations.
AWSLambdaBasicExecutionRole (AWS managed policy)	Write the Lambda’s own logs to CloudWatch Logs.

Removing the connector

Deleting the CloudFormation stack immediately revokes all of Outbound’s access. Do this after following the offboarding guide — if you revoke access while Outbound still owns your default routes, you’ll be left managing the cutover back by hand.