AWS Transform agent security: a layered trust model

AWS Transform agents are constrained by nine security layers. Here's what each enforces, what's a hard boundary, and what you own as a builder.

Rusty Nations

Enabling partners and customers to build migration agents on AWS Transform

Published Jul 13, 2026

Last modified Jul 21, 2026

Your agent runs in an AWS account with access to real resources. Before you deploy it, you need to understand what constrains it. This post breaks down the layered security model that governs AWS Transform agents, so you can build with confidence and answer security review questions.

Prerequisites

An AWS account with AWS Transform configured
An agent deployed to AWS Transform (the Agent Builder Toolkit in Kiro is the fastest path)
Basic IAM knowledge (roles, trust policies, inline policies)

The trust stack at a glance

AWS Transform's security model is layered. Some controls are inherited from Amazon Bedrock AgentCore - the same infrastructure primitives that power all AgentCore workloads - while others are application-level controls specific to AWS Transform. This distinction matters: the AgentCore layers carry AWS-native security review and compliance rigor, not bespoke controls built for one service.

Layer	What it controls	The question it answers	Enforcement	Provided by
IAM Execution Roles	API and resource access ceiling	"What CAN this agent access?"	Hard (AWS-enforced)	AgentCore
Workspace Isolation	Tenant boundary, scoped auth tokens	"Can it reach other tenants?"	Hard (platform token)	AWS Transform
Tool Declaration + IAM	What the LLM can choose; what your agent can access	"What is it supposed to do?"	Soft (model) + Hard (IAM)	AgentCore + Builder
Connector Mediation	Cross-account credential brokering	"How does it access customer resources?"	Hard (STS + role)	AWS Transform
Subagent Isolation	Per-instance tokens, independent roles	"Can child agents escape their scope?"	Hard (token) + Soft (IAM design)	AWS Transform + AgentCore
Human-in-the-Loop	Configurable approval gates	"Who approves risky actions?"	Hard (blocks execution)	AWS Transform
Artifact Security	S3 + CMK, workspace-scoped	"Where does customer data go?"	Hard (encryption + ACL)	AWS Transform
Composability Trust	Registry transparency, workspace boundaries for composed agents	"Can I trust agents I didn't build?"	Hard (workspace) + Trust (publisher)	AWS Transform + Publisher
Observability	CloudWatch, X-Ray, decision logs	"How do I verify all of the above?"	Audit (detective)	AgentCore + AWS

Layer 1: IAM Execution Roles

Provided by: Amazon Bedrock AgentCore

Every AWS Transform agent operates under distinct IAM roles. You configure these when you deploy your agent.

AgentCoreExecutionRole

The runtime identity for your agent. Trusted only by bedrock-agentcore.amazonaws.com.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "123456789012"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:*"
        }
      }
    }
  ]
}

The aws:SourceAccount and aws:SourceArn conditions ensure only AgentCore resources in your account can assume this role (sometimes referred to as preventing a "confused deputy" attack).

This role determines the ceiling of what your agent can access. Typical permissions:

Permission	Purpose
`bedrock:InvokeModel`	Call foundation models
`bedrock-agentcore:GetWorkloadAccessToken*`	Runtime token operations
`transform-agents:*`	AWS Transform platform API (jobs, status, messages)
`ecr:BatchGetImage`, `ecr:GetDownloadUrlForLayer`	Pull your container image
`logs:CreateLogStream`, `logs:PutLogEvents`	Write CloudWatch logs
`xray:PutTraceSegments`	Distributed tracing

For S3 access, you add scoped permissions here:

1
2
3
4
5
6
7
8
{
  "Effect": "Allow",
  "Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket"],
  "Resource": [
    "arn:aws:s3:::my-agent-data-bucket",
    "arn:aws:s3:::my-agent-data-bucket/*"
  ]
}

Note: The permissions table above is a simplified view showing the categories relevant to builders. Your actual role may include additional platform-internal service namespaces. Always inspect the full policy document attached to your role.

ATXAgentInvokeRole (AWSTransformAgentInvokeRole)

Controls who can trigger your agent. The trust policy targets the AWS Transform compute service principal (check the Developer Guide for the current value, as this may change).

This is the role ARN you provide in computeConfiguration.provisionedComputeConfiguration.agentCoreConfiguration.atxAccessRoleArn when publishing an agent version. It enables AWS Transform to invoke your agent runtime on your behalf.

What this means for your security review

You can inspect every IAM policy document attached to your agent's roles (via the IAM console or CLI). There is no implicit ambient authority. The execution role is the hard ceiling.

Layer 2: Workspace Isolation

Provided by: AWS Transform

AWS Transform organizes work into workspaces. Each workspace is scoped to a specific customer engagement. This is a hard security boundary:

Agents in one workspace cannot access resources in another
Each workspace issues its own authorization tokens
Cross-workspace communication is not possible at the platform level

Your agent receives a WORKSPACE_ID environment variable at runtime. All calls to the AWS Transform platform API - the backend that manages jobs, artifacts, connectors, messaging, and agent lifecycle - are scoped to that workspace. Even if the same agent serves multiple workspaces, each invocation's authorization token restricts platform API access to that specific workspace's data. One workspace's job cannot read another workspace's artifacts, messages, or connector configurations.

Builder implication: You do not need to implement tenant isolation in your agent code. The platform enforces it at the token layer.

Layer 3: Tool Declaration and IAM as the Real Boundary

Provided by: Amazon Bedrock AgentCore (runtime) + builder-configured IAM

An AWS Transform agent's LLM can only use tools it's been explicitly given. But the tool declaration is one layer in a defense-in-depth model, not a standalone security boundary. Understanding where each layer enforces is critical.

Two enforcement layers

Layer	What it prevents	Hard boundary?
Tool registration (model-level)	LLM choosing undeclared tools	Soft - constrains the LLM's choices
IAM execution role	Container accessing unpermitted APIs	Hard - AWS enforces regardless of code

How tool registration works

In your agent code, tools are registered via the @tool decorator (Strands Agents SDK ) or through MCP tool declarations. The LLM cannot select an undeclared tool because it never sees one. As seen in this example from a Hadoop Migration Agent:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
from strands.tools import tool

@tool
def parse_hadoop_config(config_path: str) -> dict:
    """Parse a Hadoop XML configuration file and extract properties.

    Reads core-site.xml, hdfs-site.xml, yarn-site.xml, hive-site.xml, or
    similar Hadoop configuration files and returns a dictionary of properties.

    Args:
        config_path: Path to the XML configuration file

    Returns:
        Dictionary with property names as keys and values as values,
        plus metadata about the config type.
    """
    ...

Only tools registered this way are visible to the LLM at runtime. The agentCard in your published version separately declares capabilities for the registry and marketplace (from the Agent Registration API schema ):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "name": "Agent Connectors",
  "description": "Connector types used by this agent",
  "params": {
    "connectors": [
      {
        "connectorTypeId": "platform|s3|1",
        "displayName": "Platform S3 Managed Policy Connector",
        "required": true,
        "description": "S3 bucket for storing transformation artifacts"
      }
    ]
  }
}

A pragmatic view of tool containment

The agentCard is a documentation and discoverability artifact. It tells the registry and anyone evaluating your agent what it's designed to do. Reviewers will examine it during evaluation.

Tool registration controls what the LLM can choose, while IAM controls what the runtime can actually reach - these are complementary layers, not redundant ones. The LLM only sees declared tools, and the IAM execution role enforces a hard ceiling on what APIs are accessible regardless of what code runs.

This is why IAM least-privilege is the primary security boundary. Even if a prompt injection bypasses tool registration, the execution role limits what APIs are reachable. A tightly scoped role means the blast radius is contained to exactly the permissions you granted - nothing more. Tool declarations communicate intent; IAM enforces the boundary.

The recommended enforcement approach

The Well-Architected Agentic AI Lens prescribes: "Authorization implemented only through prompt instructions is insufficient. Implement authorization as an external, deterministic check that happens before the tool executes."

For AWS Transform agents, the practical defense-in-depth is:

Tool registration - Prevents the LLM from choosing undeclared actions (necessary but insufficient)
IAM least-privilege - The baseline role has no resource access. Add only what your declared tools need (this is your hard boundary)

Builder takeaway: IAM is your security boundary. The baseline role starts with no resource access - you add only what your tools need. Tool declarations communicate what your agent is designed to do, but IAM is what enforces it.

Layer 4: Connector-Mediated Resource Access

Provided by: AWS Transform platform

For cross-account or connector-managed resource access, agents don't hold credentials directly. The AWS Transform platform brokers access:

A connector is configured with an IAM role that has access to specific customer resources
When the agent needs to act on those resources, the platform assumes the connector role
The platform vends short-lived, scoped credentials to the agent

Same-account vs. cross-account

Same-account access: Your agent uses its AgentCoreExecutionRole identity-based policy directly. No connector required. boto3.client("s3") resolves credentials from the agent's role. This is the simple path. For a full walkthrough of this pattern, see Amazon S3 as a living data layer for your AWS Transform agent .

Cross-account / connector-mediated access: The agent calls list_s3_connectors() to discover available connectors, then uses connector-specific download/upload tools. The platform brokers the credential exchange.

1
2
3
4
5
6
# Pattern: connector first, direct fallback
connectors = list_s3_connectors()
if connectors:
    data = download_from_connector(connector_id, key)
else:
    data = download_s3_file(bucket, key)  # Falls back to runtime role

Credential lifecycle: Connector credentials are temporary STS tokens with a configurable duration of 15 minutes to 12 hours (durationSeconds: 900-43200, per the GetTemporaryCredentialsForConnector API). This range matches STS AssumeRole session limits, indicating the platform calls AssumeRole on the connector's IAM role under the hood. The connector role's IAM policy is the scope ceiling for vended credentials. Separately, the agent's authorization token (which gates platform API access) has its own refresh cycle managed by the SDK.

Known sharp edge: Connector authorization is separately gated at the platform level. list_s3_connectors() may succeed while data plane calls fail with ValidationException: Partner 'X' is not authorized to access this type of connector. Always implement the direct fallback.

Layer 5: Subagent Containment

Provided by: AWS Transform (token scoping) + Amazon Bedrock AgentCore (runtime isolation)

AWS Transform supports multi-agent patterns via the A2A (Agent-to-Agent) protocol. An orchestrator spawns subagents to handle specialized tasks.

Architecture

Orchestrators are registered with type: "ORCHESTRATOR_AGENT" and declare subagent dependencies
Subagents are RESTRICTED visibility (only orchestrators can invoke them via the platform API)
Each subagent instance processes exactly one message, stateless
The platform API mediates all subagent creation (orchestrator calls InvokeAgent)

Two containment mechanisms

1. Authorization token (workspace + job scoping)

Each subagent instance receives a fresh AUTHORIZATION_TOKEN at invocation time. This token:

Is generated per-instance by the platform (not inherited from the parent)
Scoped to the workspace and job context
Cannot cross workspace boundaries
Short-lived and refreshable via the SDK's auth token refresher
Gates all platform API access (artifacts, messages, HITL, connectors, job status)

This prevents lateral movement across workspaces and jobs.

2. Independent IAM roles (resource access scoping)

Each agent (orchestrator or subagent) deploys with its own AgentCoreExecutionRole. The IAM permissions are defined independently per agent.

What this means in practice

Each agent's IAM permissions are scoped independently. The platform enforces containment at the workspace and job boundary (via per-instance tokens), while you control resource-level access through each agent's execution role.

This means:

You scope each agent's execution role to its specific needs - orchestrators and subagents don't share a single permission set
The platform prevents lateral movement across workspaces and jobs regardless of how roles are configured
The platform's baseline role has no access to your resources. You add only the permissions each agent's tools require. Workspace isolation is the platform's.

Builder implication: The platform's baseline execution role has no access to your resources by default. You add only the permissions each agent's tools require. The platform ensures agents cannot escape their workspace/job boundary, but does not automatically enforce least-privilege inheritance across the orchestrator-subagent hierarchy.

Recommendations for multi-agent security

Add only the permissions each subagent needs - don't reuse a broader role from another agent
Make orchestrators narrow - orchestrators that only dispatch work need minimal IAM (invoke Bedrock, call the platform API)
Make subagents task-specific - a "read config" subagent should have read-only S3 access, not s3:*
Rely on workspace isolation for tenant separation, and IAM for resource-level access control

Layer 6: Human-in-the-Loop Controls

Provided by: AWS Transform

For high-risk operations, agents can pause and request human approval via the HITL framework:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Create a HITL task that pauses execution (pseudocode - actual MCP tool is create_autoform_hitl_task)
hitl_task = create_autoform_hitl_task(
    step_id=step_id,
    title="Approve CloudFormation Deployment",
    description="The agent wants to deploy stack 'prod-vpc'. Review and approve.",
    fields=[
        {"name": "approved", "type": "boolean", "label": "Approve this deployment?"}
    ]
)

# Agent blocks here until human responds
response = poll_hitl_response(hitl_task.task_id)
if not response.get("approved"):
    raise AbortError("Human denied the operation")

Builder decisions:

You choose which operations require HITL gates
A read-only analysis agent might need zero gates
An agent that creates infrastructure should gate destructive operations
The HITL task description has a character limit (keep descriptions concise)

Audit: Every approval/denial is recorded as a task artifact, queryable after the job completes.

Layer 7: Artifact Security

Provided by: AWS Transform

Customer content is handled through the Artifact API:

Stored in S3 with CMK encryption
Access governed by workspace boundaries
Not shared across workspaces or accessible to other agents
Upload/download mediated by the platform API (signed URLs)

Your agent accesses artifacts via the platform API (through the MCP server binary or direct API calls), which handles auth and workspace scoping automatically.

Layer 8: Composability - Using Agents You Didn't Build

Provided by: AWS Transform (registry, workspace isolation) + builder due diligence

AWS Transform is designed for composition. The platform provides first-party agents (VMware migration, mainframe modernization, database conversion) that have been through AWS security review, so you don't rebuild solved problems. Your orchestrator calls them via the A2A protocol.

The security boundaries described in the previous layers apply equally to composed agents. Here's how to compose responsibly.

The platform handles isolation

These guarantees hold regardless of who built the agent:

Workspace isolation. The composed agent receives a token scoped to your workspace and job. It cannot access other tenants, other workspaces, or other jobs.
Per-instance token. The agent gets a fresh authorization token. It cannot reuse yours or escalate to your orchestrator's scope.
Artifact boundaries. The composed agent can only access artifacts within the current workspace context.
Observability. When a composed agent runs in your account (customerConfigurationRequired: true), CloudWatch, X-Ray, and CloudTrail capture its behavior fully.

Note: Your CloudTrail always captures connector-level IAM activity, and you always see artifacts/worklogs written to your workspace. For deeper visibility into a composed agent's internal execution, review the agent's observability documentation or run test jobs and examine the X-Ray traces.

Inspect an agent before composing

Before you compose with an agent, query the registry to understand what it declares. Use list-agents to see all agents available to your account (including first-party AWS Transform agents):

1
2
3
aws atxagentregistryexternal list-agents \
  --endpoint-url <registry-endpoint> \
  --region us-east-1

(Your registry endpoint URL is provided during onboarding with the Agent Builder Toolkit.)

Here's what a first-party AWS Transform agent looks like in the registry (the VMware Migration agent):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "name": "vmware-migration-agent-v2",
    "type": "ORCHESTRATOR_AGENT",
    "ownerType": "INTERNAL_AGENT",
    "ownerName": "VMWARE",
    "description": "Orchestrator agent for VMware migration",
    "accountAccess": "ENABLED",
    "customerConfigurationRequired": false,
    "customerConfiguredAgentDependencies": [],
    "visibility": "PUBLIC",
    "jobOrchestrator": true,
    "jobOrchestratorMetadata": {
        "chatUILabel": "VMware Migration",
        "chatAgentIdentifier": "VMware Migration",
        "a2aSupported": true
    },
    "deprecated": false
}

Key fields to evaluate:

Field	What it tells you
`ownerType`	Who built it: `INTERNAL_AGENT` (AWS first-party), `DIRECT_AGENT` (partner/customer), or `MARKETPLACE_AGENT`
`customerConfigurationRequired`	`false` means it runs in the publisher's account. `true` means it deploys into yours.
`customerConfiguredAgentDependencies`	What other agents it calls (transitive composition). Empty here means no declared sub-agents.
`a2aSupported`	Whether it supports the Agent-to-Agent protocol for composition
`visibility`	`PUBLIC` (discoverable by all allowlisted accounts) or `RESTRICTED` (orchestrator-invoked only)

Practical guidance for composing securely

Review the agentCard before composing. Check Agent Connectors - what resources does it request? If a code analysis agent declares an S3 connector, understand what bucket access it's getting.
Understand the customerConfigurationRequired trade-off. When false, the agent runs in the publisher's account - resources in the account your agent operates in are only exposed through explicit connectors, limiting blast radius. But you also have less visibility into the agent's IAM permissions. When true, the agent deploys into your account - you own the IAM role and can inspect it, but you're responsible for scoping it correctly.
Check transitive dependencies. If the agent you're calling itself calls other agents (customerConfiguredAgentDependencies), understand the full chain.
Use observability after composition. CloudTrail shows what IAM calls were made. If the agent runs in your account, its CloudWatch Logs capture execution details. Review these during testing.
First-party AWS Transform agents go through AWS security review. This is the same trust model as any managed AWS service - you trust that S3 doesn't read your data, that Lambda doesn't exfiltrate your function code. First-party agents carry that same relationship. Third-party marketplace agents will have their own security review processes.

Layer 9: Observability and Audit

Provided by: Amazon Bedrock AgentCore + standard AWS services

None of the above matters if you can't verify it at runtime.

Signal	What it shows	How to access
CloudWatch Logs	Full execution traces per agent run	Log group auto-created by AgentCore
AWS X-Ray	Distributed tracing across agent, platform, and connector calls	Enabled via `xray:PutTraceSegments` permission
CloudTrail	IAM role assumptions, API calls	Standard account-level trail
Job artifacts	Agent decision history, HITL approvals	AWS Transform webapp or platform API

Builder recommendation: Enable X-Ray tracing in your execution role and verify traces flow end-to-end during testing. Security teams will ask for these traces during review.

Security review checklist

Whether your own security team is reviewing an agent deployed in your account, or a customer's security team is evaluating an agent you built for them:

IAM policy documents - The policies attached to AgentCoreExecutionRole and AWSTransformAgentInvokeRole
Trust policies - Only bedrock-agentcore.amazonaws.com can assume the execution role
Tool manifest - The agentCard.capabilities.extensions array in your published version
Connector configuration - Which resources are accessible and under what conditions
HITL policy - Which operations require human approval (document this in your agent's README)
Composed agent dependencies - List all agents your orchestrator invokes, their ownerType, customerConfigurationRequired setting, and what connectors they access
Observability - CloudWatch log group, X-Ray service map, CloudTrail events

Get started

Inspect your execution role. Run aws iam list-attached-role-policies --role-name AgentCoreExecutionRole and review every policy. That role is your hard security ceiling.
Verify workspace scoping. Check that your agent receives WORKSPACE_ID and AUTHORIZATION_TOKEN at runtime. All platform API calls are gated by these.
Query the registry. Run aws atxagentregistryexternal list-agents to see what agents are available for composition and inspect their declared capabilities.
Review your IAM before you ship. Confirm you've only added the permissions your tools actually need. The baseline starts secure - keep it that way.

The trust model is layered: IAM constrains what your agent can do, workspace tokens prevent lateral movement, and the registry gives you transparency into agents you didn't build. Each layer operates independently - no single failure gives an agent unchecked access.

What's not covered here

This post covers the trust model for agents built and deployed through AWS Transform. Your agent runs on Amazon Bedrock AgentCore, and additional security configurations are available at the AgentCore layer that the AWS Transform Agent Builder Toolkit does not expose directly - including VPC network isolation, PrivateLink private connectivity, and Cedar-based tool authorization. You can apply these to your deployed runtime through the AgentCore CLI or console. See Protecting your data using VPC and AWS PrivateLink and Policy in Amazon Bedrock AgentCore for those capabilities.

Builder Center

AWS Transform agent security: a layered trust model

Rusty Nations

Prerequisites

The trust stack at a glance

Layer 1: IAM Execution Roles

AgentCoreExecutionRole

ATXAgentInvokeRole (AWSTransformAgentInvokeRole)

What this means for your security review

Layer 2: Workspace Isolation

Layer 3: Tool Declaration and IAM as the Real Boundary

Two enforcement layers

How tool registration works

A pragmatic view of tool containment

The recommended enforcement approach

Layer 4: Connector-Mediated Resource Access

Same-account vs. cross-account

Layer 5: Subagent Containment

Architecture

Two containment mechanisms

What this means in practice

Recommendations for multi-agent security

Layer 6: Human-in-the-Loop Controls

Layer 7: Artifact Security

Layer 8: Composability - Using Agents You Didn't Build

The platform handles isolation

Inspect an agent before composing

Practical guidance for composing securely

Layer 9: Observability and Audit

Security review checklist

Get started

What's not covered here

Further reading