Skip to content

CATS Configuration

The cats.yaml schema, as Pydantic models. Only the models below are stable configuration surface; loader internals are not part of the public API.

CatsConfig pydantic-model

Bases: BaseSettings, CatsBaseModel

This class defines all CATS config management and ultimately the contents of cats.yaml - each subclass attribute defines a yaml key and section.

See each subclass for greater detail.

Show JSON schema:
{
  "$defs": {
    "AccountSettings": {
      "additionalProperties": false,
      "description": "Account settings for CATS.\n\nUsed at global and account levels. Fields have sensible defaults.\n\nAttributes:\n    additional_roles: Additional IAM roles to create, keyed by role name and accessible as AccountUnderTest.role.<name>\n    default_test_role_managed_policies: A list of AWS managed IAM policy names to attach to the default test role.\n    default_test_role_inline_policies: Inline IAM policies to attach to the default test role, keyed by\n        policy name. Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.\n    fixture_scope: Pytest fixture scope for account fixtures\n    allow_shell: Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command.\n        Off by default. This is a deploy-time setting: when true, the test role's SSM policy includes the\n        run-command document. Changing it requires redeployment. See docs/security.md for implications.",
      "properties": {
        "additional_roles": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z][A-Za-z0-9_]*$": {
              "$ref": "#/$defs/CatsAdditionalTestRole"
            }
          },
          "propertyNames": {
            "not": {
              "enum": [
                "False",
                "None",
                "True",
                "and",
                "as",
                "assert",
                "async",
                "await",
                "break",
                "class",
                "continue",
                "def",
                "default",
                "del",
                "elif",
                "else",
                "except",
                "finally",
                "for",
                "from",
                "global",
                "if",
                "import",
                "in",
                "is",
                "lambda",
                "nonlocal",
                "not",
                "or",
                "pass",
                "raise",
                "return",
                "try",
                "while",
                "with",
                "yield"
              ]
            },
            "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
          },
          "title": "Additional Roles",
          "type": "object"
        },
        "default_test_role_managed_policies": {
          "default": [],
          "description": "Additional permissions to grant CATS in each AccountUnderTest. Adds listed Managed Policies by name or ARN.",
          "items": {
            "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
            "type": "string"
          },
          "title": "Default Test Role Managed Policies",
          "type": "array",
          "uniqueItems": true
        },
        "default_test_role_inline_policies": {
          "default": {},
          "description": "Inline IAM policies for the default test role, keyed by policy name. Values are policy documents, or string paths to JSON files relative to cats.yaml.",
          "patternProperties": {
            "^[A-Za-z0-9+=,.@_-]+$": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "required": [
                    "Statement"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9+=,.@_-]+$"
          },
          "title": "Default Test Role Inline Policies",
          "type": "object"
        },
        "fixture_scope": {
          "default": "session",
          "description": "Pytest fixture scope for account fixtures",
          "enum": [
            "session",
            "function",
            "module",
            "class"
          ],
          "title": "Fixture Scope",
          "type": "string"
        },
        "allow_shell": {
          "default": false,
          "description": "Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command. Deploy-time setting.",
          "title": "Allow Shell",
          "type": "boolean"
        }
      },
      "title": "AccountSettings",
      "type": "object"
    },
    "CatsAccountUnderTest": {
      "additionalProperties": false,
      "description": "One target account to configure specific test resources and tag with metadata.\n\nThe key name in cats.yaml defines the name of the generated AccountUnderTest\nresource within CATS test code.\n\nAttributes:\n    account_id: 12-digit AWS account ID string (required) of target account\n    account_name: Optional metadata on an account friendlyname\n    account_email: Optional metadata on an account email\n    notes: Optional metadata for general notes in your yaml file\n    account_network_under_test: A key/value dictionary of network test targets in this account, where each entry\n        will have network infrastructure deployed and made available on the AccountUnderTest class resource.\n        The number of targets an account can hold is bounded by CloudFormation's 51,200-byte template limit,\n        which `cats validate` measures for the exact configuration (targets, handlers and listen ports all\n        count); split targets across a second account entry with the same account_id when it says so.\n    tags: Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}\n    network_settings: Per-account network settings override. Overrides global, overridden by target.\n    account_settings: Per-account settings override. Overrides global_account_settings.",
      "properties": {
        "account_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Account Name"
        },
        "account_email": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Account Email"
        },
        "notes": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Notes"
        },
        "account_id": {
          "pattern": "^[0-9]{12}$",
          "title": "Account Id",
          "type": "string"
        },
        "account_network_under_test": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z][A-Za-z0-9]*$": {
              "$ref": "#/$defs/CatsNetworkUnderTest"
            }
          },
          "propertyNames": {
            "maxLength": 15,
            "not": {
              "enum": [
                "False",
                "None",
                "True",
                "and",
                "as",
                "assert",
                "async",
                "await",
                "break",
                "class",
                "continue",
                "def",
                "del",
                "elif",
                "else",
                "except",
                "finally",
                "for",
                "from",
                "global",
                "if",
                "import",
                "in",
                "is",
                "lambda",
                "name",
                "nonlocal",
                "not",
                "or",
                "partition",
                "pass",
                "raise",
                "return",
                "role",
                "session",
                "tags",
                "try",
                "while",
                "with",
                "yield"
              ]
            },
            "pattern": "^[A-Za-z][A-Za-z0-9]*$"
          },
          "title": "Account Network Under Test",
          "type": "object"
        },
        "tags": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": "object"
            },
            {
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            }
          ],
          "default": {},
          "title": "Tags"
        },
        "network_settings": {
          "$ref": "#/$defs/NetworkSettings",
          "default": {
            "enabled_network_handlers": [
              "ec2"
            ],
            "interface_endpoints": [],
            "gateway_endpoints": [],
            "interface_endpoint_security_group_ids": null,
            "udp_listen_ports": [],
            "tcp_listen_ports": [],
            "ec2_instance_type": "t3.micro",
            "existing_ec2_instance_profile_name": null,
            "existing_ec2_ami_id": null,
            "network_call_timeout_seconds": 30
          }
        },
        "account_settings": {
          "$ref": "#/$defs/AccountSettings",
          "default": {
            "additional_roles": {},
            "default_test_role_managed_policies": [],
            "default_test_role_inline_policies": {},
            "fixture_scope": "session",
            "allow_shell": false
          }
        }
      },
      "required": [
        "account_id"
      ],
      "title": "CatsAccountUnderTest",
      "type": "object"
    },
    "CatsAdditionalTestRole": {
      "additionalProperties": false,
      "anyOf": [
        {
          "properties": {
            "managed_policies": {
              "minItems": 1
            }
          },
          "required": [
            "managed_policies"
          ]
        },
        {
          "properties": {
            "inline_policies": {
              "minProperties": 1
            }
          },
          "required": [
            "inline_policies"
          ]
        }
      ],
      "description": "CATS deploys one role by default: this configuration block allows defining additional roles.\n\nEach entry of `additional_roles` is keyed by the role's name: `account.role.<name>` returns a session\nfor it, and the deployed IAM role is named {cfn_stack_prefix}{account_keyname}-<name>. A role\ndeclares at least one of `managed_policies` and `inline_policies`.\n\nAttributes:\n    managed_policies: A list of AWS managed IAM policy names or full policy ARNs to attach to this role.\n        Full list available at https://docs.aws.amazon.com/aws-managed-policy/latest/reference/policy-list.html\n    inline_policies: Inline IAM policies to attach to this role, keyed by policy name.\n        Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.",
      "properties": {
        "managed_policies": {
          "default": [],
          "items": {
            "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
            "type": "string"
          },
          "title": "Managed Policies",
          "type": "array",
          "uniqueItems": true
        },
        "inline_policies": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z0-9+=,.@_-]+$": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "required": [
                    "Statement"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9+=,.@_-]+$"
          },
          "title": "Inline Policies",
          "type": "object"
        }
      },
      "title": "CatsAdditionalTestRole",
      "type": "object"
    },
    "CatsDeploymentSettings": {
      "additionalProperties": false,
      "allOf": [
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-cn"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^cn\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-us-gov"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-iso"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-iso-b"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-iso-e"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-iso-f"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "partition": {
                "const": "aws-eusc"
              }
            },
            "required": [
              "partition"
            ]
          },
          "then": {
            "properties": {
              "aws_region": {
                "anyOf": [
                  {
                    "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                  },
                  {
                    "not": {
                      "anyOf": [
                        {
                          "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^cn\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                        },
                        {
                          "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "description": "Settings for CATS infrastructure deployment. These settings are used when calling\n'cats infra' commands.\n\nAttributes:\n    deploy_role_name: When deploying from a central account, role to use in all target accounts - for example, AWSControlTowerExecution.\n        An IAM role name (not an ARN or a path): interpolated into arn:{partition}:iam::{account_id}:role/{deploy_role_name}.\n    allow_deploy_to_current_account: Allow deploying to the starting account, with current role\n    parent_account_id: 12-digit AWS account ID that test roles will trust (the account running CATS).\n        Required by deploy and show-template; validation and config loading work without it.\n    aws_region: Region CATS deploys its stacks into and connects its test sessions to. Falls back to the\n        AWS_REGION environment variable when unset. Required by deploy, show-template, test-time session\n        construction and `cats run`; validation and config loading work without it.\n    partition: AWS partition. Derived from aws_region when unset (us-gov-west-1 gives aws-us-gov, cn-north-1\n        gives aws-cn, eusc-de-east-1 gives aws-eusc); a Region no partition claims is treated as aws, as\n        botocore does. An explicit value that disagrees with the Region is a configuration error.\n    cfn_stack_prefix: Prefix for all deployed CATS resources. Used to namespace stacks, roles, and parameters.\n        May not start with aws, amazon or amzn (in any case): SSM reserves those for its own document names,\n        and the probe document is named {cfn_stack_prefix}{account}-Probe.",
      "properties": {
        "deploy_role_name": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z0-9+=,.@_-]{1,64}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "IAM role name CATS assumes in each account under test to deploy; interpolated into arn:{partition}:iam::{account_id}:role/{name}.",
          "title": "Deploy Role Name"
        },
        "allow_deploy_to_current_account": {
          "default": false,
          "description": "By default, CATS will not try and deploy infrastructure in the account it begins working in. Set this to True to allow deploying test infrastructure without role assumption in the profile running CATS. For example, set this to deploy tests in an AWS Organizations root account using the credentials you called `cats infra` with.",
          "title": "Allow Deploy To Current Account",
          "type": "boolean"
        },
        "parent_account_id": {
          "anyOf": [
            {
              "pattern": "^[0-9]{12}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Parent Account Id"
        },
        "aws_region": {
          "anyOf": [
            {
              "pattern": "^[a-z]{2}[a-z0-9-]*-[0-9]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Aws Region"
        },
        "partition": {
          "default": "aws",
          "description": "AWS partition. Derived from aws_region when unset; an explicit value must agree with the Region.",
          "enum": [
            "aws",
            "aws-cn",
            "aws-eusc",
            "aws-iso",
            "aws-iso-b",
            "aws-iso-e",
            "aws-iso-f",
            "aws-us-gov"
          ],
          "title": "Partition",
          "type": "string"
        },
        "cfn_stack_prefix": {
          "default": "CATS-test-infra-",
          "maxLength": 64,
          "pattern": "^(?![Aa][Ww][Ss]|[Aa][Mm][Aa][Zz][Oo][Nn]|[Aa][Mm][Zz][Nn])[A-Za-z][A-Za-z0-9-]*$",
          "title": "Cfn Stack Prefix",
          "type": "string"
        }
      },
      "title": "CatsDeploymentSettings",
      "type": "object"
    },
    "CatsNetworkUnderTest": {
      "additionalProperties": false,
      "description": "Target network segment to send and receive network plane data.\n\nThe key name in cats.yaml defines the name of the generated AccountUnderTest\nresource within CATS test code.\n\n``vpc_id``, ``subnet_ids`` and ``existing_security_group_ids`` each take a literal id\n(``vpc-...``, ``subnet-...``, ``sg-...``) or the name of an SSM parameter holding one, which\nmust start with ``/``. The parameter is read in the target account at deploy time.\n\nAttributes:\n    vpc_id: The VPC to work from: a VPC id (vpc-...) or an SSM parameter name (/...) containing one\n    subnet_ids: A list of subnet ids (subnet-...) or SSM parameter names (/...) containing subnet IDs inside target VPC.\n        The EC2 listener deploys into the first subnet; Lambda handlers and interface endpoints use all of them,\n        so list every subnet (e.g. one per AZ) the Lambda probes should reach from.\n    subnet_id: The single-subnet spelling: ``subnet_id: subnet-1`` means ``subnet_ids: [subnet-1]``. Give one\n        or the other, not both. Input only: the loaded model carries ``subnet_ids`` alone, so a dumped\n        configuration re-validates.\n    existing_security_group_ids: Security groups to attach to every resource CATS deploys in this target -\n        the EC2 listener and, when the lambda handler is enabled, the probe Lambda. Accepts security\n        group ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        By default CATS creates its own groups instead: one for the EC2 listener with ingress scoped to the\n        target's tcp_listen_ports and udp_listen_ports, and an egress-only one for the lambdas. Provide your\n        own groups for any other ingress posture (open-all, custom source CIDRs, fully closed), or to speed\n        up `cats infra destroy` with the lambda handler - CloudFormation cannot delete a stack-owned lambda\n        security group until Lambda releases its Hyperplane ENIs, which takes up to ~20 minutes. Groups CATS\n        does not own are never waited on.\n        The groups must allow the traffic your tests need, in both directions. Outbound is the one most\n        likely to bite: the lambda handlers only reach a destination if the groups permit egress to it,\n        and a group with any explicit egress rule no longer allows all outbound traffic. Inbound matters\n        too - reaching an EC2 listener requires access on its tcp_listen_ports and udp_listen_ports.\n        Traffic a group blocks surfaces as a FAILURE result at test time, not a deploy-time error.\n    tags: Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}\n    network_settings: Per-target network settings. Populated with resolved values after config load.",
      "oneOf": [
        {
          "required": [
            "subnet_id"
          ]
        },
        {
          "required": [
            "subnet_ids"
          ]
        }
      ],
      "properties": {
        "vpc_id": {
          "pattern": "^(vpc-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
          "title": "Vpc Id",
          "type": "string"
        },
        "subnet_id": {
          "anyOf": [
            {
              "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Subnet Id"
        },
        "subnet_ids": {
          "default": [],
          "items": {
            "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
            "type": "string"
          },
          "title": "Subnet Ids",
          "type": "array",
          "uniqueItems": true
        },
        "existing_security_group_ids": {
          "anyOf": [
            {
              "items": {
                "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
                "type": "string"
              },
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Existing Security Group Ids"
        },
        "tags": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": "object"
            },
            {
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            }
          ],
          "default": {},
          "title": "Tags"
        },
        "network_settings": {
          "$ref": "#/$defs/NetworkSettings",
          "default": {
            "enabled_network_handlers": [
              "ec2"
            ],
            "interface_endpoints": [],
            "gateway_endpoints": [],
            "interface_endpoint_security_group_ids": null,
            "udp_listen_ports": [],
            "tcp_listen_ports": [],
            "ec2_instance_type": "t3.micro",
            "existing_ec2_instance_profile_name": null,
            "existing_ec2_ami_id": null,
            "network_call_timeout_seconds": 30
          }
        }
      },
      "required": [
        "vpc_id"
      ],
      "title": "CatsNetworkUnderTest",
      "type": "object"
    },
    "CatsReportingSettings": {
      "additionalProperties": false,
      "description": "Settings for CATS reporting while running Pytest tests.\n\nReport writers are dispatched at the end of a pytest session based on\n``report_formats``. Multiple formats can be emitted from a single run \u2014\nsee the Reporting guide for the full output contract and the OSCAL\n``pytest_cats_standards`` hook.\n\nAttributes:\n    enabled: Whether to emit any reports at all. ``False`` disables every\n        writer including ``junit`` and ``securityhub``, and withholds the\n        ``securityhub:BatchImportFindings`` grant from the test role at deploy.\n    report_formats: Writers to run, in order. Each value corresponds to a\n        :class:`ReportFormat` member (``cats_json``, ``oscal_ar``, ``junit``,\n        ``securityhub``). Defaults to ``[cats_json]``; at least one is required\n        (to write nothing, set ``enabled`` to false). List ``securityhub`` last: the\n        import is network-bound and the files before it never wait on it.\n    custom_markers: Marker names permitted in ``@cats(...)`` kwargs. Values\n        surface in both the CATS JSON and OSCAL outputs (as top-level keys\n        and ``Observation.props[]`` respectively).\n    oscal_import_ap_href: URI reference recorded as ``import-ap.href`` in the\n        OSCAL assessment results \u2014 point it at your assessment plan document.\n        Defaults to an empty reference.\n    securityhub: Region and severity for the ``securityhub`` format; see\n        :class:`CatsSecurityHubSettings`. Ignored unless ``securityhub`` is in\n        ``report_formats``.\n    report_dir: Directory for every report file (``report.json``,\n        ``assessment-results.json``, ``junit.xml``, ``securityhub-findings.json``\n        and their timestamped variants). A relative path resolves against the\n        directory that holds ``cats.yaml``, like ``inline_policies`` file paths.\n        ``--cats-report-dir`` on the pytest command line overrides it. Unset\n        means the current working directory.\n    latest_files: Write the fixed-name files (``report.json``,\n        ``assessment-results.json``, ``junit.xml``, ``securityhub-findings.json``),\n        overwritten on every run so they always describe the newest run.\n    timestamped_files: Also write one immutable set per run, named with the\n        run id: ``report-<run_id>.json``, ``assessment-results-<run_id>.json``,\n        ``junit-<run_id>.xml``, ``securityhub-findings-<run_id>.json``. The run id is\n        ``YYYYMMDDTHHMMSSZ`` (UTC) and is also recorded inside every file, so the\n        files of one run can be matched. A run that writes timestamped files claims\n        its id when the session starts, so two sessions starting in the same second\n        never share one. With ``latest_files`` and ``timestamped_files`` both ``false``\n        no report file is written at all; ``securityhub`` still imports its findings.\n        ``enabled: false`` is the switch that disables every writer.",
      "properties": {
        "enabled": {
          "default": true,
          "title": "Enabled",
          "type": "boolean"
        },
        "report_formats": {
          "default": [
            "cats_json"
          ],
          "items": {
            "$ref": "#/$defs/ReportFormat"
          },
          "minItems": 1,
          "title": "Report Formats",
          "type": "array",
          "uniqueItems": true
        },
        "custom_markers": {
          "default": [],
          "items": {
            "not": {
              "enum": [
                "control_group",
                "control_ids",
                "filterwarnings",
                "parametrize",
                "skip",
                "skipif",
                "standard_name",
                "usefixtures",
                "xfail"
              ]
            },
            "pattern": "^(?!cats_)[A-Za-z_][A-Za-z0-9_]*$",
            "type": "string"
          },
          "title": "Custom Markers",
          "type": "array",
          "uniqueItems": true
        },
        "oscal_import_ap_href": {
          "default": "",
          "title": "Oscal Import Ap Href",
          "type": "string"
        },
        "securityhub": {
          "$ref": "#/$defs/CatsSecurityHubSettings",
          "default": {
            "aws_region": null,
            "failed_severity": "HIGH",
            "only_with_standard": true
          }
        },
        "report_dir": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Report Dir"
        },
        "latest_files": {
          "default": true,
          "title": "Latest Files",
          "type": "boolean"
        },
        "timestamped_files": {
          "default": false,
          "title": "Timestamped Files",
          "type": "boolean"
        }
      },
      "title": "CatsReportingSettings",
      "type": "object"
    },
    "CatsSecurityHubSettings": {
      "additionalProperties": false,
      "description": "Settings for the ``securityhub`` report format.\n\nAttributes:\n    aws_region: Region whose Security Hub receives the findings, the same in every account under\n        test. Defaults to ``cats_deployment_settings.aws_region``. The test role's import grant\n        is scoped to this Region's product ARN, so changing it requires ``cats infra deploy``.\n    failed_severity: ``Severity.Label`` of the finding for a failed test. Defaults to ``HIGH``:\n        a control that does not enforce. Errors are ``MEDIUM``, expected failures ``LOW``,\n        passes and skips ``INFORMATIONAL``.\n    only_with_standard: Import findings only for tests that carry a standard (``@cats(standard_name=...)``),\n        the default: a compliance finding needs a control to attest to, and ``report.json`` still records\n        every test. ``false`` imports every test that used an account fixture, typed ``CATS`` when it\n        carries no standard. Removing ``@cats`` from a test stops updating its finding, which stays\n        ``ACTIVE`` in Security Hub for 90 days.",
      "properties": {
        "aws_region": {
          "anyOf": [
            {
              "pattern": "^[a-z]{2}[a-z0-9-]*-[0-9]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Region whose Security Hub receives the findings. Defaults to cats_deployment_settings.aws_region.",
          "title": "Aws Region"
        },
        "failed_severity": {
          "$ref": "#/$defs/SecurityHubSeverity",
          "default": "HIGH",
          "description": "Severity label of the finding for a failed test."
        },
        "only_with_standard": {
          "default": true,
          "description": "Import findings only for tests that carry a standard. false imports every test that used an account fixture.",
          "title": "Only With Standard",
          "type": "boolean"
        }
      },
      "title": "CatsSecurityHubSettings",
      "type": "object"
    },
    "CatsTestSelectionSettings": {
      "additionalProperties": false,
      "description": "Which tests run against this deployment, decided in configuration rather than on the command line.\n\nA command-line selector (``-k``, ``-m``, ``--deselect``) narrows a run, and a deselected control\nvanishes from the report with no record of why. These keys instead define the run's scope in\nthe configuration itself, and every test they hold back is recorded as ``not_run`` with its\nreason, in every report format.\n\nAttributes:\n    provides: The requirements this deployment satisfies: free-form names matching\n        ``@cats_requires(...)`` on tests. A test runs only when every requirement it declares is\n        provided; otherwise it is ``not_run`` with the gap named. Unioned with what every\n        ``pytest_cats_provides`` hook returns, so a test pack can provide its defaults.\n    excluded: Tests held back by marker value, each with a reason (see\n        :class:`TestSelectionExclusion`). A test matching any entry is ``not_run``. An entry that\n        matches no test is reported in the terminal summary and in ``run.selection``: not an\n        error, since a ``-k`` run or a renamed test produces it, but usually a sign that the\n        exclusion is not doing what was intended.",
      "properties": {
        "provides": {
          "default": [],
          "description": "Requirements this deployment satisfies; a test requiring one not listed here is not run.",
          "items": {
            "minLength": 1,
            "type": "string"
          },
          "title": "Provides",
          "type": "array",
          "uniqueItems": true
        },
        "excluded": {
          "default": [],
          "description": "Tests held back by marker value, each with a reason; recorded as not_run.",
          "items": {
            "$ref": "#/$defs/TestSelectionExclusion"
          },
          "title": "Excluded",
          "type": "array"
        }
      },
      "title": "CatsTestSelectionSettings",
      "type": "object"
    },
    "EnabledNetworkHandler": {
      "description": "Built-in network handlers that can be enabled.",
      "enum": [
        "lambda",
        "ec2"
      ],
      "title": "EnabledNetworkHandler",
      "type": "string"
    },
    "GatewayEndpoints": {
      "description": "All currently available GatewayEndpoint types to enable using CATS in all VPCs under\ntest.",
      "enum": [
        "S3",
        "DYNAMODB",
        "S3_EXPRESS"
      ],
      "title": "GatewayEndpoints",
      "type": "string"
    },
    "NetworkSettings": {
      "additionalProperties": false,
      "description": "Network settings for CATS deployed infrastructure.\n\nUsed at global, account, and target levels. Fields have sensible defaults.\n\nInheritance: Settings inherit from parent levels (global \u2192 account \u2192 target).\nA field not explicitly set at a lower level inherits from the parent.\nTo explicitly override with an empty value, set the field to an empty list [].\nExample: setting tcp_listen_ports: [] at account level disables ports even if\nglobal_network_settings has tcp_listen_ports: [8080].\n\nAttributes:\n    enabled_network_handlers: Network handlers to deploy. First in list is used by http_call(), tcp_call(), udp_call().\n    interface_endpoints: Interface VPC endpoints CATS creates in VPCs under test: an escape hatch for a VPC with no\n        endpoint for the service and no DNS already answering for it. The create fails where the VPC has an endpoint\n        or a private hosted zone for the name; where a Resolver rule already sends the name elsewhere the endpoint\n        is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none;\n        where they are not, use the Lambda handler.\n    gateway_endpoints: Gateway endpoints CATS creates in VPCs under test. S3 is what a UDP target's listener needs\n        to write receipts where its subnet has no other path to S3.\n    interface_endpoint_security_group_ids: Security groups for the interface endpoints CATS creates: security group\n        ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        Unset, each interface endpoint is in its VPC's default security group, whose stock inbound rule admits\n        only members of that group; the listener is in CATS's own group, so set this to a group admitting TCP 443\n        from the listener's subnets unless the VPC's default group already does. Targets sharing a VPC must agree\n        on it, as they must on the endpoint lists: the endpoints are created once per VPC. Gateway endpoints take\n        no security group.\n    udp_listen_ports: UDP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound UDP.\n    tcp_listen_ports: TCP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound TCP.\n        Combined with udp_listen_ports, at most 30 ports per network target (the default\n        AWS quota is 60 inbound rules per security group).\n    ec2_instance_type: EC2 instance type to deploy in VPCs under test. Defaults to t3.micro.\n    existing_ec2_instance_profile_name: Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.\n    existing_ec2_ami_id: AMI ID (ami-...) or SSM parameter path (/...) resolved in the deploy region at deploy time.\n        Defaults to the latest Amazon Linux AMI CATS selects for the instance type's architecture.\n    network_call_timeout_seconds: Seconds SSM may take to deliver a probe command to the listener before CATS gives up;\n        30 to 2,592,000 (SSM's own bounds). The probe's own network budgets and the Lambda timeout are fixed\n        (see the probe README), not governed by this.",
      "properties": {
        "enabled_network_handlers": {
          "default": [
            "ec2"
          ],
          "description": "Network handlers to deploy; at least one, a declared target exists to be probed. First in list is used by http_call(), tcp_call(), udp_call().",
          "items": {
            "$ref": "#/$defs/EnabledNetworkHandler"
          },
          "minItems": 1,
          "title": "Enabled Network Handlers",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoints": {
          "default": [],
          "description": "AWS service names (ssm, ssmmessages, ec2messages, ...) for interface VPC endpoints CATS creates in the target VPC. An escape hatch for a VPC with no endpoint for the service and no DNS already answering for it: the create fails where the VPC has an endpoint or a private hosted zone for the name, and where a Resolver rule already sends the name elsewhere the endpoint is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none; where they are not, use the Lambda handler.",
          "items": {
            "pattern": "^[a-z0-9][a-z0-9.-]*$",
            "type": "string"
          },
          "title": "Interface Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "gateway_endpoints": {
          "default": [],
          "description": "Gateway VPC endpoints (S3, DYNAMODB, S3_EXPRESS) CATS creates in the target VPC. S3 is what a UDP target's listener needs to write receipts where its subnet has no other path to S3.",
          "items": {
            "$ref": "#/$defs/GatewayEndpoints"
          },
          "title": "Gateway Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoint_security_group_ids": {
          "anyOf": [
            {
              "items": {
                "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
                "type": "string"
              },
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Security groups for the interface VPC endpoints CATS creates (sg-... or SSM parameter paths), admitting TCP 443 from the listener subnets. Unset, each endpoint is in its VPC's default group, whose stock rule admits only that group's members, which the listener is not. Targets sharing a VPC must agree on it.",
          "title": "Interface Endpoint Security Group Ids"
        },
        "udp_listen_ports": {
          "default": [],
          "description": "UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6).",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Udp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "tcp_listen_ports": {
          "default": [],
          "description": "TCP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6). Combined with udp_listen_ports, at most 30 ports per network target.",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Tcp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "ec2_instance_type": {
          "default": "t3.micro",
          "description": "EC2 instance type of the listener deployed into each network target.",
          "pattern": "^[a-z0-9-]+\\.[a-z0-9-]+$",
          "title": "Ec2 Instance Type",
          "type": "string"
        },
        "existing_ec2_instance_profile_name": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z0-9+=,.@_-]{1,128}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.",
          "title": "Existing Ec2 Instance Profile Name"
        },
        "existing_ec2_ami_id": {
          "anyOf": [
            {
              "pattern": "^(ami-[0-9a-f]{8,17}|/[a-zA-Z0-9_.\\-/]+)$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "AMI ID (ami-...) or SSM parameter path (/...) resolved at deploy time. Defaults to the latest Amazon Linux AMI CATS selects.",
          "title": "Existing Ec2 Ami Id"
        },
        "network_call_timeout_seconds": {
          "default": 30,
          "description": "Seconds SSM may take to deliver a probe command before CATS gives up; 30 to 2,592,000, SSM's own bounds. Probe and Lambda budgets are fixed.",
          "maximum": 2592000,
          "minimum": 30,
          "title": "Network Call Timeout Seconds",
          "type": "integer"
        }
      },
      "title": "NetworkSettings",
      "type": "object"
    },
    "ReportFormat": {
      "description": "Supported report output formats.\n\nValues map to report writers that run at the end of a pytest session.\nSee ``cats.report_writers`` for implementations.\n\nMembers:\n    CATS_JSON: Native CATS report written to ``report.json``. The historical\n        default and the format consumed by CATS's own tooling.\n    OSCAL_AR: OSCAL 1.2.1 Assessment Results written to\n        ``assessment-results.json``. Suitable for import into\n        compliance-trestle workspaces and other OSCAL tooling.\n    JUNIT: JUnit XML written to ``junit.xml`` for CI systems. Produced by\n        pytest's own junitxml plugin, which CATS switches on at configure time\n        and feeds a property per standard, account, tag and marker on every\n        testcase; the testsuite carries the run id.\n    SECURITYHUB: One AWS Security Hub finding per test per account under test,\n        imported into each account through its CATS test role, so failures\n        surface where control state is already watched and aggregated. Writes\n        ``securityhub-findings.json`` (what was sent, and per-account delivery\n        status) when report files are on; imports either way. Settings under\n        ``reporting.securityhub``; requires ``cats infra deploy`` after enabling,\n        for the ``securityhub:BatchImportFindings`` grant on the test role.",
      "enum": [
        "cats_json",
        "oscal_ar",
        "junit",
        "securityhub"
      ],
      "title": "ReportFormat",
      "type": "string"
    },
    "SecurityHubSeverity": {
      "description": "ASFF ``Severity.Label`` values, as Security Hub defines them.",
      "enum": [
        "CRITICAL",
        "HIGH",
        "MEDIUM",
        "LOW",
        "INFORMATIONAL"
      ],
      "title": "SecurityHubSeverity",
      "type": "string"
    },
    "TestSelectionExclusion": {
      "additionalProperties": false,
      "description": "One entry of ``test_selection.excluded``: a test carrying one of ``values`` for ``marker`` does not run.\n\nAttributes:\n    marker: The marker to match, by the name written on the test: ``standard_name`` (the ``@cats``\n        keyword), ``cats_requires`` (the decorator), or a name declared in ``reporting.custom_markers``.\n        Anything else is a configuration error, never a silent no-op: an exclusion that matches\n        nothing would let the tests it was meant to hold back into the run.\n    values: The values that exclude a test, compared for equality with the marker's value:\n        a string, or a YAML boolean, so ``true`` matches ``@cats(mutating=True)`` and ``\"true\"``\n        does not.\n    reason: Why these tests do not run here. Recorded on every excluded test as its ``not_run``\n        reason in every report format, so the control stays in the evidence together with the\n        decision that kept it out.",
      "properties": {
        "marker": {
          "description": "standard_name, cats_requires, or a marker declared in reporting.custom_markers.",
          "minLength": 1,
          "title": "Marker",
          "type": "string"
        },
        "values": {
          "description": "Marker values that exclude a test; equality on the marker's value.",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "minItems": 1,
          "title": "Values",
          "type": "array",
          "uniqueItems": true
        },
        "reason": {
          "description": "Why these tests do not run here; recorded as each excluded test's not_run reason.",
          "minLength": 1,
          "title": "Reason",
          "type": "string"
        }
      },
      "required": [
        "marker",
        "values",
        "reason"
      ],
      "title": "TestSelectionExclusion",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "This class defines all CATS config management and ultimately the contents of cats.yaml\n  - each subclass attribute defines a yaml key and section.\n\nSee each subclass for greater detail.",
  "properties": {
    "cats_deployment_settings": {
      "$ref": "#/$defs/CatsDeploymentSettings",
      "default": {
        "deploy_role_name": null,
        "allow_deploy_to_current_account": false,
        "parent_account_id": null,
        "aws_region": null,
        "partition": "aws",
        "cfn_stack_prefix": "CATS-test-infra-"
      }
    },
    "global_network_settings": {
      "$ref": "#/$defs/NetworkSettings",
      "default": {
        "enabled_network_handlers": [
          "ec2"
        ],
        "interface_endpoints": [],
        "gateway_endpoints": [],
        "interface_endpoint_security_group_ids": null,
        "udp_listen_ports": [],
        "tcp_listen_ports": [],
        "ec2_instance_type": "t3.micro",
        "existing_ec2_instance_profile_name": null,
        "existing_ec2_ami_id": null,
        "network_call_timeout_seconds": 30
      }
    },
    "global_account_settings": {
      "$ref": "#/$defs/AccountSettings",
      "default": {
        "additional_roles": {},
        "default_test_role_managed_policies": [],
        "default_test_role_inline_policies": {},
        "fixture_scope": "session",
        "allow_shell": false
      }
    },
    "accounts_under_test": {
      "default": {},
      "patternProperties": {
        "^[A-Za-z][A-Za-z0-9_]*$": {
          "$ref": "#/$defs/CatsAccountUnderTest"
        }
      },
      "propertyNames": {
        "maxLength": 25,
        "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
      },
      "title": "Accounts Under Test",
      "type": "object"
    },
    "reporting": {
      "$ref": "#/$defs/CatsReportingSettings",
      "default": {
        "enabled": true,
        "report_formats": [
          "cats_json"
        ],
        "custom_markers": [],
        "oscal_import_ap_href": "",
        "securityhub": {
          "aws_region": null,
          "failed_severity": "HIGH",
          "only_with_standard": true
        },
        "report_dir": null,
        "latest_files": true,
        "timestamped_files": false
      }
    },
    "test_selection": {
      "$ref": "#/$defs/CatsTestSelectionSettings",
      "default": {
        "provides": [],
        "excluded": []
      }
    }
  },
  "title": "CatsConfig",
  "type": "object"
}

Config:

  • extra: forbid
  • case_sensitive: True

Fields:

Validators:

  • _hint_unknown_keys
  • _validate_excluded_markers
  • _reject_case_only_keyname_collisions
  • _use_aws_region_env_var
  • _resolve_hierarchical_settings
  • _validate_combined_listen_ports
  • _validate_generated_iam_role_names
  • _validate_securityhub_region_partition

effective_securityhub_region()

The Region the securityhub format imports into, or None when the format is not configured or reporting is off.

Deploy (the test role's import grant names this Region's product ARN) and test time (the client that imports) both read this, so they cannot disagree.

require_aws_region()

The deploy Region, or CatsConfigError when cats.yaml leaves it unset and AWS_REGION is not exported.

Config loading and cats validate work without a Region; deploy, show-template, test-time session construction and cats run call this because they touch AWS.

CatsDeploymentSettings pydantic-model

Bases: CatsBaseModel

Settings for CATS infrastructure deployment. These settings are used when calling 'cats infra' commands.

Attributes:

Name Type Description
deploy_role_name ValidIamRoleName | None

When deploying from a central account, role to use in all target accounts - for example, AWSControlTowerExecution. An IAM role name (not an ARN or a path): interpolated into arn:{partition}:iam::{account_id}:role/{deploy_role_name}.

allow_deploy_to_current_account bool

Allow deploying to the starting account, with current role

parent_account_id ValidAwsAccountId | None

12-digit AWS account ID that test roles will trust (the account running CATS). Required by deploy and show-template; validation and config loading work without it.

aws_region str | None

Region CATS deploys its stacks into and connects its test sessions to. Falls back to the AWS_REGION environment variable when unset. Required by deploy, show-template, test-time session construction and cats run; validation and config loading work without it.

partition str

AWS partition. Derived from aws_region when unset (us-gov-west-1 gives aws-us-gov, cn-north-1 gives aws-cn, eusc-de-east-1 gives aws-eusc); a Region no partition claims is treated as aws, as botocore does. An explicit value that disagrees with the Region is a configuration error.

cfn_stack_prefix str

Prefix for all deployed CATS resources. Used to namespace stacks, roles, and parameters. May not start with aws, amazon or amzn (in any case): SSM reserves those for its own document names, and the probe document is named {cfn_stack_prefix}{account}-Probe.

Show JSON schema:
{
  "additionalProperties": false,
  "allOf": [
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-cn"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^cn\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-us-gov"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-iso"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-iso-b"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-iso-e"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-iso-f"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "partition": {
            "const": "aws-eusc"
          }
        },
        "required": [
          "partition"
        ]
      },
      "then": {
        "properties": {
          "aws_region": {
            "anyOf": [
              {
                "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
              },
              {
                "not": {
                  "anyOf": [
                    {
                      "pattern": "^(us|eu|ap|sa|ca|me|af|il|mx)\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^cn\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-gov\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-iso\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isob\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eu\\-isoe\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^us\\-isof\\-\\w+\\-\\d+$"
                    },
                    {
                      "pattern": "^eusc\\-(de)\\-\\w+\\-\\d+$"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  ],
  "description": "Settings for CATS infrastructure deployment. These settings are used when calling\n'cats infra' commands.\n\nAttributes:\n    deploy_role_name: When deploying from a central account, role to use in all target accounts - for example, AWSControlTowerExecution.\n        An IAM role name (not an ARN or a path): interpolated into arn:{partition}:iam::{account_id}:role/{deploy_role_name}.\n    allow_deploy_to_current_account: Allow deploying to the starting account, with current role\n    parent_account_id: 12-digit AWS account ID that test roles will trust (the account running CATS).\n        Required by deploy and show-template; validation and config loading work without it.\n    aws_region: Region CATS deploys its stacks into and connects its test sessions to. Falls back to the\n        AWS_REGION environment variable when unset. Required by deploy, show-template, test-time session\n        construction and `cats run`; validation and config loading work without it.\n    partition: AWS partition. Derived from aws_region when unset (us-gov-west-1 gives aws-us-gov, cn-north-1\n        gives aws-cn, eusc-de-east-1 gives aws-eusc); a Region no partition claims is treated as aws, as\n        botocore does. An explicit value that disagrees with the Region is a configuration error.\n    cfn_stack_prefix: Prefix for all deployed CATS resources. Used to namespace stacks, roles, and parameters.\n        May not start with aws, amazon or amzn (in any case): SSM reserves those for its own document names,\n        and the probe document is named {cfn_stack_prefix}{account}-Probe.",
  "properties": {
    "deploy_role_name": {
      "anyOf": [
        {
          "pattern": "^[A-Za-z0-9+=,.@_-]{1,64}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "IAM role name CATS assumes in each account under test to deploy; interpolated into arn:{partition}:iam::{account_id}:role/{name}.",
      "title": "Deploy Role Name"
    },
    "allow_deploy_to_current_account": {
      "default": false,
      "description": "By default, CATS will not try and deploy infrastructure in the account it begins working in. Set this to True to allow deploying test infrastructure without role assumption in the profile running CATS. For example, set this to deploy tests in an AWS Organizations root account using the credentials you called `cats infra` with.",
      "title": "Allow Deploy To Current Account",
      "type": "boolean"
    },
    "parent_account_id": {
      "anyOf": [
        {
          "pattern": "^[0-9]{12}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Parent Account Id"
    },
    "aws_region": {
      "anyOf": [
        {
          "pattern": "^[a-z]{2}[a-z0-9-]*-[0-9]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Aws Region"
    },
    "partition": {
      "default": "aws",
      "description": "AWS partition. Derived from aws_region when unset; an explicit value must agree with the Region.",
      "enum": [
        "aws",
        "aws-cn",
        "aws-eusc",
        "aws-iso",
        "aws-iso-b",
        "aws-iso-e",
        "aws-iso-f",
        "aws-us-gov"
      ],
      "title": "Partition",
      "type": "string"
    },
    "cfn_stack_prefix": {
      "default": "CATS-test-infra-",
      "maxLength": 64,
      "pattern": "^(?![Aa][Ww][Ss]|[Aa][Mm][Aa][Zz][Oo][Nn]|[Aa][Mm][Zz][Nn])[A-Za-z][A-Za-z0-9-]*$",
      "title": "Cfn Stack Prefix",
      "type": "string"
    }
  },
  "title": "CatsDeploymentSettings",
  "type": "object"
}

Config:

  • json_schema_extra: _deployment_settings_schema

Fields:

  • deploy_role_name (ValidIamRoleName | None)
  • allow_deploy_to_current_account (bool)
  • parent_account_id (ValidAwsAccountId | None)
  • aws_region (str | None)
  • partition (str)
  • cfn_stack_prefix (str)

Validators:

  • _hint_unknown_keys
  • _derive_partition_from_region

partition = 'aws' pydantic-field

AWS partition. Derived from aws_region when unset; an explicit value must agree with the Region.

NetworkSettings pydantic-model

Bases: CatsBaseModel

Network settings for CATS deployed infrastructure.

Used at global, account, and target levels. Fields have sensible defaults.

Inheritance: Settings inherit from parent levels (global → account → target). A field not explicitly set at a lower level inherits from the parent. To explicitly override with an empty value, set the field to an empty list []. Example: setting tcp_listen_ports: [] at account level disables ports even if global_network_settings has tcp_listen_ports: [8080].

Attributes:

Name Type Description
enabled_network_handlers UniqueList[EnabledNetworkHandler]

Network handlers to deploy. First in list is used by http_call(), tcp_call(), udp_call().

interface_endpoints UniqueList[Annotated[str, Field(pattern='^[a-z0-9][a-z0-9.-]*$')]]

Interface VPC endpoints CATS creates in VPCs under test: an escape hatch for a VPC with no endpoint for the service and no DNS already answering for it. The create fails where the VPC has an endpoint or a private hosted zone for the name; where a Resolver rule already sends the name elsewhere the endpoint is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none; where they are not, use the Lambda handler.

gateway_endpoints UniqueList[GatewayEndpoints]

Gateway endpoints CATS creates in VPCs under test. S3 is what a UDP target's listener needs to write receipts where its subnet has no other path to S3.

interface_endpoint_security_group_ids UniqueList[ValidSecurityGroupId] | None

Security groups for the interface endpoints CATS creates: security group ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time. Unset, each interface endpoint is in its VPC's default security group, whose stock inbound rule admits only members of that group; the listener is in CATS's own group, so set this to a group admitting TCP 443 from the listener's subnets unless the VPC's default group already does. Targets sharing a VPC must agree on it, as they must on the endpoint lists: the endpoints are created once per VPC. Gateway endpoints take no security group.

udp_listen_ports UniqueList[ValidListenPort]

UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound UDP.

tcp_listen_ports UniqueList[ValidListenPort]

TCP ports to open and listen on on deployed EC2 listeners. Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound TCP. Combined with udp_listen_ports, at most 30 ports per network target (the default AWS quota is 60 inbound rules per security group).

ec2_instance_type str

EC2 instance type to deploy in VPCs under test. Defaults to t3.micro.

existing_ec2_instance_profile_name str | None

Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.

existing_ec2_ami_id str | None

AMI ID (ami-...) or SSM parameter path (/...) resolved in the deploy region at deploy time. Defaults to the latest Amazon Linux AMI CATS selects for the instance type's architecture.

network_call_timeout_seconds int

Seconds SSM may take to deliver a probe command to the listener before CATS gives up; 30 to 2,592,000 (SSM's own bounds). The probe's own network budgets and the Lambda timeout are fixed (see the probe README), not governed by this.

Show JSON schema:
{
  "$defs": {
    "EnabledNetworkHandler": {
      "description": "Built-in network handlers that can be enabled.",
      "enum": [
        "lambda",
        "ec2"
      ],
      "title": "EnabledNetworkHandler",
      "type": "string"
    },
    "GatewayEndpoints": {
      "description": "All currently available GatewayEndpoint types to enable using CATS in all VPCs under\ntest.",
      "enum": [
        "S3",
        "DYNAMODB",
        "S3_EXPRESS"
      ],
      "title": "GatewayEndpoints",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Network settings for CATS deployed infrastructure.\n\nUsed at global, account, and target levels. Fields have sensible defaults.\n\nInheritance: Settings inherit from parent levels (global \u2192 account \u2192 target).\nA field not explicitly set at a lower level inherits from the parent.\nTo explicitly override with an empty value, set the field to an empty list [].\nExample: setting tcp_listen_ports: [] at account level disables ports even if\nglobal_network_settings has tcp_listen_ports: [8080].\n\nAttributes:\n    enabled_network_handlers: Network handlers to deploy. First in list is used by http_call(), tcp_call(), udp_call().\n    interface_endpoints: Interface VPC endpoints CATS creates in VPCs under test: an escape hatch for a VPC with no\n        endpoint for the service and no DNS already answering for it. The create fails where the VPC has an endpoint\n        or a private hosted zone for the name; where a Resolver rule already sends the name elsewhere the endpoint\n        is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none;\n        where they are not, use the Lambda handler.\n    gateway_endpoints: Gateway endpoints CATS creates in VPCs under test. S3 is what a UDP target's listener needs\n        to write receipts where its subnet has no other path to S3.\n    interface_endpoint_security_group_ids: Security groups for the interface endpoints CATS creates: security group\n        ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        Unset, each interface endpoint is in its VPC's default security group, whose stock inbound rule admits\n        only members of that group; the listener is in CATS's own group, so set this to a group admitting TCP 443\n        from the listener's subnets unless the VPC's default group already does. Targets sharing a VPC must agree\n        on it, as they must on the endpoint lists: the endpoints are created once per VPC. Gateway endpoints take\n        no security group.\n    udp_listen_ports: UDP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound UDP.\n    tcp_listen_ports: TCP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound TCP.\n        Combined with udp_listen_ports, at most 30 ports per network target (the default\n        AWS quota is 60 inbound rules per security group).\n    ec2_instance_type: EC2 instance type to deploy in VPCs under test. Defaults to t3.micro.\n    existing_ec2_instance_profile_name: Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.\n    existing_ec2_ami_id: AMI ID (ami-...) or SSM parameter path (/...) resolved in the deploy region at deploy time.\n        Defaults to the latest Amazon Linux AMI CATS selects for the instance type's architecture.\n    network_call_timeout_seconds: Seconds SSM may take to deliver a probe command to the listener before CATS gives up;\n        30 to 2,592,000 (SSM's own bounds). The probe's own network budgets and the Lambda timeout are fixed\n        (see the probe README), not governed by this.",
  "properties": {
    "enabled_network_handlers": {
      "default": [
        "ec2"
      ],
      "description": "Network handlers to deploy; at least one, a declared target exists to be probed. First in list is used by http_call(), tcp_call(), udp_call().",
      "items": {
        "$ref": "#/$defs/EnabledNetworkHandler"
      },
      "minItems": 1,
      "title": "Enabled Network Handlers",
      "type": "array",
      "uniqueItems": true
    },
    "interface_endpoints": {
      "default": [],
      "description": "AWS service names (ssm, ssmmessages, ec2messages, ...) for interface VPC endpoints CATS creates in the target VPC. An escape hatch for a VPC with no endpoint for the service and no DNS already answering for it: the create fails where the VPC has an endpoint or a private hosted zone for the name, and where a Resolver rule already sends the name elsewhere the endpoint is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none; where they are not, use the Lambda handler.",
      "items": {
        "pattern": "^[a-z0-9][a-z0-9.-]*$",
        "type": "string"
      },
      "title": "Interface Endpoints",
      "type": "array",
      "uniqueItems": true
    },
    "gateway_endpoints": {
      "default": [],
      "description": "Gateway VPC endpoints (S3, DYNAMODB, S3_EXPRESS) CATS creates in the target VPC. S3 is what a UDP target's listener needs to write receipts where its subnet has no other path to S3.",
      "items": {
        "$ref": "#/$defs/GatewayEndpoints"
      },
      "title": "Gateway Endpoints",
      "type": "array",
      "uniqueItems": true
    },
    "interface_endpoint_security_group_ids": {
      "anyOf": [
        {
          "items": {
            "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
            "type": "string"
          },
          "type": "array",
          "uniqueItems": true
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Security groups for the interface VPC endpoints CATS creates (sg-... or SSM parameter paths), admitting TCP 443 from the listener subnets. Unset, each endpoint is in its VPC's default group, whose stock rule admits only that group's members, which the listener is not. Targets sharing a VPC must agree on it.",
      "title": "Interface Endpoint Security Group Ids"
    },
    "udp_listen_ports": {
      "default": [],
      "description": "UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6).",
      "items": {
        "maximum": 65535,
        "minimum": 1,
        "type": "integer"
      },
      "title": "Udp Listen Ports",
      "type": "array",
      "uniqueItems": true
    },
    "tcp_listen_ports": {
      "default": [],
      "description": "TCP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6). Combined with udp_listen_ports, at most 30 ports per network target.",
      "items": {
        "maximum": 65535,
        "minimum": 1,
        "type": "integer"
      },
      "title": "Tcp Listen Ports",
      "type": "array",
      "uniqueItems": true
    },
    "ec2_instance_type": {
      "default": "t3.micro",
      "description": "EC2 instance type of the listener deployed into each network target.",
      "pattern": "^[a-z0-9-]+\\.[a-z0-9-]+$",
      "title": "Ec2 Instance Type",
      "type": "string"
    },
    "existing_ec2_instance_profile_name": {
      "anyOf": [
        {
          "pattern": "^[A-Za-z0-9+=,.@_-]{1,128}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.",
      "title": "Existing Ec2 Instance Profile Name"
    },
    "existing_ec2_ami_id": {
      "anyOf": [
        {
          "pattern": "^(ami-[0-9a-f]{8,17}|/[a-zA-Z0-9_.\\-/]+)$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "AMI ID (ami-...) or SSM parameter path (/...) resolved at deploy time. Defaults to the latest Amazon Linux AMI CATS selects.",
      "title": "Existing Ec2 Ami Id"
    },
    "network_call_timeout_seconds": {
      "default": 30,
      "description": "Seconds SSM may take to deliver a probe command before CATS gives up; 30 to 2,592,000, SSM's own bounds. Probe and Lambda budgets are fixed.",
      "maximum": 2592000,
      "minimum": 30,
      "title": "Network Call Timeout Seconds",
      "type": "integer"
    }
  },
  "title": "NetworkSettings",
  "type": "object"
}

Fields:

Validators:

  • _hint_unknown_keys
  • _reject_interface_endpoints_sharing_a_logical_id

ec2_instance_type = 't3.micro' pydantic-field

EC2 instance type of the listener deployed into each network target.

existing_ec2_ami_id = None pydantic-field

AMI ID (ami-...) or SSM parameter path (/...) resolved at deploy time. Defaults to the latest Amazon Linux AMI CATS selects.

existing_ec2_instance_profile_name = None pydantic-field

Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.

udp_listen_ports = [] pydantic-field

UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6).

AccountSettings pydantic-model

Bases: CatsBaseModel

Account settings for CATS.

Used at global and account levels. Fields have sensible defaults.

Attributes:

Name Type Description
additional_roles dict[ValidRoleName, CatsAdditionalTestRole]

Additional IAM roles to create, keyed by role name and accessible as AccountUnderTest.role.

default_test_role_managed_policies UniqueList[ValidManagedPolicy]

A list of AWS managed IAM policy names to attach to the default test role.

default_test_role_inline_policies dict[ValidIamPolicyName, PolicyDocument]

Inline IAM policies to attach to the default test role, keyed by policy name. Each value is either a policy document (written inline in yaml/JSON) or a string path to a JSON policy file, resolved relative to cats.yaml.

fixture_scope Literal['session', 'function', 'module', 'class']

Pytest fixture scope for account fixtures

allow_shell bool

Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command. Off by default. This is a deploy-time setting: when true, the test role's SSM policy includes the run-command document. Changing it requires redeployment. See docs/security.md for implications.

Show JSON schema:
{
  "$defs": {
    "CatsAdditionalTestRole": {
      "additionalProperties": false,
      "anyOf": [
        {
          "properties": {
            "managed_policies": {
              "minItems": 1
            }
          },
          "required": [
            "managed_policies"
          ]
        },
        {
          "properties": {
            "inline_policies": {
              "minProperties": 1
            }
          },
          "required": [
            "inline_policies"
          ]
        }
      ],
      "description": "CATS deploys one role by default: this configuration block allows defining additional roles.\n\nEach entry of `additional_roles` is keyed by the role's name: `account.role.<name>` returns a session\nfor it, and the deployed IAM role is named {cfn_stack_prefix}{account_keyname}-<name>. A role\ndeclares at least one of `managed_policies` and `inline_policies`.\n\nAttributes:\n    managed_policies: A list of AWS managed IAM policy names or full policy ARNs to attach to this role.\n        Full list available at https://docs.aws.amazon.com/aws-managed-policy/latest/reference/policy-list.html\n    inline_policies: Inline IAM policies to attach to this role, keyed by policy name.\n        Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.",
      "properties": {
        "managed_policies": {
          "default": [],
          "items": {
            "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
            "type": "string"
          },
          "title": "Managed Policies",
          "type": "array",
          "uniqueItems": true
        },
        "inline_policies": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z0-9+=,.@_-]+$": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "required": [
                    "Statement"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9+=,.@_-]+$"
          },
          "title": "Inline Policies",
          "type": "object"
        }
      },
      "title": "CatsAdditionalTestRole",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Account settings for CATS.\n\nUsed at global and account levels. Fields have sensible defaults.\n\nAttributes:\n    additional_roles: Additional IAM roles to create, keyed by role name and accessible as AccountUnderTest.role.<name>\n    default_test_role_managed_policies: A list of AWS managed IAM policy names to attach to the default test role.\n    default_test_role_inline_policies: Inline IAM policies to attach to the default test role, keyed by\n        policy name. Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.\n    fixture_scope: Pytest fixture scope for account fixtures\n    allow_shell: Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command.\n        Off by default. This is a deploy-time setting: when true, the test role's SSM policy includes the\n        run-command document. Changing it requires redeployment. See docs/security.md for implications.",
  "properties": {
    "additional_roles": {
      "default": {},
      "patternProperties": {
        "^[A-Za-z][A-Za-z0-9_]*$": {
          "$ref": "#/$defs/CatsAdditionalTestRole"
        }
      },
      "propertyNames": {
        "not": {
          "enum": [
            "False",
            "None",
            "True",
            "and",
            "as",
            "assert",
            "async",
            "await",
            "break",
            "class",
            "continue",
            "def",
            "default",
            "del",
            "elif",
            "else",
            "except",
            "finally",
            "for",
            "from",
            "global",
            "if",
            "import",
            "in",
            "is",
            "lambda",
            "nonlocal",
            "not",
            "or",
            "pass",
            "raise",
            "return",
            "try",
            "while",
            "with",
            "yield"
          ]
        },
        "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
      },
      "title": "Additional Roles",
      "type": "object"
    },
    "default_test_role_managed_policies": {
      "default": [],
      "description": "Additional permissions to grant CATS in each AccountUnderTest. Adds listed Managed Policies by name or ARN.",
      "items": {
        "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
        "type": "string"
      },
      "title": "Default Test Role Managed Policies",
      "type": "array",
      "uniqueItems": true
    },
    "default_test_role_inline_policies": {
      "default": {},
      "description": "Inline IAM policies for the default test role, keyed by policy name. Values are policy documents, or string paths to JSON files relative to cats.yaml.",
      "patternProperties": {
        "^[A-Za-z0-9+=,.@_-]+$": {
          "anyOf": [
            {
              "additionalProperties": true,
              "required": [
                "Statement"
              ],
              "type": "object"
            },
            {
              "type": "string"
            }
          ]
        }
      },
      "propertyNames": {
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9+=,.@_-]+$"
      },
      "title": "Default Test Role Inline Policies",
      "type": "object"
    },
    "fixture_scope": {
      "default": "session",
      "description": "Pytest fixture scope for account fixtures",
      "enum": [
        "session",
        "function",
        "module",
        "class"
      ],
      "title": "Fixture Scope",
      "type": "string"
    },
    "allow_shell": {
      "default": false,
      "description": "Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command. Deploy-time setting.",
      "title": "Allow Shell",
      "type": "boolean"
    }
  },
  "title": "AccountSettings",
  "type": "object"
}

Fields:

Validators:

  • _hint_unknown_keys
  • _reject_colliding_role_names

allow_shell = False pydantic-field

Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command. Deploy-time setting.

default_test_role_managed_policies = [] pydantic-field

Additional permissions to grant CATS in each AccountUnderTest. Adds listed Managed Policies by name or ARN.

fixture_scope = 'session' pydantic-field

Pytest fixture scope for account fixtures

CatsAccountUnderTest pydantic-model

Bases: CatsBaseModel

One target account to configure specific test resources and tag with metadata.

The key name in cats.yaml defines the name of the generated AccountUnderTest resource within CATS test code.

Attributes:

Name Type Description
account_id ValidAwsAccountId

12-digit AWS account ID string (required) of target account

account_name str | None

Optional metadata on an account friendlyname

account_email str | None

Optional metadata on an account email

notes str | None

Optional metadata for general notes in your yaml file

account_network_under_test dict[ValidNetworkTargetName, CatsNetworkUnderTest]

A key/value dictionary of network test targets in this account, where each entry will have network infrastructure deployed and made available on the AccountUnderTest class resource. The number of targets an account can hold is bounded by CloudFormation's 51,200-byte template limit, which cats validate measures for the exact configuration (targets, handlers and listen ports all count); split targets across a second account entry with the same account_id when it says so.

tags CatsTags

Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}

network_settings NetworkSettings

Per-account network settings override. Overrides global, overridden by target.

account_settings AccountSettings

Per-account settings override. Overrides global_account_settings.

Show JSON schema:
{
  "$defs": {
    "AccountSettings": {
      "additionalProperties": false,
      "description": "Account settings for CATS.\n\nUsed at global and account levels. Fields have sensible defaults.\n\nAttributes:\n    additional_roles: Additional IAM roles to create, keyed by role name and accessible as AccountUnderTest.role.<name>\n    default_test_role_managed_policies: A list of AWS managed IAM policy names to attach to the default test role.\n    default_test_role_inline_policies: Inline IAM policies to attach to the default test role, keyed by\n        policy name. Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.\n    fixture_scope: Pytest fixture scope for account fixtures\n    allow_shell: Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command.\n        Off by default. This is a deploy-time setting: when true, the test role's SSM policy includes the\n        run-command document. Changing it requires redeployment. See docs/security.md for implications.",
      "properties": {
        "additional_roles": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z][A-Za-z0-9_]*$": {
              "$ref": "#/$defs/CatsAdditionalTestRole"
            }
          },
          "propertyNames": {
            "not": {
              "enum": [
                "False",
                "None",
                "True",
                "and",
                "as",
                "assert",
                "async",
                "await",
                "break",
                "class",
                "continue",
                "def",
                "default",
                "del",
                "elif",
                "else",
                "except",
                "finally",
                "for",
                "from",
                "global",
                "if",
                "import",
                "in",
                "is",
                "lambda",
                "nonlocal",
                "not",
                "or",
                "pass",
                "raise",
                "return",
                "try",
                "while",
                "with",
                "yield"
              ]
            },
            "pattern": "^[A-Za-z][A-Za-z0-9_]*$"
          },
          "title": "Additional Roles",
          "type": "object"
        },
        "default_test_role_managed_policies": {
          "default": [],
          "description": "Additional permissions to grant CATS in each AccountUnderTest. Adds listed Managed Policies by name or ARN.",
          "items": {
            "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
            "type": "string"
          },
          "title": "Default Test Role Managed Policies",
          "type": "array",
          "uniqueItems": true
        },
        "default_test_role_inline_policies": {
          "default": {},
          "description": "Inline IAM policies for the default test role, keyed by policy name. Values are policy documents, or string paths to JSON files relative to cats.yaml.",
          "patternProperties": {
            "^[A-Za-z0-9+=,.@_-]+$": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "required": [
                    "Statement"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9+=,.@_-]+$"
          },
          "title": "Default Test Role Inline Policies",
          "type": "object"
        },
        "fixture_scope": {
          "default": "session",
          "description": "Pytest fixture scope for account fixtures",
          "enum": [
            "session",
            "function",
            "module",
            "class"
          ],
          "title": "Fixture Scope",
          "type": "string"
        },
        "allow_shell": {
          "default": false,
          "description": "Enable NetworkHandler.shell() for arbitrary commands on CATS EC2 instances through SSM run-command. Deploy-time setting.",
          "title": "Allow Shell",
          "type": "boolean"
        }
      },
      "title": "AccountSettings",
      "type": "object"
    },
    "CatsAdditionalTestRole": {
      "additionalProperties": false,
      "anyOf": [
        {
          "properties": {
            "managed_policies": {
              "minItems": 1
            }
          },
          "required": [
            "managed_policies"
          ]
        },
        {
          "properties": {
            "inline_policies": {
              "minProperties": 1
            }
          },
          "required": [
            "inline_policies"
          ]
        }
      ],
      "description": "CATS deploys one role by default: this configuration block allows defining additional roles.\n\nEach entry of `additional_roles` is keyed by the role's name: `account.role.<name>` returns a session\nfor it, and the deployed IAM role is named {cfn_stack_prefix}{account_keyname}-<name>. A role\ndeclares at least one of `managed_policies` and `inline_policies`.\n\nAttributes:\n    managed_policies: A list of AWS managed IAM policy names or full policy ARNs to attach to this role.\n        Full list available at https://docs.aws.amazon.com/aws-managed-policy/latest/reference/policy-list.html\n    inline_policies: Inline IAM policies to attach to this role, keyed by policy name.\n        Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.",
      "properties": {
        "managed_policies": {
          "default": [],
          "items": {
            "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
            "type": "string"
          },
          "title": "Managed Policies",
          "type": "array",
          "uniqueItems": true
        },
        "inline_policies": {
          "default": {},
          "patternProperties": {
            "^[A-Za-z0-9+=,.@_-]+$": {
              "anyOf": [
                {
                  "additionalProperties": true,
                  "required": [
                    "Statement"
                  ],
                  "type": "object"
                },
                {
                  "type": "string"
                }
              ]
            }
          },
          "propertyNames": {
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9+=,.@_-]+$"
          },
          "title": "Inline Policies",
          "type": "object"
        }
      },
      "title": "CatsAdditionalTestRole",
      "type": "object"
    },
    "CatsNetworkUnderTest": {
      "additionalProperties": false,
      "description": "Target network segment to send and receive network plane data.\n\nThe key name in cats.yaml defines the name of the generated AccountUnderTest\nresource within CATS test code.\n\n``vpc_id``, ``subnet_ids`` and ``existing_security_group_ids`` each take a literal id\n(``vpc-...``, ``subnet-...``, ``sg-...``) or the name of an SSM parameter holding one, which\nmust start with ``/``. The parameter is read in the target account at deploy time.\n\nAttributes:\n    vpc_id: The VPC to work from: a VPC id (vpc-...) or an SSM parameter name (/...) containing one\n    subnet_ids: A list of subnet ids (subnet-...) or SSM parameter names (/...) containing subnet IDs inside target VPC.\n        The EC2 listener deploys into the first subnet; Lambda handlers and interface endpoints use all of them,\n        so list every subnet (e.g. one per AZ) the Lambda probes should reach from.\n    subnet_id: The single-subnet spelling: ``subnet_id: subnet-1`` means ``subnet_ids: [subnet-1]``. Give one\n        or the other, not both. Input only: the loaded model carries ``subnet_ids`` alone, so a dumped\n        configuration re-validates.\n    existing_security_group_ids: Security groups to attach to every resource CATS deploys in this target -\n        the EC2 listener and, when the lambda handler is enabled, the probe Lambda. Accepts security\n        group ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        By default CATS creates its own groups instead: one for the EC2 listener with ingress scoped to the\n        target's tcp_listen_ports and udp_listen_ports, and an egress-only one for the lambdas. Provide your\n        own groups for any other ingress posture (open-all, custom source CIDRs, fully closed), or to speed\n        up `cats infra destroy` with the lambda handler - CloudFormation cannot delete a stack-owned lambda\n        security group until Lambda releases its Hyperplane ENIs, which takes up to ~20 minutes. Groups CATS\n        does not own are never waited on.\n        The groups must allow the traffic your tests need, in both directions. Outbound is the one most\n        likely to bite: the lambda handlers only reach a destination if the groups permit egress to it,\n        and a group with any explicit egress rule no longer allows all outbound traffic. Inbound matters\n        too - reaching an EC2 listener requires access on its tcp_listen_ports and udp_listen_ports.\n        Traffic a group blocks surfaces as a FAILURE result at test time, not a deploy-time error.\n    tags: Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}\n    network_settings: Per-target network settings. Populated with resolved values after config load.",
      "oneOf": [
        {
          "required": [
            "subnet_id"
          ]
        },
        {
          "required": [
            "subnet_ids"
          ]
        }
      ],
      "properties": {
        "vpc_id": {
          "pattern": "^(vpc-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
          "title": "Vpc Id",
          "type": "string"
        },
        "subnet_id": {
          "anyOf": [
            {
              "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Subnet Id"
        },
        "subnet_ids": {
          "default": [],
          "items": {
            "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
            "type": "string"
          },
          "title": "Subnet Ids",
          "type": "array",
          "uniqueItems": true
        },
        "existing_security_group_ids": {
          "anyOf": [
            {
              "items": {
                "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
                "type": "string"
              },
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Existing Security Group Ids"
        },
        "tags": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "type": "object"
            },
            {
              "items": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "additionalProperties": {
                      "type": "string"
                    },
                    "type": "object"
                  }
                ]
              },
              "type": "array"
            }
          ],
          "default": {},
          "title": "Tags"
        },
        "network_settings": {
          "$ref": "#/$defs/NetworkSettings",
          "default": {
            "enabled_network_handlers": [
              "ec2"
            ],
            "interface_endpoints": [],
            "gateway_endpoints": [],
            "interface_endpoint_security_group_ids": null,
            "udp_listen_ports": [],
            "tcp_listen_ports": [],
            "ec2_instance_type": "t3.micro",
            "existing_ec2_instance_profile_name": null,
            "existing_ec2_ami_id": null,
            "network_call_timeout_seconds": 30
          }
        }
      },
      "required": [
        "vpc_id"
      ],
      "title": "CatsNetworkUnderTest",
      "type": "object"
    },
    "EnabledNetworkHandler": {
      "description": "Built-in network handlers that can be enabled.",
      "enum": [
        "lambda",
        "ec2"
      ],
      "title": "EnabledNetworkHandler",
      "type": "string"
    },
    "GatewayEndpoints": {
      "description": "All currently available GatewayEndpoint types to enable using CATS in all VPCs under\ntest.",
      "enum": [
        "S3",
        "DYNAMODB",
        "S3_EXPRESS"
      ],
      "title": "GatewayEndpoints",
      "type": "string"
    },
    "NetworkSettings": {
      "additionalProperties": false,
      "description": "Network settings for CATS deployed infrastructure.\n\nUsed at global, account, and target levels. Fields have sensible defaults.\n\nInheritance: Settings inherit from parent levels (global \u2192 account \u2192 target).\nA field not explicitly set at a lower level inherits from the parent.\nTo explicitly override with an empty value, set the field to an empty list [].\nExample: setting tcp_listen_ports: [] at account level disables ports even if\nglobal_network_settings has tcp_listen_ports: [8080].\n\nAttributes:\n    enabled_network_handlers: Network handlers to deploy. First in list is used by http_call(), tcp_call(), udp_call().\n    interface_endpoints: Interface VPC endpoints CATS creates in VPCs under test: an escape hatch for a VPC with no\n        endpoint for the service and no DNS already answering for it. The create fails where the VPC has an endpoint\n        or a private hosted zone for the name; where a Resolver rule already sends the name elsewhere the endpoint\n        is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none;\n        where they are not, use the Lambda handler.\n    gateway_endpoints: Gateway endpoints CATS creates in VPCs under test. S3 is what a UDP target's listener needs\n        to write receipts where its subnet has no other path to S3.\n    interface_endpoint_security_group_ids: Security groups for the interface endpoints CATS creates: security group\n        ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        Unset, each interface endpoint is in its VPC's default security group, whose stock inbound rule admits\n        only members of that group; the listener is in CATS's own group, so set this to a group admitting TCP 443\n        from the listener's subnets unless the VPC's default group already does. Targets sharing a VPC must agree\n        on it, as they must on the endpoint lists: the endpoints are created once per VPC. Gateway endpoints take\n        no security group.\n    udp_listen_ports: UDP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound UDP.\n    tcp_listen_ports: TCP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound TCP.\n        Combined with udp_listen_ports, at most 30 ports per network target (the default\n        AWS quota is 60 inbound rules per security group).\n    ec2_instance_type: EC2 instance type to deploy in VPCs under test. Defaults to t3.micro.\n    existing_ec2_instance_profile_name: Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.\n    existing_ec2_ami_id: AMI ID (ami-...) or SSM parameter path (/...) resolved in the deploy region at deploy time.\n        Defaults to the latest Amazon Linux AMI CATS selects for the instance type's architecture.\n    network_call_timeout_seconds: Seconds SSM may take to deliver a probe command to the listener before CATS gives up;\n        30 to 2,592,000 (SSM's own bounds). The probe's own network budgets and the Lambda timeout are fixed\n        (see the probe README), not governed by this.",
      "properties": {
        "enabled_network_handlers": {
          "default": [
            "ec2"
          ],
          "description": "Network handlers to deploy; at least one, a declared target exists to be probed. First in list is used by http_call(), tcp_call(), udp_call().",
          "items": {
            "$ref": "#/$defs/EnabledNetworkHandler"
          },
          "minItems": 1,
          "title": "Enabled Network Handlers",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoints": {
          "default": [],
          "description": "AWS service names (ssm, ssmmessages, ec2messages, ...) for interface VPC endpoints CATS creates in the target VPC. An escape hatch for a VPC with no endpoint for the service and no DNS already answering for it: the create fails where the VPC has an endpoint or a private hosted zone for the name, and where a Resolver rule already sends the name elsewhere the endpoint is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none; where they are not, use the Lambda handler.",
          "items": {
            "pattern": "^[a-z0-9][a-z0-9.-]*$",
            "type": "string"
          },
          "title": "Interface Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "gateway_endpoints": {
          "default": [],
          "description": "Gateway VPC endpoints (S3, DYNAMODB, S3_EXPRESS) CATS creates in the target VPC. S3 is what a UDP target's listener needs to write receipts where its subnet has no other path to S3.",
          "items": {
            "$ref": "#/$defs/GatewayEndpoints"
          },
          "title": "Gateway Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoint_security_group_ids": {
          "anyOf": [
            {
              "items": {
                "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
                "type": "string"
              },
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Security groups for the interface VPC endpoints CATS creates (sg-... or SSM parameter paths), admitting TCP 443 from the listener subnets. Unset, each endpoint is in its VPC's default group, whose stock rule admits only that group's members, which the listener is not. Targets sharing a VPC must agree on it.",
          "title": "Interface Endpoint Security Group Ids"
        },
        "udp_listen_ports": {
          "default": [],
          "description": "UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6).",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Udp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "tcp_listen_ports": {
          "default": [],
          "description": "TCP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6). Combined with udp_listen_ports, at most 30 ports per network target.",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Tcp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "ec2_instance_type": {
          "default": "t3.micro",
          "description": "EC2 instance type of the listener deployed into each network target.",
          "pattern": "^[a-z0-9-]+\\.[a-z0-9-]+$",
          "title": "Ec2 Instance Type",
          "type": "string"
        },
        "existing_ec2_instance_profile_name": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z0-9+=,.@_-]{1,128}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.",
          "title": "Existing Ec2 Instance Profile Name"
        },
        "existing_ec2_ami_id": {
          "anyOf": [
            {
              "pattern": "^(ami-[0-9a-f]{8,17}|/[a-zA-Z0-9_.\\-/]+)$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "AMI ID (ami-...) or SSM parameter path (/...) resolved at deploy time. Defaults to the latest Amazon Linux AMI CATS selects.",
          "title": "Existing Ec2 Ami Id"
        },
        "network_call_timeout_seconds": {
          "default": 30,
          "description": "Seconds SSM may take to deliver a probe command before CATS gives up; 30 to 2,592,000, SSM's own bounds. Probe and Lambda budgets are fixed.",
          "maximum": 2592000,
          "minimum": 30,
          "title": "Network Call Timeout Seconds",
          "type": "integer"
        }
      },
      "title": "NetworkSettings",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "One target account to configure specific test resources and tag with metadata.\n\nThe key name in cats.yaml defines the name of the generated AccountUnderTest\nresource within CATS test code.\n\nAttributes:\n    account_id: 12-digit AWS account ID string (required) of target account\n    account_name: Optional metadata on an account friendlyname\n    account_email: Optional metadata on an account email\n    notes: Optional metadata for general notes in your yaml file\n    account_network_under_test: A key/value dictionary of network test targets in this account, where each entry\n        will have network infrastructure deployed and made available on the AccountUnderTest class resource.\n        The number of targets an account can hold is bounded by CloudFormation's 51,200-byte template limit,\n        which `cats validate` measures for the exact configuration (targets, handlers and listen ports all\n        count); split targets across a second account entry with the same account_id when it says so.\n    tags: Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}\n    network_settings: Per-account network settings override. Overrides global, overridden by target.\n    account_settings: Per-account settings override. Overrides global_account_settings.",
  "properties": {
    "account_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Account Name"
    },
    "account_email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Account Email"
    },
    "notes": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Notes"
    },
    "account_id": {
      "pattern": "^[0-9]{12}$",
      "title": "Account Id",
      "type": "string"
    },
    "account_network_under_test": {
      "default": {},
      "patternProperties": {
        "^[A-Za-z][A-Za-z0-9]*$": {
          "$ref": "#/$defs/CatsNetworkUnderTest"
        }
      },
      "propertyNames": {
        "maxLength": 15,
        "not": {
          "enum": [
            "False",
            "None",
            "True",
            "and",
            "as",
            "assert",
            "async",
            "await",
            "break",
            "class",
            "continue",
            "def",
            "del",
            "elif",
            "else",
            "except",
            "finally",
            "for",
            "from",
            "global",
            "if",
            "import",
            "in",
            "is",
            "lambda",
            "name",
            "nonlocal",
            "not",
            "or",
            "partition",
            "pass",
            "raise",
            "return",
            "role",
            "session",
            "tags",
            "try",
            "while",
            "with",
            "yield"
          ]
        },
        "pattern": "^[A-Za-z][A-Za-z0-9]*$"
      },
      "title": "Account Network Under Test",
      "type": "object"
    },
    "tags": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": "object"
        },
        {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              }
            ]
          },
          "type": "array"
        }
      ],
      "default": {},
      "title": "Tags"
    },
    "network_settings": {
      "$ref": "#/$defs/NetworkSettings",
      "default": {
        "enabled_network_handlers": [
          "ec2"
        ],
        "interface_endpoints": [],
        "gateway_endpoints": [],
        "interface_endpoint_security_group_ids": null,
        "udp_listen_ports": [],
        "tcp_listen_ports": [],
        "ec2_instance_type": "t3.micro",
        "existing_ec2_instance_profile_name": null,
        "existing_ec2_ami_id": null,
        "network_call_timeout_seconds": 30
      }
    },
    "account_settings": {
      "$ref": "#/$defs/AccountSettings",
      "default": {
        "additional_roles": {},
        "default_test_role_managed_policies": [],
        "default_test_role_inline_policies": {},
        "fixture_scope": "session",
        "allow_shell": false
      }
    }
  },
  "required": [
    "account_id"
  ],
  "title": "CatsAccountUnderTest",
  "type": "object"
}

Fields:

  • account_name (str | None)
  • account_email (str | None)
  • notes (str | None)
  • account_id (ValidAwsAccountId)
  • account_network_under_test (dict[ValidNetworkTargetName, CatsNetworkUnderTest])
  • tags (CatsTags)
  • network_settings (NetworkSettings)
  • account_settings (AccountSettings)

Validators:

  • _hint_unknown_keys
  • _validate_target_names_not_reserved

CatsNetworkUnderTest pydantic-model

Bases: CatsBaseModel

Target network segment to send and receive network plane data.

The key name in cats.yaml defines the name of the generated AccountUnderTest resource within CATS test code.

vpc_id, subnet_ids and existing_security_group_ids each take a literal id (vpc-..., subnet-..., sg-...) or the name of an SSM parameter holding one, which must start with /. The parameter is read in the target account at deploy time.

Attributes:

Name Type Description
vpc_id ValidVpcId

The VPC to work from: a VPC id (vpc-...) or an SSM parameter name (/...) containing one

subnet_ids UniqueList[ValidSubnetId]

A list of subnet ids (subnet-...) or SSM parameter names (/...) containing subnet IDs inside target VPC. The EC2 listener deploys into the first subnet; Lambda handlers and interface endpoints use all of them, so list every subnet (e.g. one per AZ) the Lambda probes should reach from.

subnet_id ValidSubnetId | None

The single-subnet spelling: subnet_id: subnet-1 means subnet_ids: [subnet-1]. Give one or the other, not both. Input only: the loaded model carries subnet_ids alone, so a dumped configuration re-validates.

existing_security_group_ids UniqueList[ValidSecurityGroupId] | None

Security groups to attach to every resource CATS deploys in this target - the EC2 listener and, when the lambda handler is enabled, the probe Lambda. Accepts security group ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time. By default CATS creates its own groups instead: one for the EC2 listener with ingress scoped to the target's tcp_listen_ports and udp_listen_ports, and an egress-only one for the lambdas. Provide your own groups for any other ingress posture (open-all, custom source CIDRs, fully closed), or to speed up cats infra destroy with the lambda handler - CloudFormation cannot delete a stack-owned lambda security group until Lambda releases its Hyperplane ENIs, which takes up to ~20 minutes. Groups CATS does not own are never waited on. The groups must allow the traffic your tests need, in both directions. Outbound is the one most likely to bite: the lambda handlers only reach a destination if the groups permit egress to it, and a group with any explicit egress rule no longer allows all outbound traffic. Inbound matters too - reaching an EC2 listener requires access on its tcp_listen_ports and udp_listen_ports. Traffic a group blocks surfaces as a FAILURE result at test time, not a deploy-time error.

tags CatsTags

Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}

network_settings NetworkSettings

Per-target network settings. Populated with resolved values after config load.

Show JSON schema:
{
  "$defs": {
    "EnabledNetworkHandler": {
      "description": "Built-in network handlers that can be enabled.",
      "enum": [
        "lambda",
        "ec2"
      ],
      "title": "EnabledNetworkHandler",
      "type": "string"
    },
    "GatewayEndpoints": {
      "description": "All currently available GatewayEndpoint types to enable using CATS in all VPCs under\ntest.",
      "enum": [
        "S3",
        "DYNAMODB",
        "S3_EXPRESS"
      ],
      "title": "GatewayEndpoints",
      "type": "string"
    },
    "NetworkSettings": {
      "additionalProperties": false,
      "description": "Network settings for CATS deployed infrastructure.\n\nUsed at global, account, and target levels. Fields have sensible defaults.\n\nInheritance: Settings inherit from parent levels (global \u2192 account \u2192 target).\nA field not explicitly set at a lower level inherits from the parent.\nTo explicitly override with an empty value, set the field to an empty list [].\nExample: setting tcp_listen_ports: [] at account level disables ports even if\nglobal_network_settings has tcp_listen_ports: [8080].\n\nAttributes:\n    enabled_network_handlers: Network handlers to deploy. First in list is used by http_call(), tcp_call(), udp_call().\n    interface_endpoints: Interface VPC endpoints CATS creates in VPCs under test: an escape hatch for a VPC with no\n        endpoint for the service and no DNS already answering for it. The create fails where the VPC has an endpoint\n        or a private hosted zone for the name; where a Resolver rule already sends the name elsewhere the endpoint\n        is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none;\n        where they are not, use the Lambda handler.\n    gateway_endpoints: Gateway endpoints CATS creates in VPCs under test. S3 is what a UDP target's listener needs\n        to write receipts where its subnet has no other path to S3.\n    interface_endpoint_security_group_ids: Security groups for the interface endpoints CATS creates: security group\n        ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        Unset, each interface endpoint is in its VPC's default security group, whose stock inbound rule admits\n        only members of that group; the listener is in CATS's own group, so set this to a group admitting TCP 443\n        from the listener's subnets unless the VPC's default group already does. Targets sharing a VPC must agree\n        on it, as they must on the endpoint lists: the endpoints are created once per VPC. Gateway endpoints take\n        no security group.\n    udp_listen_ports: UDP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound UDP.\n    tcp_listen_ports: TCP ports to open and listen on on deployed EC2 listeners.\n        Each port becomes two ingress rules (IPv4 and IPv6) on the listener's security group; only these ports accept inbound TCP.\n        Combined with udp_listen_ports, at most 30 ports per network target (the default\n        AWS quota is 60 inbound rules per security group).\n    ec2_instance_type: EC2 instance type to deploy in VPCs under test. Defaults to t3.micro.\n    existing_ec2_instance_profile_name: Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.\n    existing_ec2_ami_id: AMI ID (ami-...) or SSM parameter path (/...) resolved in the deploy region at deploy time.\n        Defaults to the latest Amazon Linux AMI CATS selects for the instance type's architecture.\n    network_call_timeout_seconds: Seconds SSM may take to deliver a probe command to the listener before CATS gives up;\n        30 to 2,592,000 (SSM's own bounds). The probe's own network budgets and the Lambda timeout are fixed\n        (see the probe README), not governed by this.",
      "properties": {
        "enabled_network_handlers": {
          "default": [
            "ec2"
          ],
          "description": "Network handlers to deploy; at least one, a declared target exists to be probed. First in list is used by http_call(), tcp_call(), udp_call().",
          "items": {
            "$ref": "#/$defs/EnabledNetworkHandler"
          },
          "minItems": 1,
          "title": "Enabled Network Handlers",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoints": {
          "default": [],
          "description": "AWS service names (ssm, ssmmessages, ec2messages, ...) for interface VPC endpoints CATS creates in the target VPC. An escape hatch for a VPC with no endpoint for the service and no DNS already answering for it: the create fails where the VPC has an endpoint or a private hosted zone for the name, and where a Resolver rule already sends the name elsewhere the endpoint is created but never used. Where the organization's endpoints are reachable the EC2 handler needs none; where they are not, use the Lambda handler.",
          "items": {
            "pattern": "^[a-z0-9][a-z0-9.-]*$",
            "type": "string"
          },
          "title": "Interface Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "gateway_endpoints": {
          "default": [],
          "description": "Gateway VPC endpoints (S3, DYNAMODB, S3_EXPRESS) CATS creates in the target VPC. S3 is what a UDP target's listener needs to write receipts where its subnet has no other path to S3.",
          "items": {
            "$ref": "#/$defs/GatewayEndpoints"
          },
          "title": "Gateway Endpoints",
          "type": "array",
          "uniqueItems": true
        },
        "interface_endpoint_security_group_ids": {
          "anyOf": [
            {
              "items": {
                "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
                "type": "string"
              },
              "type": "array",
              "uniqueItems": true
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Security groups for the interface VPC endpoints CATS creates (sg-... or SSM parameter paths), admitting TCP 443 from the listener subnets. Unset, each endpoint is in its VPC's default group, whose stock rule admits only that group's members, which the listener is not. Targets sharing a VPC must agree on it.",
          "title": "Interface Endpoint Security Group Ids"
        },
        "udp_listen_ports": {
          "default": [],
          "description": "UDP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6).",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Udp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "tcp_listen_ports": {
          "default": [],
          "description": "TCP ports to open and listen on on deployed EC2 listeners. Each port becomes two security group ingress rules (IPv4 and IPv6). Combined with udp_listen_ports, at most 30 ports per network target.",
          "items": {
            "maximum": 65535,
            "minimum": 1,
            "type": "integer"
          },
          "title": "Tcp Listen Ports",
          "type": "array",
          "uniqueItems": true
        },
        "ec2_instance_type": {
          "default": "t3.micro",
          "description": "EC2 instance type of the listener deployed into each network target.",
          "pattern": "^[a-z0-9-]+\\.[a-z0-9-]+$",
          "title": "Ec2 Instance Type",
          "type": "string"
        },
        "existing_ec2_instance_profile_name": {
          "anyOf": [
            {
              "pattern": "^[A-Za-z0-9+=,.@_-]{1,128}$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Existing IAM instance profile name to use for EC2 instances. If not set, CATS creates one.",
          "title": "Existing Ec2 Instance Profile Name"
        },
        "existing_ec2_ami_id": {
          "anyOf": [
            {
              "pattern": "^(ami-[0-9a-f]{8,17}|/[a-zA-Z0-9_.\\-/]+)$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "AMI ID (ami-...) or SSM parameter path (/...) resolved at deploy time. Defaults to the latest Amazon Linux AMI CATS selects.",
          "title": "Existing Ec2 Ami Id"
        },
        "network_call_timeout_seconds": {
          "default": 30,
          "description": "Seconds SSM may take to deliver a probe command before CATS gives up; 30 to 2,592,000, SSM's own bounds. Probe and Lambda budgets are fixed.",
          "maximum": 2592000,
          "minimum": 30,
          "title": "Network Call Timeout Seconds",
          "type": "integer"
        }
      },
      "title": "NetworkSettings",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Target network segment to send and receive network plane data.\n\nThe key name in cats.yaml defines the name of the generated AccountUnderTest\nresource within CATS test code.\n\n``vpc_id``, ``subnet_ids`` and ``existing_security_group_ids`` each take a literal id\n(``vpc-...``, ``subnet-...``, ``sg-...``) or the name of an SSM parameter holding one, which\nmust start with ``/``. The parameter is read in the target account at deploy time.\n\nAttributes:\n    vpc_id: The VPC to work from: a VPC id (vpc-...) or an SSM parameter name (/...) containing one\n    subnet_ids: A list of subnet ids (subnet-...) or SSM parameter names (/...) containing subnet IDs inside target VPC.\n        The EC2 listener deploys into the first subnet; Lambda handlers and interface endpoints use all of them,\n        so list every subnet (e.g. one per AZ) the Lambda probes should reach from.\n    subnet_id: The single-subnet spelling: ``subnet_id: subnet-1`` means ``subnet_ids: [subnet-1]``. Give one\n        or the other, not both. Input only: the loaded model carries ``subnet_ids`` alone, so a dumped\n        configuration re-validates.\n    existing_security_group_ids: Security groups to attach to every resource CATS deploys in this target -\n        the EC2 listener and, when the lambda handler is enabled, the probe Lambda. Accepts security\n        group ids (sg-...) or SSM parameter names (/...) holding one, resolved in the target account at deploy time.\n        By default CATS creates its own groups instead: one for the EC2 listener with ingress scoped to the\n        target's tcp_listen_ports and udp_listen_ports, and an egress-only one for the lambdas. Provide your\n        own groups for any other ingress posture (open-all, custom source CIDRs, fully closed), or to speed\n        up `cats infra destroy` with the lambda handler - CloudFormation cannot delete a stack-owned lambda\n        security group until Lambda releases its Hyperplane ENIs, which takes up to ~20 minutes. Groups CATS\n        does not own are never waited on.\n        The groups must allow the traffic your tests need, in both directions. Outbound is the one most\n        likely to bite: the lambda handlers only reach a destination if the groups permit egress to it,\n        and a group with any explicit egress rule no longer allows all outbound traffic. Inbound matters\n        too - reaching an EC2 listener requires access on its tcp_listen_ports and udp_listen_ports.\n        Traffic a group blocks surfaces as a FAILURE result at test time, not a deploy-time error.\n    tags: Metadata for filtering. List format: ['flag', {'key': 'value'}] or dict format: {'key': 'value'}\n    network_settings: Per-target network settings. Populated with resolved values after config load.",
  "oneOf": [
    {
      "required": [
        "subnet_id"
      ]
    },
    {
      "required": [
        "subnet_ids"
      ]
    }
  ],
  "properties": {
    "vpc_id": {
      "pattern": "^(vpc-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
      "title": "Vpc Id",
      "type": "string"
    },
    "subnet_id": {
      "anyOf": [
        {
          "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Subnet Id"
    },
    "subnet_ids": {
      "default": [],
      "items": {
        "pattern": "^(subnet-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
        "type": "string"
      },
      "title": "Subnet Ids",
      "type": "array",
      "uniqueItems": true
    },
    "existing_security_group_ids": {
      "anyOf": [
        {
          "items": {
            "pattern": "^(sg-[0-9a-f]+|/[a-zA-Z0-9_.\\-/]+)$",
            "type": "string"
          },
          "type": "array",
          "uniqueItems": true
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Existing Security Group Ids"
    },
    "tags": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": "object"
        },
        {
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              }
            ]
          },
          "type": "array"
        }
      ],
      "default": {},
      "title": "Tags"
    },
    "network_settings": {
      "$ref": "#/$defs/NetworkSettings",
      "default": {
        "enabled_network_handlers": [
          "ec2"
        ],
        "interface_endpoints": [],
        "gateway_endpoints": [],
        "interface_endpoint_security_group_ids": null,
        "udp_listen_ports": [],
        "tcp_listen_ports": [],
        "ec2_instance_type": "t3.micro",
        "existing_ec2_instance_profile_name": null,
        "existing_ec2_ami_id": null,
        "network_call_timeout_seconds": 30
      }
    }
  },
  "required": [
    "vpc_id"
  ],
  "title": "CatsNetworkUnderTest",
  "type": "object"
}

Config:

  • json_schema_extra: {'oneOf': [{'required': ['subnet_id']}, {'required': ['subnet_ids']}]}

Fields:

  • vpc_id (ValidVpcId)
  • subnet_id (ValidSubnetId | None)
  • subnet_ids (UniqueList[ValidSubnetId])
  • existing_security_group_ids (UniqueList[ValidSecurityGroupId] | None)
  • tags (CatsTags)
  • network_settings (NetworkSettings)

Validators:

  • _hint_unknown_keys
  • _normalize_subnet_ids

CatsAdditionalTestRole pydantic-model

Bases: CatsBaseModel

CATS deploys one role by default: this configuration block allows defining additional roles.

Each entry of additional_roles is keyed by the role's name: account.role.<name> returns a session for it, and the deployed IAM role is named {cfn_stack_prefix}{account_keyname}-. A role declares at least one of managed_policies and inline_policies.

Attributes:

Name Type Description
managed_policies UniqueList[ValidManagedPolicy]

A list of AWS managed IAM policy names or full policy ARNs to attach to this role. Full list available at https://docs.aws.amazon.com/aws-managed-policy/latest/reference/policy-list.html

inline_policies dict[ValidIamPolicyName, PolicyDocument]

Inline IAM policies to attach to this role, keyed by policy name. Each value is either a policy document (written inline in yaml/JSON) or a string path to a JSON policy file, resolved relative to cats.yaml.

Show JSON schema:
{
  "additionalProperties": false,
  "anyOf": [
    {
      "properties": {
        "managed_policies": {
          "minItems": 1
        }
      },
      "required": [
        "managed_policies"
      ]
    },
    {
      "properties": {
        "inline_policies": {
          "minProperties": 1
        }
      },
      "required": [
        "inline_policies"
      ]
    }
  ],
  "description": "CATS deploys one role by default: this configuration block allows defining additional roles.\n\nEach entry of `additional_roles` is keyed by the role's name: `account.role.<name>` returns a session\nfor it, and the deployed IAM role is named {cfn_stack_prefix}{account_keyname}-<name>. A role\ndeclares at least one of `managed_policies` and `inline_policies`.\n\nAttributes:\n    managed_policies: A list of AWS managed IAM policy names or full policy ARNs to attach to this role.\n        Full list available at https://docs.aws.amazon.com/aws-managed-policy/latest/reference/policy-list.html\n    inline_policies: Inline IAM policies to attach to this role, keyed by policy name.\n        Each value is either a policy document (written inline in yaml/JSON) or a string\n        path to a JSON policy file, resolved relative to cats.yaml.",
  "properties": {
    "managed_policies": {
      "default": [],
      "items": {
        "pattern": "^(arn:[a-z0-9-]+:iam::(aws|[0-9]{12}):policy/[A-Za-z0-9+=,.@_/-]+|[A-Za-z0-9+=,.@_/-]+)$",
        "type": "string"
      },
      "title": "Managed Policies",
      "type": "array",
      "uniqueItems": true
    },
    "inline_policies": {
      "default": {},
      "patternProperties": {
        "^[A-Za-z0-9+=,.@_-]+$": {
          "anyOf": [
            {
              "additionalProperties": true,
              "required": [
                "Statement"
              ],
              "type": "object"
            },
            {
              "type": "string"
            }
          ]
        }
      },
      "propertyNames": {
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9+=,.@_-]+$"
      },
      "title": "Inline Policies",
      "type": "object"
    }
  },
  "title": "CatsAdditionalTestRole",
  "type": "object"
}

Config:

  • json_schema_extra: {'anyOf': [{'required': ['managed_policies'], 'properties': {'managed_policies': {'minItems': 1}}}, {'required': ['inline_policies'], 'properties': {'inline_policies': {'minProperties': 1}}}]}

Fields:

  • managed_policies (UniqueList[ValidManagedPolicy])
  • inline_policies (dict[ValidIamPolicyName, PolicyDocument])

Validators:

  • _hint_unknown_keys
  • _require_a_policy

CatsReportingSettings pydantic-model

Bases: CatsBaseModel

Settings for CATS reporting while running Pytest tests.

Report writers are dispatched at the end of a pytest session based on report_formats. Multiple formats can be emitted from a single run — see the Reporting guide for the full output contract and the OSCAL pytest_cats_standards hook.

Attributes:

Name Type Description
enabled bool

Whether to emit any reports at all. False disables every writer including junit and securityhub, and withholds the securityhub:BatchImportFindings grant from the test role at deploy.

report_formats UniqueList[ReportFormat]

Writers to run, in order. Each value corresponds to a :class:ReportFormat member (cats_json, oscal_ar, junit, securityhub). Defaults to [cats_json]; at least one is required (to write nothing, set enabled to false). List securityhub last: the import is network-bound and the files before it never wait on it.

custom_markers list[str]

Marker names permitted in @cats(...) kwargs. Values surface in both the CATS JSON and OSCAL outputs (as top-level keys and Observation.props[] respectively).

oscal_import_ap_href str

URI reference recorded as import-ap.href in the OSCAL assessment results — point it at your assessment plan document. Defaults to an empty reference.

securityhub CatsSecurityHubSettings

Region and severity for the securityhub format; see :class:CatsSecurityHubSettings. Ignored unless securityhub is in report_formats.

report_dir str | None

Directory for every report file (report.json, assessment-results.json, junit.xml, securityhub-findings.json and their timestamped variants). A relative path resolves against the directory that holds cats.yaml, like inline_policies file paths. --cats-report-dir on the pytest command line overrides it. Unset means the current working directory.

latest_files bool

Write the fixed-name files (report.json, assessment-results.json, junit.xml, securityhub-findings.json), overwritten on every run so they always describe the newest run.

timestamped_files bool

Also write one immutable set per run, named with the run id: report-<run_id>.json, assessment-results-<run_id>.json, junit-<run_id>.xml, securityhub-findings-<run_id>.json. The run id is YYYYMMDDTHHMMSSZ (UTC) and is also recorded inside every file, so the files of one run can be matched. A run that writes timestamped files claims its id when the session starts, so two sessions starting in the same second never share one. With latest_files and timestamped_files both false no report file is written at all; securityhub still imports its findings. enabled: false is the switch that disables every writer.

Show JSON schema:
{
  "$defs": {
    "CatsSecurityHubSettings": {
      "additionalProperties": false,
      "description": "Settings for the ``securityhub`` report format.\n\nAttributes:\n    aws_region: Region whose Security Hub receives the findings, the same in every account under\n        test. Defaults to ``cats_deployment_settings.aws_region``. The test role's import grant\n        is scoped to this Region's product ARN, so changing it requires ``cats infra deploy``.\n    failed_severity: ``Severity.Label`` of the finding for a failed test. Defaults to ``HIGH``:\n        a control that does not enforce. Errors are ``MEDIUM``, expected failures ``LOW``,\n        passes and skips ``INFORMATIONAL``.\n    only_with_standard: Import findings only for tests that carry a standard (``@cats(standard_name=...)``),\n        the default: a compliance finding needs a control to attest to, and ``report.json`` still records\n        every test. ``false`` imports every test that used an account fixture, typed ``CATS`` when it\n        carries no standard. Removing ``@cats`` from a test stops updating its finding, which stays\n        ``ACTIVE`` in Security Hub for 90 days.",
      "properties": {
        "aws_region": {
          "anyOf": [
            {
              "pattern": "^[a-z]{2}[a-z0-9-]*-[0-9]+$",
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Region whose Security Hub receives the findings. Defaults to cats_deployment_settings.aws_region.",
          "title": "Aws Region"
        },
        "failed_severity": {
          "$ref": "#/$defs/SecurityHubSeverity",
          "default": "HIGH",
          "description": "Severity label of the finding for a failed test."
        },
        "only_with_standard": {
          "default": true,
          "description": "Import findings only for tests that carry a standard. false imports every test that used an account fixture.",
          "title": "Only With Standard",
          "type": "boolean"
        }
      },
      "title": "CatsSecurityHubSettings",
      "type": "object"
    },
    "ReportFormat": {
      "description": "Supported report output formats.\n\nValues map to report writers that run at the end of a pytest session.\nSee ``cats.report_writers`` for implementations.\n\nMembers:\n    CATS_JSON: Native CATS report written to ``report.json``. The historical\n        default and the format consumed by CATS's own tooling.\n    OSCAL_AR: OSCAL 1.2.1 Assessment Results written to\n        ``assessment-results.json``. Suitable for import into\n        compliance-trestle workspaces and other OSCAL tooling.\n    JUNIT: JUnit XML written to ``junit.xml`` for CI systems. Produced by\n        pytest's own junitxml plugin, which CATS switches on at configure time\n        and feeds a property per standard, account, tag and marker on every\n        testcase; the testsuite carries the run id.\n    SECURITYHUB: One AWS Security Hub finding per test per account under test,\n        imported into each account through its CATS test role, so failures\n        surface where control state is already watched and aggregated. Writes\n        ``securityhub-findings.json`` (what was sent, and per-account delivery\n        status) when report files are on; imports either way. Settings under\n        ``reporting.securityhub``; requires ``cats infra deploy`` after enabling,\n        for the ``securityhub:BatchImportFindings`` grant on the test role.",
      "enum": [
        "cats_json",
        "oscal_ar",
        "junit",
        "securityhub"
      ],
      "title": "ReportFormat",
      "type": "string"
    },
    "SecurityHubSeverity": {
      "description": "ASFF ``Severity.Label`` values, as Security Hub defines them.",
      "enum": [
        "CRITICAL",
        "HIGH",
        "MEDIUM",
        "LOW",
        "INFORMATIONAL"
      ],
      "title": "SecurityHubSeverity",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Settings for CATS reporting while running Pytest tests.\n\nReport writers are dispatched at the end of a pytest session based on\n``report_formats``. Multiple formats can be emitted from a single run \u2014\nsee the Reporting guide for the full output contract and the OSCAL\n``pytest_cats_standards`` hook.\n\nAttributes:\n    enabled: Whether to emit any reports at all. ``False`` disables every\n        writer including ``junit`` and ``securityhub``, and withholds the\n        ``securityhub:BatchImportFindings`` grant from the test role at deploy.\n    report_formats: Writers to run, in order. Each value corresponds to a\n        :class:`ReportFormat` member (``cats_json``, ``oscal_ar``, ``junit``,\n        ``securityhub``). Defaults to ``[cats_json]``; at least one is required\n        (to write nothing, set ``enabled`` to false). List ``securityhub`` last: the\n        import is network-bound and the files before it never wait on it.\n    custom_markers: Marker names permitted in ``@cats(...)`` kwargs. Values\n        surface in both the CATS JSON and OSCAL outputs (as top-level keys\n        and ``Observation.props[]`` respectively).\n    oscal_import_ap_href: URI reference recorded as ``import-ap.href`` in the\n        OSCAL assessment results \u2014 point it at your assessment plan document.\n        Defaults to an empty reference.\n    securityhub: Region and severity for the ``securityhub`` format; see\n        :class:`CatsSecurityHubSettings`. Ignored unless ``securityhub`` is in\n        ``report_formats``.\n    report_dir: Directory for every report file (``report.json``,\n        ``assessment-results.json``, ``junit.xml``, ``securityhub-findings.json``\n        and their timestamped variants). A relative path resolves against the\n        directory that holds ``cats.yaml``, like ``inline_policies`` file paths.\n        ``--cats-report-dir`` on the pytest command line overrides it. Unset\n        means the current working directory.\n    latest_files: Write the fixed-name files (``report.json``,\n        ``assessment-results.json``, ``junit.xml``, ``securityhub-findings.json``),\n        overwritten on every run so they always describe the newest run.\n    timestamped_files: Also write one immutable set per run, named with the\n        run id: ``report-<run_id>.json``, ``assessment-results-<run_id>.json``,\n        ``junit-<run_id>.xml``, ``securityhub-findings-<run_id>.json``. The run id is\n        ``YYYYMMDDTHHMMSSZ`` (UTC) and is also recorded inside every file, so the\n        files of one run can be matched. A run that writes timestamped files claims\n        its id when the session starts, so two sessions starting in the same second\n        never share one. With ``latest_files`` and ``timestamped_files`` both ``false``\n        no report file is written at all; ``securityhub`` still imports its findings.\n        ``enabled: false`` is the switch that disables every writer.",
  "properties": {
    "enabled": {
      "default": true,
      "title": "Enabled",
      "type": "boolean"
    },
    "report_formats": {
      "default": [
        "cats_json"
      ],
      "items": {
        "$ref": "#/$defs/ReportFormat"
      },
      "minItems": 1,
      "title": "Report Formats",
      "type": "array",
      "uniqueItems": true
    },
    "custom_markers": {
      "default": [],
      "items": {
        "not": {
          "enum": [
            "control_group",
            "control_ids",
            "filterwarnings",
            "parametrize",
            "skip",
            "skipif",
            "standard_name",
            "usefixtures",
            "xfail"
          ]
        },
        "pattern": "^(?!cats_)[A-Za-z_][A-Za-z0-9_]*$",
        "type": "string"
      },
      "title": "Custom Markers",
      "type": "array",
      "uniqueItems": true
    },
    "oscal_import_ap_href": {
      "default": "",
      "title": "Oscal Import Ap Href",
      "type": "string"
    },
    "securityhub": {
      "$ref": "#/$defs/CatsSecurityHubSettings",
      "default": {
        "aws_region": null,
        "failed_severity": "HIGH",
        "only_with_standard": true
      }
    },
    "report_dir": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Report Dir"
    },
    "latest_files": {
      "default": true,
      "title": "Latest Files",
      "type": "boolean"
    },
    "timestamped_files": {
      "default": false,
      "title": "Timestamped Files",
      "type": "boolean"
    }
  },
  "title": "CatsReportingSettings",
  "type": "object"
}

Fields:

  • enabled (bool)
  • report_formats (UniqueList[ReportFormat])
  • custom_markers (list[str])
  • oscal_import_ap_href (str)
  • securityhub (CatsSecurityHubSettings)
  • report_dir (str | None)
  • latest_files (bool)
  • timestamped_files (bool)

Validators:

  • _hint_unknown_keys
  • _validate_custom_markers → custom_markers
  • _reject_removed_junit_enabled

CatsSecurityHubSettings pydantic-model

Bases: CatsBaseModel

Settings for the securityhub report format.

Attributes:

Name Type Description
aws_region str | None

Region whose Security Hub receives the findings, the same in every account under test. Defaults to cats_deployment_settings.aws_region. The test role's import grant is scoped to this Region's product ARN, so changing it requires cats infra deploy.

failed_severity SecurityHubSeverity

Severity.Label of the finding for a failed test. Defaults to HIGH: a control that does not enforce. Errors are MEDIUM, expected failures LOW, passes and skips INFORMATIONAL.

only_with_standard bool

Import findings only for tests that carry a standard (@cats(standard_name=...)), the default: a compliance finding needs a control to attest to, and report.json still records every test. false imports every test that used an account fixture, typed CATS when it carries no standard. Removing @cats from a test stops updating its finding, which stays ACTIVE in Security Hub for 90 days.

Show JSON schema:
{
  "$defs": {
    "SecurityHubSeverity": {
      "description": "ASFF ``Severity.Label`` values, as Security Hub defines them.",
      "enum": [
        "CRITICAL",
        "HIGH",
        "MEDIUM",
        "LOW",
        "INFORMATIONAL"
      ],
      "title": "SecurityHubSeverity",
      "type": "string"
    }
  },
  "additionalProperties": false,
  "description": "Settings for the ``securityhub`` report format.\n\nAttributes:\n    aws_region: Region whose Security Hub receives the findings, the same in every account under\n        test. Defaults to ``cats_deployment_settings.aws_region``. The test role's import grant\n        is scoped to this Region's product ARN, so changing it requires ``cats infra deploy``.\n    failed_severity: ``Severity.Label`` of the finding for a failed test. Defaults to ``HIGH``:\n        a control that does not enforce. Errors are ``MEDIUM``, expected failures ``LOW``,\n        passes and skips ``INFORMATIONAL``.\n    only_with_standard: Import findings only for tests that carry a standard (``@cats(standard_name=...)``),\n        the default: a compliance finding needs a control to attest to, and ``report.json`` still records\n        every test. ``false`` imports every test that used an account fixture, typed ``CATS`` when it\n        carries no standard. Removing ``@cats`` from a test stops updating its finding, which stays\n        ``ACTIVE`` in Security Hub for 90 days.",
  "properties": {
    "aws_region": {
      "anyOf": [
        {
          "pattern": "^[a-z]{2}[a-z0-9-]*-[0-9]+$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Region whose Security Hub receives the findings. Defaults to cats_deployment_settings.aws_region.",
      "title": "Aws Region"
    },
    "failed_severity": {
      "$ref": "#/$defs/SecurityHubSeverity",
      "default": "HIGH",
      "description": "Severity label of the finding for a failed test."
    },
    "only_with_standard": {
      "default": true,
      "description": "Import findings only for tests that carry a standard. false imports every test that used an account fixture.",
      "title": "Only With Standard",
      "type": "boolean"
    }
  },
  "title": "CatsSecurityHubSettings",
  "type": "object"
}

Fields:

Validators:

  • _hint_unknown_keys

aws_region = None pydantic-field

Region whose Security Hub receives the findings. Defaults to cats_deployment_settings.aws_region.

failed_severity = SecurityHubSeverity.HIGH pydantic-field

Severity label of the finding for a failed test.

only_with_standard = True pydantic-field

Import findings only for tests that carry a standard. false imports every test that used an account fixture.

CatsTestSelectionSettings pydantic-model

Bases: CatsBaseModel

Which tests run against this deployment, decided in configuration rather than on the command line.

A command-line selector (-k, -m, --deselect) narrows a run, and a deselected control vanishes from the report with no record of why. These keys instead define the run's scope in the configuration itself, and every test they hold back is recorded as not_run with its reason, in every report format.

Attributes:

Name Type Description
provides UniqueList[Annotated[str, Field(min_length=1)]]

The requirements this deployment satisfies: free-form names matching @cats_requires(...) on tests. A test runs only when every requirement it declares is provided; otherwise it is not_run with the gap named. Unioned with what every pytest_cats_provides hook returns, so a test pack can provide its defaults.

excluded list[TestSelectionExclusion]

Tests held back by marker value, each with a reason (see :class:TestSelectionExclusion). A test matching any entry is not_run. An entry that matches no test is reported in the terminal summary and in run.selection: not an error, since a -k run or a renamed test produces it, but usually a sign that the exclusion is not doing what was intended.

Show JSON schema:
{
  "$defs": {
    "TestSelectionExclusion": {
      "additionalProperties": false,
      "description": "One entry of ``test_selection.excluded``: a test carrying one of ``values`` for ``marker`` does not run.\n\nAttributes:\n    marker: The marker to match, by the name written on the test: ``standard_name`` (the ``@cats``\n        keyword), ``cats_requires`` (the decorator), or a name declared in ``reporting.custom_markers``.\n        Anything else is a configuration error, never a silent no-op: an exclusion that matches\n        nothing would let the tests it was meant to hold back into the run.\n    values: The values that exclude a test, compared for equality with the marker's value:\n        a string, or a YAML boolean, so ``true`` matches ``@cats(mutating=True)`` and ``\"true\"``\n        does not.\n    reason: Why these tests do not run here. Recorded on every excluded test as its ``not_run``\n        reason in every report format, so the control stays in the evidence together with the\n        decision that kept it out.",
      "properties": {
        "marker": {
          "description": "standard_name, cats_requires, or a marker declared in reporting.custom_markers.",
          "minLength": 1,
          "title": "Marker",
          "type": "string"
        },
        "values": {
          "description": "Marker values that exclude a test; equality on the marker's value.",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "minItems": 1,
          "title": "Values",
          "type": "array",
          "uniqueItems": true
        },
        "reason": {
          "description": "Why these tests do not run here; recorded as each excluded test's not_run reason.",
          "minLength": 1,
          "title": "Reason",
          "type": "string"
        }
      },
      "required": [
        "marker",
        "values",
        "reason"
      ],
      "title": "TestSelectionExclusion",
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Which tests run against this deployment, decided in configuration rather than on the command line.\n\nA command-line selector (``-k``, ``-m``, ``--deselect``) narrows a run, and a deselected control\nvanishes from the report with no record of why. These keys instead define the run's scope in\nthe configuration itself, and every test they hold back is recorded as ``not_run`` with its\nreason, in every report format.\n\nAttributes:\n    provides: The requirements this deployment satisfies: free-form names matching\n        ``@cats_requires(...)`` on tests. A test runs only when every requirement it declares is\n        provided; otherwise it is ``not_run`` with the gap named. Unioned with what every\n        ``pytest_cats_provides`` hook returns, so a test pack can provide its defaults.\n    excluded: Tests held back by marker value, each with a reason (see\n        :class:`TestSelectionExclusion`). A test matching any entry is ``not_run``. An entry that\n        matches no test is reported in the terminal summary and in ``run.selection``: not an\n        error, since a ``-k`` run or a renamed test produces it, but usually a sign that the\n        exclusion is not doing what was intended.",
  "properties": {
    "provides": {
      "default": [],
      "description": "Requirements this deployment satisfies; a test requiring one not listed here is not run.",
      "items": {
        "minLength": 1,
        "type": "string"
      },
      "title": "Provides",
      "type": "array",
      "uniqueItems": true
    },
    "excluded": {
      "default": [],
      "description": "Tests held back by marker value, each with a reason; recorded as not_run.",
      "items": {
        "$ref": "#/$defs/TestSelectionExclusion"
      },
      "title": "Excluded",
      "type": "array"
    }
  },
  "title": "CatsTestSelectionSettings",
  "type": "object"
}

Fields:

Validators:

  • _hint_unknown_keys

excluded = [] pydantic-field

Tests held back by marker value, each with a reason; recorded as not_run.

provides = [] pydantic-field

Requirements this deployment satisfies; a test requiring one not listed here is not run.

TestSelectionExclusion pydantic-model

Bases: CatsBaseModel

One entry of test_selection.excluded: a test carrying one of values for marker does not run.

Attributes:

Name Type Description
marker str

The marker to match, by the name written on the test: standard_name (the @cats keyword), cats_requires (the decorator), or a name declared in reporting.custom_markers. Anything else is a configuration error, never a silent no-op: an exclusion that matches nothing would let the tests it was meant to hold back into the run.

values UniqueList[str | StrictBool]

The values that exclude a test, compared for equality with the marker's value: a string, or a YAML boolean, so true matches @cats(mutating=True) and "true" does not.

reason str

Why these tests do not run here. Recorded on every excluded test as its not_run reason in every report format, so the control stays in the evidence together with the decision that kept it out.

Show JSON schema:
{
  "additionalProperties": false,
  "description": "One entry of ``test_selection.excluded``: a test carrying one of ``values`` for ``marker`` does not run.\n\nAttributes:\n    marker: The marker to match, by the name written on the test: ``standard_name`` (the ``@cats``\n        keyword), ``cats_requires`` (the decorator), or a name declared in ``reporting.custom_markers``.\n        Anything else is a configuration error, never a silent no-op: an exclusion that matches\n        nothing would let the tests it was meant to hold back into the run.\n    values: The values that exclude a test, compared for equality with the marker's value:\n        a string, or a YAML boolean, so ``true`` matches ``@cats(mutating=True)`` and ``\"true\"``\n        does not.\n    reason: Why these tests do not run here. Recorded on every excluded test as its ``not_run``\n        reason in every report format, so the control stays in the evidence together with the\n        decision that kept it out.",
  "properties": {
    "marker": {
      "description": "standard_name, cats_requires, or a marker declared in reporting.custom_markers.",
      "minLength": 1,
      "title": "Marker",
      "type": "string"
    },
    "values": {
      "description": "Marker values that exclude a test; equality on the marker's value.",
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "boolean"
          }
        ]
      },
      "minItems": 1,
      "title": "Values",
      "type": "array",
      "uniqueItems": true
    },
    "reason": {
      "description": "Why these tests do not run here; recorded as each excluded test's not_run reason.",
      "minLength": 1,
      "title": "Reason",
      "type": "string"
    }
  },
  "required": [
    "marker",
    "values",
    "reason"
  ],
  "title": "TestSelectionExclusion",
  "type": "object"
}

Fields:

Validators:

  • _hint_unknown_keys

marker pydantic-field

standard_name, cats_requires, or a marker declared in reporting.custom_markers.

reason pydantic-field

Why these tests do not run here; recorded as each excluded test's not_run reason.

values pydantic-field

Marker values that exclude a test; equality on the marker's value.

SecurityHubSeverity

Bases: StrEnum

ASFF Severity.Label values, as Security Hub defines them.

ReportFormat

Bases: StrEnum

Supported report output formats.

Values map to report writers that run at the end of a pytest session. See cats.report_writers for implementations.

Members

CATS_JSON: Native CATS report written to report.json. The historical default and the format consumed by CATS's own tooling. OSCAL_AR: OSCAL 1.2.1 Assessment Results written to assessment-results.json. Suitable for import into compliance-trestle workspaces and other OSCAL tooling. JUNIT: JUnit XML written to junit.xml for CI systems. Produced by pytest's own junitxml plugin, which CATS switches on at configure time and feeds a property per standard, account, tag and marker on every testcase; the testsuite carries the run id. SECURITYHUB: One AWS Security Hub finding per test per account under test, imported into each account through its CATS test role, so failures surface where control state is already watched and aggregated. Writes securityhub-findings.json (what was sent, and per-account delivery status) when report files are on; imports either way. Settings under reporting.securityhub; requires cats infra deploy after enabling, for the securityhub:BatchImportFindings grant on the test role.

EnabledNetworkHandler

Bases: StrEnum

Built-in network handlers that can be enabled.

GatewayEndpoints

Bases: StrEnum

All currently available GatewayEndpoint types to enable using CATS in all VPCs under test.

logical_id_part property

A CloudFormation logical id segment: letters and digits only.

service_name property

The service segment of the endpoint's ServiceName: s3express for S3 Express One Zone, else the lowercase member.