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
TracecatSecOpsAuditRole roles you approve.What you can do
Use AWS Boto3 → Call method for the API calls below. Setrole_arn to the target audit role ARN when the check runs outside your entry account.
Triage GuardDuty findings
Triage GuardDuty findings
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.Map your AWS organization and audit SCPs
Map your AWS organization and audit SCPs
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.Query S3 logs with DuckDB
Query S3 logs with DuckDB
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.Verify CloudTrail coverage
Verify CloudTrail coverage
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.Audit IAM in each approved account
Audit IAM in each approved account
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
Get the workspace trust settings
- In Tracecat, open Credentials and configure the AWS role credential.
- Copy Principal ARN and External ID from Trust policy.
- Supply the External ID through a protected deployment input.
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.
Prepare StackSets for organization deployments
- In the AWS management account, confirm all features are enabled in AWS Organizations.
- Open CloudFormation → StackSets and activate trusted access if prompted.
- Expand Delegated administrators. If your deployment account is absent, choose Register delegated administrator and enter its account ID.
Deploy the roles
Clone the Tracecat repository and openexamples/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.
- CloudFormation
- Terraform
Create the entry role
- In
SecurityAudit, open CloudFormation → Stacks and create a stack fromcloudformation/tracecat-secops-access-role.yaml. - Set
TracecatPrincipalArnandExternalIdfrom Tracecat. - For organization access, set
TargetRoleArnsto a comma-separated list ofarn:aws:iam::<ACCOUNT_ID>:role/TracecatSecOpsAuditRolefor your approved members and the management account if needed. Leave this field blank for a single account. - To allow GuardDuty triage writes, set
EnableGuardDutyTriagetotrue. - Acknowledge named IAM resources and create the stack.
- Copy
RoleArnfrom the stack’s outputs.
Deploy to approved member accounts
- In the StackSets delegated administrator account, open CloudFormation → StackSets → Create StackSet.
- Choose Service-managed permissions and upload
cloudformation/tracecat-secops-audit-role.yaml. - Paste the entry role ARN into
EntryRoleArnsand acknowledge named IAM resources. - Under Deployment targets, choose Deploy to organizational units (OUs) and enter the root or OU ID.
- Select Intersection and enter the approved member account IDs.
- Select one Region and turn automatic deployment off.
- Review the targets, create the StackSet, and wait for the stack instances to be up to date.
Deploy the management audit role if needed
- For organization reads, sign in to the management account and open CloudFormation → Stacks.
- Create a regular stack from
cloudformation/tracecat-secops-audit-role.yaml. Use the entry role ARN forEntryRoleArns. - 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.
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.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
LogArchiveaccount, include that account in your approved members and use itsTracecatSecOpsAuditRole.
Create the S3 policy stack
- Set
RoleNameto the role you chose. - Set
LogBucketArnsto the approved bucket ARNs, separated by commas.
Connect and verify in Tracecat
Save the entry role ARN
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.Add AWS actions to your agent
Verify the entry role session
Verify a target account session
role_arn and confirm the call returns that audit role’s session.Replace an existing entry role
Create the replacement entry role
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.Allow both entry roles during cutover
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.Switch the credential and verify
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.Retire the previous entry role
FAQ
How do I connect a single account or a self-hosted deployment?
How do I connect a single account or a self-hosted deployment?
What access do the policies grant?
What access do the policies grant?
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.Why does the management account need its own stack?
Why does the management account need its own stack?
How do I read logs encrypted with SSE-KMS?
How do I read logs encrypted with SSE-KMS?
- Set
KeyArnto the full ARN of the KMS key. - Set
RoleNameto the role you used for the S3 policy stack. - Set
LogBucketArnsto the ARNs of the approved buckets encrypted by this key.
How long do chained sessions last?
How long do chained sessions last?
duration_seconds to a value from 900 to 3600.