[GENERAL ISSUE] Missing Documentation for Input Parameters Feature

[jkelley-godaddy]

Describe the issue We use AWS account specific variables in our rule evaluation. Guard supports the use of variables in rules (not templates) through a feature called "Input Parameters". However the Guard documentation does not have any information on this feature, how it works, or how to use it.

The only documentation I have been able to find is at the bottom of the GitHub release notes for version v2.1.0-pre-rc1 - see "Dynamic data lookup for inspection via multiple data files" section. Minimally I would expect this information to be in the official documentation. Ideally it would be expanded with additional examples and details so users have a complete understanding of this feature.

As we a looking to adopt Guard, official documentation of this feature would be very useful for providing guidance on how to use this feature and what it's limitations are.

Any examples Additionally help output shows the following and it appears that it may need to be updated due to confusing terminology around the definition of data:

╰❯ cfn-guard validate --help
Usage: cfn-guard validate [OPTIONS] <--rules [<RULES>...]|--payload>

Options:
...
  -i, --input-params [<INPUT_PARAMS>...]
          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.
          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

Note that in the larger help context data already signifies CloudFormation templates:

  -d, --data [<DATA>...]
          Provide a data file or directory of data files in JSON or YAML. Supports passing multiple values by using this option repeatedly.
          Example:
           --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

However, in the context of --input-params the term data is overloaded, it refers to param1.yaml which is a parameter mapping, NOT a CloudFormation template like in the --data flag.

We would request that this help output also be updated for clarity and completeness.

Operating System: MacOS

OS Version Sonoma 14.5

Additional context Add any other context about the problem here.

[dannyvassallo]

@jkelley-godaddy Thanks for raising this issue! We'll prioritize updating those docs & help output shortly.

[dannyvassallo]

Hey @jkelley-godaddy! We made these changes in the linked PR here. The help text updates will go out with the next Guard release. Thanks for the call out!