# Validate and test policies
<a name="policy-validate-policies"></a>

Before deploying policies to production, Policy in AgentCore provides validation and analysis capabilities to catch errors and identify potential issues. Validation and analysis work differently depending on whether you are generating policies from natural language or creating and updating policies directly.

**Topics**
+ [

# Validation and analysis overview
](policy-validation-overview.md)
+ [

# Policy generation: per-policy validation
](policy-generation-validation.md)
+ [

# Policy create and update: per-policy engine validation
](policy-create-update-validation.md)

# Validation and analysis overview
<a name="policy-validation-overview"></a>

## Cedar validation (static analysis)
<a name="policy-cedar-validation"></a>

Cedar validation performs static analysis to ensure policies are syntactically correct and comply with the schema:
+  **Syntax correctness** — Verifies Cedar policy language syntax
+  **Schema compliance** — Checks that policies reference valid actions (tools), use correct data types, and access only defined context fields
+  **Type safety** — Ensures parameter types match the gateway’s tool definitions

## Cedar analysis (automated reasoning)
<a name="policy-cedar-analysis"></a>

Cedar analysis uses automated reasoning to detect potential security and logic issues:
+  **Overly permissive policies** — If created, the policy engine will allow all requests for the specified principal, action, and resource combination
+  **Overly restrictive policies** — If created, the policy engine will deny all requests for the specified principal, action, and resource combination
+  **Ineffective policies** — If created, the policy has no impact: a Permit policy does not allow any requests, or a Forbid policy does not deny any requests. This applies at the policy level during generation, not at the policy engine level

# Policy generation: per-policy validation
<a name="policy-generation-validation"></a>

When using the policy authoring service to generate policies from natural language, validation and analysis occur **per individual policy** during generation.

## How it works
<a name="policy-generation-validation-how"></a>

1. Natural language is converted to a Cedar policy

1. Each generated policy is validated against the gateway schema

1. Analysis runs on each policy individually

1. Results are available in the generation response

## Example: Generate and validate a policy
<a name="policy-generation-validation-example"></a>

Retrieving generation results is a two-step process: first check the generation status, then list the generated assets to see the policies and their validation findings.

Start a policy generation:

```
aws bedrock-agentcore-control start-policy-generation \
  --policy-engine-id MyEngine-abc123 \
  --name RefundPolicy \
  --content '{
    "rawText": "Allow customer service agents to process refunds up to 500 dollars for orders placed within the last 30 days"
  }' \
  --resource '{
    "arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/MyGateway-xyz789"
  }'
```

The response includes a policy generation ID and status:

```
{
  "policyGenerationId": "RefundPolicy-def456",
  "policyEngineId": "MyEngine-abc123",
  "status": "GENERATING"
}
```

Check the generation status using `get-policy-generation` :

```
aws bedrock-agentcore-control get-policy-generation \
  --policy-engine-id MyEngine-abc123 \
  --policy-generation-id RefundPolicy-def456
```

The response shows the overall generation status:

```
{
  "policyGenerationId": "RefundPolicy-def456",
  "status": "GENERATED",
  "statusReasons": []
}
```

Once the status is `GENERATED` , list the generated assets to retrieve the policies and their per-policy validation findings:

```
aws bedrock-agentcore-control list-policy-generation-assets \
  --policy-engine-id MyEngine-abc123 \
  --policy-generation-id RefundPolicy-def456
```

The response includes each generated policy with its Cedar definition and validation findings:

```
{
  "policyGenerationAssets": [
    {
      "policyGenerationAssetId": "asset-1",
      "definition": {
        "cedar": {
          "statement": "permit(\n  principal is AgentCore::OAuthUser,\n  action == AgentCore::Action::\"RefundTool__process_refund\",\n  resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/MyGateway-xyz789\"\n) when {\n  context.input.amount <= 500\n};"
        }
      },
      "findings": [
        {
          "type": "VALID"
        }
      ],
      "rawTextFragment": "Allow customer service agents to process refunds up to 500 dollars"
    },
    {
      "policyGenerationAssetId": "asset-2",
      "definition": {
        "cedar": {
          "statement": "permit(\n  principal,\n  action == AgentCore::Action::\"RefundTool__view_order_history\",\n  resource\n);"
        }
      },
      "findings": [
        {
          "type": "ALLOW_ALL",
          "description": "Overly Permissive: Policy Engine will allow every request for the specified principal (AgentCore::OAuthUser), action (RefundTool__view_order_history) and resource (gateway/*) combination if the policy is added or updated"
        }
      ],
      "rawTextFragment": "Allow customer service agents to view order history"
    }
  ]
}
```

## Validation findings per policy
<a name="policy-generation-findings"></a>

Each generated policy asset includes a `findings` array of `Finding` objects, each with a `type` and `description` . The following examples show different finding types:

A policy that passed validation and analysis:

```
{
  "findings": [
    {
      "type": "VALID"
    }
  ]
}
```

A policy flagged as overly permissive:

```
{
  "findings": [
    {
      "type": "ALLOW_ALL",
      "description": "Overly Permissive: Policy Engine will allow every request for the specified principal (AgentCore::OAuthUser), action (RefundTool__view_order_history) and resource (gateway/*) combination if the policy is added or updated"
    }
  ]
}
```

A policy that could not be generated from the natural language input:

```
{
  "findings": [
    {
      "type": "NOT_TRANSLATABLE",
      "description": "Unsupported Condition Error: The request includes conditions that rely on data or attributes currently not supported."
    }
  ]
}
```

## Common findings for generated policies
<a name="policy-common-findings"></a>

The following table describes the finding types that can be returned for generated policies:


| Finding type | Severity | Description | Recommended action | 
| --- | --- | --- | --- | 
|   `VALID`   |  Success  |  Policy is valid Cedar with no findings. No description is returned for this finding type.  |  No action required. The policy is ready to use.  | 
|   `INVALID`   |  Error  |  The generated Cedar policy contains syntax errors or does not comply with the gateway schema.  |  Review the generated policy for schema violations or syntax issues. Rephrase the natural language input and regenerate.  | 
|   `NOT_TRANSLATABLE`   |  Error  |  Natural language could not be converted to valid Cedar. The request may include conditions that rely on unsupported data or attributes.  |  Double check targeted gateway resource for tools definition.  | 
|   `ALLOW_ALL`   |  Warning  |  Permit policy applies to all principal, action, and resource combinations.  |  Confirm that unrestricted access is intended. Add conditions to restrict the scope if not.  | 
|   `ALLOW_NONE`   |  Warning  |  Permit policy is non-determining because it permits nothing.  |  Review the policy conditions. The policy may contain contradictory or unreachable conditions.  | 
|   `DENY_ALL`   |  Warning  |  Policy denies all actions for all principals.  |  Confirm that a full deny is intended. This overrides all permit policies due to forbid-overrides-permit semantics.  | 
|   `DENY_NONE`   |  Warning  |  Forbid policy is non-determining because it denies nothing.  |  Review the policy conditions. The forbid policy may contain contradictory or unreachable conditions.  | 

# Policy create and update: per-policy engine validation
<a name="policy-create-update-validation"></a>

When creating or updating policies directly (not through generation), validation and analysis takes into account the new policy as well as its interactions with **all preexisting policies** in the policy engine.

## How it works
<a name="policy-create-update-validation-how"></a>

1. The policy is validated against the Cedar schema for **all gateways** associated with the policy engine

1. Analysis runs in the context of the **entire policy engine** 

1. The validation mode determines whether creation fails on findings. For more information about validation modes, see [Add policies to the Policy Engine](add-policies-to-engine.md) 

## Example: Create a policy with validation
<a name="policy-create-validation-example"></a>

Create a policy with strict validation that rejects policies with any findings:

```
aws bedrock-agentcore-control create-policy \
  --policy-engine-id MyEngine-abc123 \
  --name RestrictRefunds \
  --validation-mode FAIL_ON_ANY_FINDINGS \
  --definition '{
    "cedar": {
      "statement": "forbid(\n  principal,\n  action == Action::\"processRefund\",\n  resource\n) when {\n  context.amount > 1000\n};"
    }
  }'
```

The response indicates the policy is being created:

```
{
  "policyId": "RestrictRefunds-ghi789",
  "status": "CREATING"
}
```

Check the policy status to confirm validation passed:

```
aws bedrock-agentcore-control get-policy \
  --policy-engine-id MyEngine-abc123 \
  --policy-id RestrictRefunds-ghi789
```

When validation passes, the policy becomes active:

```
{
  "policyId": "RestrictRefunds-ghi789",
  "status": "ACTIVE",
  "statusReasons": []
}
```

## Example: Validation failure
<a name="policy-validation-failure-example"></a>

If a policy references an action that doesn’t exist in any associated gateway’s schema, validation fails:

```
aws bedrock-agentcore-control create-policy \
  --policy-engine-id MyEngine-abc123 \
  --name InvalidPolicy \
  --validation-mode FAIL_ON_ANY_FINDINGS \
  --definition '{
    "cedar": {
      "statement": "permit(\n  principal,\n  action == Action::\"nonExistentTool\",\n  resource\n);"
    }
  }'
```

When you check the policy status, the response shows the validation failure:

```
aws bedrock-agentcore-control get-policy \
  --policy-engine-id MyEngine-abc123 \
  --policy-id InvalidPolicy-jkl012
```

```
{
  "policyId": "InvalidPolicy-jkl012",
  "status": "CREATE_FAILED",
  "statusReasons": [
    "Validation failed: Action 'nonExistentTool' is not defined in the schema for any associated gateway"
  ]
}
```