Merge pull request #430 from awslabs/update-readme-md

Update README and doc configs to use README.md

docs/commands/clean.md

@@ -0,0 +1,7 @@
+# Clean
+
+The `clean` command is the inverse of the `init` command, and can be
+used to completely remove Config resources from an account, including
+the Configuration Recorder, Delivery Channel, S3 buckets, Roles, and
+Permissions. This is useful for testing account provisioning automation
+and for running automated tests in a clean environment.

docs/commands/create-rule-template.md

@@ -0,0 +1,28 @@
+# Create-Rule-Template
+
+Generates and saves to a file a single CloudFormation template that can
+be used to deploy the specified Rule(s) into any account. This feature
+has two primary uses:
+
+- Multi-account Config setup in which the Lambda Functions for custom rules are deployed into a centralized \"security\" or \"compliance\" account and the Config Rules themselves are deployed into \"application\" or \"satellite\" accounts.
+- Combine many Config Rules into a single CloudFormation template for easier atomic deployment and management.
+
+The generated CloudFormation template includes a Parameter for the
+AccountID that contains the Lambda functions that provide the compliance
+logic for the Rules, and also exposes all of the Config Rule input
+parameters as CloudFormation stack parameters.
+
+By default the generated CloudFormation template will set up Config as
+per the settings used by the RDK `init` command, but those resources can
+be omitted using the `--rules-only` flag.
+
+The `--config-role-arn` flag can be used for assigning existing config
+role to the created Configuration Recorder. The
+`-t | --tag-config-rules-script <file path>` can now be used for output
+the script generated for create tags for each config rule.
+
+As of version 0.6, RDK supports Config remediation. Note that in order
+to use SSM documents for remediation you must supply all of the
+necessary document parameters. These can be found in the SSM document
+listing on the AWS console, but RDK will *not* validate at rule creation
+that you have all of the necessary parameters supplied.

docs/commands/create.md

@@ -0,0 +1,7 @@
+# Create
+
+As of version 0.6, RDK supports Config remediation. Note that in order
+to use SSM documents for remediation you must supply all of the
+necessary document parameters. These can be found in the SSM document
+listing on the AWS console, but RDK will *not* validate at rule creation
+that you have all of the necessary parameters supplied.

docs/commands/deploy.md

@@ -0,0 +1,47 @@
+# Deploy
+
+This command will deploy the specified Rule(s) to the Account and Region
+determined by the credentials being used to execute the command, and the
+value of the AWS_DEFAULT_REGION environment variable, unless those
+credentials or region are overridden using the common flags.
+
+Once deployed, RDK will **not** explicitly start a Rule evaluation.
+Depending on the changes being made to your Config Rule setup AWS Config
+may re-evaluate the deployed Rules automatically, or you can run an
+evaluation using the AWS configservice CLI.
+
+The `--functions-only` flag can be used as part of a multi-account
+deployment strategy to push **only** the Lambda functions (and
+necessary Roles and Permssions) to the target account. This is intended
+to be used in conjunction with the `create-rule-template` command in
+order to separate the compliance logic from the evaluated accounts. For
+an example of how this looks in practice, check out the [AWS
+Compliance-as-Code
+Engine](https://github.com/awslabs/aws-config-engine-for-compliance-as-code/).
+The `--rdklib-layer-arn` flag can be used for attaching Lambda Layer ARN
+that contains the desired rdklib. Note that Lambda Layers are
+region-specific. The `--lambda-role-arn` flag can be used for assigning
+existing iam role to all Lambda functions created for Custom Config
+Rules. The `--lambda-layers` flag can be used for attaching a
+comma-separated list of Lambda Layer ARNs to deploy with your Lambda
+function(s). The `--lambda-subnets` flag can be used for attaching a
+comma-separated list of Subnets to deploy your Lambda function(s). The
+`--lambda-security-groups` flag can be used for attaching a
+comma-separated list of Security Groups to deploy with your Lambda
+function(s). The `--custom-code-bucket` flag can be used for providing
+the custom code S3 bucket name, which is not created with rdk init, for
+generated cloudformation template storage. The `--boundary-policy-arn`
+flag can be used for attaching boundary Policy ARN that will be added to
+rdkLambdaRole. The `--lambda-timeout` flag can be used for specifying
+the timeout associated to the lambda function
+
+Note: Behind the scenes the `--functions-only` flag generates a
+CloudFormation template and runs a \"create\" or \"update\" on the
+targeted AWS Account and Region. If subsequent calls to `deploy` with
+the `--functions-only` flag are made with the same stack name (either
+the default or otherwise) but with *different Config rules targeted*,
+any Rules deployed in previous `deploy`s but not included in the latest
+`deploy` will be removed. After a functions-only `deploy` **only** the
+Rules specifically targeted by that command (either through Rulesets or
+an explicit list supplied on the command line) will be deployed in the
+environment, all others will be removed.s

docs/commands/export.md

@@ -0,0 +1,19 @@
+# Export
+
+This command will export the specified Rule(s) to the terraform file, it
+supports the terraform versions 0.11 and 0.12.
+
+The `--format` flag can be used to specify export format, currently it
+supports only terraform. The `--version` flag can be used to specify the
+terraform version. The `--rdklib-layer-arn` flag can be used for
+attaching Lambda Layer ARN that contains the desired rdklib. Note that
+Lambda Layers are region-specific. The `--lambda-role-arn` flag can be
+used for assigning existing iam role to all Lambda functions created for
+Custom Config Rules. The `--lambda-layers` flag can be used for
+attaching a comma-separated list of Lambda Layer ARNs to deploy with
+your Lambda function(s). The `--lambda-subnets` flag can be used for
+attaching a comma-separated list of Subnets to deploy your Lambda
+function(s). The `--lambda-security-groups` flag can be used for
+attaching a comma-separated list of Security Groups to deploy with your
+Lambda function(s). The `--lambda-timeout` flag can be used for
+specifying the timeout associated to the lambda function

docs/commands/init.md

@@ -0,0 +1,27 @@
+# Init
+
+Sets up the AWS Config Service in an AWS Account. This includes:
+
+- Config Configuration Recorder
+- Config Delivery Channel
+- IAM Role for Delivery Channel
+- S3 Bucket for Configuration Snapshots
+- S3 Bucket for Lambda Code
+
+Additionally, `init` will make sure that the Configuration Recorder is
+on and functioning, that the Delivery Channel has the appropriate Role
+attached, and that the Delivery Channel Role has the proper permissions.
+
+Note: Even without Config Rules running the Configuration Recorder is
+still capturing Configuration Item snapshots and storing them in S3, so
+running `init` will incur AWS charges!
+
+Also Note: AWS Config is a regional service, so running `init` will only
+set up Config in the region currently specified in your
+AWS_DEFAULT_REGION environment variable or in the `--region` flag.
+
+Advanced Options:
+
+- `--config-bucket-exists-in-another-account`: \[optional\] If the bucket being used by a Config Delivery Channel exists in another account, it is possible to skip the check that the bucket exists. This is useful when using `init` to initialize AWS Config in an account which already has a delivery channel setup with a central bucket. Currently, the rdk lists out all the buckets within the account your are running `init` from, to check if the provided bucket name exists, if it doesn\'t then it will create it. This presents an issue when a Config Delivery Channel has been configured to push configuration recordings to a central bucket. The bucket will never be found as it doesn\'t exist in the same account, but cannot be created as bucket names have to be globally unique.
+- `--skip-code-bucket-creation`: \[optional\] If you want to use custom code bucket for rdk, enable this and use flag `--custom-code-bucket` to `rdk deploy`
+- `control-tower`: \[optional\] If your account is part of an AWS Control Tower setup \--control-tower will skip the setup of configuration_recorder and delivery_channel

docs/commands/logs.md

@@ -0,0 +1,14 @@
+# Logs
+
+The `logs` command provides a shortcut to accessing the CloudWatch Logs
+output from the Lambda Functions that back your custom Config Rules.
+Logs are displayed in chronological order going back the number of log
+entries specified by the `--number` flag (default 3). It supports a
+`--follow` flag similar to the UNIX command `tail` so that you can
+choose to continually poll CloudWatch to deliver new log items as they
+are delivered by your Lambda function.
+
+In addition to any output that your function emits via `print()` or
+`console.log()` commands, Lambda will also record log lines for the
+start and stop of each Lambda invocation, including the runtime and
+memory usage.

docs/commands/modify.md

@@ -0,0 +1,7 @@
+# Modify
+
+Used to modify the local metadata for Config Rules created by the RDK.
+This command takes the same arguments as the `create` command (all of
+them optional), and overwrites the Rule metadata for any flag specified.
+Changes made using `modify` are not automatically pushed out to your AWS
+Account, and must be deployed as usual using the `deploy` command.

docs/commands/rulesets.md

@@ -0,0 +1,27 @@
+# Rulesets
+
+Rulesets provide a mechanism to tag individual Config Rules into groups
+that can be acted on as a unit. Ruleset tags are single keywords, and
+the commands `deploy`, `create-rule-template`, and `undeploy` can all
+expand Ruleset parameters and operate on the resulting list of Rules.
+
+The most common use-case for Rulesets is to define standardized Account
+metadata or data classifications, and then tag individual Rules to all
+of the appropriate metadata tags or classification levels.
+
+Example: If you have Account classifications of \"Public\", \"Private\",
+and \"Restricted\" you can tag all of your Rules as \"Restricted\", and
+a subset of them that deal with private network security as \"Private\".
+Then when you need to deploy controls to a new \"Private\" account you
+can simply use `rdk create-rule-template --rulesets Private` to generate
+a CloudFormation template that includes all of the Rules necessary for
+your \"Private\" classification, but omit the Rules that are only
+necessary for \"Restricted\" accounts. Additionally, as your compliance
+requirements change and you add Config Rules you can tag them as
+appropriate, re-generate your CloudFormation templates, and re-deploy to
+make sure your Accounts are all up-to-date.
+
+You may also choose to classify accounts using binary attributes
+(\"Prod\" vs. \"Non-Prod\" or \"PCI\" vs. \"Non-PCI\"), and then
+generate account-specific CloudFormation templates using the Account
+metadata to ensure that the appropriate controls are deployed.

docs/commands/sample-ci.md

@@ -0,0 +1,17 @@
+# Sample-CI
+
+This utility command outputs a sample Configuration Item for the
+specified resource type. This can be useful when writing new custom
+Config Rules to help developers know what the CI structure and plausible
+values for the resource type are.
+
+Note that you can construct Config Evaluations for any resource type
+that is supported by CloudFormation, however you can not create
+change-triggered Config Rules for resource types not explicitly
+supported by Config, and some of the console functionality in AWS Config
+may be limited.
+
+[CFN-supported
+resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-supported-resources.html)
+[Config-supported
+resources](https://docs.aws.amazon.com/config/latest/developerguide/resource-config-reference.html)

docs/commands/test-local.md

@@ -0,0 +1,9 @@
+# Test-Local
+
+Shorthand command for running the unit tests defined for Config Rules
+that use a Python runtime. When a Python 3.7+ Rule is created using the
+`create` command a unit test template is created in the Rule directory.
+This test boilerplate includes minimal tests, as well as a framework for
+using the `unittest.mock` library for stubbing out Boto3 calls. This
+allows more sophisticated test cases to be written for Periodic rules
+that need to make API calls to gather information about the environment.

docs/commands/undeploy.md

@@ -0,0 +1,10 @@
+# Undeploy
+
+The inverse of `deploy`, this command is used to remove a Config Rule
+and its Lambda Function from the targeted account.
+
+This is intended to be used primarily for clean-up for testing
+deployment automation (perhaps from a CI/CD pipeline) to ensure that it
+works from an empty account, or to clean up a test account during
+development. See also the [clean](./clean.html) command if you want to
+more thoroughly scrub Config from your account.