Agents Harden

harden

Prepare your AgentCore agent for production — security, reliability, and performance.

When to use

• You're about to take an agent to production
• You want a checklist of what to review before launch
• You want to restrict who can call your agent
• You want to scope down IAM permissions from the defaults
• You're hitting throttling or quota errors (loads `references/limits.md`)
• You need to tune session lifecycle for your workload
• You're running long-running background work in your agent

Input

No arguments required. The skill reads your project config and produces a checklist with specific findings for your project.

Process

Step 0: Verify CLI version

Run agentcore --version. This skill requires v0.9.0 or later. If the version is older, tell the developer to run agentcore update before proceeding.

Step 1: Read the project

Read agentcore/agentcore.json to understand:

• What resources are configured (memory, gateway, credentials, evaluators)
• What framework is being used
• What network mode is configured (PUBLIC or VPC)

Step 2: Run through the checklist

Work through each category and report findings specific to the project.

IAM: Scope down permissions

The auto-created execution role has broad Bedrock access (arn:aws:bedrock:*::foundation-model/*). For production, scope it to the specific models your agent uses.

Check the current execution role:

agentcore status --json | jq -r '.runtimes[0].executionRoleArn'

Recommended production Bedrock policy:

{
  "Effect": "Allow",
  "Action": [
    "bedrock:InvokeModel",
    "bedrock:InvokeModelWithResponseStream"
  ],
  "Resource": [
    "arn:aws:bedrock:<REGION>::foundation-model/anthropic.claude-sonnet-4-5-20250929-v1:0"
  ]
}

Replace the resource ARN with the specific model(s) your agent uses.

ECR access: Scope to your specific repository:

{
  "Effect": "Allow",
  "Action": ["ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer"],
  "Resource": "arn:aws:ecr:<REGION>:<YOUR_ACCOUNT_ID>:repository/bedrock-agentcore-<AGENT_NAME>-*"
}

Trust policy: Verify the execution role's trust policy is scoped to your account:

{
  "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
  "Action": "sts:AssumeRole",
  "Condition": {
    "StringEquals": {"aws:SourceAccount": "<YOUR_ACCOUNT_ID>"},
    "ArnLike": {"aws:SourceArn": "arn:aws:bedrock-agentcore:<REGION>:<YOUR_ACCOUNT_ID>:*"}
  }
}

Runtime resource-based policies (API-only): For fine-grained control over which principals can invoke your runtime — beyond what IAM roles and JWT auth provide — use PutAgentRuntimeResourcePolicy via boto3. This is not exposed in the CLI or agentcore.json. Use the awsknowledge MCP server if available to look up the current API shape.

Shell Access: Scope InvokeAgentRuntimeCommand separately

If your project uses InvokeAgentRuntimeCommand (see `agents-build/references/integrate.md`), audit its IAM permissions separately from InvokeAgentRuntime. The two actions have different blast radii: InvokeAgentRuntimeCommand is arbitrary shell execution inside a live microVM with the runtime's full execution role — callers can read/write the filesystem, reach any network resource the agent can reach, and access the execution role's credentials.

Check which principals have the permission:

# List customer-managed policies in your account, then inspect each for InvokeAgentRuntimeCommand
aws iam list-policies --scope Local \
  --query 'Policies[*].[PolicyName, Arn, DefaultVersionId]' \
  --output table
# Then for each policy of interest:
aws iam get-policy-version \
  --policy-arn <POLICY_ARN> \
  --version-id <VERSION_ID> \
  --query 'PolicyVersion.Document'

Alternatively, use the IAM console: IAM → Policies → Filter by type: Customer managed → search for InvokeAgentRuntimeCommand in the policy JSON editor.

Separate IAM policy for command callers — keep this distinct from the policy granting InvokeAgentRuntime:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": "bedrock-agentcore:InvokeAgentRuntimeCommand",
    "Resource": "arn:aws:bedrock-agentcore:<REGION>:<YOUR_ACCOUNT_ID>:runtime/<RUNTIME_NAME>-*"
  }]
}

Enable CloudTrail alerting. Create an EventBridge rule to notify your security team when InvokeAgentRuntimeCommand is called:

aws events put-rule \
  --name AgentCoreCommandExecution \
  --event-pattern '{"source":["aws.bedrock-agentcore"],"detail-type":["AWS API Call via CloudTrail"],"detail":{"eventName":["InvokeAgentRuntimeCommand"]}}' \
  --state ENABLED

If commands are constructed from user input anywhere in calling code: validate before passing — reject strings containing &&, ;, $(...), backticks, |, or other shell metacharacters.

Inbound auth: Control who can call your agent

By default, agents use AWS IAM (SigV4) for inbound auth. For production, verify this is configured correctly.

Check current auth config:

agentcore status --runtime <AgentName> --json | jq '.runtimes[0].authorizerConfig'

Options:

AWS_IAM (default) — callers must sign requests with SigV4. Good for internal services and AWS-native clients.

CUSTOM_JWT — callers present a JWT from your identity provider. Good for web/mobile apps and external clients.

agentcore add agent \
  --name MyAgent \
  --authorizer-type CUSTOM_JWT \
  --discovery-url https://your-idp.example.com/.well-known/openid-configuration \
  --allowed-audience my-api \
  --allowed-clients my-client-id

[!WARNING] Never use --authorizer-type NONE in production. It allows unauthenticated access to your agent — anyone with the endpoint URL can invoke it. Always use AWS_IAM or CUSTOM_JWT. If you see NONE in production, change it immediately.

Choosing allowedClients vs allowedAudience

This is the most common JWT misconfiguration. The right choice depends on what's inside the token your IdP issues.

Decode a sample token (at your IdP or with jwt.io) and look at the payload:

• Token has a client_id claim, no aud claim → configure `allowedClients` on the runtime
• Token has an aud claim → configure `allowedAudience` on the runtime
• Token has both → use allowedAudience. The aud claim is the standard OIDC audience field; use that as the primary check.

If you pick the wrong one, invocations return 403 even with a valid token — the runtime is validating against a claim the token doesn't have.

Issuer ↔ discovery URL prefix requirement

AgentCore enforces the OIDC discovery spec (RFC 8414 §3): the issuer value in the discovery document must be a URL prefix of the discovery endpoint.

That means if your discovery URL is https://qa.example.com/.well-known/openid-configuration, the issuer field in that document must start with https://qa.example.com. If the document advertises an issuer like https://example.com (no subdomain), validation fails.

Some enterprise IdPs (PingFederate, Paylocity, some Keycloak setups) host the discovery endpoint on an environment-specific subdomain while advertising a production-level issuer. This pattern is incompatible with the RFC 8414 prefix rule.

Fix options:

1. Align the IdP's discovery endpoint with its issuer — serve discovery from the same origin as the issuer.
2. Point the runtime at the actual discovery URL domain — configure the runtime's discovery URL with the subdomain that matches the token's issuer.

Debugging JWT auth failures

When invocations fail with 403, narrow down which check is failing.

`Authorization method mismatch` — the runtime's auth type and the request's auth type don't match. Two cases: