AWS transform documentation change
Summary
Major documentation expansion adding support for Hyper-V and bare metal servers, restructuring prerequisites by environment type, providing detailed Kerberos authentication configuration, and updating access configuration procedures for multiple discovery sources.
Security assessment
The changes primarily expand platform support and reorganize documentation. Security-related improvements include: 1) Enhanced Kerberos authentication guidance with detailed configuration steps and case-sensitivity warnings, 2) Recommendation to change default VM password ('discovery'/'password') for strong security, 3) Clarification of required sudo commands for Linux collection with security implications for privilege escalation, 4) Specification of authentication methods for Hyper-V (NTLM/HTTPS only, Kerberos/HTTP or HTTPS). However, there's no evidence these changes address a specific security vulnerability or incident.
Diff
diff --git a/transform/latest/userguide/discovery-tool-setup.md b/transform/latest/userguide/discovery-tool-setup.md index 805bfff53..de6e3954f 100644 --- a//transform/latest/userguide/discovery-tool-setup.md +++ b//transform/latest/userguide/discovery-tool-setup.md @@ -5 +5 @@ -Installing the discovery toolConfigure krb5.conf For Kerberos Authentication ProtocolImport a self-signed certificate authority into the discovery toolConfigure discovery tool access to vCenterConfigure the discovery tool for OS accessUpdating the discovery toolRevoking vCenter access +Installing the discovery toolConfigure Kerberos authenticationImport a self-signed certificate authority into the discovery toolConfigure discovery tool accessConfigure the discovery tool for OS accessUpdating the discovery toolRevoking access @@ -13 +13 @@ Installing the discovery toolConfigure krb5.conf For Kerberos Authentication Pro -These are the prerequisites for using AWS Transform discovery tool: +The following are the prerequisites for using the AWS Transform discovery tool: @@ -15 +15 @@ These are the prerequisites for using AWS Transform discovery tool: - * VMware vCenter Server version 6.5, 6.7, 7.0 or 8.0 +**General prerequisites** @@ -17 +17 @@ These are the prerequisites for using AWS Transform discovery tool: - * You should have permissions to deploy an OVA into your VMware vCenter + * The tool requires 4 vCPU, 16 GB of RAM, and a 35 GB hard disk. @@ -19 +19 @@ These are the prerequisites for using AWS Transform discovery tool: - * For VMware vCenter Server setup, make sure that you can provide vCenter credentials with Read and View permissions set for the System group + * DHCP must be available in the network for the discovery tool VM. @@ -21,5 +21 @@ These are the prerequisites for using AWS Transform discovery tool: - * The tool requires 4 vCPU, 16GB of RAM, and a 35GB hard disk - - * DHCP must be available in the network for the discovery tool VM - - * The tool collects data using a centralized approach. VMs that are in scope must allow inbound connectivity from the discovery tool VM (default ports, custom port configuration is supported): + * The tool collects data by using a centralized approach. Servers in scope must allow inbound connectivity from the discovery tool VM (default ports, custom port configuration is supported): @@ -31 +27,23 @@ These are the prerequisites for using AWS Transform discovery tool: - * SNMP – UDP/161 + * SNMP – UDP/161 (used for network collection only, not OS metrics) + + * For Linux, user accounts that can use SSH to connect to the server. The discovery tool runs various commands over SSH for network collection and OS metrics. Some commands require sudo access: `ss` or `netstat` (network collection), `dmidecode` (server provisioning), and `lvdisplay` (storage provisioning). Each of these commands has a graceful fallback if sudo is not available, but without sudo the discovery tool might not collect all available data. We recommend configuring passwordless sudo for the SSH user to ensure complete data collection. + + + + +**VMware prerequisites** + + * VMware vCenter Server version 6.5, 6.7, 7.0, or 8.0. + + * Permissions to deploy an OVA into your VMware vCenter. + + * For VMware vCenter Server setup, vCenter credentials with Read and View permissions set for the System group. + + + + +**Hyper-V prerequisites** + + * Windows Server with the Hyper-V role enabled. + + * WinRM enabled on Hyper-V hosts. @@ -33 +51 @@ These are the prerequisites for using AWS Transform discovery tool: - * For Linux, user accounts that can SSH into the server. For SSH discovery, the tool uses ss -tnap. + * A user account with Hyper-V management permissions. @@ -35 +53,12 @@ These are the prerequisites for using AWS Transform discovery tool: - * The SSH user must be able to execute the ss command using sudo. If ss is not available, the tool will fall back to netstat. + * Supported authentication: NTLM (HTTPS only) and Kerberos (HTTP or HTTPS). + + + + +**Bare metal prerequisites** + + * A CSV file with server hostnames or IP addresses and the credential names (optional) that map to the friendly names of the OS credentials configured or to be configured on the discovery tool. The CSV must use the following headers: + + hostname_or_ip,credential_name + + * Servers must be reachable from the discovery tool VM on the appropriate ports (SSH port 22 for Linux, WinRM port 5985/5986 for Windows). @@ -41,0 +71,2 @@ These are the prerequisites for using AWS Transform discovery tool: +###### VMware installation + @@ -48,0 +80,7 @@ These are the prerequisites for using AWS Transform discovery tool: +###### Hyper-V installation + + * Download the VHD file from this URL: https://s3.us-east-1.amazonaws.com/atx.discovery.collector.bundle/releases/latest/AWS-Transform-discovery-tool.vhd + + + + @@ -50,0 +89,2 @@ These are the prerequisites for using AWS Transform discovery tool: +#### Deploy on VMware + @@ -82 +122 @@ Descriptions of the replaceable values in the example: -#### Discovery tool virtual machine specifications +##### VMware virtual machine specifications @@ -90 +130 @@ Descriptions of the replaceable values in the example: - * **Disks** \- 35 GB + * **Disks** – 35 GB @@ -96,0 +137,30 @@ Descriptions of the replaceable values in the example: +#### Deploy on Hyper-V + + 1. Copy the VHD file to the Windows Server machine that has the Hyper-V role enabled. + + 2. Open Hyper-V Manager. + + 3. Choose **New** , and then choose **Virtual Machine**. + + 4. Complete the setup wizard. On the **Specify Generation** page, select **Generation 1**. Generation 2 virtual machines do not support the VHD format. On the **Assign Memory** page, allocate at least 16384 MB. On the **Connect Virtual Hard Disk** page, choose **Use an existing virtual hard disk** and select the VHD file that you copied. + + 5. Start the VM. After a few minutes, check the **Networking** tab of the VM in Hyper-V Manager to find the IP address, or connect to the VM console and run `ip addr`. You use this IP address to connect to the discovery tool. + + + + +##### Hyper-V virtual machine specifications + + * **Operating System** – Amazon Linux 2023 + + * **RAM** – We recommend allocating at least 16 GB + + * **CPU** – We recommend allocating at least 4 cores + + * **Disks** – 35 GB (included in the VHD) + + * **Hyper-V requirements** – See [Hyper-V host requirements for running AL2023 on Hyper-V](https://docs.aws.amazon.com/linux/al2023/ug/hyperv-supported-configurations.html#hyperv-host-requirements) + + + + @@ -99 +169 @@ Descriptions of the replaceable values in the example: - * The discovery tool VM comes by default with a username and password ("discovery", "password"). For strong security users are highly encouraged to update the password using `sudo passwd discovery` after logging into the VM through vSphere Client → Discovery Tool VM → "Launch Web Console". + * The discovery tool VM comes by default with a username and password ("discovery", "password"). For strong security, we recommend that you update the password by using `sudo passwd discovery` after logging into the VM through your hypervisor's console (for example, vSphere Client for VMware or Hyper-V Manager for Hyper-V). @@ -108 +178,26 @@ Descriptions of the replaceable values in the example: -## Configure krb5.conf For Kerberos Authentication Protocol (optional) +## Configure Kerberos authentication + +Kerberos authentication is the recommended method for connecting to Windows servers from the discovery tool. The discovery tool VM uses native Amazon Linux 2023 Kerberos libraries to authenticate against your Active Directory domain. + +The following are key points about Kerberos authentication on the discovery tool VM: + + * Use the `kinit` command to obtain a Kerberos ticket and `klist` to verify the ticket. + + * The Kerberos configuration file is located at `/etc/krb5.conf`. + + * Before you configure the discovery tool, verify that `kinit` succeeds from the CLI on the discovery tool VM. + + + + +### Kerberos prerequisites + +Before you configure Kerberos authentication, verify that you have the following information and network connectivity. + + 1. Obtain the following information from your Active Directory administrator: + + * The Kerberos realm name (typically your domain name in uppercase, for example, `EXAMPLE.COM`). + + * The hostname or IP address of the Key Distribution Center (KDC), which is typically a domain controller (for example, `dc01.example.com`). + + * A service account with permissions to authenticate against the target Windows servers. @@ -110 +205 @@ Descriptions of the replaceable values in the example: -krb5.conf configuration may not be required if your environment has proper DNS SRV records configured for Kerberos service discovery. However, explicit configuration is recommended for: Environments without DNS-based Kerberos discovery, Custom or non-standard Kerberos setups. + 2. Verify that the discovery tool VM has network connectivity to the following: @@ -112 +207 @@ krb5.conf configuration may not be required if your environment has proper DNS S -To configure the Kerberos authentication protocol on your discovery tool VM: + * The KDC on port 88 (TCP and UDP) for Kerberos authentication. @@ -114 +209 @@ To configure the Kerberos authentication protocol on your discovery tool VM: - 1. SSH to Discovery tool VM + * The target Windows servers on WinRM ports (5985 for HTTP, 5986 for HTTPS). @@ -116 +210,0 @@ To configure the Kerberos authentication protocol on your discovery tool VM: - 2. Open krb5.conf configuration file in the `/etc` folder. To do so, you can use the following example `sudo nano /etc/krb5.conf` @@ -118 +211,0 @@ To configure the Kerberos authentication protocol on your discovery tool VM: - 3. Update the krb5.conf configuration file with at least the following information. @@ -120,0 +214 @@ To configure the Kerberos authentication protocol on your discovery tool VM: +### Configure Kerberos @@ -121,0 +216 @@ To configure the Kerberos authentication protocol on your discovery tool VM: +Complete the following steps to configure Kerberos authentication on the discovery tool VM. @@ -122,0 +218,14 @@ To configure the Kerberos authentication protocol on your discovery tool VM: + 1. SSH to the discovery tool VM. + + ssh discovery@<discovery-tool-vm-ip> + + 2. Edit the Kerberos configuration file at `/etc/krb5.conf`. + + sudo nano /etc/krb5.conf + +Add the following configuration, replacing the placeholder values with your environment details. + + [libdefaults] + default_realm = EXAMPLE.COM + dns_lookup_realm = false + dns_lookup_kdc = true @@ -125,3 +234,2 @@ To configure the Kerberos authentication protocol on your discovery tool VM: - <KERBEROS_REALM> = { - kdc = <KDC_hostname> - default_domain = <domain_name> + EXAMPLE.COM = { + kdc = dc01.example.com @@ -130,2 +239,47 @@ To configure the Kerberos authentication protocol on your discovery tool VM: - .<domain_name> = <KERBEROS_REALM> - <domain_name> = <KERBEROS_REALM> + .example.com = EXAMPLE.COM + example.com = EXAMPLE.COM + +###### Important + +Kerberos is case-sensitive. The realm name must be in uppercase (for example, `EXAMPLE.COM`, not `example.com`). The domain name in the `[domain_realm]` section must be in lowercase. + + 3. Verify that you can obtain a Kerberos ticket by running the `kinit` command. +