PowerShell script to start a scan from a device

Have you ever needed to run a scan from the client side?

There are times when you may want to trigger a scan from the device as part of an automation rather than from the console (or waiting for the next scheduled scan to run). One example is to automatically update the Automox inventory when a Windows 10 in-place upgrade successfully completes.

Luckily, @Nic recently published a topic to clean up inactive devices (Powershell script to remove devices that have been disconnected longer than X days) that I was able to repurpose to manage this task. Thank you @Nic!

This script leverages the API to identify the local device, and then sends a secondary API call to schedule a scan for itself (Pretty handy, right?).

There are two areas in the code you’ll need to update to get the script to function:

1. 
   

   $orgID = ‘YOUR_ORG_ID’ - put your Org ID, which can be found by looking at the URL of your console and selecting the value after the “?o=”: https://console.automox.com/dashboard?o=999999 1. In this example URL the Org ID is the 999999 portion.

   
   


2. 
   

   $apiKey = ‘YOUR_API_KEY’ - in your console, go to Settings->API and select the API key. Note that the API key is per admin user, so you and another admin in your console will have different API keys.

   
   

Once you’ve made those two changes, you can run the script below on any Windows device using PowerShell.

If you wish to run the script in a test mode to verify the computer is being properly identified locally and through the API return, you can uncomment this line:

#echo "device: $serverName `t serverID: $ServerID `t  hostname: $hostName"

and comment out the line that requests the scan for the device:

$getOSResponse = Invoke-WebRequest -UseBasicParsing -Method Post -Uri $getURI -Headers $headers -Body($body| ConvertTo-Json)

That will show you the device name, device ID, and the hostname as well as generate the json files to $logPath to help with troubleshooting.

Here is the script!

Trigger a Scan On-Demand From Device:

#    [-------------------------------------DISCLAIMER------------------------------------]

#    This script is provided as-is with no implicit

#     warranty or support. It's always considered a best practice

#     to test scripts in a DEV/TEST environment, before running them

#     in production.

#     Please proceed with caution.

#     Do not distribute your API Key to any untrusted 3rd party.

#    [-------------------------------------DISCLAIMER-------------------------------------]

     

#     The SETUP section gets your API return and is not specific to any particular use-case.

#     The OPERATIONAL section is specific to one scenario and can be overhauled for your specific uses.



############################# SETUP Section #############################



#modify log path as desired

$logPath = 'C:\temp\'



#Easier to maintain, especially if multiple organizations, or for repurposing for different API Tables

$apiInstance = 'https://console.automox.com/api/'

$apiTable = 'servers'

#replace the two variables below with your Org ID and your API key

$orgID = 'YOUR_ORG_ID'

$apiKey = 'YOUR_API_KEY'

$orgAndKey = "?o=$orgID&api_key=$apiKey"



#optional query to filter, if the whole server list is too long, you could add policyid to filter to only devices targeted with a specific policy

$query = ''



#initialize empty arrays to store server IDs

$toGetOS = @()

$failRefresh = @()

$successRefresh = @()



#put components together

$getURI = $apiInstance + $apiTable + $orgAndKey + $query



#Get the json body of the Web Request

$jsonReturn = (Invoke-WebRequest -UseBasicParsing -Method Get -Uri $getURI).Content



#Convert to object with manipulatable properties/values

$servers = $jsonReturn | ConvertFrom-Json



#Export to C



############################# END Setup Section #############################





############################# OPERATIONAL Section #############################



#Check each server for checkin time, conditionally take action

foreach ($server in $servers) {

    #pull out wanted details

    $serverID = $server.id

    $serverName = $server.name

    

    #get local computer name

    $hostName = $env:COMPUTERNAME



    #uncomment line below if you want to see all the servers names and IDs for troubleshooting

    #echo "device: $serverName `t serverID: $ServerID `t  hostName: $hostName"

    

    

    if ($serverName -eq $hostName) {

        #Data collection code here        

        $toGetOS = @{"ServerName"=$serverName;"ServerID"=$serverID}

        

        $headers = @{

            "Authorization" = "Bearer $apiKey"

            "Content-Type" = "application/json"

        }

        $body = @{

            command_type_name = "GetOS"

          }



        #Hardcoded would look like this $getURI = https://console.automox.com/api/servers/YOUR_SERVER_ID/queues?o=YOUR_ORG_ID

        $getURI = $apiInstance + $apiTable + '/' + $serverID + '/queues?o=' + $orgID

        #echo $getURI = $apiInstance + $apiTable + '/' + $serverID + '/queues?0=' + $orgID



        #Attempt to run Refresh for local system and track failures

        try { 

            $getOSResponse = Invoke-WebRequest -UseBasicParsing -Method Post -Uri $getURI -Headers $headers -Body($body| ConvertTo-Json)

            Write-Output "Successfully requested getOS for Server: $serverName"

            $successRefresh = @{"ServerName"=$serverName;"ServerID"=$serverID}

        }

        catch { 

            $failRefresh = @{"ServerName"=$serverName;"ServerID"=$serverID}

            Write-Output "Failed to Refresh Server: $serverName" 

        }

    }

    #Output logging into json files for later review/manipulation

    $toGetOS | ConvertTo-Json | Out-File $logPath\toBeTRefreshed.json

    $successRefresh | ConvertTo-Json | Out-File $logPath\Refresh_Success.json

    $failRefresh | ConvertTo-Json | Out-File $logPath\Refresh_Failed.json

} 

Hope that helps!