1E 23.11 (SaaS)

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.

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.

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.

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'.

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.

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.

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

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.

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

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"

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

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.

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.

We can now upload the instruction to 1E,

and then run it.

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.

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.

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.