Requirements for using the 1E PowerShell Toolkit
Common requirements for using the toolkit. Specific requirements for some features. Further features have additional requirements that are described on their pages.
Please refer to Installing the 1E PowerShell Toolkit for detail about installation and the toolkit's files.
Running PowerShell
Important note about the PowerShell ISE (integrated scripting environment)
When you request PowerShell by typing 'PowerShell' at the Windows start prompt, you are taken into an instance of the PowerShell ISE, not a standard PowerShell session. While the PowerShell Toolkit will work within the ISE, there are two important considerations:
The interactive search feature is not available because the PowerShell ISE does not emulate the single character keyboard input functionality that is used
Scripts run under the ISE run much slower than they do in a regular PowerShell environment. This is because the ISE is intended primarily for script debugging.
Consequently, in most situations, you should run the PowerShell Toolkit from a regular PowerShell session. You can start a regular session by just typing 'PowerShell' from the Windows command prompt.
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.localNote
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
Account privileges in 1E and the 1E PowerShell Toolkit
The toolkit feature has a number of capabilities, and some of these require additional privileges.
To use the Dynamic Scripting, Dynamic File Copy, Dynamic Activity Record Query or Dynamic SCALE functionality, the user requires a valid code signing certificate, just as they would if they were using the TIMS authoring tool. The certificate is placed in the users local machine certificate store as it would be for TIMS usage. See below for more information.
Note
It is also possible to query 1E Activity Records without requiring a code certificate as an alternative mechanism has been provided that uses a dedicated instruction., For more information see Querying Tachyon Activity Records using the Tachyon PowerShell Toolkit.
To use the remaining functionality, which involves executing and managing instructions and instruction sets, the account must be able to perform some or all of the below functions , depending on the activity they are invoking:
Upload instructions and assign them to an instruction set
Create instruction sets
Execute instructions
Cancel instructions.
Note
At the time of writing, Least Privilege testing has not been conducted and so for preliminary evaluation it is recommend that you use a privileged 1E account with global administrator rights.
Code Signing Certificate
If you wish to use the Dynamic Scripting and executable command execution using the Tachyon PowerShell Toolkit, Querying Tachyon Activity Records using the Tachyon PowerShell Toolkit, or Dynamic SCALE , you will require the following to sign your instructions.
Note
You do not require these to use the remaining functionality in the PowerShell Toolkit.
Updated license | A valid license that includes an instruction prefix that you will use when creating dynamic instructions. For more detail, please refer to Running instructions for the first time. NoteThe PowerShell module file assumes an instruction prefix of 1E-Exchange for the code signing certificate. Please refer to Key features and concepts of the 1E PowerShell Toolkit for instructions on changing the prefix to match your license. Please refer to Instruction XML management cmdlets for details of a cmdlet that allows the prefix to be dynamically overridden. |
Code signing certificate | A valid code signing certificate that has a trust chain that can be validated on the device on which you are running PowerShell, as well as the 1E server and its associated infrastructure and devices. To sign instructions, you must have copied the code signing certificate to the local machine personal certificate store on the device from which you are running PowerShell. If you intend to run PowerShell from a non-elevated command prompt under your 1E account context, you may need to go into the Certificate Manager utility (certlm.msc) and set the certificate private key permissions to allow your account to access the private key. This will remove the need to elevate during the code signing phase. |
1E Instruction Signing utility | The Instruction Signing utility (1E.InstructionSigner.exe) is included in the toolkit, and is used to sign the dynamic instructions when they are created. |
PowerShell execution policy
Before you can use the PowerShell Toolkit, you must ensure that your local PowerShell execution policy settings allow scripts to be executed. At the time of writing the PowerShell Toolkit files are not digitally signed, so you need to set a PowerShell policy that allows unsigned scripts to be executed. You will normally only need to do this once on a specific device.
You use the set-executionpolicy cmdlet to define a PowerShell policy. Note that if you choose to use the RemoteSigned execution policy, then you must ensure that the PowerShell Toolkit core files (ps1EToolkit.psd1 and ps1EToolkit.psm1) are not tagged with an external trust zone alternate data stream. This is a mechanism that Windows uses to tag files which are downloaded from an external source such as the internet. Files which contain this alternate data stream are checked to ensure that the trust zone associated with the stream contents is appropriate. Files whose trust zone lies outside the local internet will be blocked from executing if the PowerShell execution policy specifies RemoteSigned.
To remove a trust zone alternate data stream, you can use the standard File Explorer UI and select Unblock from the File Properties screen. There are also PowerShell cmdlets to manage ADS content. To detect if a file is tagged with an alternate data stream, you can use the dir /r command from the command prompt.
For more information on alternate data streams, see NTFS File Streams | History & Tools | Alternate Data Streams (ADS) (stealthbits.com)
Note
When you are using the PowerShell Toolkit to execute instructions which run PowerShell scripts on remote devices, the device execution policy is managed by 1E. The requirements discussed here apply only to the device on which you are executing the PowerShell Toolkit cmdlets, not any remote devices managed by 1E that you may communicate with while using the toolkit. You will not have to change the PowerShell policy on these devices. 1E can manage this for you automatically.
Signing PowerShell scripts
You may be able to sign PowerShell scripts using the same code signing certificate used to sign instructions. Then to use the script, the certificate's public key must exist in the Trusted Publishers store.
