Skip to content

Commit 387aa7d

Browse files
Brian969Brian969
authored
More doc tweaks (#421)
- add unofficial roadmap - add PDF ZIP to ToC - minor doc tweaks
1 parent 25159a5 commit 387aa7d

File tree

5 files changed

+122
-13
lines changed

5 files changed

+122
-13
lines changed

‎README.md‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -132,13 +132,14 @@ This summarizes the installation process, the full installation document can be
132132
- deploy, configure and guardrail multiple accounts at the same time
133133
- change Accelerator configuration settings
134134

135-
# **Documentation** (Linked)
135+
# **Documentation**
136136

137137
### - [Installation, Upgrades and Basic Operations Guide](./docs/installation/installation.md)
138138

139139
- Link to [releases](https://github.com/aws-samples/aws-secure-environment-accelerator/releases)
140-
- [Link](./docs/installation/customization-index.md) to sample config file and customization details
141-
- [Link](./docs/architectures/pbmm/log-file-locations.md) to AWS SEA Central Logging Bucket Structures
140+
- [Link](./docs/installation/customization-index.md) to sample config files and customization details
141+
- AWS SEA Central Logging [Bucket Structures](./docs/architectures/pbmm/log-file-locations.md)
142+
- Unofficial [Roadmap](./docs/roadmap.md)
142143

143144
### - [Accelerator Operations/Troubleshooting Guide](./docs/operations/operations-troubleshooting-guide.md)
144145

@@ -152,4 +153,8 @@ This summarizes the installation process, the full installation document can be
152153

153154
---
154155

155-
[...Go to Accelerator Table of Contents](./docs/index.md)
156+
Note: A ZIP file containing a PDF version of all documentation can be found [here](https://github.com/aws-samples/aws-secure-environment-accelerator/actions?query=workflow%3A%22Generate+Documentation%22).
157+
158+
---
159+
160+
[Go to Accelerator Table of Contents](./docs/index.md)

‎docs/index.md‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
# AWS Secure Environment Accelerator
22

3-
## **Documentation** (Linked)
3+
## **Documentation**
44

5-
### - [Solution Summary / Repo Root](../README.md)
5+
### - [Solution Summary / Repo root](../README.md)
6+
7+
- Unofficial [Roadmap](./roadmap.md)
68

79
### - [Installation, Upgrades and Basic Operations Guide](./installation/installation.md)
810

911
- Link to [releases](https://github.com/aws-samples/aws-secure-environment-accelerator/releases)
10-
- [Link](./installation/customization-index.md) to sample config file and customization details
11-
- [Link](./architectures/pbmm/log-file-locations.md) to AWS SEA Central Logging Bucket Structures
12+
- [Link](./installation/customization-index.md) to sample config files and customization details
13+
- AWS SEA Central Logging [Bucket Structures](./architectures/pbmm/log-file-locations.md)
1214

1315
### - [Accelerator Operations/Troubleshooting Guide](./operations/operations-troubleshooting-guide.md)
1416

@@ -18,6 +20,10 @@
1820

1921
### - [Prescriptive PBMM Architecture Design Document](./architectures/pbmm/architecture.md) (Early Draft)
2022

21-
### - [Frequently Asked Questions](./faq/faq.md)
23+
### - [Frequently Asked Questions](./faq/faq.md) (Future)
24+
25+
---
26+
27+
Note: A ZIP file containing a PDF version of all documentation can be found [here](https://github.com/aws-samples/aws-secure-environment-accelerator/actions?query=workflow%3A%22Generate+Documentation%22).
2228

2329
---

‎docs/installation/installation.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -117,10 +117,11 @@ If deploying to an internal AWS account, to successfully install the entire solu
117117

118118
### 1.2.2. Basic Accelerator Configuration
119119

120-
1. You can use the [`config.example.json`](../../reference-artifacts/config.example.json) file as base
120+
1. You can use the [`config.example.json`](../../reference-artifacts/config.example.json) or [`config.lite-example.json`](../../reference-artifacts/config.lite-example.json) files as base
121121
- Use the version from the Github code branch you are deploying from as some parameters have changed over time
122122
- On upgrades, compare your deployed configuration file with the latest branch configuration file for any new or changed parameters
123-
- This configuration file can be used, as-is, with only minor modification to successfully deploy the standard architecture
123+
- These configuration files can be used, as-is, with only minor modification to successfully deploy the standard architecture
124+
- These files are described in more detail [here](./customization-index.md)
124125
2. At minimum, you MUST update the AWS account names and email addresses in the sample file:
125126

126127
1. For existing accounts, they must match identically to the account names and email addresses defined in AWS Organizations;
@@ -383,7 +384,7 @@ Finally, while we started with a goal of delivering on the 12 guardrails, we bel
383384
## 3.1. Upgrades
384385

385386
- 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.
386-
- Upgrades to `v1.2.1 and above` from v1.2.0 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.
387+
- Upgrades to `v1.2.1 and above` from v1.2.0 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. Up to approximately 50 endpoints can be re-deployed during the upgrade state machine execution. Skipping this step will result in an upgrade failure due to throttling issues.
387388
- 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
388389
- 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).
389390
- 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`.
@@ -411,7 +412,7 @@ Finally, while we started with a goal of delivering on the 12 guardrails, we bel
411412
- Shard count - can only increase/reduce by half the current limit. i.e. you can change from `1`-`2`, `2`-`3`, `4`-`6`
412413
- Always add any new items to the END of all lists or sections in the config file, otherwise
413414
- Update validation checks will fail (vpc's, subnets, share-to, etc.)
414-
- VPC endpoint deployments will fail - do NOT re-order or insert VPC endpoints (unless you first remove them all completely, execute the state machine, then re-add them, and again run the state machine)
415+
- VPC endpoint deployments will fail - do NOT re-order or insert VPC endpoints (unless you first remove them all completely, execute the state machine, then re-add them, and again run the state machine) - this challenge no longer exists as of v1.2.1.
415416
- To skip, remove or uninstall a component, you can simply change the section header, instead of removing the section
416417
- change "deployments"/"firewalls" to "deployments"/"xxfirewalls" and it will uninstall the firewalls and maintain the old config file settings for future use
417418
- Objects with the parameter deploy: true, support setting the value to false to remove the deployment

‎docs/roadmap.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# AWS Secure Environment Accelerator
2+
3+
# **Roadmap**
4+
5+
- This is an unofficial roadmap to provide customers with a general product direction
6+
- This roadmap does not constitute a commitment, items can be added, removed, and re-prioritized at any time, for any reason
7+
- We are not providing any feature release timelines or commitments
8+
9+
---
10+
11+
## In-Progress
12+
13+
- Deploy SSM Automation documents (needed for AWS Config Remediation)
14+
- Deploy Managed AWS Config rules per ou, globally
15+
- First sample rule: auto-enable logging on new ELB's (includes remediation)
16+
- Followed by a collection of NIST 800-53 non-remediating rules
17+
- Include SCP to protect 'PBMMAccel-' prefixed Config rules
18+
- Documentation updates, improvements and finalization
19+
- Ongoing defect remediation and codebase improvements
20+
21+
## Planned
22+
23+
- Deploy additional specific remediating Config rules
24+
- Dependant on current in-progress tasks
25+
- Auto-remediate unencrypted S3 buckets
26+
- Auto-remediate missing role on all new and existing EC2 instances
27+
- Auto-remediate missing permissions on all new and existing EC2 instances
28+
- See: https://aws.amazon.com/blogs/mt/applying-managed-instance-policy-best-practices/
29+
- Deploy Customer provided Lambda's (if required for above Config rule remediations)
30+
- Enable NEW Guardduty S3 features moved from Macie
31+
- Push CloudWatch Log Agent using Run Command - all instances
32+
- Enable 'SSM Global Inventory (Managed Instance Config)
33+
- https://docs.aws.amazon.com/config/latest/developerguide/recording-managed-instance-inventory.html
34+
- https://aws.amazon.com/about-aws/whats-new/2018/11/aws-systems-manager-now-supports-multi-account-and-multi-region-inventory-view/
35+
- Firewall tweaks: Add out-of-box A/P firewall support, 2nd tunnel support
36+
- Add support for this new S3 feature: https://aws.amazon.com/about-aws/whats-new/2020/10/amazon-s3-object-ownership-enables-bucket-owners-to-automatically-assume-ownership-of-objects-uploaded-to-their-buckets/
37+
- Full PBMM/Medium Cloud Security Profile ITSG write-ups / Documentation
38+
- SCP improvements and improved coverage (i.e. S3)
39+
40+
## Assessing
41+
42+
- Spoke sub-account local VPC CIDR management
43+
- Deploy customer provided Service Catalog Items
44+
- Improve existing ALB deployment codebase (add http support, alarms, add seperate health-check VIF)
45+
- Mechanism to allow sub-accounts to request perimeter FW/ALB flow updates
46+
- Enable WAF on ALB's
47+
- Allow disabling SH rules on a per OU/account basis
48+
- Email SH findings/alerts based on risk rating
49+
- Encrypt all CWL groups w/CMK
50+
- Open security tools outside Canada (Core OU only?)
51+
- Config file cleanup and formal JSON schema
52+
- Adopt a JSON pointer syntax in config file (allow duplicate object naming)
53+
- improve consistency, remove type mutations, ensure multiples are implemented (or remove them until supported)
54+
- config file to become a contract
55+
56+
## WISH LIST
57+
58+
- Accelerator Wizard based GUI interface (to abstract/hide the configuration file)
59+
- Easy mode (limited selections) and Advanced mode (extreme customization)
60+
- Deployed in Ops account, permissions based on IAM credentials
61+
- Org Admin can make any configuration change
62+
- Account Admin creates accounts, makes minor changes, approves user requests
63+
- Users can request a 'set of accounts' of a certain type, request account changes, a flow, or a custom vpc
64+
- Phased deliver (Org Admin Wizard on day 1, slowly add workflows)
65+
66+
---
67+
68+
[...Return to Accelerator Table of Contents](./index.md)

‎index.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# AWS Secure Environment Accelerator
2+
3+
## **Documentation**
4+
5+
### - [Solution Summary / Repo root](../README.md)
6+
7+
- Unofficial [Roadmap](./roadmap.md)
8+
9+
### - [Installation, Upgrades and Basic Operations Guide](./installation/installation.md)
10+
11+
- Link to [releases](https://github.com/aws-samples/aws-secure-environment-accelerator/releases)
12+
- [Link](./installation/customization-index.md) to sample config files and customization details
13+
- [Link](./architectures/pbmm/log-file-locations.md) to AWS SEA Central Logging Bucket Structures
14+
15+
### - [Accelerator Operations/Troubleshooting Guide](./operations/operations-troubleshooting-guide.md)
16+
17+
### - [Accelerator Developer Guide](./developer/developer-guide.md) (Early Draft)
18+
19+
### - [Accelerator Governance and Contributing Guide](../CONTRIBUTING.md) (Early Draft)
20+
21+
### - [Prescriptive PBMM Architecture Design Document](./architectures/pbmm/architecture.md) (Early Draft)
22+
23+
### - [Frequently Asked Questions](./faq/faq.md)
24+
25+
---
26+
27+
Note: A ZIP file containing a PDF version of all documentation can be found [here](https://github.com/aws-samples/aws-secure-environment-accelerator/actions?query=workflow%3A%22Generate+Documentation%22).
28+
29+
---

0 commit comments

Comments
 (0)