Security Controls REST API

Home 

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.

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

A list of patch scan results.

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

   

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

 

DetectedPatches[]

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

 

PatchScanMachines[]

     

POST

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

Request Body

Operation location

Input Models

URL Parameters

Name Type Description

count

Integer

Provide the count of items to return. The maximum value is 50.

createdByMe

Boolean

Returns only those items created by the user.

name

String

Returns the items whose name matches the specified name.

start

Integer

Sets the starting point.

Request Body

Name Required? Type Default Value Description

credentialId

No

Guid

 

Specifies the GUID.

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 the name.

runAsCredentialId

Yes

Guid

 

Specifies the reference to a credential to use to start a scan. Overwrites RunAsDefault behavior.

runAsDefault

No

Boolean

 

Gets or sets an indication whether to run the scan as the user who invokes the REST API (integrated authentication).

templateId

Yes

Guid

None

Specifies the patch scan template ID.

useMachineCredential

No

Boolean

 

An indication whether to use machine credentials.

Example

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

{

"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.fakedomain.com:3121/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF"

},

"machines": {

"href": "https://device-name.fakedomain.com:3121/st/console/api/v1.0/patch/scans/01234567-89AB-CDEF-0123-456789ABCDEF/machines"

},

"template": {

"href": "https://device-name.fakedomain.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

Start a patch scan

POST Request

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

{ "machineGroupIds":["1006"], "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.

Find the machines from 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/machines

Queue a patch scan named "Scan of My Machine" for machine group with ID 1 using template with ID 01234567-89AB-CDEF-0123-456789ABCDEF

POST Request

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

{ "MachineGroupIds": [1], "Name": "Scan of My Machine", "TemplateId":"01234567-89AB-CDEF-0123-456789ABCDEF", "runAsCredentialId":"01234567-89AB-CDEF-0123-456789ABCDEF"}

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

DELETE Request

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

 

Output Models

DetectedPatch

Name Type Description

bulletinId

String

The bulletin identifier.

cultureName

String

The culture identifier.

kb

String

The KB issued by the vendor of the patch.

links

Links

Shows the related URLs for download.

patchType

KnownPatchType

The patch type.

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.

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.

PatchScanMachine

Name Type Description

completedOn

DateTime

The date and time that the machine assessment was completed.

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.

Severity

None

Critical

Important

Moderate

Low


Was this article useful?    

The topic was:

Inaccurate

Incomplete

Not what I expected

Other