Steve provides research, analysis, insight and commentary on topical issues and events.
He lives in New Zealand and has been working at FastTrack Software for 10 years as a cyber security analyst and technical writer.
How-to: Use PowerShell to Query Admin By Request
Introduction
The Admin By Request API allows you to get the necessary data into your preferred SIEM system. This blog covers how to test functionality and get data from Admin By Request using Windows PowerShell.
There are five tasks involved:
1. Task A: Enable and Copy API Key
2. Task B: Copy Required URLs from Resources
Task B.1: Copy Inventory URL
Task B.2: Copy Auditlog URL
3. Task C: Start PowerShell and Declare API Key
4. Task D: Define General Variables
5. Task E: Get Data
Task E.1: Get Inventory Data
Task E.2: Get Auditlog Data
IMPORTANT: In order to use Invoke-RestMethods cmdlets used during this task, you will need to be running Windows PowerShell version 3.0 or higher.
Task A: Enable and Copy API Key
1. In the Admin By Request user portal, navigate to menu Settings > Windows Settings:
2. From the left-hand side menu, select option Privacy (not the PRIVACY tab at the top):
3. Click the API ACCESS tab at the top:
4. Set API access to ON and copy the API Key to the clipboard using the copy to clipboard button to the right of the API Key:
NOTE: The API Key is an inactive key in these examples; used for demonstration purposes only.
5. Paste the API Key into notepad (or similar) to be retrieved later, so that it is not overwritten in Task B.1.
Task B: Copy Required URLs from Resources
In this task we will locate and copy two URLs to be used to make queries in subsequent tasks.
Task B.1: Copy Inventory URL
2. From the list of resources, copy the URL you want to work with using the copy to clipboard button to the right of the URL:
NOTE: For this example, we want to return our current inventory.
IMPORTANT: The URL depends on your datacentre. In this example we are using data centre 1, so see dc1api in the URL. You may see dc2api, etc.
3. Paste the inventory URL into notepad (or similar) to be retrieved later, so that it is not overwritten in Task B.2.
Task B.2: Copy Auditlog URL
2. From the list of resources, copy the URL you want to work with using the copy to clipboard button to the right of the URL:
NOTE: For this example, we want to return an array of auditlog entries.
IMPORTANT: The URL depends on your datacentre. In this example we are using data centre 1, so see dc1api in the URL. You may see dc2api, etc.
3. Paste the Auditlog URL into notepad (or similar) to be retrieved later, so that it is not overwritten in Task C.
Task C: Start PowerShell and Declare API Key
NOTE: If you want to run the code within this blog as a script you will need to change the default execution policy to bypass or unrestricted using the following line of code in PowerShell. However, the full process will not be covered in the scope of this blog.
set-executionpolicy bypass -scope process
1. Launch Windows PowerShell and declare the API Key by copying and pasting the following line of code into the window:
$apikey = '74521893577544cdac9b927df962f8a0'
2. Replace the API Key in this line of code with the API Key you copied in Task A.
3. Press Enter on your keypad:
NOTE: In Tasks C and D, pressing Enter will not return anything, but will take you to a new line in PowerShell. The username has been blurred out in these examples.
Task D: Define General Variables
In this task we will define several variables to make the code easier to work with.
1. Define a header variable by copying and pasting the following line of code into the window:
$header = @{"apikey"=$apikey}
2. Press Enter on your keypad:
3. Define an inventory variable by copying and pasting the following line of code into the window:
$inventory = 'https://dc1api.adminbyrequest.com/inventory'
4. Replace the URL in this line of code with the inventory URL you copied in Task B.1.
5. Press Enter on your keypad.
6. Define an auditlog variable by copying and pasting the following line of code into the window:
$auditlog = 'https://dc1api.adminbyrequest.com/auditlog'
7. Replace the URL in this line of code with the auditlog URL you copied in Task B.2.
8. Press Enter on your keypad:
Task E: Get Data
In this task we will run the GET method to return the data we want.
Task E.1: Get Inventory Data
1. Copy and paste the following line of code into the window:
Invoke-Restmethod -uri $inventory -header $header -Method GET
2. Press Enter on your Keypad:
NOTE: In Tasks E.1 and E.2, pressing Enter will execute the method and return data. There will be a brief pause before the data is returned in this task (E.1) and in task E.2. Key information is blurred out in these examples.
IMPORTANT: Without any parameters specified, a maximum of 50 entries are returned.
Task E.2: Get Auditlog Data
1. Copy and paste the following line of code into the window:
Invoke-Restmethod -uri $auditlog -header $header -Method GET
2. Press Enter on your Keypad:
NOTE: From here we may want to output the data to a CSV file for further aggregation, however this step requires formatting and will not be covered in the scope of this blog.
Voila! We have now successfully used Windows PowerShell to get inventory and auditlog data written to screen.
This procedure was created with the assistance of Mads Christian Mozart Johansen.