CATS - Control Acceptance Testing Suite
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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.