docs(cfn-guard): Add missing Input Parameters documentation & Update … (

#557)

* docs(cfn-guard): Add missing Input Parameters documentation & Update help messaging

* docs(cfn-guard): Add info about conflicting key paths

* docs(pre-commit-hook): Add instructions on how to handle autoupdate tags (#558)

* docs(github-action): Update tag in examples (#556)

README.md

@@ -392,6 +392,81 @@ spec:
 
 The container `app` does not contain CPU limits specified, which fails the overall evaluation as shown in the screenshot.
 
+#### Using Input Parameters
+
+Guard allows you to use input parameters for dynamic data lookups during validation. This feature is particularly useful when you need to reference external data in your rules. However, when specifying input parameter keys, Guard requires that there are no conflicting paths.
+
+##### How to use
+
+1. Use the `--input-parameters` or `-i` flag to specify files containing input parameters. Multiple input parameter files can be specified and will be combined to form a common context. Input parameter keys can not have conflicting paths.
+2. Use the `--data` or `-d` flag to specify the actual template file to be validated.
+
+##### Example Usage
+
+1. Create an input parameter file (e.g., `network.yaml`):
+
+```yaml
+NETWORK:
+  allowed_security_groups: ["sg-282850", "sg-292040"]
+  allowed_prefix_lists: ["pl-63a5400a", "pl-02cd2c6b"]
+```
+
+2. Reference these parameters in your guard rule file (e.g., `security_groups.guard`):
+
+```
+let groups = Resources.*[ Type == 'AWS::EC2::SecurityGroup' ]
+
+let permitted_sgs = NETWORK.allowed_security_groups
+let permitted_pls = NETWORK.allowed_prefix_lists
+rule check_permitted_security_groups_or_prefix_lists(groups) {
+    %groups {
+        this in %permitted_sgs or
+        this in %permitted_pls
+    }
+}
+
+rule CHECK_PERMITTED_GROUPS when %groups !empty {
+    check_permitted_security_groups_or_prefix_lists(
+       %groups.Properties.GroupName
+    )
+}
+```
+
+3. Create a failing data template (e.g., `security_groups_fail.yaml`):
+
+```yaml
+# ---
+# AWSTemplateFormatVersion: 2010-09-09
+# Description: CloudFormation - EC2 Security Group
+
+Resources:
+  mySecurityGroup:
+    Type: "AWS::EC2::SecurityGroup"
+    Properties:
+      GroupName: "wrong"
+```
+
+4. Run the validate command:
+
+```
+cfn-guard validate -r security_groups.guard -i network.yaml -d security_groups_fail.yaml
+```
+
+In this command:
+- `-r` specifies the rule file
+- `-i` specifies the input parameter file
+- `-d` specifies the data file (template) to be validated
+
+##### Multiple Input Parameters
+
+You can specify multiple input parameter files:
+
+```
+cfn-guard validate -r rules.guard -i params1.yaml -i params2.yaml -d template.yaml
+```
+
+All files specified with `-i` will be combined to form a single context for parameter lookup.
+
 #### Test
 
 Test command is used during the development of guard policy rules files. Test provides a simple integrated unit-test frameworks that allows authors to individually test each policy file for different types of inputs. Unit testing helps authors gain confidence that the rule does indeed conform to expectations. It can also be used as regression tests for rules. Here is example run for `test` command

guard/README.md

@@ -89,7 +89,7 @@ Options:
            --data template1.yaml --data ./data-dir1 --data template2.yaml
           For directory arguments such as `data-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template
   -i, --input-parameters [<input-parameters>...]
-          Provide a data file or directory of data files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. All the parameter files passed as input get merged and this combined context is again merged with each file passed as an argument for `data`. Due to this, every file is expected to contain mutually exclusive properties, without any overlap. Supports passing multiple values by using this option repeatedly.
+          Provide a parameter file or directory of parameter files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. All the parameter files passed as input get merged and this combined context is again merged with each file passed as an argument for `data`. Due to this, every file is expected to contain mutually exclusive properties, without any overlap. Supports passing multiple values by using this option repeatedly.
           Example:
            --input-parameters param1.yaml --input-parameters ./param-dir1 --input-parameters param2.yaml
           For directory arguments such as `param-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template

guard/src/commands/validate.rs

@@ -530,7 +530,7 @@ const RULES_HELP: &str = "Provide a rules file or a directory of rules files. Su
 const DATA_HELP: &str = "Provide a data file or directory of data files in JSON or YAML. Supports passing multiple values by using this option repeatedly.\
                           \nExample:\n --data template1.yaml --data ./data-dir1 --data template2.yaml\
                           \nFor directory arguments such as `data-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template";
-const INPUT_PARAMETERS_HELP: &str = "Provide a data file or directory of data files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. \
+const INPUT_PARAMETERS_HELP: &str = "Provide a parameter file or directory of parameter files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. \
                            All the parameter files passed as input get merged and this combined context is again merged with each file passed as an argument for `data`. Due to this, every file is \
                            expected to contain mutually exclusive properties, without any overlap. Supports passing multiple values by using this option repeatedly.\
                           \nExample:\n --input-parameters param1.yaml --input-parameters ./param-dir1 --input-parameters param2.yaml\