Getting Started with 1E’s Tachyon and PowerShell

Published:21 February 2022 - 8 min. read

1E’s Tachyon is primarily a GUI-driven endpoint management solution, but not entirely. As it turns out, the 1E PowerShell module exists called the PSTachyonToolkit that lets you leverage the power of Tachyon PowerShell!

This module is potentially good news to administrators who want to interface with Tachyon via PowerShell. Imagine the opportunities to develop automation for monitoring, communication, data processing, and issue remediation.

Where can I get the module? What are some of the possible operations you can perform? Where can I find help? These were just some of my questions when I started exploring the module. Read on, and this guide will help you start working with the PSTachyonToolkit.

Getting the 1E PowerShell PSTachyonToolkit Module

When you need a PowerShell module, you’d probably think about installing it from PSGallery or NuGet. But in this case, the 1E PowerShell module isn’t available yet in any of the well-known module galleries.

Instead, you may find the download link for the module from the Support Portal for 1E customers. Once you download the module, install or extract its contents to your preferred location.

While the module contains many files, know that there are five essential files for the module to work.

FileFunction
PSTachyonToolkit.psd1The PowerShell module manifest file.
PSTachyonToolkit.psm1The main PowerShell module file.
methods.jsonThe main PowerShell module file.
The main PowerShell module file.The main PowerShell module file.
The main PowerShell module file.A typical .NET configuration file containing the Tachyon signing tool configuration settings.

Simple Cross-Platform Agent Language for Extensibility (SCALE) is 1E’s interpreted programming language.

Now that you have the 1E PowerShell module, you can import the module into your PowerShell session.

Import-Module .\PSTachyonToolkit.psd1

Next, specify the Tachyon server FQDN the module will connect. Running any other Tachyon commands will produce an error without setting the Tachyon server first.

Set-TachyonServer -Server <TACHYON SERVER FQDN>

The current PSTachyonToolkit module version is 1.0.0, and there are 182 cmdlets available.

PSTachyonToolkit Module Version
PSTachyonToolkit Module Version

The PSTachyonToolkit module works on Windows PowerShell 5.1 and PowerShell (Core) 7.x. 1E claims that the module is more performant in PowerShell (Core) than in Windows PowerShell.

Also, 1E does not recommend using the toolkit in PowerShell ISE when using the Search-TachyonServer feature.

The official documentation for the PSTachyonToolkit does not seem to exist (yet) on 1E’s website.

Retrieving Device Details and Status

Every organization categorizes machines based on their criticality. A payroll server may be highly critical, while a desktop computer can be non-critical. With the PSTachyonToolkit, you can quickly query the device details and status using the Get-TachyonDevice cmdlet.

Executing the Get-TachyonDevice command without parameters returns only the endpoints’ FQDN.

Listing all endpoint device FQDNs
Listing all endpoint device FQDNs

To get all available properties of each endpoint, append the -Full switch to the command. But most of the time, returning all properties is not necessary. Thus, filtering the properties to display makes more sense, especially for monitoring.

For example, to get the essential endpoint details, you could select which properties to return, such as the below command.

Get-TachyonDevice -Full | Select-Object Status,Fqdn,Criticality,OsVerTxt,DeviceType

As you can see below, the result gives you a high-level overview of the endpoint status ( 0 = offline, 1 = online ). And the Criticality code gives you the idea of whether you should quickly react (or panic) when the device status is offline. For reference, the criticality values are as follows.

Criticality CodeValue
0Undefined (or not set)
1Non-Critical
2Low
3Medium
4High
5Critical
Getting device details and status
Getting device details and status

At this point, you can now customize your script to fit your monitoring requirements. For example, you would typically only want to monitor servers with at least a high criticality. In which case, you could run the below command.

Get-TachyonDevice -Full | `
Where-Object {$_.DeviceType -eq 'Server' `
-and $_.Criticality -ge 4 `
-and $_.Status -eq 0} | `
Select-Object Status,Fqdn,Criticality,OsVerTxt,DeviceType
Getting device details and status with filtering
Getting device details and status with filtering

And while you’re at it, why not build a custom HTML report or send alerts to Teams?

Working with Tachyon Instructions

At the heart of Tachyon are instructions. And when you need to search and run instructions, you’d usually open a browser and navigate the Tachyon Explorer. But with the PSTachyonToolkit, you can now interact with Tachyon instructions within PowerShell in several ways.

The 1E PowerShell module allows you to perform an interactive search and execution of Tachyon instructions. For example, suppose you need to determine your endpoints’ current PowerShell execution policy, you can do an interactive search for the instructions related to the execution policy.

To enter the interactive search mode, run the command below without any parameters.

Search-TachyonServer

Now you can type in the search term, such as execution policy, and press Enter. There are a few results when searching for execution policy, as you can see below. Select which instruction to run by pressing its corresponding number. In this example, instruction 0 is what you want to run.

Searching Tachyon instructions
Searching Tachyon instructions

The command then asks you to enter the required parameter value, in this example, the TargetScope. The TargetScope value could be any part of the target endpoints’ FQDN. For example, the TargetScope for the below is any computer with 1EDemoLab.com in their FQDN.

Specifying the target scope
Specifying the target scope

As you can see below, Tachyon returns an aggregated result showing 7 Unrestricted and 2 RemoteSigned endpoints PowerShell execution policies.

Showing the Tachyon instruction result
Showing the Tachyon instruction result

If you want a detailed list of endpoints instead of an aggregated result, run the Search-TachyonServer command with the -Drilldown switch.

Search-TachyonServer -Drilldown

As a result, the result shows a list of the nine endpoints instead of the summary.

Returning a detailed list result with the Drilldown parameter
Returning a detailed list result with the Drilldown parameter

This interactive search mode is undoubtedly a helpful feature of the 1E PowerShell module. But the name Search-TachyonServer sounds like a command for searching Tachyon servers instead of searching for Tachyon instructions.

In my opinion, the cmdlet name Search-TachyonInstruction would be more descriptive and intuitive. Maybe the developers at 1E can consider adding that cmdlet alias in future module releases.

Running Existing Instructions

Apart from interactively searching for instructions to run, you can also invoke instructions if you already know the instruction name. The Invoke-TachyonInstruction cmdlet allows you to execute instruction by its name.

Like the previous example, the instruction name for listing the PowerShell execution policy is 1E-Explorer-TachyonCore-GetExecutionPolicyPowershellCommandLine. To execute this instruction from PowerShell, do so by running the command:

Invoke-TachyonInstruction `
-instruction 1E-Explorer-TachyonCore-GetExecutionPolicyPowershellCommandLine `
-TargetScope <scope> -Drilldown
Invoking a published Tachyon instruction
Invoking a published Tachyon instruction

The ability to invoke instructions from PowerShell would allow developers to integrate Tachyon into their PowerShell automation efforts. For example, if you can get a list of endpoints with an Unrestricted execution policy, you can also automate changing the execution policy to RemoteSigned.

Publishing Instructions

Searching and running pre-built instructions is a quick way to retrieve information and run actions against Tachyon devices. But an organization will always have a unique requirement that may not be available out-of-the-box.

Typically, developers write custom Tachyon instructions using the Tachyon Instruction Management Studio (TIMS). The resulting instruction XML file would then be uploaded to the Tachyon web portal to publish.

But now, you have the option to publish new instructions or updates to existing instructions via PowerShell. For example, the code below retrieves all expired certificates from every device’s Personal certificate store.

@allCerts = Security.GetCertificates();
SELECT EffectiveDate, ExpirationDate, FriendlyName, StoreName, Subject, Thumbprint, Issuer
    FROM @allCerts
    WHERE datetime(@allCerts.ExpirationDate) >= datetime("%environment:now%")
	and StoreName = "Personal";

This example is saved as 1E-Demo-GetExpiredPersonalCertificates.xml and digitally signed in TIMS.

Saving an instruction in TIMS
Saving an instruction in TIMS

When you’re ready to publish the instruction, run the Publish-TachyonInstruction cmdlet and specify the XML filename. Also, specify an instruction set to assign the instruction, such as Certificate Management for this example.

Publish-TachyonInstruction `
-File .\1E-Demo-GetExpiredPersonalCertificates.xml `
-InstructionSet 'Certificate Management'
Publishing an instruction in PowerShell
Publishing an instruction in PowerShell

After publishing, you can now ask the question in Tachyon Explorer and through the Search-TachyonServer cmdlet.

Searching for the new instruction in PowerShell
Searching for the new instruction in PowerShell
Searching for the new instruction in Tachyon Explorer
Searching for the new instruction in Tachyon Explorer

Running Dynamic Instructions

Another feature the 1E PowerShell toolkit has is running SCALE instructions and PowerShell scripts on the fly; you don’t need to create an instruction XML file first. This feature is possible through the Invoke-TachyonDynamic command.

When you run the Invoke-TachyonDynamic cmdlet, the following actions happen in the background:

  • Automatically generate the instruction XML file containing your code.
  • Digitally sign the instruction XML file. By default, the command uses the first code signing certificate on your local computer’s (LocalMachine\My) personal certificate store.

If you need to modify the signing certificate configuration, such as changing the store location or specifying the certificate subject name, you’ll need to edit the Tachyon.InstructionSigner.exe.config file.

  • Publish the dynamic instruction to the DynamicScripting instruction set. The dynamic instruction name follows the <prefix>-<random characters> naming convention, such as 1E-Demo-33ce873be9b64af586ed8464a1a33265.

The default instruction prefix is 1E-Exchange. Make sure to change the prefix that corresponds to your license by running the Set-TachyonInstructionPrefix <prefix> command first.

  • Invoke the dynamic instruction.

If you did not set the prefix or set a prefix that is not part of your Tachyon server license, you’d get the following error message when you run the dynamic instruction.

Dynamic instruction error because of the wrong prefix
Dynamic instruction error because of the wrong prefix

Dynamic SCALE

Suppose you want to run a SCALE code to retrieve the endpoint operating system name and version; your code would look similar to the one below.

Note: When running Dynamic SCALE code, the last line should assign the output to the @result table. If not, the dynamic instruction will not contain the proper data.

@os = OperatingSystem.GetSummary();
@result = SELECT Caption,Version from @os;

Assuming that you saved the file as GetOsInfo.txt, the below command runs this dynamic SCALE code. The -Scale parameter points to the file containing your SCALE code.

# Set the licensed instruction prefix
Set-TachyonInstructionPrefix "1E-Demo"

# Run the dynamic SCALE
Invoke-TachyonDynamic -Scale .\GetOsInfo.txt -TargetScope "1edemolab.com"

The output would look similar to the below screenshot.

Running a dynamic SCALE in Tachyon
Running a dynamic SCALE in Tachyon

Dynamic Scripting

At times, running PowerShell scripts to perform actions or retrieve information is more convenient than SCALE. The Invoke-TachyonDynamic command allows running PowerShell scripts directly on endpoint devices.

For example, the script below retrieves the endpoint devices’ WinRM service name and status. The result is in JSON format to serialize the output as you see fit.

Get-Service WinRM | Select-Object Name,Status | ConvertTo-Json

Assuming the PowerShell script filename is GetWinRMStatus.ps1, the command below will run the PowerShell script directly on the devices through Tachyon. The -Force switch overrides the PowerShell execution policy on the target device.

Invoke-TachyonDynamic -Script .\GetWinRMStatus.ps1 `
-TargetScope <scope> -Force `
-Schema 'Name string(30), Status string(20)'

Specifying a custom schema using the -Schema parameter is optional. But in this example, adding a custom schema that matches the object’s properties brings the results to the top.

Executing a Tachyon dynamic script
Executing a Tachyon dynamic script

WMI Integration

The PSTachyonToolkit module comes with the Invoke-TachyonWmiQuery command to run WMI query commands directly on endpoint devices. And since the query process happens through the Tachyon server, the process does not involve WMI remoting (WinRM).

Before running the Invoke-TachyonWMIQuery command, you must publish the 1E-Exchange-ExecuteWMIQuery.xml instruction XML. You can find the XML file inside the module folder. Otherwise, the cmdlet will not work.

For example, you can invoke a WMI query to get the BIOS information of all endpoint devices. You’ll only need to provide the query string (-Query), the WMI namespace (-Namespace), and the target endpoint scope (-TargetScope).

Invoke-TachyonWMIQuery -Query "select * from win32_bios" -Namespace "root\cimv2" -TargetScope <scope>
Invoking a WMI query
Invoking a WMI query

While the Invoke-TachyonWMIQuery provides a quick way to perform WMI queries against remote devices, I find that it lacks some useful features. There’s no native way to filter the results like the Invoke-TachyonInstruction or use a custom schema like the Invoke-TachyonDynamic.

Conclusion

Even in its first official release, the 1E PowerShell PSTachyonToolkit module is already feature-packed. What you’ve learned so far in this guide is merely the basics. Overall, the 1E PowerShell PSTachyonToolkit is a promising addition to Tachyon’s extensibility.

What’s not to like when a powerful product such as Tachyon works with PowerShell? The ability to produce results as close to what you can get using Tachyon Explorer is quite impressive. You can even generate reusable cmdlets from existing functions and instructions!

In future articles, we’ll tackle a few specific automation use cases with PSTachyonToolkit. Such as killing processes that may be impacting user experience, fixing network latency issues, and tagging devices based on observed workload. Stay tuned!

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!