Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

feat(cloudformation): check Capabilities without AUTH via CFN_ENFORCE_CAPABILITIES (#1940)

iot-rocket567d86d535e1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4afdca46..060cd41f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,11 @@ Versioning follows [Semantic Versioning](https://semver.org/).
### Added
+- **CloudFormation — `Capabilities` check without `AUTH`** — `CFN_ENFORCE_CAPABILITIES=1` refuses a template whose IAM resources or macros the request does not acknowledge also without `AUTH=true`, as AWS always does.
+
+### Fixed
+
+- **CloudFormation — nested stack with a `Transform`** — where `Capabilities` are checked, a nested stack whose template declares a `Transform` or calls `Fn::Transform` fails with `Requires capabilities : [CAPABILITY_AUTO_EXPAND]` unless the parent acknowledged `CAPABILITY_AUTO_EXPAND`, as on AWS.
- **CloudFormation — `AWS::RDS::DBCluster` and `AWS::RDS::DBInstance` update in place** — a stack update re-ran the create, which gave the resource a new endpoint, resource id and create time and emptied the cluster's member list; the properties the create stores now change on the existing record, a create-only or `Engine` change replaces the resource or, under a custom identifier, is refused, a cluster `MasterUsername` change leaves the cluster as it is, change sets report which properties replace, and a stack-created cluster can now be described and answers `Fn::GetAtt DBClusterResourceId`. Contributed by @iot-rocket.
- **CloudFormation — `AWS::Pipes::Pipe` and `AWS::Scheduler::ScheduleGroup` update in place** — a pipe keeps its stream position and `CreationTime` when `Description`, `Target`, `RoleArn`, `DesiredState` or `Tags` change, gets `Description` and `Tags` on create and refuses a create-only source change under an explicit `Name`, and a schedule group takes template and stack tag changes while keeping tags added through `TagResource`.
- **CloudFormation — EKS cluster and node group updates** — `AWS::EKS::Cluster` applies `Version`, `Logging`, `ResourcesVpcConfig`, `AccessConfig.AuthenticationMode` and `Tags` in place and `AWS::EKS::Nodegroup` applies `ScalingConfig`, `Labels`, `Taints`, `UpdateConfig`, `LaunchTemplate`, `Version`, `ReleaseVersion` and `Tags`, where every such change used to report `UPDATE_COMPLETE` and was dropped.
diff --git a/README.md b/README.md
index c8c7ce86..14cd9804 100644
--- a/README.md
+++ b/README.md
@@ -912,6 +912,7 @@ The registry must be reachable by the Docker daemon running the task containers.
| `LAMBDA_WARM_TTL_SECONDS` | `300` | How long an idle warm Lambda container stays in the pool before the reaper evicts it |
| `LAMBDA_ACCOUNT_CONCURRENCY` | `0` | Account-level concurrent-invocation cap (0 = unbounded). Match real AWS by setting to `1000`. Used to simulate `ConcurrentInvocationLimitExceeded` throttles |
| `SFN_MOCK_CONFIG` | _(unset)_ | Path to JSON file for Step Functions mock testing; compatible with AWS SFN Local format. Also accepts `LOCALSTACK_SFN_MOCK_CONFIG` |
+| `CFN_ENFORCE_CAPABILITIES` | _(unset)_ | Set `1` to have CloudFormation refuse a template whose IAM resources or macros the request's `Capabilities` do not acknowledge (`InsufficientCapabilitiesException`, and on a nested stack a failed resource), as AWS always does, also without `AUTH=true`. Under `AUTH=true` the check always runs |
| `ATHENA_ENGINE` | `auto` | SQL engine for Athena: `auto`, `duckdb`, `mock` |
| `SMTP_HOST` | _(unset)_ | SMTP server for SES email relay (e.g. `mailhog:1025`). When set, SES SendEmail/SendRawEmail actually deliver mail. When unset, emails are stored in-memory only |
| `MINISTACK_APIGW_PROXY_TIMEOUT_SECONDS` | `30` | API Gateway v1/v2 HTTP `HTTP_PROXY` / `HTTP` integration: upstream request timeout (seconds) |
diff --git a/ministack/services/cloudformation/handlers.py b/ministack/services/cloudformation/handlers.py
index fecc7b34..beda45bb 100644
--- a/ministack/services/cloudformation/handlers.py
+++ b/ministack/services/cloudformation/handlers.py
@@ -7,6 +7,7 @@ CloudFormation handlers — API action handlers for all supported CloudFormation
import copy
import json
import logging
+import os
from ministack.core.responses import get_account_id, get_region, new_uuid, now_iso
from ministack.services.cloudformation import drift as _drift
@@ -206,14 +207,13 @@ def _check_capabilities(sent, template, params, macros=True):
``template``, because a macro may add IAM resources and AWS asks for those
to be acknowledged as well (template-macros-overview.html).
- Capabilities are IAM scope, so the check only runs under ``AUTH=true``;
- without it every template is accepted as before. ``CAPABILITY_IAM`` is
+ The check runs under ``AUTH=true``, and without it when
+ ``CFN_ENFORCE_CAPABILITIES=1``. ``CAPABILITY_IAM`` is
satisfied by either IAM capability, ``CAPABILITY_NAMED_IAM`` only by
itself. Pass ``macros=False`` for ``CreateChangeSet``: the API reference
says ``CAPABILITY_AUTO_EXPAND`` "doesn't apply to creating change sets".
Returns an error response or ``None``."""
- from ministack.app import AUTH
- if not AUTH:
+ if not _capabilities_enforced():
return None
given = set(_extract_string_members(params, "Capabilities"))
required = _required_iam_capabilities(template)
@@ -225,6 +225,12 @@ def _check_capabilities(sent, template, params, macros=True):
return _error("InsufficientCapabilitiesException", _insufficient_capabilities_message(missing))
+def _capabilities_enforced():
+ """Whether Capabilities are checked: under ``AUTH``, or with ``CFN_ENFORCE_CAPABILITIES`` on."""
+ from ministack.app import AUTH
+ return AUTH or os.environ.get("CFN_ENFORCE_CAPABILITIES", "").strip().lower() in ("1", "true", "yes", "on")
+
+
def _required_iam_capabilities(template):
"""The capabilities a template's IAM resources demand, which is the rule
both the request-level check and the nested-stack check enforce.
diff --git a/ministack/services/cloudformation/provisioners.py b/ministack/services/cloudformation/provisioners.py
index 0bab3850..9e3c1829 100644
--- a/ministack/services/cloudformation/provisioners.py
+++ b/ministack/services/cloudformation/provisioners.py
@@ -4067,20 +4067,22 @@ def _check_nested_stack_capabilities(parent_stack_name, template):
stacks that contain IAM resources, you must acknowledge IAM capabilities",
using-cfn-nested-stacks), so the set the parent stored covers the child
and, through the child's own record, every level below it. Like the
- parent's check this runs under AUTH=true only, and it reads the IAM
- rule alone: whether a child template's own Transform needs
- CAPABILITY_AUTO_EXPAND on the parent is not modelled here.
+ parent's check it runs under AUTH=true or CFN_ENFORCE_CAPABILITIES=1. A
+ child template with a macro needs CAPABILITY_AUTO_EXPAND on the parent.
"""
- from ministack.app import AUTH
- if not AUTH:
- return
from ministack.services.cloudformation.handlers import (
+ _capabilities_enforced,
_insufficient_capabilities_message,
_missing_capabilities,
_required_iam_capabilities,
+ _uses_macro,
)
- missing = _missing_capabilities(set(_parent_capabilities(parent_stack_name)),
- _required_iam_capabilities(template))
+ if not _capabilities_enforced():
+ return
+ required = _required_iam_capabilities(template)
+ if _uses_macro(template):
+ required.append("CAPABILITY_AUTO_EXPAND")
+ missing = _missing_capabilities(set(_parent_capabilities(parent_stack_name)), required)
if missing:
raise ValueError(_insufficient_capabilities_message(missing))
@@ -4092,13 +4094,13 @@ def _parent_capabilities(parent_stack_name):
def _inherited_capabilities(parent_stack_name):
- """What a child stack's record carries, which is the parent's set under
- AUTH=true and nothing without it. The set exists to be read by the check
- on the level below, so recording it where no check runs would only change
- what DescribeStacks reports on a child.
+ """What a child stack's record carries, which is the parent's set where
+ the check runs and nothing elsewhere. The set exists to be read by the
+ check on the level below, so recording it where no check runs would only
+ change what DescribeStacks reports on a child.
"""
- from ministack.app import AUTH
- return _parent_capabilities(parent_stack_name) if AUTH else []
+ from ministack.services.cloudformation.handlers import _capabilities_enforced
+ return _parent_capabilities(parent_stack_name) if _capabilities_enforced() else []
def _cfn_nested_stack_deploy(logical_id, props, parent_stack_name, *,
@@ -4203,7 +4205,7 @@ def _cfn_nested_stack_deploy(logical_id, props, parent_stack_name, *,
"ParentId": _cr_stack_id(parent_stack_name),
# The parent's acknowledgement covers every level of nesting, so a
# child of this child reads the same set. Only the check needs it, so
- # it is recorded only where the check runs: without AUTH a child's
+ # it is recorded only where the check runs: elsewhere a child's
# DescribeStacks reports what it reported before, nothing.
"Capabilities": _inherited_capabilities(parent_stack_name),
}
diff --git a/tests/test_cfn.py b/tests/test_cfn.py
index f4a8a769..5dba7d90 100644
--- a/tests/test_cfn.py
+++ b/tests/test_cfn.py
@@ -3178,6 +3178,60 @@ def test_cfn_nested_stack_capabilities_are_rechecked_on_an_update(monkeypatch):
_forget_nested_test_stacks(parent)
[email protected]("auth,setting", [(False, "1"), (True, "0"), (True, "typo")])
+def test_cfn_capabilities_setting_turns_the_check_on(monkeypatch, auth, setting):
+ """CFN_ENFORCE_CAPABILITIES turns the check on without AUTH, and no value
+ of it turns the check off under AUTH, for CreateStack and nested stacks."""
+ import ministack.app as app_mod
+ from ministack.services.cloudformation import _stack_events, _stacks
+ from ministack.services.cloudformation.handlers import _create_stack
+
+ monkeypatch.setattr(app_mod, "AUTH", auth)
+ monkeypatch.setenv("CFN_ENFORCE_CAPABILITIES", setting)
+ uid = _uuid_mod.uuid4().hex[:8]
+ stack_name = f"cfn-caps-setting-{uid}"
+ url = "http://localhost:4566/tpl/child.json"
+ try:
+ status, code, message = _caps_error(
+ _create_stack(_caps_params(_CAPS_ROLE_TEMPLATE, StackName=stack_name)))
+ assert (status, code, message) == (
+ 400, "InsufficientCapabilitiesException",
+ "Requires capabilities : [CAPABILITY_IAM]")
+ assert stack_name not in _stacks
+ with pytest.raises(ValueError, match=r"Requires capabilities : \[CAPABILITY_IAM\]"):
+ _deploy_nested_child(monkeypatch, f"{stack_name}-p", [],
+ {url: _CAPS_ROLE_TEMPLATE}, url)
+ child = _deploy_nested_child(monkeypatch, f"{stack_name}-p2", ["CAPABILITY_IAM"],
+ {url: _CAPS_ROLE_TEMPLATE}, url)
+ assert _stacks[child]["Capabilities"] == ["CAPABILITY_IAM"]
+ finally:
+ stack = _stacks.pop(stack_name, None)
+ if stack:
+ _stack_events.pop(stack["StackId"], None)
+ _forget_nested_test_stacks(f"{stack_name}-p")
+
+
+def test_cfn_nested_stack_macro_needs_auto_expand_on_the_parent(monkeypatch):
+ """A child template with a Transform fails the nested stack unless the
+ parent acknowledged CAPABILITY_AUTO_EXPAND."""
+ import ministack.app as app_mod
+ from ministack.services.cloudformation import _stacks
+
+ monkeypatch.setattr(app_mod, "AUTH", True)
+ uid = _uuid_mod.uuid4().hex[:8]
+ parent = f"cfn-nested-macro-{uid}"
+ url = "http://localhost:4566/tpl/macro.json"
+ templates = {url: {"Transform": "AWS::LanguageExtensions",
+ "Resources": {"H": {"Type": "AWS::CloudFormation::WaitConditionHandle"}}}}
+ try:
+ with pytest.raises(ValueError, match=r"Requires capabilities : \[CAPABILITY_AUTO_EXPAND\]"):
+ _deploy_nested_child(monkeypatch, parent, ["CAPABILITY_IAM"], templates, url)
+ child = _deploy_nested_child(monkeypatch, parent, ["CAPABILITY_AUTO_EXPAND"], templates, url)
+ assert _stacks[child]["StackStatus"] == "CREATE_COMPLETE"
+ finally:
+ _forget_nested_test_stacks(parent)
+
+
def test_cfn_create_stack_refuses_missing_capabilities_under_auth(monkeypatch):
import ministack.app as app_mod
from ministack.services.cloudformation import _stack_events, _stacks