aws-cloudformation / cloudformation-guard

Guard offers a policy-as-code domain-specific language (DSL) to write rules and validate JSON- and YAML-formatted data such as CloudFormation Templates, K8s configurations, and Terraform JSON plans/configurations against those rules. Take this survey to provide feedback about cfn-guard: https://amazonmr.au1.qualtrics.com/jfe/form/SV_bpyzpfoYGGuuUl0
Apache License 2.0
1.29k stars 180 forks source link

[GENERAL ISSUE] Missing Documentation for Input Parameters Feature #548

Closed jkelley-godaddy closed 1 month ago

jkelley-godaddy commented 2 months ago

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 commented 2 months ago

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

dannyvassallo commented 1 month ago

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!