Connect AWS CloudTrail

Step 1 - Open Integrations

Go to app.jutsu.ai and select Integrations in the left navigation.

Figure 1. Open Integrations in Jutsu.

Step 2 - Select AWS CloudTrail

In the Cloud section, select the AWS CloudTrail card. The integration ingests AWS API calls, console sign-ins, and resource changes delivered through CloudTrail log files.

Figure 2. Select the AWS CloudTrail integration card.

Step 3 - Name the integration

Enter a name that clearly identifies the AWS account or environment, such as Acme - Production.

Keep Cross-account role selected. It is the recommended and currently supported connection method. Access-key onboarding is shown as Coming soon and cannot be selected.

Figure 3. Name the integration and keep Cross-account role selected.

Step 4 - Start setup

Select Start setup. Jutsu creates a pending integration, a unique external ID, and a secure one-time registration link. The registration link expires after 24 hours.

Figure 4. Select Start setup.

What happens next: Jutsu opens a second phase of the dialog with a Launch stack button. No credentials or resource identifiers need to be copied by hand.

Step 5 - Launch the CloudFormation stack

Select Launch stack. The AWS CloudFormation console opens in a new browser tab in us-east-1 with the template, stack name, and Jutsu registration values prefilled.

Figure 5. Launch the prefilled CloudFormation stack.

Important: Confirm that you are signed in to the intended AWS account. Do not change ExternalId, JutsuAccountId, JutsuAssetId, JutsuRegistrationToken, or JutsuRegisterUrl.

Step 6 - Review stack settings and acknowledge IAM

Review the resource summary and these optional parameters before creating the stack:

CreateJutsuTrailAnywayNo by default. Reuse discovered trails. Choose Yes only for an isolated Jutsu-managed trail.
CleanupAutoCreatedTrailOnDeleteYes by default. Deletes a Jutsu-created trail and bucket, including stored logs, when the stack is deleted.
RetentionDays1 day by default. Applies only to a bucket this stack creates. Increase it for a longer outage-recovery window.

At the bottom of the page, select I acknowledge that AWS CloudFormation might create IAM resources. AWS requires this acknowledgement because the template creates IAM roles and policies.

Figure 6. Acknowledge that CloudFormation may create IAM resources.

Step 7 - Create the stack

Select Create stack. CloudFormation begins provisioning the SQS queue, IAM roles, Lambda function, trail discovery, bucket notifications, and automatic registration with Jutsu.

Figure 7. Select Create stack.

Do not close the AWS account or switch regions: You can leave the browser tab open while CloudFormation creates the resources. The stack event list updates as each resource completes.

Step 8 - Wait for CREATE_COMPLETE

Wait until the stack changes from CREATE_IN_PROGRESS to CREATE_COMPLETE. A few minutes is normal. The Events tab lists each resource, the current status, and any status reason.

Figure 8. The jutsu-cloudtrail stack has reached CREATE_COMPLETE.

If creation fails: For CREATE_FAILED or ROLLBACK_COMPLETE, open Events and read the earliest failed resource and its status reason before retrying.

Step 9 - Confirm the connection in Jutsu

Return to Jutsu. While the setup dialog is open, it checks the registration automatically and changes to Connected. You can also choose Close and finish later; refresh Integrations or Assets after the AWS stack completes.

Once connected, events begin streaming shortly. The asset may show Warming up until the first CloudTrail log file arrives.

Figure 9. The AWS CloudTrail asset is connected.

Verify that events are arriving

  1. Open Assets and select the AWS CloudTrail asset.
  2. During the initial delivery window, the asset may show Warming up. Allow up to about 15 minutes for the first log file.
  3. In asset details, check Last event, Source-type breakdown (last 24 h), and 20 most recent events.
  4. If multiple trails were discovered, open the asset's Trails action and choose which wired trails Jutsu should ingest. Successfully wired trails are enabled by default.

Severity filter: New assets start at Medium and above. Some routine CloudTrail events may be classified below Medium. If the connection is healthy but expected lower-severity activity is missing, review the asset's Severity filter.

What healthy looks like

Asset statusConnected or Active
TrailsAt least one discovered trail is both wired and enabled
Last eventA recent timestamp after CloudTrail delivers its first log file
Connection testAssume-role and SQS queue are reachable

Troubleshooting

The stack does not reach CREATE_COMPLETE

  • Open the CloudFormation Events tab and inspect the earliest failed resource and its status reason.
  • Confirm that your AWS identity can create the IAM roles, Lambda function, SQS queue, S3 notification configuration, and CloudTrail resources in the template.
  • If a stack or queue named jutsu-cloudtrail already exists, inspect it before creating another one. Remove an abandoned stack only when it is safe to delete its resources.

The stack is complete, but Jutsu still shows Pending

  • Wait a minute and refresh Integrations or Assets.
  • Check CloudFormation Events for a failure on the JutsuRegister custom resource.
  • The one-time registration link expires after 24 hours. If it expired before registration completed, start a new setup from Jutsu.

The asset is Connected, but no events appear

  • Allow up to about 15 minutes for the first CloudTrail delivery.
  • Confirm the source trail is actively logging and delivering files to its S3 bucket.
  • Open the asset's Trails action. The intended trail must be both wired and enabled.
  • A trail bucket owned by another AWS account cannot be auto-wired.
  • Review the asset's Severity filter; the default is Medium and above.
  • When the asset reports that setup is taking longer than expected, use Test connection to verify that Jutsu can assume the role and reach the SQS queue.

Security and access

  • No AWS access key or secret is copied into Jutsu.
  • The cross-account role requires a unique external ID and is scoped to the Jutsu SQS queue and the S3 buckets that were successfully wired.
  • The setup Lambda uses broader permissions only while CloudFormation creates or deletes the stack so it can discover trails and manage S3 notification configuration.
  • The one-time registration token is stored by Jutsu only as a cryptographic hash and cannot be reused after successful registration.

Pause or disconnect

PauseDisable the asset in Jutsu to stop ingestion without deleting its configuration.
ArchiveArchive the asset to stop ingestion and free its plan slot. Previously collected events and alerts remain available. Archiving does not remove AWS resources.
Remove AWS resourcesDelete the jutsu-cloudtrail CloudFormation stack in the connected AWS account. The stack removes its queue, IAM roles, Lambda resources, and the notification entries it added to existing trail buckets.

Data-loss warning: If CleanupAutoCreatedTrailOnDelete was left at Yes, deleting the stack also stops and deletes JutsuManagedTrail, empties its managed S3 bucket, and deletes that bucket. Existing customer-owned trails and buckets are not deleted.