AWS securityagent documentation change
Summary
Restructured domain verification process with detailed steps for adding target domains and verifying ownership via DNS TXT records or HTTP routes. Added explicit guidance for Route53 vs external DNS providers and HTTP token validation requirements.
Security assessment
The changes enhance documentation around domain verification requirements for penetration testing authorization, which is a security control to prevent unauthorized testing. However, there's no evidence of addressing a specific newly-discovered vulnerability. The updates clarify existing security processes rather than patching a weakness.
Diff
diff --git a/securityagent/latest/userguide/enable-test-domain.md b/securityagent/latest/userguide/enable-test-domain.md index af0dd41a1..2abc7e1a6 100644 --- a//securityagent/latest/userguide/enable-test-domain.md +++ b//securityagent/latest/userguide/enable-test-domain.md @@ -4,0 +5,2 @@ +Step 1: Add a target domainStep 2: Verify domain ownership + @@ -7 +9 @@ -Before you can run a penetration test on an application, you need to verify its domain name. AWS Security Agent will only perform penetration tests against validated domains. +Before you can run a penetration test on an application, you need to add a target domain and verify ownership. AWS Security Agent will only perform penetration tests against verified domains. @@ -13 +15,37 @@ You do not need to validate ancillary domains that your application may use. You - 1. Navigate to the Agent Space overview page +## Step 1: Add a target domain + +To add a target domain, navigate to the **Penetration test** tab on the Agent Space overview page. Depending on whether you have already configured penetration testing, use one of the following methods: + + * **First-time setup** : Choose **Set up penetration test** to open the penetration test wizard. In the first step, enter the domain and choose a verification method. + + * **Adding a domain to an existing configuration** : In the **Target Domains** table, choose **Add domain**. Enter the domain and choose a verification method in the modal. + + + + +You can add a base domain or a sub-domain, such as `example.com` or `billing.example.com`. AWS suggests using a sub-domain where you have permission to create `TXT` records. + +Choose one of the following verification methods: + + * **DNS TXT record** : Prove domain ownership by creating a DNS TXT record with your DNS provider. + + * **HTTP route** : Prove domain ownership by creating a route on your web server that contains a unique token provided by AWS Security Agent. + + + + +## Step 2: Verify domain ownership + +After adding the domain, verify ownership using the method you selected. You can trigger verification at any time from the **Target Domains** table by selecting the domain and choosing **Verify**. + +### Verify using a DNS TXT record + +AWS Security Agent generates a TXT DNS record value. You must add this record with your DNS provider to prove ownership. + +**If the domain is registered in Route 53 (same AWS account):** + +AWS Security Agent can create the DNS record automatically. Select the domain from the Target Domains table and choose **One-click verification**. AWS Security Agent creates the DNS validation record and completes verification automatically. + +**If the domain is registered with another DNS provider:** + + 1. Copy the TXT record value provided by AWS Security Agent. @@ -15 +53 @@ You do not need to validate ancillary domains that your application may use. You - 2. Select the **Penetration test** tab + 2. Add the TXT record with your DNS registrar. @@ -17 +55 @@ You do not need to validate ancillary domains that your application may use. You - 3. Select **Add domain** + 3. Return to the Target Domains table, select the domain, and choose **Verify**. @@ -19 +56,0 @@ You do not need to validate ancillary domains that your application may use. You - 4. Enter the domain you want to validate. You can validate a base domain, or a sub-domain, such as `example.com` or `billing.example.com`. AWS suggests validating a sub-domain where you have permission to create `TXT` records. @@ -21 +57,0 @@ You do not need to validate ancillary domains that your application may use. You - 5. Validate the domain. You can validate the domain in two ways: @@ -23 +58,0 @@ You do not need to validate ancillary domains that your application may use. You - * **DNS_TXT validation** : You prove domain ownership by creating a DNS TXT record. @@ -25 +60 @@ You do not need to validate ancillary domains that your application may use. You - * **Domains registered in Route53** : AWS Security Agent can automatically create the validation DNS records if the domain is registered in the same AWS Account. +### Verify using HTTP route validation @@ -27 +62 @@ You do not need to validate ancillary domains that your application may use. You - * **Other domains** : AWS Security Agent will generate a `TXT` DNS record. Update your DNS records with your registrar to include this validation record. +This method proves domain ownership by placing a unique token on your web server. Only domain owners or authorized web administrators can create routes on a web server, which proves ownership. @@ -29 +64 @@ You do not need to validate ancillary domains that your application may use. You - * **HTTP_ROUTE validation** : You prove domain ownership by creating a route path containing a unique token provided by the service in a certain JSON format on your web server. This method leverages the fact that only domain owners (or their authorized web administrators) can create routes to their web servers. + 1. Create a file at the following path on your web server: @@ -31 +66 @@ You do not need to validate ancillary domains that your application may use. You - * The route path should be created at the root of the domain. The route path is `.well-known/aws/securityagent-domain-verification.json` + .well-known/aws/securityagent-domain-verification.json @@ -33 +68 @@ You do not need to validate ancillary domains that your application may use. You - * The format for placing the tokens is: + 2. Place the token provided by AWS Security Agent in the file using this format: @@ -39 +74 @@ You do not need to validate ancillary domains that your application may use. You - * After you have placed the token, you can verify your ownership. The Security Agent service will do an HTTPS GET request call to the entire verification URL and will verify the token. + 3. Return to the Target Domains table, select the domain, and choose **Verify**. AWS Security Agent sends an HTTPS GET request to the verification URL and validates the token. @@ -41 +76 @@ You do not need to validate ancillary domains that your application may use. You - * If the domain is accessible on the public internet, make sure that your domain has a valid SSL certificate. + 4. If the domain is accessible on the public internet, make sure that your domain has a valid SSL certificate before running verification. @@ -48 +83 @@ You do not need to validate ancillary domains that your application may use. You -If your domain is registered in multiple agent spaces and you are using HTTP_ROUTE verification method, you can place the tokens provided to you for both agent spaces in the same `tokens` array. +If your domain is registered in multiple agent spaces and you are using HTTP route validation, you can place the tokens for both agent spaces in the same `tokens` array.