Merge pull request #153 from domain-protect/doc-updates

Documentation updates
domain-protect · Dec 3, 2024 · 2401e53 · 2401e53
2 parents cb9da3d + b159b9a
commit 2401e53
Show file tree

Hide file tree

Showing 6 changed files with 82 additions and 92 deletions.
diff --git a/README.md b/README.md
@@ -28,8 +28,13 @@ Talk and demo on [YouTube](https://youtu.be/fLrRLmKZTvE)
 * [manual scans](manual_scans/aws/README.md) of cloud accounts with no installation
 
 ## Installation
-* the simplest way to install is to use the separate [Domain Protect Deploy](https://github.com/domain-protect/domain-protect-deploy) repository with GitHub Actions deployment workflow
-* for other methods see [Installation](docs/installation.md)
+* Domain Protect is packaged as a [public Terraform Module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
+* Ensure [requirements](/docs/requirements.md) are met
+* See [Installation](docs/installation.md) for details on how to install
+
+## Migration
+
+See [migration](/docs/migration.md) for a guide to migrating from the [original Domain Protect repository](https://github.com/domain-protect/domain-protect) to the [Terraform Module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
 
 ## Collaboration
 > 📢 We welcome contributions! Please see the [OWASP Domain Protect website](https://owasp.org/www-project-domain-protect/) for more details.
@@ -115,7 +120,7 @@ No resources.
 | <a name="input_lambdas"></a> [lambdas](#input\_lambdas) | list of names of Lambda files in the lambda/code folder | `list(any)` | <pre>[<br/>  "current",<br/>  "update"<br/>]</pre> | no |
 | <a name="input_memory_size"></a> [memory\_size](#input\_memory\_size) | Memory allocation for scanning Lambda functions | `number` | `128` | no |
 | <a name="input_memory_size_slack"></a> [memory\_size\_slack](#input\_memory\_size\_slack) | Memory allocation for Slack Lambda functions | `number` | `128` | no |
-| <a name="input_org_primary_account"></a> [org\_primary\_account](#input\_org\_primary\_account) | The AWS account number of the organization primary account | `string` | `""` | no |
+| <a name="input_org_primary_account"></a> [org\_primary\_account](#input\_org\_primary\_account) | The AWS account number of the organization primary account | `string` | n/a | yes |
 | <a name="input_permissions_boundary_arn"></a> [permissions\_boundary\_arn](#input\_permissions\_boundary\_arn) | permissions boundary ARN to attach to every IAM role | `string` | `null` | no |
 | <a name="input_platform"></a> [platform](#input\_platform) | Python platform used for install of Regex and other libraries | `string` | `"manylinux2014_x86_64"` | no |
 | <a name="input_production_environment"></a> [production\_environment](#input\_production\_environment) | Name of production environment - takeover is only turned on in this environment | `string` | `""` | no |

diff --git a/docs/index.md b/docs/index.md
@@ -19,7 +19,8 @@ Prevent subdomain takeover ...
 ![Alt text](assets/images/domain-protect.png?raw=true "Domain Protect architecture")
 
 ## OWASP Global AppSec Dublin - talk and demo
-[![Global AppSec Dublin 2023](assets/images/global-appsec-dublin.png)](https://youtu.be/fLrRLmKZTvE)
+<a href="#"><img src="https://raw.githubusercontent.com/domain-protect/terraform-aws-domain-protect/main/docs/assets/images/global-appsec-dublin.png" /></a>
+Talk and demo on [YouTube](https://youtu.be/fLrRLmKZTvE)
 
 ## Features
 * scan Amazon Route53 across an AWS Organization for domain records vulnerable to takeover
@@ -30,8 +31,13 @@ Prevent subdomain takeover ...
 * [manual scans](manual_scans/aws/README.md) of cloud accounts with no installation
 
 ## Installation
-* the simplest way to install is to use the separate [Domain Protect Deploy](https://github.com/domain-protect/domain-protect-deploy) repository with GitHub Actions deployment workflow
-* for other methods see [Installation](docs/installation.md)
+* Domain Protect is packaged as a [public Terraform Module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
+* Ensure [requirements](/docs/requirements.md) are met
+* See [Installation](docs/installation.md) for details on how to install
+
+## Migration
+
+See [migration](/docs/migration.md) for a guide to migrating from the [original Domain Protect repository](https://github.com/domain-protect/domain-protect) to the [Terraform Module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
 
 ## Collaboration
 We welcome collaborators! Please see the [OWASP Domain Protect website](https://owasp.org/www-project-domain-protect/) for more details.
@@ -50,6 +56,7 @@ We welcome collaborators! Please see the [OWASP Domain Protect website](https://
 [Vulnerable A records (IP addresses)](a-records.md) *optional feature*<br>
 [Requirements](requirements.md)<br>
 [Installation](installation.md)<br>
+[Migration](migration.md)<br>
 [Slack Webhooks](slack-webhook.md)<br>
 [AWS IAM policies](aws-iam-policies.md)<br>
 [CI/CD](ci-cd.md)<br>

diff --git a/docs/installation.md b/docs/installation.md
@@ -1,101 +1,50 @@
 # Installation
 
 Before starting ensure [requirements](requirements.md) are met
-## GitHub Actions (recommended)
 
-<img src="assets/images/pipeline.png">
+## Initial installation
 
-* deploy Domain Protect in your AWS Organization
-* no need to clone or fork Domain Protect
-* internal / private deployment repository to protect sensitive information
-* uses OpenID Connect - no IAM user with long-lived access keys
-* update to latest version of Domain Protect any time by running pipeline
+* Include the following code snippet to your code
 
-Follow detailed instructions in separate [Domain Protect Deploy](https://github.com/domain-protect/terraform-aws-domain-protect-deploy) repository with GitHub Actions deployment workflow
-
-## Atlantis
-
-Per [official documentation](https://www.runatlantis.io/), Atlantis is an application for automating Terraform via pull requests
-
-* For atlantis to work, you can simply create a new stack (folder) in your environment with the name `domain-protect`. You will then make the necessary changes to the `atlantis.yaml` file, so atlantis knows where all the terraform code is from.
-
-Example changes to `atlantis.yaml`:
-
-```yaml
-- name: domain-protect-security-audit
-  dir: security/domain-protect
-  workspace: security-audit
-  workflow: security-audit
-  terraform_version: 1.3.1
-```
-
-* In the `domain-protect` folder, you can copy the content of `main.tf` file from this repo. For each of the module, make sure you change the source to this repo so you can reuse the module here
-
-For example, update:
-
-```terraform
-module "kms" {
-  source  = "./modules/kms"
-  project = var.project
-  region  = var.region
-}
 ```
-
-to
-
-```terraform
-module "kms" {
-  source  =  "git::https://github.com/domain-protect/terraform-aws-domain-protect.git//modules/kms"
-  project = var.project
-  region  = var.region
+module "domain_protect" {
+  source  = "domain-protect/domain-protect/aws"
+  version = "1.0.0"
+
+  environment              = "dev"
+  org_primary_account      = "123456789012"
+  security_audit_role_name = "DomainProtectAudit"
+  slack_channels           = ["security-alerts-dev"]
+  slack_webhook_urls       = ["https://hooks.slack.com/services/XXX/XXX/XXX"]
 }
 ```
+* Replace the version with the latest in the [Terraform registry](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
+* Create variable values based on the example below in `terraform.tfvars` or as variables in your CI/CD pipeline
+* The Slack webhook URL is sensitive and should be protected, e.g. as a CI/CD pipeline secret
 
-Also, because of the way the lambda code modules are set up, you will need to copy the contents of `scripts/lambda-build`, `build` and `lambda_code` folders with the same path to your `domain-protect` folder. In the end, you will have a structure like this:
-
-* domain-protect
-  * main.tf
-  * variables.tf
-  * terraform.tfvars
-  * build
-  * lambda_code
-  * scripts
-    * lambda-build
-      * create-package-for-each.sh
-      * create-package.sh
-
-Finally, make sure you the scripts in `scripts/lambda-build` are executable before committing to your repo by running `chmod +x`
-
-The downside of this approach is changes to `build`, `lambda_code`, or `scripts` folders from source folder have to be synced manually to local folder
+| VARIABLE                        | EXAMPLE VALUE / COMMENT                               |
+| ------------------------------- | ------------------------------------------------------|
+| environment                     | "dev" (not needed if Terraform workspace used)        |
+| org_primary_account             | "123456789012"                                          |
+| security_audit_role_name        | "DomainProtectAudit" (not needed if "domain-protect-audit" used)|
+| slack_channels                  | ["security-alerts-dev"]                               |
+| slack_webhook_urls              | ["https://hooks.slack.com/services/XXX/XXX/XXX"]      |
 
-This is only one of the many ways to deploy with atlantis. You should tailor to your environment. Please reach out to us to brainstorm on your deployment workflow.
+* Add extra variables if desired as detailed in [module inputs](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest?tab=inputs)
+* see the [examples directory](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/examples) for complete Terraform examples including `provider.tf` and `backend.tf` files
 
-## Manual installation (not recommended)
+## Multiple environments
+Domain Protect is designed so that multiple environments can be deployed, e.g. `dev` and `prd`.
 
-* replace the Terraform state S3 bucket fields in the command below as appropriate
-* for local testing, duplicate `terraform.tfvars.example`, rename without the `.example` suffix
-* enter details appropriate to your organization and save
-* alternatively enter Terraform variables within your CI/CD pipeline
-* deploy development environment for detection only
-* default scan schedule for dev environment is 12 hours
+It's important that only one environment, e.g. `prd` can perform active takeover, to avoid conflicts between environments.
 
-```bash
-terraform init -backend-config=bucket=TERRAFORM_STATE_BUCKET -backend-config=key=TERRAFORM_STATE_KEY -backend-config=region=TERRAFORM_STATE_REGION
-terraform workspace new dev
-terraform plan
-terraform apply
-```
+* ensure you only set the variable `takeover = true` for a single environment, e.g. `prd`
 
-* deploy production environment for detection and automated takeover
-* default scan schedule for `prd` environment is 60 minutes
+Make sure to also update `production_environment` to match the `environment` variable when deploying to production.
 
-```bash
-terraform workspace new prd
-terraform plan
-terraform apply
-```
+## Terraform workspaces
 
-### Overriding workspace/environment name
+By default Domain Protect uses the value of the Terraform workspace, e.g. `dev` `prd` as the environment name
 
 If you're using external tooling or systems where `terraform.workspace` works differently, you can override the value by setting the `environment` variable.
 
@@ -104,8 +53,6 @@ If you're using external tooling or systems where `terraform.workspace` works di
 environment="prod" # used instead of terraform.workspace
 ```
 
-Make sure to also update `production_environment` to match the `environment` variable when deploying to production.
-
 ## Adding notifications to extra Slack channels
 
 * add an extra channel to your slack_channels variable list

diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,32 @@
+# Migration
+
+Domain Protect was initially published as a [stand-alone Terraform repository](https://domain-protect/domain-protect) which is no longer being maintained.
+
+Domain Protect has now been published as a [public Terraform module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest) from the repo [terraform-aws-domain-protect](https://github.com/domain-protect-terraform-aws-domain-protect).
+
+Users of Domain Protect should migrate to use the Terraform module which has the benefits of increased flexibility and straightforward updates.
+
+Steps to migrate from the stand-alone repository to the module are detailed below.
+
+## Migration Option 1 - Destroy and recreate
+
+This is the simplest option, however you will lose your vulnerability and IP address databases. There's also likely to be some downtime during the switchover.
+
+* Destroy the old evironment using `terraform destroy`
+* Create a new environment using the [Terraform module](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest)
+
+## Migration Option 2 - Phased upgrade
+
+Phased option preserving databases and avoiding downtime:
+
+* Upgrade Domain Protect using your existing deployment methodology from the [original Domain Protect repository](https://github.com/domain-protect/domain-protect) to version `0.5.1` and your current variables
+* This is pinned to use version `0.5.1` of the Terraform module
+* Create a new repository for your deployment(s), calling the Terraform module directly, which should result in no changes other than the usual Lambda rebuild
+* See the [examples folder](https://github.com/domain-protect/terraform-aws-domain-protect/tree/main/examples) in this repository for example Terraform
+* Update the Terraform module version to the latest version, this will require some adjustment of Terraform variables:
+
+    * `slack_channels_dev` no longer used - simply pass in different variables for each environment
+    * set `takeover` as `true` in prod and `false` in development environment
+
+* Ensure no changes with a Terraform plan for each environment, other than the usual Lambda rebuilds
+* After you've finished, destroy or archive your old repository
diff --git a/docs/requirements.md b/docs/requirements.md
@@ -1,12 +1,12 @@
 # Requirements
 
-In order to deploy resources from this repo successfully, it is necessary to meet the requirements below, as the terraform code we provide will not create them
+In order to deploy Domain Protect successfully, it is necessary to meet the requirements below, as the terraform module will not create them
 
 * Slack App or legacy Slack webhook, see [Slack Webhook](slack-webhook.md) for details
 * Security audit account within AWS Organizations
 * Security audit read-only role with an identical name in every AWS account of the Organization
 * Storage bucket for Terraform state file
-* OIDC role (preferred) or IAM user with [deploy policy](../aws-iam-policies/domain-protect-deploy.json) assigned, for CI/CD deployment
+* OIDC role with [deploy policy](../aws-iam-policies/domain-protect-deploy.json) assigned, for CI/CD deployment
 
 ## Security audit role in every AWS account
 

diff --git a/variables.tf b/variables.tf
@@ -12,7 +12,6 @@ variable "region" {
 
 variable "org_primary_account" {
   description = "The AWS account number of the organization primary account"
-  default     = ""
   type        = string
 }