Skip to main content

1E 23.11 (SaaS)

Installing the 1E PowerShell Toolkit

How to install the toolkit, and information about its installation files.

Downloading the 1E PowerShell Toolkit

You can download a zip from the https://support.1e.com/.

Installing the 1E PowerShell Toolkit
Installing to the default module folder location

First, download and extract the zip.

Then, to install to the default module folder, copy the Toolkit files to the appropriate default PowerShell modules folder location. This will make the Toolkit modules available to either the current user, or all users on the install device, depending on the path you chose.

To see the appropriate folder locations, examine the $Env:PSModulePath variable in PowerShell.

  • First location is the per-user module folder

  • Second location is the per-machine install folder. This is typically: C:\Program Files\WindowsPowerShell\Modules

Assuming you are installing to the per-machine folder, create a new folder under this path called PS1EToolkit and copy the following files into this folder.

  • PS1EToolkit.psd1

  • ps1Etoolkit.psm1

  • methods.json

  • 1E.InstructionSigner.exe

  • 1E.InstructionSigner.exe.config

You can now import the Toolkit into a PowerShell session by typing:

import-module PS1EToolkit

Note

You do not need to copy the supplied Instructions XML files because they are intended to be uploaded to 1E to provide support for OSQuery integration and Querying Tachyon Activity Records using the Tachyon PowerShell Toolkit. Uploading these, only has to be done once.

Installing to the current folder

You can alternatively choose to run the PowerShell Toolkit from any folder you choose. To do this, ensure that the files from the above location are in an appropriate folder and launch a PowerShell command prompt, from an account that has the appropriate 1E privileges.

Import the manifest with:

import-module .\ps1EToolkit

Note

You can use the optional -Force parameter to import-module to ensure that the module is always imported, even if already present. This may be useful if you have an older version of the Toolkit already installed to the default module folder location but want to override with a later version which is in a specific folder.

You can use the get-1EToolkitversion to determine the currently active version of the Toolkit at any time.

Setting the 1E Server

Before you can use the PowerShell Toolkit, you must define the server to which it will connect.

Set the server you want to communicate with:

set-1Eserver <server name>

For example, if the server is 'tachyon.urth.local'

set-1Eserver tachyon.urth.local

Note

If you fail to set the server, any command you subsequently invoke will throw an exception and indicate that you need to set this first.

The above PowerShell command also confirms that the server responds appropriately when set. If you specify an invalid server address, or the server is not responding correctly, an error will be thrown.

Alternate credentials

If you wish to connect to the server using alternate credentials (i.e, not in the context of your current user account) then you can use the optional-Credentialparameter to set-1Eserver. To be prompted for these credentials, use the standard PowerShell get-credential cmdlet. For example:-Credential (get-credential)

Script customization

To customize the pstachyonToolkit.psm1 script, simply change the variables at the top of the script to reflect the environment in which you are working. The current set of customizable variables are shown below.

$TACHYONCONSUMER = "Explorer" # Consumer to use when executing instructions
$INSTPREFIX = "1E-Exchange" # Instruction prefix that you have a license for and corresponding code signing certificate in your local machine cert store
$INSTRUCTIONSET = "DynamicScripting" # Instruction set name where dynamic instructions are created in Tachyon
$MAXTARGETDEVICES = 10 # Maximum number of devices allowed to be targeted by scope; this is a safety-catch to prevent you accidentally sending stuff out to a large device count

Note

If you make changes to this script, you should reload the module using the -force option to ensure that the cached module code is correctly replaced in your PowerShell command instance, as follows:

import-module .\pstachyonToolkit.psd1 -force

Toolkit files

The PowerShell Toolkit contains the following files.

For most functionality, you need only the .pms1 and .psd1 files.

The other files highlighted are additionally required if you wish to use the dynamic instruction creation functionality. They are not otherwise required during normal operation.

The instruction XML files provide helper functionality for certain cmdlets. To use that functionality, you need only upload these instructions once to your 1E instance. After that, anyone using the PowerShell Toolkit can use these helper instructions, provided their 1E user has been granted appropriate instruction permissions on whichever instruction set you have placed these instructions.

ps1EToolkit.psm1

The main PowerShell module.

ps1EToolkit.psd1

The PowerShell module manifest.

methods.json

A json file containing each available SCALE module and method, along with the method parameters and schema. This file is used when creating instructions that invoke 1E methods.

1E.InstructionSigner.exe

1E.InstructionSigner.exe.config

These two files constitute the instruction signing tool. You do not need this tool unless you want to be able to dynamically create instructions and then sign them for upload.

Please refer to Requirements for using the 1E PowerShell Toolkit.

1E-Exchange-ActivityRecordQry.xml

A helper instruction for querying 1E Activity Records. For more information see the link above on 1E Activity Record queries.

1E-Exchange-OSQuery.xml

A helper instruction for performing OSQuery queries. For more information see the link above on OSQuery integration.

1E-Exchange-CreateEncryptionCert.xml

A helper instruction used with the credential management cmdlets. For more information see the link above on secure credential management.

1E-Exchange-CreateCredential.xml

A helper instruction used with the credential management cmdlets. For more information see the link above on secure credential management.

1E-Exchange-ListCredentials.xml

A helper instruction used with the credential management cmdlets. For more information see the link above on secure credential management.

1E-Exchange-DeleteCredential.xml

A helper instruction used with the credential management cmdlets. For more information see the link above on secure credential management.

1E-Exchange-ExecuteWMIQuery.xml

A helper instruction used with the invoke-wmiquery cmdlet, to run WMI queries. For more information, see the link above on WMI Integration.