ExtraHop Client for Windows PowerShell (v2.0)

[fookanen]

PowerShell Module for ExtraHop REST + Open Data Context APIs

Description:
Many IT environments leverage Windows PowerShell for automation, service management and reporting. This post provides a PowerShell module which can be used to interact both with the ExtraHop REST API, as well as theOpen Data Context APIs (session table).

Requirements:

• Windows PowerShell version 5.0 or higher.
• ExtraHop 6.0 or higher firmware.

If these requirements cannot be satisfied, see legacy standalone versions:
ExtraHop API Client for PowerShell (Legacy)
ExtraHop Open Data Context Client (Legacy)

Installation:

1. Download ExtraHopClient_v2.0.6.txt (124.6 KB), saving it as: ExtraHopClient.psm1
2. Save above ExtraHopClient.psm1 to a directory in PowerShell Module Path:

The module file (ExtraHopClient.psm1) will need to be in directory named ExtraHopClient within the PS Module Path. To determine the directory locations included in the module path, open PowerShell and view the $env:PSModulePath variable

##Example:
PS C:\Users\extrahop> $env:PSModulePath
C:\Users\extrahop\Documents\WindowsPowerShell\Modules;C:\Program Files\WindowsPowerShell\Modules;C:\WINDOWS\system32\WindowsPowerShell\v1.0\Modules\

Based on above, the module could be saved in the following location:

#####C:\Users\extrahop\Documents\WindowsPowerShell\Modules\ExtraHopClient\ExtraHopClient.psm1

3. Launch PowerShell, and verify installation of module by issuing the following command:

      PS> Get-Module -ListAvailable

You should see output that looks like this:


Note: You may also want to verify that your PowerShell version is 5.0 or higher. You can do so with the following command:

PS> $PSVersionTable




**REST API Client:**
4. Instantiate the API client object using this command: $c = New-ExtraHopClient -Host host [ -ApiKey apikey ]
5. Invoke REST API functions:


(Open above image in new tab to view details)


**Open Data Context API Client:**
6. Instantiate the ODC client object using this command: $odc = New-ExtraHopODCClient -Host host [ -Port port ]



7. An optional configuration file can be passed to the ExtraHopAPIClient using the '-Conf' parameter. The default location is %USERPROFILE%.extrahop.cfg and the content uses the following format:

Host host1
Target host1.domain.com
ApiKey c809a02b19044ab29c7de4b8364f5865
Host host2

ApiKey a40ba0ab18242cb23cdd54b83f4f5367


This configuration file stores the API keys for both host1 and host2. The “Target” entry is optional, and when omitted, the “Host” entry is assumed to be the host address.

---

#Exported Module Functions: **New-ExtraHopAPIClient** -Host host [ -ApiKey apikey ] [ -VerifyCert $true/$false ] - Returns an `ExtraHopAPIClient` object which can be used to interact with the ExtraHop REST API. **New-ExtraHopODCClient** -Host host [ -Port port ] - Returns an `ExtraHopODCClient` object which can be used to interact with the ExtraHop Open Data Context API (Session Table).

---

#Documentation:
ExtraHop Client for Windows PowerShell v2.0.0.docx (160.2 KB)

[mca_unch]

A new API call ‘POST /records/cursor’ has been added in a recent ExtraHop version, but the PowerShell module only supports an old deprecated API ‘GET /records/curser/{cursor)}’ that has issues.

Can the PowerShell module be updated to add support for the new ‘POST /records/cursor’ API ?

Thanks !

Regards,
Mario

[fookanen]

Hi @mca_unch,

Thanks for calling this out. The latest version just published (2.0.6) leverages the new cursor API. Here’s how you can use it:

> $c = New-ExtraHopAPIClient -Host <host> -APIKey <apikey>
> $rec_query = @{ "from"="-30m"; "types"=@("~http"); "context_ttl"=300000 }
>$rs = $c.RecordSearch( $rec_query )

This will return an ExtraHop RecordSet object.

> $rs.GetType()

IsPublic IsSerial Name                                     BaseType                                                                                                                                                                         
-------- -------- ----                                     --------                                                                                                                                                                         
True     False    RecordSet                                ExtraHopRESTAPI    

This new RecordSet object contains a .NextPage() method that will use the new Cursor API to grab the next Page of the RecordSet. Each time .NextPage() is called, it will update the .records array property with the next set of records. Continue using the .NextPage() method while checking the .EOR (End of RecordSet) property to know when the RecordSet has reached the last page. Alternatively, the .current_page property can be used in conjunction with the .page_count property as well.

Cheers!