Patch Scans

A patch scan is used to identify the installed and missing patches on one or more target machines. You can perform a scan, display information about a scan and delete the results of a scan.

If you initiate a patch scan remotely via the REST API, you must add a session credential.

Base URL

        https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans

Supported Requests

Method URL Input Return

DELETE

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/{scan id}

 

Success or failure code.

GET

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans

URL Parameters

ScanResult

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/{scan id}

 

Patch scan status

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/{scan id}/machines

  PatchScanMachine

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/{scan id}/machines/{scan machine id}/patches

 

DetectedPatches[]

POST

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans

Request Body

Operation location

Input Models

Name Type Description

count

Integer

Provide the count of items to return. The default is 10 and the maximum value is 1000.

createdByMe

Boolean

Returns only those items created by the user.

This parameter will be removed in a future release and should only be used in legacy requests.

name

String

Returns the items whose name matches the specified name.

onOrAfter

DateTime

Returns the scans started on or after the specified date.

onOrBefore

DateTime

Returns the scans started on or before the specified date.

start

Integer

Sets the starting point. The items are sorted by their unique identifier and the starting point is the index into that sorted list.

If you initiate a patch scan remotely via the REST API, you must add a session credential.

Name Required? Type Default Value Description

connectionMethod

No

Enum

None

Specifies the method used to connect to the machines that are being scanned. This parameter is only used if an endpoint name is specified using the endpointNames parameter. Valid values are:

  • Inherit: Use the global setting specified on the Scan Options dialog available from Tools > Options > Scan. For more information, see Ivanti Security Controls help (opens in a new window).This is the default.
  • IPAddress: A connection is made by IP address after name/machine resolution is performed.
  • Fqdn: A connection is made using the Fully Qualified Domain Name (FQDN). This supports SPN name validation, which may be required in networks using Kerberos authentication.

credentialId

No

Guid

  

Specifies the credential to use to connect to new endpoints or groups that do not have an assigned credential. If a credentialId is not specified, then either default credentials or integrated Windows authentication credentials (in that order) will be used.

diagnosticTraceEnabled

No

Boolean

  

An indication whether diagnostics tracing should be enabled during scan.

endpointNames

Conditional

String[]

None

Specifies the endpoint names.

Either one endpoint or machine group must be specified.

machineGroupIds

Conditional

Integer[]

None

Specifies a list of machine groups to scan.

Either one endpoint or machine group must be specified.

name

Yes

String

None

Specifies a name for the scan operation.

runAsCredentialId

No

Guid

  

Specifies the reference to a credential to use to start a scan. This parameter provides backward capability with previous versions.

This command is deprecated, use a session credential instead.

sshServerValidationMode

No

String

Blocked

Specifies if an SSH connection can be used when the console communicates with endpoints that support SSH and for which SMB fails. There are potential security risks when using an SSH connection, so be sure to review the SSH Authentication topic before making a decision.

  • Blocked: The console will not be able to make an SSH connection with the endpoints.
  • SkipServerAuthentication: An SSH connection is allowed between the console and the endpoints without the use of SSH server authentication. This should only be used if you are certain that the endpoints are trusted and safe Linux machines.

templateId

Yes

Guid

None

Specifies the patch scan template ID.

useMachineCredential

No

Boolean

 

An indication whether to use machine credentials. If No is specified, then either default credentials or integrated Windows authentication credentials (in that order) will be used. This parameter is only used if an endpoint name is specified using the endpointNames parameter.

Example with Sample Response

Find a patch scan with ID 01234567-89AB-CDEF-0123-456789ABCDEF

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF

Sample Response

Copy 
{
    "consoleName": "device-name",
    "definitionDate": "2018-06-25T18:13:13.343",
    "definitionVersion": "2.0.2.5244",
    "expectedResultTotal": 1,
    "id": "01234567-89AB-CDEF-0123-456789ABCDEF",
    "isComplete": true,
    "links": {
        "self": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF"
        },
        "machines": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF/machines"
        },
        "template": {
            "href": "https://device-name.example.com:3121/st/console/api/v1.0/patch/scanTemplates/01234567-89AB-CDEF-0123-456789ABCDEF"
        }
    },
    "name": "My Machine",
    "receivedResultCount": 1,
    "scanType": "Patch",
    "startedOn": "2018-06-26T15:21:54.617Z",
    "updatedOn": "2018-06-26T15:21:54.617Z",
    "user": "SHAVLIK\\joe.coder"
}

Other Request Examples

DELETE Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF/machines

GET Request

https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF/machines/8/patches

POST Request

Copy 
https://<consoleFQDN:port>/st/console/api/v1.0/patch/scans

{ "machineGroupIds": [1], "name": "Scan of Sample Group", "templateId": "4c7069eb-6e1c-4352-91fc-04d4d8abc07b", "runAsCredentialId": "01234567-89AB-CDEF-0123-456789ABCDEF"}

If using PowerShell to initiate the request, use Invoke-WebRequest rather than Invoke-RestMethod. This will allow you to interact with the Operation-Location header information. For an example, see Start-to-Finish Example.

Output Models

Name Type Description

bulletinId

String

The bulletin identifier.

cultureName

String

The culture identifier.

kb

String

The KB issued by the vendor of the patch.

instanceName

String

The instance name, optionally used when a patch applies to a product with an instance name (for example, SQL Server).

links

Links

Shows the related URLs for download.

patchType

KnownPatchType

The patch type. Valid options are:

  • Undefined (0):
  • SecurityPatch (1): Patch is associated with a security bulletin
  • SoftwareDistribution (2): Free third-party products that can be installed and do not require special licensing
  • SecurityTools (3): A patch for a security tool such as Windows Defender
  • NonSecurityPatch (4): Stability updates, bug fixes, etc.
  • CustomActions (6): Special patch that performs a custom action without deploying a patch

patchId

Guid

The patch ID from the catalog data or from a custom patch specification.

productName

String

The name of the product that is fixed by the patch.

productId

Guid

The unique product identifier.

scanItemId

Int64

The unique identifier of ID of the patch summary. This correlates to the ScanItem identifier found in the application database.

scanState

ItemType

The state of the patch installation. Valid options are:

  • Warning: The item may require additional validation or cannot be installed in certain circumstances.
  • Note: An installation note is available for this item.
  • Informational: The item is for informational purposes. For example, a new product installation may be available.
  • FoundPatch: The patch is installed.
  • MissingPatch: The patch is missing.
  • InstalledPatch: The patch is effectively installed.
  • MissingServicePack: The service pack (product level) is missing.

servicePackName

String

The name of the service pack to which the patch applies.

vendorSeverity

Severity

The vendor-defined severity of the security risk or issue that this patch corrects.
Name Type Description

completedOn

DateTime

The date and time that the machine assessment was completed.

dnsName

String

The full DNS name of the assessed machine. If the value is null, then dnsName will not be displayed.

domain

String

The domain short-name of the assessed machine.

errorDescription

String

An optional description of the patch scan or resolution error.

errorNumber

Integer

An error code representing a resolution or assessment failure.

id

Integer

The unique identifier of the machine patch assessment.

installedPatchCount

Integer

The total number of installed patches found in the assessment.

links

Links

Shows the related URLs.

missingPatchCount

Integer

The total number of missing patches detected in the assessment.

missingServicePackCount

Integer

The total number of missing service packs detected in the assessment.

name

String

The resolved short-name or host name of the machine.

virtualMachinePath

String

The virtual machine path if this is a hosted VM.

virtualServer

String

The virtual machine server name if this is a hosted VM.
Name Type Description

consoleName

String

The name of the console that ran the scan.

defintionDate

DateTime

The creation date of the XML used by the scanner.

definitionVersion

String

The version of the XML used by the scanner.

expectedResultTotal

Int32

The expected number of individual machine results associated with this scan.

id

Guid

The scan ID.

isComplete

Boolean

Indicated whether the scan is complete.

links

Links

Shows the related URLs.

name

String

The scan name.

receivedResultCount

Int32

The number of individual machine results associated with this scan.

scanType

Enum

The type of scan that was performed.

startedOn

DateTime

The time the scan was started.

updatedOn

DateTime

The time that the scan ended or was last updated.

user

String

The user that started the scan.
  • None
  • Critical
  • Important
  • Moderate
  • Low