Additional Information

Helpful Tips

At a high level, the integration performs the following sequence on each scan:

1. Detects vCenter and ESXi versions with unauthenticated calls, which determines whether collection uses the SOAP or REST API.

2. Authenticates to the vCenter API (bearer/session token) or to the ESXi SOAP API using the configured credential.

3. Enumerates the ESXi hosts the vCenter server manages.

4. Collects installed software components (VIBs) for each managed ESXi host and stores them in the scanner's Knowledge Base.

5. Enumerates virtual machines per ESXi host and retrieves virtual machine details, reporting active and inactive virtual machines against the applicable host.

6. If Auto-Discovery is enabled, adds discovered ESXi hosts and virtual machines to the scan as additional targets.

7. If compliance audits are configured, collects configuration data over the SOAP API and evaluates the audit checks.

Practical guidance:

• Collection runs once per scan against a single target and is reused for the remaining targets — so a failure at the collection step affects reporting for every enumerated host.

• Always list the vCenter server as a target when you want vCenter vulnerability results or vCenter compliance results.

• Run the curl tests below from the scanner so that network connectivity to the vCenter host is exercised at the same time as permissions.

• Disable Report Active and Inactive Virtual Machines in very large environments where virtual machine inventory is not needed, to reduce scan duration and request volume.

Testing Integration Connectivity

The following curl commands mirror the integration's own REST API request flow (vCenter 7.0.3+). The following curl commands also contain environmental variables (for example, ${VCENTER_USERNAME}). If you are not familiar with using variables, you can use manual entry within the commands. Options are provided for both in each section.

vCenter API authentication

Tenable uses bearer token authentication authorized to the vCenter username/password entered in the scan credentials. You can use this simple curl command test to ensure that this user has the appropriate permissions and to rule out any authentication issues to the vCenter REST API before running a scan.

You can choose to export environmental variables, such as VCENTER_USERNAME. The following curl commands are formatted for environmental variables. You can also manually enter these values. If executed manually, an example of the username:password of the authentication command may look like this:

-u 'myuser:mypassword'

curl -k -X POST -u "${VCENTER_USERNAME}:${VCENTER_PASSWORD}" https://${VCENTER}/api/session

Manual entry option:

• Replace "${VCENTER_USERNAME}:${VCENTER_PASSWORD}" with -u 'myuser:mypassword'.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

A successful response yields a session token that can be used for subsequent requests. Example of a successful response, which is the session token to be used in subsequent requests: "7b08862e67aa48f758c627fc2aa710a6".

If you do not obtain a session token, the following table lists some possible reasons why.

List the ESXi hosts vCenter manages

If authentication to the vCenter REST API was successful, Tenable then makes a request to vCenter to gather a list of ESXi hosts that it manages. This list of ESXi hosts is enumerated in subsequent requests.

To test this, run the following curl command:

curl -k -X GET -H "vmware-api-session-id: ${SESSION}" https://${VCENTER}/api/vcenter/host

Manual entry option:

• Replace ${SESSION} with the value received from the authentication request.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

If successful, expect the following response: Status Code 200: OK

Server Response:

[
  {
    "host": "host-1006",
    "name": "1.1.1.1",
    "connection_state": "CONNECTED",
    "power_state": "POWERED_ON"
  },
  {
    "host": "host-1007",
    "name": "1.1.1.2",
    "connection_state": "CONNECTED",
    "power_state": "POWERED_ON"
  },
  {
    "host": "host-1008",
    "name": "1.1.1.3",
    "connection_state": "CONNECTED",
    "power_state": "POWERED_ON"
  }
]

List installed software components (VIBs) per ESXi host

In this request, Tenable asks vCenter to report on the installed software components (VIBs) for each of the ESXi hosts it manages. Take the "host" (host-id) for any of the list of hosts from the previous call to test the following command, which rules out any permission errors:

curl -k -X GET -H "vmware-api-session-id: ${SESSION}" https://${VCENTER}/api/esx/hosts/${ESX_HOST}/software/installed-components

The ${ESX_HOST} value should be one of the "host" values received from the request to get a list of ESXi hosts managed by the vCenter.

Manual entry option:

• Replace ${SESSION} with the value received from the authentication request.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

• Replace ${ESX_HOST} with one of the "host" values received from the request to get a list of ESXi hosts managed by the vCenter.

A successful response yields similar results: Status Code 200: OK

Server Response:

{
  "Broadcom-ELX-IMA-plugin": {
    "display_version": "12.0.1200.0-6vmw",
    "display_name": "Broadcom IMA plugin for Emulex OneConnect iSCSI Driver",
    "version": "12.0.1200.0-6vmw.800.1.0.20513097",
    "platforms": ["host"]
  },
  "Broadcom-ELX-brcmfcoe": {
    "display_version": "12.0.1500.3-4vmw",
    "display_name": "Broadcom Emulex Connectivity Division fcoe driver for FCoE adapters",
    "version": "12.0.1500.3-4vmw.800.1.0.20513097",
    "platforms": ["host"]
  },
  "Broadcom-ELX-lpfc": {
    "display_version": "14.0.635.4-14vmw",
    "display_name": "Broadcom Emulex Connectivity Division lpfc driver for FC adapters",
    "version": "14.0.635.4-14vmw.800.1.20.21203435",
    "platforms": ["host"]
  },
  "esx-update": {
    "display_version": "8.0.0 Build 21493926",
    "display_name": "ESXi Install/Upgrade Component",
    "version": "8.0.0-1.25.21493926",
    "platforms": ["host"]
  },
  "esxio-update": {
    "display_version": "8.0.0 Build 21493926",
    "display_name": "ESXi Install/Upgrade Component",
    "version": "8.0.0-1.25.21493926",
    "platforms": ["host"]
  }
}

Most often, if you do not have the correct vCenter Lifecycle Manager permissions, you receive the following response (refer to the permissions section for proper configuration): Status Code 403: UNAUTHORIZED

Server Response:

{
  "error_type": "NOT_FOUND",
  "messages": [
    {
      "args": [],
      "default_message": "Not found.",
      "id": "com.vmware.vapi.rest.httpNotFound."
    }
  ]
}

List virtual machines on one ESXi host

Tenable sends a request to the vCenter API to get a list of virtual machines hosted on a specific ESXi host. This list of virtual machines is enumerated in subsequent requests.

curl -f -k -X GET -H "vmware-api-session-id: ${SESSION}" https://${VCENTER}/api/vcenter/vm?hosts=${ESX_HOST}

Manual entry option:

• Replace ${SESSION} with the value received from the authentication request.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

• Replace ${ESX_HOST} with one of the "host" values received from the request to get a list of ESXi hosts managed by the vCenter.

Retrieve details for a specific virtual machine

From the list of virtual machines, you can take one of the virtual machine IDs (for example, vm-1024) and send a request to vCenter to retrieve virtual machine details for that specific virtual machine. The ${VM} value should be one of the "vm" values received from the request to get a list of virtual machines hosted on the ESXi server.

curl -f -k -X GET -H "vmware-api-session-id: ${SESSION}" https://${VCENTER}/api/vcenter/vm/${VM}/guest/identity

Manual entry option:

• Replace ${SESSION} with the value received from the authentication request.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

• Replace ${VM} with one of the "vm" values received from the request to get a list of virtual machines hosted on the ESXi server.

If a virtual machine is powered off, this results in a status code of 503 Service Unavailable. If this happens, run the following alternative command.

curl -f -k -X GET -H "vmware-api-session-id: ${SESSION}" https://${VCENTER}/api/vcenter/vm/${VM}

Manual entry option:

• Replace ${SESSION} with the value received from the authentication request.

• Replace ${VCENTER} with your vCenter IP address or FQDN.

• Replace ${VM} with one of the "vm" values received from the request to get a list of virtual machines hosted on the ESXi server.