With the release of Nexpose 5.11.1 we made some changes under the hood that improved scan performance and scan integration performance. As a result of those changes, the rules applied to using SiteSaveRequest in API 1.1 became stricter, which may have caused issues for some users. In the past this "worked" for the most part, though there were certainly side effects observable in the Web interface after the fact. Since these issues were not always apparent, nothing appeared wrong with this approach. If you are affected by these issues check the end of the post for workarounds.

Note: This is not something that changed in the Nexpose API or the Nexpose Ruby gem.

While reviewing the 1.1 API documentation and XML DTD (Document Type Definition) I realized why this might be confusing, so we're in the process of updating the documentation to be more clear on this. I'll walk you through where things can go wrong.

Below is a snippet of the relevant section of the Site XML DTD where scan targets are defined:

<!ELEMENT Hosts ((range|host)+)>  
  
<!-- IPv4 address range of the form 10.0.0.1 -->  
<!ELEMENT range EMPTY>  
     <!ATTLIST range from CDATA #REQUIRED>  
     <!ATTLIST range to CDATA #IMPLIED>  
  
<!-- named host (usually DNS or Netbios name -->  
<!ELEMENT host (#PCDATA)>  

This is what it looks like using a correct example:

<hosts>  
    <range from="192.168.1.50" to=""/>  
    <range from="172.16.0.1" to="172.16.0.255"/>  
    <host>example.com</host>  
    <host>server01.internal.example.com</host>  
</hosts>  

Note that on line 2 we have a range element with a from attribute containing an IP address, but a to attribute that is empty. This is how a single IP address is correctly defined as a scan target in a site configuration. On line 3 we see a full IP address range, as expected. On lines 4 and 5 we see two examples of host names.

Since the DTD may not obviously indicate how to save a single IP address, you might think it's correct to do this instead:

<hosts>  
    <host>192.168.1.50</host>  
    <host>172.16.0.25</host>  
</hosts>  

This does work: the site is saved and these IP addresses can be scanned. Unfortunately this causes some issues with the way assets are treated before and after scans, which have become more apparent with the 5.11.1 release. This includes difficulty launching ad hoc scans on individual assets from the UI and reporting on assets that were scanned since the 5.11.1 release.

For those of you who are affected by these issues there are 2 ways to address this:

  1. Change the way your API calls are made to use the range element for IP addresses and re-save any affected site configurations.
    • If you use the Nexpose Ruby gem, use the add_asset method instead of add_host. The add_asset method will detect whether the input is an IP address or host name and assign it appropriately.
  2. Modify your site configuration in the Web interface and save. You may need to add a new IP address or host name to the site, save, and then remove it and save again for this to work.
    • Note that if you did not update your API calls, this problem will occur again.

After the next scan, the ad hoc scans and reporting should behave correctly again for these assets.