Using Powershell and the Nexpose API to create Exceptions

Nexpose, like other vulnerability management platforms, has the ability to create exceptions for the vulnerabilities it finds. You might need to issue exceptions because the vulnerability is a false positive, a compensating control is in place, or the risk is acceptable to the business.

Unfortunately, you sometimes have to create exceptions for hundreds, if not thousands, of vulnerabilities within Nexpose. It’s far too time consuming to create those manually.

The good news is that Nexpose has a well documented API. I’ve used this API to create a Powershell module that can help automate the submission of vulnerability exceptions.

The module can be downloaded from my GitHub page. The Wiki has a manual with more usage examples.

https://github.com/afxdub/Nexpose-API

To install the module, place the PSM1 file in ‘My Documents\WindowsPowerShell\Modules‘ in a new folder called ‘Nexpose-API‘. Then, it can be loaded in your Powershell script using the command:

Import-Module Nexpose-API

The module contains two cmdlets, Get-IDFromIP and Add-Exception.

Example Usage

The code below illustrates the usage of the Add-Exception cmdlet. Lines 1-23 are necessary if you are connecting to a Nexpose server with a self-signed certificate. On line 25, the Nexpose-API module is imported.

In this example, a list of asset IPs are passed to the script and the Add-Exception cmdlet is used to create an Exception for the vulnerability ‘http-options-enabled’ on port 8080. The exception will expire on 12/5/2019. On line 56, the Add-Exception module is called. After the code is a detailed explanation of all of the parameters.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

if (-Not ("TrustAllCertsPolicy" -as [type]))
{
add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy
    {
        public bool CheckValidationResult
        (
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem
        )
        {
            return true;
        }
    }
"@


    [System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy
}

Import-Module Nexpose-API

# *$*$*$*$*$*$*$*$*$*$*$*$*$*$*
#  Functions
# *$*$*$*$*$*$*$*$*$*$*$*$*$*$*


Function Get-FileName()
{
	[System.Reflection.Assembly]::LoadWithPartialName("System.windows.forms") | Out-Null
	
	$OpenFileDialog = New-Object System.Windows.Forms.OpenFileDialog
	$OpenFileDialog.filter = "TXT (*.txt)| *.txt|All files (*.*)| *.*"
	$OpenFileDialog.ShowDialog() | Out-Null
	$OpenFileDialog.filename
}


# *$*$*$*$*$*$*$*$*$*$*$*$*$*$*
#  Main
# *$*$*$*$*$*$*$*$*$*$*$*$*$*$*

$cred = Get-Credential
$fileObj = Get-FileName
$fileContents = Get-Content $fileObj -ErrorAction Stop

$VulnID = "http-options-enabled"
$apiBaseURL = "https://<yourNexposeServer>:<portNumber>"

foreach ($IPtoSearch in $fileContents)
{
    $ExceptionResponse = Add-Exception -assetIP $IPtoSearch -NexposeURL $apiBaseURL -credentials $cred -vulnID $VulnID -Reason 'Acceptable Risk' -Comment "Testing" -Type Instance -port "8080" -ExpirationDate '12/5/2019'
    if ($ExceptionResponse)
    {
        Write-Host "Exception created with ID: " $ExceptionResponse
    }
    else
    {
        Write-Host "Exception not created.  Error." -ForegroundColor Cyan
    }
}

Add-Exceptions has the following parameters.

• assetIP – Required. The IP address of the asset in Nexpose.
• NexposeURL – Required. The URL of your Nexpose server.
• vulnID – Required. The vulnerability ID. For example http-options-enabled.
• credentials – Required. A Powershell credential object. This will be used to authenticate to the Nexpose server
• Reason – Required. valid values are False Positive, Compensating Control, Acceptable Use, Acceptable Risk, Other
• Comment – Required. Additional information about the vulnerability exception
• Type – Required. Supported values are Asset and Instance. I’ll try to add support for Global, Site, and Asset Group later.
• VulnKey – Optional. If Type is ‘Instance’, the Key to uniquely identify the vulnerability
• Port – Optional. If Type is ‘Instance’, the Port to uniquely identify the vulnerability
• ExpirationDate – Optional. Expiration date for the exception. If no value is provided, the exception will never expire.

If the exception is successfully created, the cmdlet will return the ID of the exception object. If it returns NULL, then there was an error and no exception was created.

I have used this module to create exceptions for hundreds of vulnerabilities within Nexpose and hope this can be of use to others. As more use cases come up, the module will be extended.