Skip to main content

1E 23.11 (SaaS)

Creating your own cmdlet from an instruction

Walkthrough example of using the PowerShell Toolkit to turn a useful 1E instruction into a PowerShell cmdlet for re-use. We'll also see how easy it is to take any of the 1E platform's hundreds of powerful inbuilt agent methods and automatically wrap them in an instruction and/or PowerShell cmdlet, with just a couple of simple commands.

The source instruction

The source instruction is designed to retrieve all certificates on machines which expire within a certain number of days. The number of days can be passed as a parameter to the instruction.

This is quite straightforward to create using TIMS and leveraging the 1E platform's powerful built-in functions. In this case, we invoke the Security.GetCertificates() method and then filter to show only certificates which expire within the specified number of days.

Notice how the results can be queried as if they were database tables. We can easily select the columns we want to return, and the criteria for their retrieval.

233276658.png

Run in the test lab with a value of 80 days, we see that one certificate is due to expire on 7th April this year.

233276657.png

We are now ready to deploy our instruction. When the file is saved, it will be automatically signed by a certificate, as you can see above. This ensures that instructions are secure and tamper-proof and can only be authored by appropriately-privileged users who have access to the required signing certificate.

Publishing the instruction to 1E

Now that we have our signed instruction, we need to upload it to the platform.

While we can use Endpoint Troubleshooting to quickly and easily bring the instruction into 1E, we can also do this with the 1E PowerShell Toolkit.

We use the Publish-TachyonInstruction cmdlet to upload the instruction and assign it to an instruction set, in this example, the set 'AJM'.

233276656.png
Invoking the instruction

We can now easily invoke the instruction, using the Invoke-TachyonInstruction cmdlet.

The TargetScope parameter defines how we will select the target devices which will receive and process the instruction. In this example, we simply specify a string which is shorthand for 'fqdn like %urth%'. In our test lab, this targets all devices.

The TargetScope parameter doesn't just accept simple strings. You can define a scope expression instead. Scope expressions are very powerful. You can select devices by name, partial name, by device attributes such as operating system type and version, and many other criteria. You can also combine these criteria using AND , OR and NOT to create precisely targeted instructions.

See the link below for more information on using -TargetScope

Using scope and filter expressions with the Tachyon PowerShell Toolkit

Notice that we now get two results back. This is because, previously, we were just testing the instruction on our local machine. Now we have deployed it to our estate and so we have picked up another machine with an expiring certificate.

You can see how we were also prompted for the number of days parameter. Instruction parameters are automatically mapped to PowerShell parameters so that you can either directly specify them on the PowerShell command line or supply them as part of a PowerShell prompt.

233276655.png
Turning the instruction into a reusable cmdlet

We can now turn this instruction into a reusable cmdlet which we can then simply import and run, just like any other PowerShell cmdlet. This gives you the enormous power and flexibility of hundreds of instructions as part of your PowerShell environment.

To do this, we use the New-TachyonCmdLet cmdlet. We provide the name of the instruction and then the name of the cmdlet we'd like to create from it.

233276653.png

Now we can simply import and use the cmdlet, just like any other PowerShell cmdlet. Note how the parameters are automatically prompted for.

233276652.png

Note

You can, of course, combine many cmdlets into a single .psm1 file. This lets you bundle up all your favorite instructions as cmdlets and then make them available to other people, such as help-desk administrators.

Leveraging the power of the 1E framework via cmdlets

Although your generated cmdlet is simple to use, it inherits the enormous power and flexibility of the 1E framework. As you can see, generated cmdlets support many optional parameters which leverage framework features.

233276651.png
Using the -ResultFilter parameter to filter cmdlet results

For example, you can use the 1E platform's powerful result filtering option to select only results you want to see. Let's have a closer look at the information returned from the cmdlet.

This is easy, just assign to a PowerShell variable and then send to the PowerShell format-list cmdlet

233276650.png

We can see here that one certificate is found in the Personal store of a device and two others are coming from the Trusted store on another device.

Suppose we just wanted to see the results for certificates in the Personal stores of all devices. We didn't create the instruction with an optional parameter to select just these, but we can still do this easily.

All generated cmdlets leverage the full power of the 1E framework. Therefore, we can just run the cmdlet but this time we supply an optional parameter -ResultFilter. We provide a value of "StoreName=Personal"

Note

-ResultFilter is one of the many parameters that all cmdlets inherit from the Tachyon Framework. As you can see, there are several others which provide great power and flexibility automatically.

233276649.png

As you can see, we only receive back results where the filter matches.

Automatically creating an instruction from a method

Our journey began with a instruction that was authored using TIMS. But you can create instructions yourself directly from PowerShell if you wish.

At the start of this page, we saw how the instruction was created to retrieve the certificates. It used a built-in method called Security.GetCertificates() to retrieve them.

You can use the PowerShell Toolkit to automatically create instructions from inbuilt methods. To do this, we use the new-TachyonInstructionXmlForMethod cmdlet.

We specify the name of the built-in method that we want to be turned into an instruction, in this case, Security.GetCertificates.

233276648.png

The instruction XML file has been automatically created for us. Because we did not author this file using the TIMS authoring tool, we need to sign it before we can upload it to Tachyon. This is easy, using the protect-instructionxml cmdlet.

233276647.png

We can now upload the instruction to 1E,

233276646.png

and then run it.

233276645.png

Note that because we simply wrapped the Security.GetCertificates() method in an instruction, by default, it had no parameters. Therefore it returns all certificates on all target devices. We can still, of course, leverage the full power of the 1E framework to filter these results, and we can also turn this instruction into a PowerShell cmdlet, just like we did previously.

Finding out more about inbuilt agent methods

You can use the get-tachyonmethodinfo cmdlet to list all inbuilt agent methods you can use with the PowerShell toolkit. This cmdlet can also return detailed information on method parameters and results.

For more information, please refer to Instruction XML management cmdlets.

Conclusions

In this scenario, we've shown how easy it is to leverage the power of 1E. It was easy to query and return the data we wanted, and then, using the PowerShell Toolkit, create cmdlets for reuse that leverage the power of the framework.

We could also easily create new instructions, directly from any inbuilt method. This can save hours or even days of work developing complex scripts to retrieve information from devices.

As well as being quick and easy, this process is also scaleable, secure and performant. No PowerShell remoting infrastructure or permissions are required, yet the platform's flexible and granular role-based access controls ensure that only appropriately privileged users can initiate actions through 1E and PowerShell.