Doc-Config-File-Tweaks (#415)

- tweak installation instructions for v1.2.2
- tweak features summary for v1.2.1 and v1.2.2
- tweak default config files for v1.2.1 and v1.2.2
- add central logging bucket documentation
-

Author: Brian969

README.md

@@ -46,6 +46,7 @@ Specifically the accelerator deploys and manages the following functionality, bo
 - Zone sharing and VPC associations
 - Managed Active Directory sharing, including R53 DNS resolver rule creation/sharing
 - Automated TGW inter-region peering
+- Populate Parameter Store with all `user` objects to be used by customers' IaC
 
 ### Identity
 
@@ -86,18 +87,19 @@ Specifically the accelerator deploys and manages the following functionality, bo
 ### Centralized Logging and Alerting
 
 - Deploys an rsyslog auto-scaling cluster behind a NLB, all syslogs forwarded to CloudWatch Logs
+- Centralized access to "Cloud Security Service" Consoles from designated AWS account
 - Centralizes logging to a single centralized S3 bucket (enables, configures and centralizes)
   - VPC Flow logs w/Enhanced metadata fields (also sent to CWL)
   - Organizational Cost and Usage Reports
   - CloudTrail Logs including S3 Data Plane Logs (also sent to CWL)
   - All CloudWatch Logs (includes rsyslog logs)
   - Config History and Snapshots
-  - Route 53 Public Zone Logs
+  - Route 53 Public Zone Logs (also sent to CWL)
   - GuardDuty Findings
   - Macie Discovery results
   - ALB Logs
-  - SSM Session Logs
-- Centralized access to "Cloud Security Service" Consoles from designated AWS account
+  - SSM Session Logs (also sent to CWL)
+  - Resolver Query Logs (also sent to CWL)
 
 ## Relationship with AWS Landing Zone Solution (ALZ)
 
@@ -136,6 +138,7 @@ This summarizes the installation process, the full installation document can be
 
 - Link to [releases](https://github.com/aws-samples/aws-secure-environment-accelerator/releases)
 - [Link](./docs/installation/customization-index.md) to sample config file and customization details
+- [Link](./docs/architectures/pbmm/log-file-locations.md) to AWS SEA Central Logging Bucket Structures
 
 ### - [Accelerator Operations/Troubleshooting Guide](./docs/operations/operations-troubleshooting-guide.md)
 

docs/architectures/pbmm/log-file-locations.md

@@ -0,0 +1,55 @@
+# AWS SEA Central Logging Structures
+
+## Accelerator Central Logging Buckets:
+
+---
+
+| Bucket Type          | Bucket Name                                             | Purpose                                                 |
+| -------------------- | ------------------------------------------------------- | ------------------------------------------------------- |
+| AES Encrypted Bucket | pbmmaccel-logarchive-phase0-aescacentral1-1py9vr4cdwuxu | ALB Logs - ALB's do not support logging to a KMS bucket |
+| KMS Encrypted Bucket | pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo    | All other AWS logs                                      |
+
+---
+
+### Notes:
+
+- Every customer has two logging buckets
+- Customers could use any account name for their central logging account
+- Bucket name format is: {Accel-Prefix}-{Account-Name}-{Accel-Phase}-xxx{Region}-{Random}
+  - {Accel-Prefix} should always be 'pbmmaccel' for Canada
+  - {Accel-Phase} should always be 'phase0'
+  - {region} should always be 'cacentral1' for Canada
+  - {account} is likely to be 'log-archive'
+  - xxx is either "aes" or "" (nothing)
+
+## Accelerator Bucket Folders:
+
+---
+
+| Log Type               | Folder Path                                                                               | Example                                                                                                                                                                                                                                                                                                                             |
+| ---------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ELB (in AES bucket)    | {account#}/elb-{elbname}/AWSLogs/{account#}/\*                                            | <ul><li> s3://pbmmaccel-logarchive-phase0-aescacentral1-1py9vr4ucwuxu/123456789012/elb-Core-mydevacct1-alb/AWSLogs/123456789012/ELBAccessLogTestFile </li></ul><ul><li>s3://pbmmaccel-logarchive-phase0-aescacentral1-1py9vr4ucwuxu/123456789013/elb-Public-Prod-perimeter-alb/AWSLogs/123456789013/ELBAccessLogTestFile </li></ul> |
+| VPC Flow Logs          | {account#}/{vpc-name}/AWSLogs/{account#}/vpcflowlogs/{region}/{year}/{month}/{day}/\*     | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/123456789012/Test-East-lcl/AWSLogs/123456789012/vpcflowlogs/us-east-1/2020/08/31/123456789012_vpcflowlogs_us-east-1_fl-04af3543c74402594_20200831T1720Z_73d3922a.log.gz </li></ul>                                                                               |
+| Macie Reports          | {account#}/macietestobject                                                                | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/123456789014/macie-test-object </li></ul>                                                                                                                                                                                                                        |
+| Cost and Usage Reports | {account#}/cur/Cost-and-Usage-Report/\*                                                   | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/123456789015/cur/Cost-and-Usage-Report/\* </li></ul>                                                                                                                                                                                                             |
+| Config History         | AWSLogs/{account#}/Config/{region}/{year}/{month}/{day}/ConfigHistory/\*                  | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/AWSLogs/123456789016/Config/ca-central-1/2020/8/31/ConfigHistory/123456789016_Config_ca-central-1_ConfigHistory_AWS::CloudFormation::Stack_20200831T011226Z_20200831T025845Z_1.json.gz </li></ul>                                                                |
+| Config Snapshot        | AWSLogs/{account#}/Config/{region}/{year}/{month}/{day}/ConfigSnapshot/\*                 | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/AWSLogs/123456789016/Config/ca-central-1/2020/8/30/ConfigSnapshot/123456789016_Config_ca-central-1_ConfigSnapshot_20200830T193058Z_5d173149-e6d0-41e4-af7f-031ff736f8c8.json.gz </li></ul>                                                                       |
+| GuardDuty              | AWSLogs/{account#}/GuardDuty/{region}/{year}/{month}/{day}/\*                             | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/AWSLogs/123456789014/GuardDuty/ca-central-1/2020/09/02/294c9171-4867-3774-9756-f6f6c209616f.jsonl.gz </li></ul>                                                                                                                                                  |
+| CloudWatch Logs        | CloudWatchLogs/{year}/{month}/{day}/{hour}/\*                                             | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/CloudWatchLogs/2020/08/30/00/PBMMAccel-Kinesis-Delivery-Stream-1-2020-08-30-00-53-33-35aeea4c-582a-444b-8afa-848567924094 </li></ul>                                                                                                                             |
+| CloudTrail Digest      | {org-id}/AWSLogs/{org-id}/{account#}/CloudTrail-Digest/{region}/{year}/{month}/{day}/\*   | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/o-fxozgwu6rc/AWSLogs/o-fxozgwu6rc/123456789016/CloudTrail-Digest/ca-central-1/2020/08/30/123456789016_CloudTrail-Digest_ca-central-1_PBMMAccel-Org-Trail_ca-central-1_20200830T190938Z.json.gz </li></ul>                                                        |
+| CloudTrail Insights    | {org-id}/AWSLogs/{org-id}/{account#}/CloudTrail-Insights/{region}/{year}/{month}/{day}/\* | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/o-fxozgwu6rc/AWSLogs/o-fxozgwu6rc/123456789015/CloudTrail-Insight/ca-central-1/2020/09/23/123456789015_CloudTrail-Insight_ca-central-1_20200923T0516Z_KL5e9VCV2SS7IqzB.json.gz </li></ul>                                                                        |
+| CloudTrail             | {org-id}/AWSLogs/{org-id}/{account#}/CloudTrail/{region}/{year}/{month}/{day}/\*          | <ul><li> s3://pbmmaccel-logarchive-phase0-cacentral1-1tr23emhncdzo/o-fxozgwu6rc/AWSLogs/o-fxozgwu6rc/123456789016/CloudTrail/ca-central-1/2020/08/30/123456789016_CloudTrail_ca-central-1_20200830T0115Z_3YQJxwt5qUaOzMtL.json.gz </li></ul>                                                                                        |
+
+---
+
+### Notes:
+
+- Account number is sometimes duplicated in path because logs replicated from another account always need to start with the source account number
+- Macie reports will only appear in the {account#} for the central security account, and only if a customer schedules PII discovery reports
+- All CloudWatch Logs from all accounts are mixed in the same folder, the embedded log format contains the source account information as documented here: https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/ValidateLogEventFlow.html
+- With the exception of CloudWatch Logs, all logs are in the original format provided by the log source/service.
+
+---
+
+[...Return to Accelerator Table of Contents](../../index.md)
+

docs/index.md

@@ -8,6 +8,7 @@
 
 - Link to [releases](https://github.com/aws-samples/aws-secure-environment-accelerator/releases)
 - [Link](./installation/customization-index.md) to sample config file and customization details
+- [Link](./architectures/pbmm/log-file-locations.md) to AWS SEA Central Logging Bucket Structures
 
 ### - [Accelerator Operations/Troubleshooting Guide](./operations/operations-troubleshooting-guide.md)
 

docs/installation/installation.md

@@ -30,6 +30,7 @@ These installation instructions assume the prescribed architecture is being depl
     - [2.0.8. Can I upgrade directly to the latest release, or must I perform upgrades sequentially?](#208-can-i-upgrade-directly-to-the-latest-release-or-must-i-perform-upgrades-sequentially)
     - [2.0.9. Can I update the config file while the State Machine is running? When will those changes be applied?](#209-can-i-update-the-config-file-while-the-state-machine-is-running-when-will-those-changes-be-applied)
     - [2.0.10. How do I update some of the supplied sample configuration items found in reference-artifact, like SCPs and IAM policies?](#2010-how-do-i-update-some-of-the-supplied-sample-configuration-items-found-in-reference-artifact-like-scps-and-iam-policies)
+    - [2.0.11. I wish to be in compliance with the 12 TBS Guardrails, what don't you cover with the provided sample architecture?](#2011-i-wish-to-be-in-compliance-with-the-12-tbs-guardrails-what-dont-you-cover-with-the-provided-sample-architecture)
 - [3. Notes](#3-notes)
   - [3.1. Upgrades](#31-upgrades)
     - [3.1.1. Summary of Upgrade Steps (all versions)](#311-summary-of-upgrade-steps-all-versions)
@@ -367,15 +368,26 @@ To overide items like SCP's or IAM policies, customers simply need to provide th
 
 The Accelerator was designed to allow customers complete customization capabilities without any requirement to update code or fork the GitHub repo. Additionally, rather than forcing customers to provide a multitude of config files for a standard or prescriptive installation, we provide and auto-deploy with Accelerator versions of most required configuration items from the reference-artifacts folder of the repo. If a customer provides the required configuration file in their Acclerator S3 input bucket, we will use the customer supplied version of the configuration file rather than the Accelerator version. At any time, either before initial installation, or in future, a customer can place updated SCPs, policies, or other supported file types into their input bucket and we will use those instead of Accelerator supplied versions. If a customer wishes to revert to the sample configuration, simply removing the specific files from their S3 bucket and rerunning the accelerator will revert to the repo version of the removed files. Customer only need to provide the specific files they wish to overide, not all files.
 
+### 2.0.11. I wish to be in compliance with the 12 TBS Guardrails, what don't you cover with the provided sample architecture?
+
+The AWS SEA allows for a lot of flexibility in deployed architectures. If used, the provided PBMM sample architecture was designed to deliver on the technical portion of _all_ 12 of the GC guardrails, when automation was possible.
+
+What don't we cover? Assigning MFA to users is a manual process. Specifically you need to procure Yubikeys for your root/break glass users, and enable a suitable form of MFA for _all_ other users (i.e. virtual, email, other). The guardrails also include some organizational processes (i.e. break glass procedures, or signing an MOU with CCCS) which customers will need to work through independently.
+
+While AWS is providing the tools to help customer be compliant with the 12 PBMM guardrails (which were developed in collaboration with the GC) - it's up to each customers ITSec organization to assess and determine if the deployed controls actually meet their security requirements.
+
+Finally, while we started with a goal of delivering on the 12 guardrails, we believe we have extended well beyond those security controls, to further help customers move towards meeting the full PBMM technical control profile (official documentation is weak in this area at this time).
+
 # 3. Notes
 
 ## 3.1. Upgrades
 
 - Always compare your configuration file with the config file from the latest release to validate new or changed parameters or changes in parameter types / formats.
-- Upgrades to v1.2.0 and above from v1.1.9 and below require setting `account-warming-required` to `false`, (Perimeter and Ops accounts) or the rsyslog and firewalls will be removed and then re-installed on the subsequent state machine execution
-- Upgrades from v1.1.7 and below require the one-time removal of incorrectly created and associated resolver rules for private DNS domains. While we created a manual [script](../reference-artifacts/Custom-Scripts/resolver-rule-cleanup.sh) to remove the incorrect associations, it is quicker to manually delete the incorrect associations using the console (`shared-network` account, Route 53, Resolvers).
-- Upgrades from versions v1.1.6 and below require updating the `GithubRepository` in the CFN stack, as we renamed the GitHub repo with release v1.1.7 to `aws-secure-environment-accelerator`.
-- Upgrades to v1.1.5 and above from v1.1.4 and below:
+- Upgrades to `v1.2.2 and above` from v1.2.1 and below - if more than 5 VPC endpoints are deployed in any account (i.e. endpoint vpc in the shared network account), before upgrade, they must be removed from the config file and state machine executed to de-provision them. Endpoints can be re-deployed during the upgrade state machine execution. Skipping this step will result in an upgrade failure due to throttling issues.
+- Upgrades to `v1.2.0 and above` from v1.1.9 and below require setting `account-warming-required` to `false`, (Perimeter and Ops accounts) or the rsyslog and firewalls will be removed and then re-installed on the subsequent state machine execution
+- Upgrades from `v1.1.7 and below` require the one-time removal of incorrectly created and associated resolver rules for private DNS domains. While we created a manual [script](../reference-artifacts/Custom-Scripts/resolver-rule-cleanup.sh) to remove the incorrect associations, it is quicker to manually delete the incorrect associations using the console (`shared-network` account, Route 53, Resolvers).
+- Upgrades from `v1.1.6 and below` require updating the `GithubRepository` in the CFN stack, as we renamed the GitHub repo with release v1.1.7 to `aws-secure-environment-accelerator`.
+- Upgrades to `v1.1.5 and above` from v1.1.4 and below:
   - requires providing the "overrideComparison": true flag to the State Machine, as we are changing file formats and cannot compare to previous config file versions. Use extra caution, as we are not blocking breaking changes to the configuration file when this parameter is provided. (As the State Machine self-executes without the above parameter, it will fail on first run. Rerun the State Machine providing the parameter)
   - High probability of a State Machine failure due to a 1hr step timeout limitation. No easy fix available. Simply rerun the State Machine. We are reversing something from the v1.1.4 release which is extremely time consuming.
 
@@ -389,7 +401,7 @@ The Accelerator was designed to allow customers complete customization capabilit
   - Redeploy the Installer CFN stack using the latest template (provide bucket name and notification email address)
   - The pipeline will automatically run and trigger the upgraded state machine
 - If you are using a pre-existing GitHub token:
-  - Update the Installer CFN stack, providing the `GithubBranch` associated with the release (eg. `release/v1.2.0`)
+  - Update the Installer CFN stack using the latest template, providing the `GithubBranch` associated with the release (eg. `release/v1.2.2`)
     - Go To Code Pipeline and Release the PBMMAccel-InstallerPipeline
 
 ## 3.2. Configuration File Hints and Tips