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:forbidcase_sensitive:True
Fields:
-
cats_deployment_settings(CatsDeploymentSettings) -
global_network_settings(NetworkSettings) -
global_account_settings(AccountSettings) -
accounts_under_test(dict[ValidAccountKeyname, CatsAccountUnderTest]) -
reporting(CatsReportingSettings) -
test_selection(CatsTestSelectionSettings)
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 |
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:
-
enabled_network_handlers(UniqueList[EnabledNetworkHandler]) -
interface_endpoints(UniqueList[Annotated[str, Field(pattern='^[a-z0-9][a-z0-9.-]*$')]]) -
gateway_endpoints(UniqueList[GatewayEndpoints]) -
interface_endpoint_security_group_ids(UniqueList[ValidSecurityGroupId] | None) -
udp_listen_ports(UniqueList[ValidListenPort]) -
tcp_listen_ports(UniqueList[ValidListenPort]) -
ec2_instance_type(str) -
existing_ec2_instance_profile_name(str | None) -
existing_ec2_ami_id(str | None) -
network_call_timeout_seconds(int)
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:
-
additional_roles(dict[ValidRoleName, CatsAdditionalTestRole]) -
default_test_role_managed_policies(UniqueList[ValidManagedPolicy]) -
default_test_role_inline_policies(dict[ValidIamPolicyName, PolicyDocument]) -
fixture_scope(Literal['session', 'function', 'module', 'class']) -
allow_shell(bool)
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 |
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: |
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 |
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}-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. |
report_formats |
UniqueList[ReportFormat]
|
Writers to run, in order. Each value corresponds to a
:class: |
custom_markers |
list[str]
|
Marker names permitted in |
oscal_import_ap_href |
str
|
URI reference recorded as |
securityhub |
CatsSecurityHubSettings
|
Region and severity for the |
report_dir |
str | None
|
Directory for every report file ( |
latest_files |
bool
|
Write the fixed-name files ( |
timestamped_files |
bool
|
Also write one immutable set per run, named with the
run id: |
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 |
failed_severity |
SecurityHubSeverity
|
|
only_with_standard |
bool
|
Import findings only for tests that carry a standard ( |
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:
-
aws_region(str | None) -
failed_severity(SecurityHubSeverity) -
only_with_standard(bool)
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
|
excluded |
list[TestSelectionExclusion]
|
Tests held back by marker value, each with a reason (see
:class: |
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:
-
provides(UniqueList[Annotated[str, Field(min_length=1)]]) -
excluded(list[TestSelectionExclusion])
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: |
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 |
reason |
str
|
Why these tests do not run here. Recorded on every excluded test as its |
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.