From 077026f4c150ad25bd174e365dde16cc4fefbd78 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Mon, 2 Dec 2024 21:08:14 +0000 Subject: [PATCH 1/5] Documentation updates --- README.md | 9 +++- docs/index.md | 13 +++-- docs/installation.md | 113 ++++++++++++------------------------------- docs/migration.md | 32 ++++++++++++ docs/requirements.md | 4 +- variables.tf | 1 - 6 files changed, 81 insertions(+), 91 deletions(-) create mode 100644 docs/migration.md diff --git a/README.md b/README.md index 7bfe110e..a579f318 100644 --- 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. diff --git a/docs/index.md b/docs/index.md index aa06bd37..276bcb9e 100644 --- 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) + +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*
[Requirements](requirements.md)
[Installation](installation.md)
+[Migration](migration.md)
[Slack Webhooks](slack-webhook.md)
[AWS IAM policies](aws-iam-policies.md)
[CI/CD](ci-cd.md)
diff --git a/docs/installation.md b/docs/installation.md index ca2cf412..bf3c10bb 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,101 +1,50 @@ # Installation Before starting ensure [requirements](requirements.md) are met -## GitHub Actions (recommended) - +## 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 = var.environment + org_primary_account = var.org_primary_account + security_audit_role_name = var.security_audit_role_name + slack_channels = var.slack_channels + slack_webhook_urls = var.slack_webhook_urls } ``` +* 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 GitHub Actions environment variables +* The Slack webhook URL is sensitive and should be protected, e.g. as a GitHub Actions 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 | "012345678901" | +| security_audit_role_name | "dp-audit" (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 imputs](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 new file mode 100644 index 00000000..c4c667d2 --- /dev/null +++ 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 index 57e234a7..153f2b3d 100644 --- 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 index ccebeb0d..29070eb9 100644 --- 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 } From cac0852555f1fd42efe151d10ddf84eec0f98879 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Tue, 3 Dec 2024 21:53:56 +0000 Subject: [PATCH 2/5] address PR comments --- README.md | 2 +- docs/installation.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a579f318..0d3d2358 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ No resources. | [lambdas](#input\_lambdas) | list of names of Lambda files in the lambda/code folder | `list(any)` | 
[
  "current",
  "update"
]
| no | | [memory\_size](#input\_memory\_size) | Memory allocation for scanning Lambda functions | `number` | `128` | no | | [memory\_size\_slack](#input\_memory\_size\_slack) | Memory allocation for Slack Lambda functions | `number` | `128` | no | -| [org\_primary\_account](#input\_org\_primary\_account) | The AWS account number of the organization primary account | `string` | `""` | no | +| [org\_primary\_account](#input\_org\_primary\_account) | The AWS account number of the organization primary account | `string` | n/a | yes | | [permissions\_boundary\_arn](#input\_permissions\_boundary\_arn) | permissions boundary ARN to attach to every IAM role | `string` | `null` | no | | [platform](#input\_platform) | Python platform used for install of Regex and other libraries | `string` | `"manylinux2014_x86_64"` | no | | [production\_environment](#input\_production\_environment) | Name of production environment - takeover is only turned on in this environment | `string` | `""` | no | diff --git a/docs/installation.md b/docs/installation.md index bf3c10bb..05f5311f 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,19 +19,19 @@ module "domain_protect" { } ``` * 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 GitHub Actions environment variables -* The Slack webhook URL is sensitive and should be protected, e.g. as a GitHub Actions secret +* 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 | VARIABLE | EXAMPLE VALUE / COMMENT | | ------------------------------- | ------------------------------------------------------| | environment | "dev" (not needed if Terraform workspace used) | -| org_primary_account | "012345678901" | +| org_primary_account | "012345678901" | | security_audit_role_name | "dp-audit" (not needed if "domain-protect-audit" used)| | slack_channels | ["security-alerts-dev"] | -| slack_webhook_urls | ["https://hooks.slack.com/services/XXX/XXX/XXX"] | +| slack_webhook_urls | ["https://hooks.slack.com/services/XXX/XXX/XXX"] | * Add extra variables if desired as detailed in [Module imputs](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 +* 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 ## Multiple environments Domain Protect is designed so that multiple environments can be deployed, e.g. `dev` and `prd`. From c5011c18ded3c44ed27ceb6fd34e4080723894c9 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Tue, 3 Dec 2024 21:59:06 +0000 Subject: [PATCH 3/5] address PR comments --- docs/installation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 05f5311f..c342cb11 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -11,11 +11,11 @@ module "domain_protect" { source = "domain-protect/domain-protect/aws" version = "1.0.0" - environment = var.environment - org_primary_account = var.org_primary_account - security_audit_role_name = var.security_audit_role_name - slack_channels = var.slack_channels - slack_webhook_urls = var.slack_webhook_urls + 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) @@ -25,8 +25,8 @@ module "domain_protect" { | VARIABLE | EXAMPLE VALUE / COMMENT | | ------------------------------- | ------------------------------------------------------| | environment | "dev" (not needed if Terraform workspace used) | -| org_primary_account | "012345678901" | -| security_audit_role_name | "dp-audit" (not needed if "domain-protect-audit" 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"] | From db3d45599a7e3557dc85b94f6db021c8613d9088 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Tue, 3 Dec 2024 22:00:56 +0000 Subject: [PATCH 4/5] Update docs/installation.md Co-authored-by: RB <7775707+nitrocode@users.noreply.github.com> --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index c342cb11..cb9d3ff2 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -30,7 +30,7 @@ module "domain_protect" { | slack_channels | ["security-alerts-dev"] | | slack_webhook_urls | ["https://hooks.slack.com/services/XXX/XXX/XXX"] | -* Add extra variables if desired as detailed in [Module imputs](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest?tab=inputs) +* 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 ## Multiple environments From b159b9ab7f4b5049e14dd7db254ebbbdc61b6d27 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Tue, 3 Dec 2024 22:05:00 +0000 Subject: [PATCH 5/5] address PR comments --- docs/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation.md b/docs/installation.md index cb9d3ff2..7a05b967 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -31,7 +31,7 @@ module "domain_protect" { | slack_webhook_urls | ["https://hooks.slack.com/services/XXX/XXX/XXX"] | * 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 +* 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 ## Multiple environments Domain Protect is designed so that multiple environments can be deployed, e.g. `dev` and `prd`.