feat: Read-Only Resources SGR check and rules (#85)

* feat: Read-Only Resources SGR check and rules

Author: zhaomicx

README.md

@@ -26,12 +26,31 @@ In order to start using Basic Linting you need to run following command:
 $ guard-rail --schema file://path-to-schema-1 --schema file://path-to-schema-2 --rule file://path-to-custom-ruleset1 --rule file://path-to-custom-ruleset2
 ```
 
+#### Read-Only Resource Checks
+For read-only resources, you can use the `--is-read-only` flag to run only the essential checks:
+```bash
+$ guard-rail --schema file://path-to-schema --is-read
+```
+
+When `--is-read-only` is specified, only the following checks are performed:
+- `ARN001`: arn related property MUST have pattern specified
+- `ARN002`: arn related property MUST have pattern specified
+- `COM001`: ensure_properties_do_not_support_multitype
+- `PID001`: primaryIdentifier MUST exist
+- `PID002`: primaryIdentifier MUST contain values
+- `PR005`: primaryIdentifier MUST have properties defined in the schema
+- `PR007`: readOnlyProperties MUST have properties defined in the schema
+- `PER003`: Resource MUST implement read handler
+- `PER004`: Resource MUST NOT specify wildcard permissions for read handler
+- `PER010`: Resource MUST implement list handler
+- `PER011`: Resource MUST NOT specify wildcard permissions for list handler
+
 **[List of Linting Rules](docs/BASIC_LINTING.md)**
 
 #### Breaking Change (Stateful)
 Along with basic linting, guard rail supports capability of breaking change evaluation. Provider developer must provider two json objects - previous & current versions of the same resource schema. CloudFormation authored rules will be run and evaluation current version of the schema whether it is compliant or not.
 
-In order to start using Basic Linting you need to run following command:
+In order to start using Breaking Change evaluation you need to run following command:
 ```bash
 $ guard-rail --schema file://path-to-schema-1 --schema file://path-to-schema-2 --rule ... --stateful
 ```

src/cli.py

@@ -53,7 +53,11 @@ def main(args_in=None):
     compliance_result = None
 
     if not args.stateful:
-        payload: Stateless = Stateless(schemas=collected_schemas, rules=collected_rules)
+        payload: Stateless = Stateless(
+            schemas=collected_schemas,
+            rules=collected_rules,
+            is_read_only=args.is_read_only,
+        )
         compliance_result = invoke(payload)
     else:
         # should be index safe as argument validation should fail prematurely

src/rpdk/guard_rail/core/data_types.py

@@ -33,10 +33,12 @@ class Stateless:
     Args:
         schemas (List[Dict[str, Any]]): Collection of Resource Provider Schemas
         rules (List[str]): Collection of Custom Compliance Rules
+        is_read_only (bool): Whether to run only read resource checks
     """
 
     schemas: List[Dict[str, Any]]
     rules: List[str] = field(default_factory=list)
+    is_read_only: bool = field(default=False)
 
 
 @dataclass

src/rpdk/guard_rail/core/runner.py

@@ -25,7 +25,7 @@
     Stateless,
 )
 from rpdk.guard_rail.core.stateful import schema_diff
-from rpdk.guard_rail.rule_library import combiners, core, permissions, stateful, tags
+from rpdk.guard_rail.rule_library import combiners, core, mutable, stateful, tags
 from rpdk.guard_rail.utils.common import is_guard_rule
 from rpdk.guard_rail.utils.logger import LOG, logdebug
 from rpdk.guard_rail.utils.schema_utils import add_paths_to_schema
@@ -35,22 +35,29 @@
 
 
 @logdebug
-def prepare_ruleset(mode: str = "stateless"):
+def prepare_ruleset(mode: str = "stateless", is_read_only: bool = False):
     """Fetches module level schema rules based on mode.
 
     Iterates over provided modules (core, combiners, permissions, tags) or (stateful)
     and checks if content is a guard rule-set, ten adds it to the list
     `to-run`
 
+    Args:
+        is_read_only: whether the calling resource schema is read only or not
+        mode: The mode (stateless or stateful)
+
     Returns:
         Set[str]: set of rules in a string form
     """
     rule_modules = {
-        "stateless": [core, combiners, permissions, tags],
+        "stateless": [core, mutable, combiners, tags],
         "stateful": [stateful],
     }
     rule_set = set()
     for module in rule_modules[mode]:
+        module_name = module.__name__.split(".")[-1]
+        if is_read_only and module_name == "mutable":
+            continue
         for content in pkg_resources.contents(module):
             if not is_guard_rule(content):
                 continue
@@ -148,7 +155,7 @@ def _(payload):
     """
 
     compliance_output = []
-    ruleset = prepare_ruleset() | set(payload.rules)
+    ruleset = prepare_ruleset(is_read_only=payload.is_read_only) | set(payload.rules)
 
     def __execute_rules__(schema_exec, ruleset):
         output = None
@@ -160,6 +167,7 @@ def __execute_rules__(schema_exec, ruleset):
         schema_with_paths = add_paths_to_schema(schema=schema)
         schema_to_execute = __exec_rules__(schema=schema_with_paths)
         output = __execute_rules__(schema_exec=schema_to_execute, ruleset=ruleset)
+
         compliance_output.append(output)
     return compliance_output
 
@@ -191,6 +199,7 @@ def __execute__(schema_exec, ruleset):
 
     schema_to_execute = __exec_rules__(schema=schema_difference)
     output = __execute__(schema_exec=schema_to_execute, ruleset=ruleset)
+
     output.schema_difference = schema_difference
     compliance_output.append(output)
 

src/rpdk/guard_rail/rule_library/core/schema-linter-core-permission-rules.guard

@@ -0,0 +1,91 @@
+let wildcard_notation = /^[a-z0-9-]{0,20}:([a-zA-Z0-9]+)?\*$/
+
+
+
+rule ensure_resource_read_handler_exists_and_have_permissions {
+    handlers.read exists
+    <<
+    {
+        "result": "NON_COMPLIANT",
+        "check_id": "PER003",
+        "message": "Resource MUST implement read handler"
+    }
+    >>
+
+    handlers.read.permissions exists
+    <<
+    {
+        "result": "NON_COMPLIANT",
+        "check_id": "PER004",
+        "message": "Resource read handler MUST have permissions list specified"
+    }
+    >>
+
+    when handlers.read.permissions exists {
+        handlers.read.permissions !empty
+        <<
+        {
+            "result": "NON_COMPLIANT",
+            "check_id": "PER004",
+            "message": "Resource read handler MUST have non-empty permissions"
+        }
+        >>
+    }
+
+    when handlers.read.permissions !empty {
+        handlers.read.permissions.* {
+            this != %wildcard_notation
+            <<
+            {
+                "result": "NON_COMPLIANT",
+                "check_id": "PER004",
+                "message": "Resource MUST NOT specify wildcard permissions for read handler"
+            }
+            >>
+        }
+    }
+}
+
+rule ensure_resource_list_handler_exists_and_have_permissions {
+    handlers.list exists
+    <<
+    {
+        "result": "NON_COMPLIANT",
+        "check_id": "PER010",
+        "message": "Resource MUST implement list handler"
+    }
+    >>
+
+    handlers.list.permissions exists
+    <<
+    {
+        "result": "NON_COMPLIANT",
+        "check_id": "PER011",
+        "message": "Resource list handler MUST have permissions list specified"
+    }
+    >>
+
+    when handlers.list.permissions exists {
+        handlers.list.permissions !empty
+        <<
+        {
+            "result": "NON_COMPLIANT",
+            "check_id": "PER011",
+            "message": "Resource list handler MUST have non-empty permissions"
+        }
+        >>
+    }
+
+    when handlers.list.permissions !empty {
+        handlers.list.permissions.* {
+            this != %wildcard_notation
+            <<
+            {
+                "result": "NON_COMPLIANT",
+                "check_id": "PER011",
+                "message": "Resource MUST NOT specify wildcard permissions for list handler"
+            }
+            >>
+        }
+    }
+}

src/rpdk/guard_rail/rule_library/core/schema-linter-core-rules.guard

@@ -133,7 +133,7 @@ rule ensure_write_and_read_only_intersection_is_empty
     }
 }
 
-rule verify_property_notation
+rule verify_property_notation_for_immutable_properties
 {
     let paths = paths
     when primaryIdentifier exists {
@@ -149,19 +149,6 @@ rule verify_property_notation
         }
     }
 
-    when createOnlyProperties exists {
-        createOnlyProperties[*] {
-            this IN %paths
-            <<
-            {
-                "result": "NON_COMPLIANT",
-                "check_id": "PR006",
-                "message": "createOnlyProperties MUST have properties defined in the schema"
-            }
-            >>
-        }
-    }
-
     when readOnlyProperties exists {
         readOnlyProperties[*] {
             this IN %paths
@@ -174,19 +161,6 @@ rule verify_property_notation
             >>
         }
     }
-
-    when writeOnlyProperties exists {
-        writeOnlyProperties[*] {
-            this IN %paths
-            <<
-            {
-                "result": "NON_COMPLIANT",
-                "check_id": "PR008",
-                "message": "writeOnlyProperties MUST have properties defined in the schema"
-            }
-            >>
-        }
-    }
 }
 
 

src/rpdk/guard_rail/rule_library/permissions/__init__.py renamed to src/rpdk/guard_rail/rule_library/mutable/__init__.py

@@ -46,50 +46,6 @@ rule ensure_resource_create_handler_exists_and_have_permissions {
     }
 }
 
-rule ensure_resource_read_handler_exists_and_have_permissions {
-    handlers.read exists
-    <<
-    {
-        "result": "NON_COMPLIANT",
-        "check_id": "PER003",
-        "message": "Resource MUST implement read handler"
-    }
-    >>
-
-    handlers.read.permissions exists
-    <<
-    {
-        "result": "NON_COMPLIANT",
-        "check_id": "PER004",
-        "message": "Resource read handler MUST have permissions list specified"
-    }
-    >>
-
-    when handlers.read.permissions exists {
-        handlers.read.permissions !empty
-        <<
-        {
-            "result": "NON_COMPLIANT",
-            "check_id": "PER004",
-            "message": "Resource read handler MUST have non-empty permissions"
-        }
-        >>
-    }
-
-    when handlers.read.permissions !empty {
-        handlers.read.permissions.* {
-            this != %wildcard_notation
-            <<
-            {
-                "result": "NON_COMPLIANT",
-                "check_id": "PER004",
-                "message": "Resource MUST NOT specify wildcard permissions for read handler"
-            }
-            >>
-        }
-    }
-}
-
 rule ensure_resource_update_handler_exists_and_have_permissions {
     handlers.update exists
     <<
@@ -179,47 +135,3 @@ rule ensure_resource_delete_handler_exists_and_have_permissions {
         }
     }
 }
-
-rule ensure_resource_list_handler_exists_and_have_permissions {
-    handlers.list exists
-    <<
-    {
-        "result": "NON_COMPLIANT",
-        "check_id": "PER010",
-        "message": "Resource MUST implement list handler"
-    }
-    >>
-
-    handlers.list.permissions exists
-    <<
-    {
-        "result": "NON_COMPLIANT",
-        "check_id": "PER011",
-        "message": "Resource list handler MUST have permissions list specified"
-    }
-    >>
-
-    when handlers.list.permissions exists {
-        handlers.list.permissions !empty
-        <<
-        {
-            "result": "NON_COMPLIANT",
-            "check_id": "PER011",
-            "message": "Resource list handler MUST have non-empty permissions"
-        }
-        >>
-    }
-
-    when handlers.list.permissions !empty {
-        handlers.list.permissions.* {
-            this != %wildcard_notation
-            <<
-            {
-                "result": "NON_COMPLIANT",
-                "check_id": "PER011",
-                "message": "Resource MUST NOT specify wildcard permissions for list handler"
-            }
-            >>
-        }
-    }
-}

src/rpdk/guard_rail/rule_library/permissions/schema-linter-core-permission-rules.guard renamed to src/rpdk/guard_rail/rule_library/mutable/schema-linter-mutable-permission-rules.guard

@@ -0,0 +1,29 @@
+rule verify_property_notation_for_mutable_properties
+{
+    let paths = paths
+    when createOnlyProperties exists {
+        createOnlyProperties[*] {
+            this IN %paths
+            <<
+            {
+                "result": "NON_COMPLIANT",
+                "check_id": "PR006",
+                "message": "createOnlyProperties MUST have properties defined in the schema"
+            }
+            >>
+        }
+    }
+
+    when writeOnlyProperties exists {
+        writeOnlyProperties[*] {
+            this IN %paths
+            <<
+            {
+                "result": "NON_COMPLIANT",
+                "check_id": "PR008",
+                "message": "writeOnlyProperties MUST have properties defined in the schema"
+            }
+            >>
+        }
+    }
+}