Internal test runner
For internal network tests only. What the runner is, what it can reach, and how to check what it did.
This page only applies if Trace is running an internal network test for you. If your test covers an application or your external network, you won't install the runner and can skip this.
What it is
The runner is a small container that Trace starts inside a VPC you choose, in your own AWS account. It lets Trace test your network from the inside, the way an attacker who got a foothold would see it.
- You install it yourself, as its own stack (CloudFormation or Terraform), from the AWS integration page.
- It only runs while Trace is testing or retesting.
- It doesn't listen for incoming connections. It connects out to Trace.
It can join your security groups
By default the runner sits in its own security group, which none of your rules mention. From there it sees what any new machine in the VPC would see.
Some of your rules only let in machines that belong to a certain security group. To test those rules, Trace starts the runner inside that group, up to four groups in the VPC at a time.
- What it gets: the group's network access. Nothing else.
- What it doesn't get: the workload's IAM role, its data, or its credentials.
- When it happens: during your test and when findings are retested.
Checking what it did
- Every start is in CloudTrail. Look for the
RunTaskevent fromecs.amazonaws.comon the runner's cluster. The security groups it started in are listed underrequestParameters.networkConfiguration.awsvpcConfiguration.securityGroups. - Every command is logged. The runner writes each command it runs and each connection it opens to its CloudWatch log group,
/trace/internal-runner/<runner ID>. You choose how long AWS keeps it when you install. - Findings say where they were proven. A finding found from inside a security group names that group in its proof.
Limiting or stopping it
- Trace's own connections stay in scope. Connections Trace opens through the runner only go to addresses in your test's scope. Commands run on the runner itself aren't limited that way.
- To limit what it can reach, give the runner subnets of its own and put a network ACL on them. A network ACL doesn't filter traffic between machines in the same subnet. Narrowing the runner's own security group isn't enough either once it has joined another group, because the rules of every group it's in apply together.
- You can't restrict which groups it joins with IAM. AWS has no permission setting for that.
- To stop a run in progress, ask Trace, or stop the task yourself in the ECS console, on the cluster named
trace-internal-runner-<runner ID>.
Removing it
If a run is in progress, stop it first: AWS won't delete the stack while the runner is running. Then delete the stack in AWS (or run terraform destroy), and remove the runner on the AWS integration page. The runner's log group is kept on purpose, as your record of what it did. Delete it yourself when you no longer need it.