From ab57179de1a7845e7353a3e2715a9e2bf17d3f37 Mon Sep 17 00:00:00 2001 From: Paul Schwarzenberger Date: Mon, 16 Dec 2024 21:36:52 +0000 Subject: [PATCH] Update docs --- docs/installation.md | 14 ++----- docs/integration-tests.md | 18 ++++++++- mkdocs.yml | 85 +++++++++++++++++++++------------------ 3 files changed, 65 insertions(+), 52 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index 7a05b967..3c156b6e 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,7 +4,7 @@ Before starting ensure [requirements](requirements.md) are met ## Initial installation -* Include the following code snippet to your code +* Include a code snippet in your code based on the example below: ``` module "domain_protect" { @@ -13,24 +13,16 @@ module "domain_protect" { 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 +* Add extra variables if desired as detailed in [module inputs](https://registry.terraform.io/modules/domain-protect/domain-protect/aws/latest?tab=inputs) * 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 | "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"] | +## Examples -* 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 diff --git a/docs/integration-tests.md b/docs/integration-tests.md index 37dd46d9..aaf83707 100644 --- a/docs/integration-tests.md +++ b/docs/integration-tests.md @@ -4,7 +4,23 @@ Domain protect uses `pytest` to run unit tests against the code, and will fail the build if any tests fail. All integration tests live under the `integration_tests` folder in the root of the solution. -Integration tests test a single flow through the application, involving multiple units interacting, mocking out external dependencies. This ensures flows through the application provide the correct results when the units work together. +Integration tests test a single flow through the application, involving multiple units interacting. This ensures flows through the application provide the correct results when the units work together. + +## Integration Tests - Manual Scans + +Integration tests for manual scans have been set up using Mocks to simulate the responses from AWS or CloudFlare. They can therefore easily be run locally. + +## Integration Tests - Deployment + +Deployment integration tests are set up without using Mocks, as follows: + +* plan and apply Terraform within an AWS Account in a test AWS Organization +* create deliberately vulnerable DNS records in AWS +* create deliberately vulnerable DNS records in CloudFlare +* trigger the appropriate Domain Protect Lambda functions +* ensure that the vulnerabilities are detected in the specified timeframe, by querying DynamoDB +* delete the vulnerable DNS records +* ensure the vulnerabilities are marked as fixed within the database. ## Running tests locally diff --git a/mkdocs.yml b/mkdocs.yml index c3a01f67..6d0f0dd0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -46,49 +46,54 @@ extra: nav: - Home: index.md - - Manual AWS scans: manual-aws-scans.md - - Manual Cloudflare scans: manual-cf-scans.md - Architecture: architecture.md - - Database: database.md - - Reports: reports.md - - Automated takeover: automated-takeover.md - - Cloudflare: cloudflare.md - - Bugcrowd: bugcrowd.md - - HackerOne: hackerone.md - - Vulneratbility types: vulnerability-types.md - - Vulnerable A records (IP addresses): a-records.md - - 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 - - Development: development.md - - Code Standards: code-standards.md - - Automated Tests: automated-tests.md - - Manual Tests: manual-tests.md - - Individual Manual Tests: - - A record Elastic IP / EC2: test-records/a-eip.md - - A record Global Accelerator: test-records/a-globalaccelerator.md - - Alias CloudFront S3: test-records/alias-cloudfront.md - - Alias Elastic Beanstalk: test-records/alias-eb.md - - Alias S3: test-records/alias-s3.md - - CNAME Azure: test-records/cname-azure.md - - CNAME CloudFront S3: test-records/cname-cloudfront.md - - CNAME Elastic Beanstalk: test-records/cname-eb.md - - CNAME Google: test-records/cname-google.md - - CNAME S3: test-records/cname-s3.md - - NS Subdomain: test-records/ns-subdomain.md - - NS Domain: test-records/ns-domain.md - - CloudFlare Azure: test-records/cloudflare-azure.md - - Cloudflare CNAME: test-records/cloudflare-cname.md - - Cloudflare Elastic Beanstalk: test-records/cloudflare-eb.md - - CloudFlare NS: test-records/cloudflare-ns.md - - Cloudflare S3: test-records/cloudflare-s3.md - - A records (IP addresses): a-records.md - - Takeover: automated-takeover.md + - Features: + - Database: database.md + - Reports: reports.md + - Automated takeover: automated-takeover.md - Cloudflare: cloudflare.md - Bugcrowd: bugcrowd.md + - HackerOne: hackerone.md + - Vulneratbility types: vulnerability-types.md + - Vulnerable A records (IP addresses): a-records.md + - Installation: + - 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 + - Manual scans: + - Manual AWS scans: manual-aws-scans.md + - Manual Cloudflare scans: manual-cf-scans.md + - Development: + - Development: development.md + - Code Standards: code-standards.md + - Automated Tests: automated-tests.md + - Manual Tests: manual-tests.md + - Individual Manual Tests: + - A record Elastic IP / EC2: test-records/a-eip.md + - A record Global Accelerator: test-records/a-globalaccelerator.md + - Alias CloudFront S3: test-records/alias-cloudfront.md + - Alias Elastic Beanstalk: test-records/alias-eb.md + - Alias S3: test-records/alias-s3.md + - CNAME Azure: test-records/cname-azure.md + - CNAME CloudFront S3: test-records/cname-cloudfront.md + - CNAME Elastic Beanstalk: test-records/cname-eb.md + - CNAME Google: test-records/cname-google.md + - CNAME S3: test-records/cname-s3.md + - NS Subdomain: test-records/ns-subdomain.md + - NS Domain: test-records/ns-domain.md + - CloudFlare Azure: test-records/cloudflare-azure.md + - Cloudflare CNAME: test-records/cloudflare-cname.md + - Cloudflare Elastic Beanstalk: test-records/cloudflare-eb.md + - CloudFlare NS: test-records/cloudflare-ns.md + - Cloudflare S3: test-records/cloudflare-s3.md + - A records (IP addresses): a-records.md + - Takeover: automated-takeover.md + - Cloudflare: cloudflare.md + - Bugcrowd: bugcrowd.md + - HackerOne: hackerone.md - Conference Talks and Blog Posts: talks.md plugins: