Skip to main content

CATS - Control Acceptance Testing Suite

PyPI Python License

CATS proves your AWS security controls and applications work by testing them, not just by checking configuration. Network paths, data perimeters, SCP and IAM enforcement, service behavior: all probed and proven through CLI, MCP, or pytest tests, across as many accounts and regions as you point it at.

from cats import AccountUnderTest, CatsNetworkResponse, cats


@cats(standard_name="SOC2-CC6.6")
def test_prod_cannot_reach_dev(
    prod_account: AccountUnderTest,
    dev_account: AccountUnderTest,
) -> None:
    """Prove the production network cannot reach development."""
    target = dev_account.private.ec2_dns_name

    result = prod_account.private.tcp_call(target, 443)

    # TIMEOUT: no response, consistent with a silent drop. REFUSED would mean the path is open.
    assert result == CatsNetworkResponse.TIMEOUT

CATS deploys ephemeral test infrastructure into each account under test: IAM roles, plus EC2 listeners and Lambda probes where you define network targets. Each account is exposed as a typed pytest fixture, and CATS reports what the tests proved, including OSCAL assessment results for compliance evidence. AI agents can interact with the deployed infrastructure through MCP or the cats run CLI.

How it works

cats infra deploy  →  cats test  →  cats infra destroy

A parent account assumes a deploy role in each account under test to create a CloudFormation stack (test role, optional network listeners), tests run against those resources through least-privilege test roles, and the stack is destroyed. Infrastructure is ephemeral by design: deploy, test, destroy, every cycle.

Security note: CATS runs with high privilege across many accounts using hub-and-spoke IAM trust. Treat its parent account, its deploy role, and its configuration as production security infrastructure. See the identity model and security model.

Use CATS with AI agents

cats mcp (install aws-cats[mcp]) exposes deployed CATS infrastructure as MCP tools. cats run provides the probing operations through a shell interface with JSON output, with no optional extra to install.

Agents can use either interface to inspect accounts and test network paths before writing repeatable pytest tests. Generate the supporting agent documentation with cats prompts --all; start initial configuration with cats prompts setup.

See Agentic and the MCP reference.

Install

Requires Python 3.11+.

uv init && uv add aws-cats    # in a new directory; or: pip install aws-cats

Quickstart

You need AWS credentials in a parent account, and a role CATS can assume in each account under test (AWSControlTowerExecution in Control Tower organizations, OrganizationAccountAccessRole, or your own).

export ACCOUNT_ID=<your_account_id>
uv run cats init --parent-account-id $ACCOUNT_ID --deploy-role-name "AWSControlTowerExecution"

Add an account under test to the generated cats.yaml:

global_account_settings:
  additional_roles:
    readonly:
      managed_policies:
        - ReadOnlyAccess

accounts_under_test:
  myaccount:
    account_id: "123456789012"

Deploy, write a test, run it, clean up:

uv run cats infra deploy myaccount
from cats import AccountUnderTest


def test_sts_works(myaccount_account: AccountUnderTest) -> None:
    result = myaccount_account.role.readonly.client("sts").get_caller_identity()
    assert result["Account"] == myaccount_account.account_id
uv run cats test
uv run cats infra destroy myaccount

Every account in cats.yaml becomes a <name>_account fixture. cats generate-types gives the fixtures real types for IDE autocomplete and mypy (install aws-cats[types] for the typed boto3 clients behind .client(...)). The full walkthrough is in the quickstart.

Documentation

The rendered documentation is at awslabs.github.io/cats; the same pages are in docs/ as Markdown, where the tabs, admonitions and API reference blocks render as plain text.

Getting started Installation, first test, multi-account setup
Concepts How it works, identity model, network testing, versioning and compatibility
Guides Writing tests, configuration, infrastructure, reporting and OSCAL, standards registry
Security Threat model, listener authentication, least privilege
Troubleshooting When deploys or tests misbehave

Run cats --help for the complete command reference, or see the CLI reference (commands, exit codes, streams).

Developing

uv sync
uv run pre-commit run --all-files   # lint, format, types, license headers
uv run pytest tests/unit_tests/
uv run mkdocs serve                 # docs at http://127.0.0.1:8000

The integration suite deploys real stacks and is run on its own, uv run pytest tests/integration/, with the environment variables tests/integration/constants.py reads. Run the two suites separately: the integration suite's conftest.py declares itself a test pack, and a pytest tests/ run that collects both loads it too late for that, which CATS reports as a warning.

CATS is published as open source but is not currently accepting contributions. Bug reports are welcome as GitHub issues; potential security issues go through SECURITY.md instead.

Usage attribution

CATS adds AwsCats/<version> to the HTTP User-Agent header of the AWS API calls it makes, so that usage of CATS can be attributed to the project in AWS service logs. A test suite built on CATS may declare its own name and version through the pytest_cats_test_pack hook, which CATS adds to the same header as AwsCatsPack/<name>#<version>, optionally followed by release metadata the suite declares. Nothing else is added, collected, or transmitted.

Security

Report potential security issues according to SECURITY.md, not as public GitHub issues.

License

Apache-2.0. See LICENSE and NOTICE.

Metadata

Release files for aws-cats 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aws-cats 1.0.0
File Size Uploaded Provenance Actions
aws_cats-1.0.0.tar.gz 559.5 kB With provenance Details for aws_cats-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aws-cats 1.0.0
File Interpreter ABI Platform Actions
aws_cats-1.0.0-py3-none-any.whl Python 3 none any Details for aws_cats-1.0.0-py3-none-any.whl

Total release size: 826.6 kB

Release files / aws_cats-1.0.0.tar.gz

Download URL aws_cats-1.0.0.tar.gz
Size 559.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fe85393a63d4cf5873c7a21f6e5cff2c84e51b6d8ae65d104ca093483059e9e7
BLAKE2b-256 checksum
How to use checksums
d6efaa6fbd57ab76c9ef65c4a9197a68de7fc60b29bf5519257dc75e2feba89c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / aws_cats-1.0.0-py3-none-any.whl

Download URL aws_cats-1.0.0-py3-none-any.whl
Size 267.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6af5eae280881f9e56797f67d3f8508031272c5bcdf7681006fd93e50e4938fe
BLAKE2b-256 checksum
How to use checksums
2978ce0fb9e7506b3cd73721b91c30766e7fdf8df092d5927dd9081531740df1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for aws-cats 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aws_cats-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page