cloud-radar 0.11.1a4__py3-none-any.whl → 0.12.1__py3-none-any.whl

cloud_radar/cf/unit/__init__.py

@@ -1,4 +1,6 @@
+from ._hooks import ResourceHookContext
+from ._resource import Resource
 from ._stack import Stack
 from ._template import Template
 
-__all__ = ["Template", "Stack"]
+__all__ = ["Template", "Stack", "Resource", "ResourceHookContext"]

cloud_radar/cf/unit/_hooks.py

@@ -0,0 +1,199 @@
+from dataclasses import dataclass
+
+# Work around some circular import issue until someone smarter
+# can work out the right way to restructure / refactor this
+# Solution from https://stackoverflow.com/a/39757388/230449
+from typing import TYPE_CHECKING, Callable, Dict, List, Union
+
+from ._resource import Resource
+from ._stack import Stack
+
+if TYPE_CHECKING:
+    from ._template import Template
+
+
+@dataclass
+class ResourceHookContext:
+    """Class that contains the context for a resource hook to evaluate.
+
+    Attributes:
+        logical_id (str): The logical ID for the resource in the CloudFormation
+            template which is to be evaluated.
+        resource_definition (Resource): The definition of the resource to be evaluated.
+        stack (Stack): the rendered stack that the resource is part of
+        template (Template): the template that is being rendered to produce the stack
+    """
+
+    logical_id: str
+    resource_definition: Resource
+    stack: Stack
+    template: "Template"
+
+
+@dataclass
+class ResourceHookCollection:
+    """
+    Class that holds the two collections of hooks that we can evaluate against
+    individual Resource items in a rendered stack.
+
+    Each Callable is expected to take in a single parameter - an instance of
+    ResourceHookContext.
+
+    Attributes:
+        plugin (Dict[str, List[Callable]]): The dict of Resource Type to
+            list of hooks which were loaded from plugins.
+        local (Dict[str, List[Callable]]): The dict of Resource Type to
+            list of hooks which were defined with the template.
+    """
+
+    plugin: Dict[str, List[Callable]]
+    local: Dict[str, List[Callable]]
+
+
+@dataclass
+class TemplateHookCollection:
+    """
+    Class that holds the two collections of hooks that we can evaluate
+    against a loaded Template.
+
+    Each Callable is expected to take in a single parameter - an
+    instance of Template.
+
+    Attributes:
+        plugin (List[Callable]): The list of hooks which were loaded from plugins.
+        local (List[Callable]): The list of hooks which were defined with the template.
+    """
+
+    plugin: List[Callable]
+    local: List[Callable]
+
+
+class HookProcessor:
+    """
+    Class that handles holding and evaluating the collections of hooks that we run
+    against Templates and Resources.
+
+    In future this will include loading hooks from plugins, but that has not been
+    implemented yet.
+
+    This supports suppressing rules based on Metadata at either the Template or
+    Resource level, using something like this:
+
+    Metadata:
+      Cloud-Radar:
+        ignore-hooks:
+          - s3_check_bucket_name_region
+
+    To allow this to work, you should ensure that the function names that you implement
+    for hooks have unique and descriptive names.
+
+    """
+
+    def __init__(self) -> None:
+        self._resources: ResourceHookCollection = ResourceHookCollection(
+            plugin={}, local={}
+        )
+        self._template: TemplateHookCollection = TemplateHookCollection(
+            plugin=[], local=[]
+        )
+        # TODO: Add support for loading plugin hooks
+
+    @property
+    def template(self):
+        return self._template.local
+
+    @template.setter
+    def template(self, value: List[Callable]):
+        self._template.local = value
+
+    @property
+    def resources(self):
+        return self._resources.local
+
+    @resources.setter
+    def resources(self, value: Dict[str, List[Callable]]):
+        self._resources.local = value
+
+    def _is_hook_suppressed_in_dict(self, hook_name: str, metadata: Dict) -> bool:
+        cloud_radar_metadata = metadata.get("Cloud-Radar", {})
+        ignored_hooks = cloud_radar_metadata.get("ignore-hooks", {})
+
+        return hook_name in ignored_hooks
+
+    def _is_hook_suppressed(
+        self, hook_name, template: "Template", resource: Union[Resource, None] = None
+    ) -> bool:
+        # First check if a suppression exists in the template,
+        # as that will take precedence.
+        hook_suppressed = self._is_hook_suppressed_in_dict(
+            hook_name, template.template.get("Metadata", {})
+        )
+
+        if not hook_suppressed and resource:
+            # if not suppression was found at the template level, check the
+            # resource level
+            hook_suppressed = self._is_hook_suppressed_in_dict(
+                hook_name, resource.get("Metadata", {})
+            )
+
+        return hook_suppressed
+
+    def _evaluate_template_hooks(
+        self, hook_type: str, hooks: List[Callable], template: "Template"
+    ) -> None:
+        for single_hook in hooks:
+            # Only process the hook if it has not been marked as to be
+            # ignored
+            if not self._is_hook_suppressed(single_hook.__name__, template, None):
+                print(f"Processing {hook_type} hook {single_hook.__name__}")
+
+                single_hook(template=template)
+
+    def _evaluate_resource_hooks(
+        self,
+        hook_type: str,
+        hooks: Dict[str, List[Callable]],
+        stack: Stack,
+        template: "Template",
+    ) -> None:
+        # Iterate through the resources in the rendered stack
+        for logical_id in stack.data.get("Resources", {}):
+            print("Got resource " + logical_id)
+            resource_definition = stack.get_resource(logical_id)
+
+            resource_type = resource_definition.get("Type")
+
+            # Get the hooks that have been defined for this type of resource
+            type_hooks = hooks.get(resource_type, [])
+
+            hook_context = ResourceHookContext(
+                logical_id=logical_id,
+                resource_definition=resource_definition,
+                stack=stack,
+                template=template,
+            )
+
+            # Iterate through each defined hook and call them.
+            for single_hook in type_hooks:
+                # Only process the hook if it has not been marked as to be
+                # ignored
+                if not self._is_hook_suppressed(
+                    single_hook.__name__, template, resource_definition
+                ):
+                    print(f"Processing {hook_type} hook {single_hook.__name__}")
+
+                    single_hook(context=hook_context)
+
+    def evaluate_resource_hooks(self, stack: Stack, template: "Template") -> None:
+        # Evaluate the global hooks first, then the local ones
+        self._evaluate_resource_hooks("plugin", self._resources.plugin, stack, template)
+        self._evaluate_resource_hooks("local", self._resources.local, stack, template)
+
+    def evaluate_template_hooks(self, template: "Template") -> None:
+        print(template)
+        # raise ValueError(type(template))
+        # raise ValueError(template.template)
+
+        # Evaluate the global hooks first, then the local ones
+        self._evaluate_template_hooks("plugin", self._template.plugin, template)
+        self._evaluate_template_hooks("local", self._template.local, template)

cloud_radar/cf/unit/_template.py

@@ -9,6 +9,7 @@ import yaml  # noqa: I100
 from cfn_tools import dump_yaml, load_yaml  # type: ignore  # noqa: I100, I201
 
 from . import functions
+from ._hooks import HookProcessor
 from ._stack import Stack
 
 IntrinsicFunc = Callable[["Template", Any], Any]
@@ -20,6 +21,7 @@ class Template:
     """
 
     AccountId: str = "5" * 12
+    Hooks = HookProcessor()
     NotificationARNs: list = []
     NoValue: str = ""  # Not yet implemented
     Partition: str = "aws"  # Other regions not implemented
@@ -79,6 +81,10 @@ class Template:
             "Transform", None
         )
 
+        # All loaded, validate against any template level hooks
+        # that have been configured
+        self.Hooks.evaluate_template_hooks(self)
+
     @classmethod
     def from_yaml(
         cls,
@@ -317,6 +323,9 @@ class Template:
 
         stack = Stack(self.template)
 
+        # Evaluate any hooks prior to returning this stack
+        self.Hooks.evaluate_resource_hooks(stack, self)
+
         return stack
 
     def resolve_values(  # noqa: max-complexity: 13
@@ -596,7 +605,12 @@ def validate_aws_parameter_constraints(
 
     # There are a few variants of SSM parameters, but they all have the
     # same regex pattern
-    ssm_parameter_value_regex = r"^(/{0,1}(?!/))[A-Za-z0-9/-_]+(.([a-zA-Z]+))?$"
+    #
+    # This is based on the documentation for the PutParameter API operation
+    # https://docs.aws.amazon.com/systems-manager/latest/APIReference/
+    # API_PutParameter.html#systemsmanager-PutParameter-request-Name
+    #
+    ssm_parameter_value_regex = r"^([/]{0,1}[a-zA-Z0-9_.-]*){1,15}$"
 
     if parameter_type.startswith("AWS::SSM::Parameter::Value<"):
         # SSM parameter, need to validate that the type in the angle brackets
@@ -640,7 +654,7 @@ def validate_aws_parameter_constraints(
             raise ValueError(
                 (
                     f"Value {parameter_value} does not match the expected pattern "
-                    f"for SSM parameter {parameter_name}"
+                    f"for SSM parameter {parameter_name}."
                 )
             )
 
@@ -784,7 +798,7 @@ def validate_string_parameter_constraints(
 
 def add_metadata(template: Dict, region: str) -> None:
     """This functions adds the current region to the template
-    as metadate because we can't treat Region like a normal pseduo
+    as metadata because we can't treat Region like a normal pseudo
     variables because we don't want to update the class var for every run.
 
     Args:
@@ -792,12 +806,16 @@ def add_metadata(template: Dict, region: str) -> None:
         region (str): The region that template will be tested with.
     """
 
-    metadata = {"Cloud-Radar": {"Region": region}}
-
     if "Metadata" not in template:
         template["Metadata"] = {}
 
-    template["Metadata"].update(metadata)
+    # Get the existing metadata (so we do not overwrite any
+    # hook suppressions), then set the region into it before
+    # updating the template
+    cloud_radar_metadata = template["Metadata"].get("Cloud-Radar", {})
+    cloud_radar_metadata["Region"] = region
+
+    template["Metadata"]["Cloud-Radar"] = cloud_radar_metadata
 
 
 # All the other Cloudformation intrinsic functions start with `Fn:` but for some reason

cloud_radar/cf/unit/functions.py

@@ -830,17 +830,21 @@ def ref(template: "Template", var_name: str) -> Any:
 
     if "Parameters" in template.template:
         if var_name in template.template["Parameters"]:
+            # This is a reference to a parameter
+
             param_def = template.template["Parameters"][var_name]
-            if "Type" in param_def and param_def["Type"].startswith(
-                "AWS::SSM::Parameter::Value<"
-            ):
+            param_type = param_def.get("Type", "")
+            param_value = param_def["Value"]
+
+            if param_type.startswith("AWS::SSM::Parameter::Value<"):
                 # This is an SSM parameter value, look it up from our dynamic references
-                return template._get_dynamic_reference_value(
-                    "ssm", template.template["Parameters"][var_name]["Value"]
-                )
+                return template._get_dynamic_reference_value("ssm", param_value)
+            if param_type == "CommaDelimitedList" or param_type.startswith("List<"):
+                # Return the value split into a list of strings
+                return param_value.split(",")
 
             # If we get this far, regular parameter value to lookup & return
-            return template.template["Parameters"][var_name]["Value"]
+            return param_value
 
     if var_name in template.template["Resources"]:
         return var_name

{cloud_radar-0.11.1a4.dist-info → cloud_radar-0.12.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloud-radar
-Version: 0.11.1a4
+Version: 0.12.1
 Summary: Run functional tests on cloudformation stacks.
 Home-page: https://github.com/DontShaveTheYak/cloud-radar
 License: Apache-2.0
@@ -114,6 +114,8 @@ You can Test:
 
 You can test all this locally without worrying about AWS Credentials.
 
+A number of these tests can be configured in a common way to apply to all templates through the use of the [hooks](./examples/unit/hooks/README.md) functionality.
+
 ### Functional Testing
 
 This project is a wrapper around Taskcat. Taskcat is a great tool for ensuring your Cloudformation Template can be deployed in multiple AWS Regions. Cloud-Radar enhances Taskcat by making it easier to write more complete functional tests.
@@ -197,7 +199,7 @@ The default values for pseudo parameters:
 | **StackId**      | ""              |
 | **StackName**    | ""              |
 | **URLSuffix**    | "amazonaws.com" |
-_Note: Bold variables are not fully impletmented yet see the [Roadmap](#roadmap)_
+_Note: Bold variables are not fully implemented yet see the [Roadmap](#roadmap)_
 
 At the point of creating the `Template` instance additional configuration is required to be provided if you are using certain approaches to resolving values.
 

{cloud_radar-0.11.1a4.dist-info → cloud_radar-0.12.1.dist-info}/RECORD

@@ -2,16 +2,17 @@ cloud_radar/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cloud_radar/cf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cloud_radar/cf/e2e/__init__.py,sha256=83Bf_ftCxMimG1mxQH0xsKFCmsrQ7YJEAQkeZtJIxL0,47
 cloud_radar/cf/e2e/_stack.py,sha256=Qm5vQsUSUluHirTFTs_n40yI6Z8-HMZ837OvSJcyWqM,1676
-cloud_radar/cf/unit/__init__.py,sha256=51z7nRi_PhTkagVzJOgXth1bm3zvWoBlT9D0I3VGxdY,91
+cloud_radar/cf/unit/__init__.py,sha256=H9iQw4PSZEW-u0Ey-Z8eZfzQ6GJ7wdxmkKE8Z09U7pU,198
 cloud_radar/cf/unit/_condition.py,sha256=e7gwcz87yF6dKl2quxmOmjzHku8OW6EWAsgbCeDMARg,711
+cloud_radar/cf/unit/_hooks.py,sha256=3_uMDzIs6rt_TZfP5-Qz5gIBmJo8rxd2GBBXxTVZsa0,6914
 cloud_radar/cf/unit/_output.py,sha256=rhQQ4aJu06bxAoG7GOXkuOPzAmLCrTA2Ytb8rNXA4Vg,1822
 cloud_radar/cf/unit/_parameter.py,sha256=AdPIqc2ggSW1VR0USF30zjphX3z1HHbGKQt8n-Kzhfo,3199
 cloud_radar/cf/unit/_resource.py,sha256=dWaR-5s6ea5mIu6Dhf1hY31Wd4WLHbHsbyxnu2Tz6QI,8512
 cloud_radar/cf/unit/_stack.py,sha256=_S0L9O7Lw-QAJDKubClp2b6UYtYfyzg272_7WQkUdo8,5785
-cloud_radar/cf/unit/_template.py,sha256=geGy8fiO6esi6a3iwwpUTEJy04WivLYzsVSBCjCO7aE,31463
-cloud_radar/cf/unit/functions.py,sha256=KPPPNLrXzYMi5dtsXkvi0RvaaeAnvBC_2MhqHPs1lHo,28329
+cloud_radar/cf/unit/_template.py,sha256=u1r1RkUPI0t8SGolWEjb3doavFwUQRaE0wOKCi_ijiI,32242
+cloud_radar/cf/unit/functions.py,sha256=k1i12FDChgLwGsG-3q9kdYbuEOgnMEs0qPynp-YcZAM,28494
 cloud_radar/cf/unit/test__template.py,sha256=jVPMJTn6Q0sSZ8BjRGyutuR9-NjdHdwDTVsd2kvjQbs,1491
-cloud_radar-0.11.1a4.dist-info/LICENSE.txt,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-cloud_radar-0.11.1a4.dist-info/METADATA,sha256=AVbK7qWXsXhGZUSGt4Ww0x7TZjVB8qFnmwg9vCPL4F8,15366
-cloud_radar-0.11.1a4.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
-cloud_radar-0.11.1a4.dist-info/RECORD,,
+cloud_radar-0.12.1.dist-info/LICENSE.txt,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+cloud_radar-0.12.1.dist-info/METADATA,sha256=vwvpMBogg8baN7ninA1rMU_jFP7lpotb_xbhkYY9tu8,15527
+cloud_radar-0.12.1.dist-info/WHEEL,sha256=7Z8_27uaHI_UZAc4Uox4PpBhQ9Y5_modZXWMxtUi4NU,88
+cloud_radar-0.12.1.dist-info/RECORD,,