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

Update docs
domain-protect · Dec 16, 2024 · a2c8d35 · a2c8d35
2 parents fa071d7 + ab57179
commit a2c8d35
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 52 deletions.
diff --git 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
@@ -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
@@ -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: