agents-harden

What this skill does

# 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`](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:**

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

**Recommended production Bedrock policy:**

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`](../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:**

```bash
# 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`:

```json
{
  "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:

```bash
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:**

```bash
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.

```bash
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:

- The runtime is configured for `AWS_IAM` (or no authorizer) but the caller is sending a Bearer token → reconfigure the