VMware vCenter API Helpful Guidelines

REST API Endpoints

There are a number of API endpoints that the integration makes requests to. This document focuses on the REST API endpoints that are supported on vCenter 7.0.3 and above.

Tenable is asked a lot about permissions. In the most simplistic way, you must have permissions configured to get a successful response back from the following API endpoints. It is critical that when performing the following tests that they be run from the scanner to rule out any network connectivity issues with the vCenter Host. While running them from any machine is valid, this rules out the scanner’s ability/inability to communicate with the vCenter Host.

The following curl commands contain environmental variables (e.g., ${VCENTER_USERNAME}. If you are not familiar with the use of environmental variables then using manual entry within the commands is another option. 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.

Users can use this simple curl command test to ensure this user has the appropriate permissions and to rule out any authentication issues to the vCenter REST API before running a scan.

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

-u "myuser:mypassword"

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 the user does not obtain a session token, here are some possible reasons why:

Reason: Incorrect Username and/or Password
Status Code 401: Unauthorized
Server Response:

Reason: Incorrect vCenter Host, vCenter Host does not support REST API, or tried to verify SSL certificate in a scan policy.
Status Code 500: Server Error
Server Response: Error 500 Server Error or no response at all

Get a list of ESXi hosts managed by vCenter

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 are enumerated in subsequent requests.

To test this, the user can run the following curl command:

Manual entry option:

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

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

If successful, users can expect the following response.

Status Code 200: OK
Server Response:

Get a list of 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 that it manages. The user takes the “host” (host-id) for any of the list of hosts from the previous call and test the following command to rule out any permission errors.

User

The ${ESX_HOST} value should be the 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 would yield similar results.

Status Code 200: OK
Server Response:

Most often, if the user does not have the correct vCenter Lifecycle Manager permissions, they receive the following response. Refer to our permissions section for proper configuration.

Status Code 403: UNAUTHORIZED

Server Response:

Get a list of virtual machines per ESXi host

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

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.

Get virtual machine details for a specific virtual machine

From the list of virtual machines, you can take one of the virtual machine IDs (e.g., vm-1024) and send a request to vCenter to retrieve virtual machine details for that specific virtual machine.

The ${VM} value should be the one of the “vm” values received from the request to get a list of virtual machines hosted on the ESXi server.

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 VM is powered off, this results in a status code of 503 Service Unavailable. If this happens, users can run the following alternative command.

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.

VMware vCenter API Scan Results Review

This section explains scan results from plugin output to debug log reporting in an effort to help guide you in the review process for the vCenter Integration.

Plugin Families and Plugins

General

Integration Discovered Host (168417)

Reports on targets that were added to the scan using an auto-discovery feature in an integration. vCenter is a Tenable integration that supports auto-discovery, specifically ESXi, and virtual machine hosts.

Settings

Nessus Scan Information (19506) - Credentialed Checks

Tenable has observed user confusion with respect to Credentialed Checks: ‘yes/no’ in plugin ID 19506 (Nessus Scan Information) and how authentication is interpreted with the vCenter integration. Unless an SSH credential is included along with a VMware vCenter SOAP API credential, Credentialed Checks do not represent failed/successful authentication to the host. What is the difference? Traditionally, when running an authenticated scan to a host using SSH or Windows credentials, users can expect to see Credentialed Checks: ‘yes/’no’ based on whether login credentials to the target machine were valid. In the case of the vCenter Integration, Tenable is authenticating to the vCenter API, not the host machine, so this is an important difference to point out.

When running a scan using the VMware ESXi SOAP API Integration, you can expect to see Credentialed Checks:

• ‘yes’ if the integration collected VIBs for that host and Credentialed Checks:

• ‘no’ if the integration did not collect VIBs.

Tenable plans to release a new plugin in 2024 to signal success/failure of authentication and other requests to various vCenter API endpoints, in order to clear up confusion and make this simple for users. In the meantime, refer to the troubleshooting tips in the following sections for help with diagnosing potential errors that may arise.

Service Detection

VMware vCenter Detect (63061)

This plugin gathers the vCenter version from an unauthenticated SOAP API call to the vCenter host. It’s important to note that even later versions (v7.0.3) maintain a SOAP API. The version gathered from this plugin is used for vCenter vulnerability detection plugins that rely on versioning. This plugin runs independently of the integration and it is not indicative of vCenter authentication issues experienced using the integration. However, it does serve a purpose when deciding whether to collect vCenter and ESXi host data from either the vCenter SOAP or REST API, which is version-dependent; SOAP less than v7.0.3 and REST v7.0.3+.

VMware vSphere Detect (57396)

This plugin gathers the ESXi version from an unauthenticated SOAP API call to the ESXi host. The version gathered from this plugin is used for ESXi vulnerability detection plugins that rely on versioning. This plugin runs independently of the integration and it is not indicative of vCenter authentication issues experienced using the integration.

VMware ESX Local Security Checks

VMware vCenter Data Collection (63062)

This plugin handles everything from authentication to the vCenter REST API, collection of vCenter managed ESXi hosts, collection of ESXi VIBs, ESXi managed virtual machines, and virtual machine details for vCenter and ESXi versions 7.0.3+. You can find additional information related to the debug log for this plugin in the Debug Log Reporting section of this document. Data collection and storage is executed on only one of the targets in the target settings and is used for reporting on subsequent targets enumerated during the scan.

VMware vCenter Legacy Data Collection (180178)

This plugin executes everything from authentication to the vCenter SOAP API, collection of vCenter managed ESXi hosts, collection of ESXi VIBs, ESXi managed virtual machines, and virtual machine details for vCenter and ESXi versions less than 7.0.3. You can find additional information related to the debug log for this plugin in the Debug Log Reporting section of this document. Data collection and storage is executed on only one of the targets in the target settings and is used for reporting on subsequent targets enumerated during the scan.

VMware vCenter Auto-Discovery (180179)

This plugin executes the auto-discovery process when the user has enabled Auto-Discovery of ESXi hosts and virtual machines. You can find additional information related to the debug log for this plugin in the Debug Log Reporting section of this document.

VMware vCenter Managed ESXi Installed VIBs (154017)

This plugin reports the installed VIBs collected on a vCenter managed ESXi host. Other plugins and processes are dependent on the successful collection of ESXi installed VIBs, such as Credentialed Checks and vulnerability detection plugins. However, Tenable does not execute vulnerability detections on the specific VIBs data collected.

VMware vCenter Active Virtual Machines (84340)

This plugin reports active virtual machines (powered on) that were collected on a specific ESXi host and therefore are reported on the applicable ESXi host.

VMware vCenter Inactive Virtual Machines (84341)

This plugin reports inactive virtual machines (powered off) that were collected on a specific ESXi host and therefore are reported on the applicable ESXi host.

Note: In addition to these integration-related plugins, ESXi vulnerability detection plugins belong to the VMware ESXi Local Security Checks plugin family. If this plugin family is disabled, scan results will not include these vulnerability detections.

Policy Compliance

VMware vCenter/vSphere Compliance Checks (64455)

This plugin must be enabled in order to execute compliance scanning and perform compliance checks against both vCenter and ESXi hosts.

Plugin Debug Log Reporting

vCenter Authentication and Data Collection

When troubleshooting or verifying authentication to the vCenter API, users can find this debug log reporting in vmware_vcenter_collect.nbin~Collection_host for REST (v7.0.3+) and vmware_vcenter_collect_legacy.nbin~Collection_host for SOAP (less than v7.0.3). Collection_host is presented by the IP/FQDN of the host that the collection was executed on, which is done only once. In verifying successful vCenter authentication, it is important to look in the correct debug logs. Specifically, do not verify authentication by looking in the debug logs for the VMware vCenter Detect or VMware vSphere detect plugins. These detection plugins are unrelated to the integration and should not be used to verify authentication, because they always perform unauthenticated requests.

These logs also contain all other aspects of data collection including retrieving all ESXi hosts managed by a vCenter, VIBs installed for each ESXi, virtual machines hosted on ESXi, and virtual machine details for each virtual machine.

For example, if a particular ESXi host in the scan results has credentialed checks: no, the user should already know that there are potentially a few issues that could cause this from happening:

• Authentication to the vCenter API failed, therefore no data was retrieved.

• It is possible that this particular host was not retrieved as a managed ESXi host on the vCenter host in the credential, therefore VIBs were not retrieved.

• The ESXi host is managed by vCenter, but there was an error in the response to the request to collect VIBs for that particular host.

The user can look at this collection log and see if any issues were encountered. With the help of the curl tests provided in the REST API Endpoints section, Tenable has given the user some resources to help diagnose their issues with the integration.