Skip to main content
Give Tracecat agents and workflows one AWS entry role. This guide uses SecurityAudit for your security account, which serves as the GuardDuty delegated administrator for the Regions you monitor.

Set up the AWS connection with an AI assistant

The Tracecat executor uses the workspace External ID to assume the entry role. Tracecat then uses temporary sessions to assume only the TracecatSecOpsAuditRole roles you approve.

What you can do

Use AWS Boto3 → Call method for the API calls below. Set role_arn to the target audit role ARN when the check runs outside your entry account.
Use the entry role in each GuardDuty Region. Call guardduty.list_detectors, then list_findings with DetectorId and get_findings with DetectorId and FindingIds. Enable triage writes to archive or unarchive findings and submit feedback.
Use the management audit role. Start with organizations.list_roots. Call list_organizational_units_for_parent and list_accounts_for_parent with each root or OU as ParentId. To include inherited SCPs, call list_policies_for_target with Filter: SERVICE_CONTROL_POLICY and pass each account, ancestor OU, and root ID as TargetId. Read each policy with describe_policy and its PolicyId. Use Call paginator for the list calls.
Configure the amazon_s3 credential in Connect and verify in Tracecat. Add core.duckdb.execute_sql to your workflow. The inputs below count events in one Parquet partition. Replace the bucket, path, Region, and audit role ARN. Omit role_arn if the entry role has direct bucket access.
Use the audit role in the trail’s owning account and set region_name to the trail’s home Region. Call cloudtrail.get_trail_status with the full trail ARN as Name to check IsLogging and delivery errors. Call get_event_selectors with the ARN as TrailName to see which events the trail captures.
Use the member audit role with the AWS-managed SecurityAudit policy. Call iam.list_roles to inventory role trust policies, then list_attached_role_policies with RoleName to see which managed policies each role uses.

Before you deploy

1

Get the workspace trust settings

  1. In Tracecat, open Credentials and configure the AWS role credential.
  2. Copy Principal ARN and External ID from Trust policy.
  3. Supply the External ID through a protected deployment input.
2

Choose the AWS accounts and Region

  • Choose one deployment Region for the IAM stacks and StackSet.
  • For organization access, record your root ID (r-…) or OU ID (ou-…) and your approved member account IDs. Include the management account ID if you want organization reads.
  • Run aws sts get-caller-identity --profile <PROFILE> for each AWS CLI profile you use.
3

Prepare StackSets for organization deployments

  1. In the AWS management account, confirm all features are enabled in AWS Organizations.
  2. Open CloudFormation → StackSets and activate trusted access if prompted.
  3. Expand Delegated administrators. If your deployment account is absent, choose Register delegated administrator and enter its account ID.
We strongly recommend deploying StackSets from a dedicated delegated administrator account. Use the management account to register it and to deploy the separate management audit role. Register a StackSets delegated administrator.

Deploy the roles

Clone the Tracecat repository and open examples/connections/aws. For a single account, deploy only the entry role. For organization access, keep the security account out of the member account allowlist because it uses the entry role directly.
1

Create the entry role

  1. In SecurityAudit, open CloudFormation → Stacks and create a stack from cloudformation/tracecat-secops-access-role.yaml.
  2. Set TracecatPrincipalArn and ExternalId from Tracecat.
  3. For organization access, set TargetRoleArns to a comma-separated list of arn:aws:iam::<ACCOUNT_ID>:role/TracecatSecOpsAuditRole for your approved members and the management account if needed. Leave this field blank for a single account.
  4. To allow GuardDuty triage writes, set EnableGuardDutyTriage to true.
  5. Acknowledge named IAM resources and create the stack.
  6. Copy RoleArn from the stack’s outputs.
2

Deploy to approved member accounts

  1. In the StackSets delegated administrator account, open CloudFormation → StackSets → Create StackSet.
  2. Choose Service-managed permissions and upload cloudformation/tracecat-secops-audit-role.yaml.
  3. Paste the entry role ARN into EntryRoleArns and acknowledge named IAM resources.
  4. Under Deployment targets, choose Deploy to organizational units (OUs) and enter the root or OU ID.
  5. Select Intersection and enter the approved member account IDs.
  6. Select one Region and turn automatic deployment off.
  7. Review the targets, create the StackSet, and wait for the stack instances to be up to date.
3

Deploy the management audit role if needed

  1. For organization reads, sign in to the management account and open CloudFormation → Stacks.
  2. Create a regular stack from cloudformation/tracecat-secops-audit-role.yaml. Use the entry role ARN for EntryRoleArns.
  3. Acknowledge named IAM resources, create the stack, and wait for it to complete.

Grant read access to archived logs

  • Tracecat can list S3 buckets in each connected AWS account.
  • Tracecat can read bucket metadata, including location, encryption settings, and bucket policies.
  • After you deploy the log archive S3 policy stack, this setup grants file reads only for approved log archive buckets.
Attach the S3 policy to a Tracecat role whose S3 object access should be limited to the archive. The policy denies s3:ListBucket and s3:GetObject outside the allowlist across the entire role, even when another policy grants those actions. Deploy one S3 policy stack per role and update its allowlist when you add buckets.
1

Choose the role that will read the logs

  • If the buckets are in your entry account, use your entry role.
  • If the buckets are in a separate LogArchive account, include that account in your approved members and use its TracecatSecOpsAuditRole.
2

Create the S3 policy stack

In the bucket owner’s account, create a CloudFormation stack from the log archive template. Follow this step for either deployment method.
  • Set RoleName to the role you chose.
  • Set LogBucketArns to the approved bucket ARNs, separated by commas.
Acknowledge named IAM resources and create the stack.
If your logs use SSE-KMS, follow the KMS setup in the FAQ before testing file reads.

Connect and verify in Tracecat

1

Save the entry role ARN

Save the entry stack’s RoleArn as AWS_ROLE_ARN in the aws credential. For S3 actions or DuckDB queries against S3, set AWS_ROLE_ARN in the amazon_s3 credential to the same ARN. Use role credentials with AWS_ROLE_ARN and leave access key fields empty.
2

Add AWS actions to your agent

Add the AWS actions to your agent’s available tools. See AI preset agent tools.
3

Verify the entry role session

Run AWS Boto3 → Call method and confirm it returns the entry role session.
4

Verify a target account session

For a target account, add its role_arn and confirm the call returns that audit role’s session.
Verify each path you configured.

Replace an existing entry role

1

Create the replacement entry role

Create a separate entry stack with a distinct EntryRoleName and the same target role allowlist. With Terraform, add a second stack resource with a distinct resource address, stack name, and role name. Keep the original stack in place during the cutover.
2

Allow both entry roles during cutover

For organization access, update the existing target role stacks to trust both entry role ARNs. Pass both ARNs as EntryRoleArns, or set organization.previous_entry_role_arn in Terraform when switching the audit stacks’ entry role reference. Wait until the target stack instances are up to date.
3

Switch the credential and verify

Set AWS_ROLE_ARN to the new stack’s RoleArn output in each credential you use and repeat the verification calls. Check any workflows that still need write permissions granted by the previous role. Restore the previous ARN if a check fails.
4

Retire the previous entry role

After verification and once the previous role has no callers, remove it from target role trust policies and retire its stack.

FAQ

Deploy only the entry role and omit the organization settings. For self-hosted Tracecat, use the executor’s IAM role as the principal. The default Fargate setup requires the entry role in a different account from Tracecat. See AWS role assumption.
The AWS-managed SecurityAudit policy grants security configuration reads in each account, including GuardDuty reads. The optional triage policy uses Resource: '*' so the entry role can archive findings, unarchive findings, and update feedback wherever the GuardDuty delegated administrator can manage findings. The log policy limits object listing and reads to approved buckets. See SecurityAudit and GuardDuty administrator permissions.
Service-managed StackSets deploy to member accounts. Create a regular stack in the management account for Organizations and CloudTrail reads. Use the full trail ARN for organization-trail checks. See StackSet account targeting.
In the log bucket owner’s account, create one KMS policy stack per key. If an organization trail specifies its own key, use that key for its logs.
  • Set KeyArn to the full ARN of the KMS key.
  • Set RoleName to the role you used for the S3 policy stack.
  • Set LogBucketArns to the ARNs of the approved buckets encrypted by this key.
Acknowledge named IAM resources and create the stack. Confirm the key policy allows the role to decrypt. For keys in the same account as the role, the key policy can grant access directly or delegate it to IAM. For cross-account keys, the key policy must authorize the role or its account.The template matches the bucket ARN for S3 Bucket Keys and object ARNs for object-level encryption. See CloudTrail KMS key policies.
AWS limits the session for the second role to one hour. Set duration_seconds to a value from 900 to 3600.