Merge pull request #4 from PSSecTools/development

1.2.10

JEAnalyzer/JEAnalyzer.psd1

@@ -4,16 +4,16 @@
 
 	# Version number of this module.
 
-	ModuleVersion = '1.1.0'
+	ModuleVersion = '1.2.10'
 
 	# ID used to uniquely identify this module
 	GUID = '346caa76-534a-4651-88f5-359e85cd71c0'
 
 	# Author of this module
-	Author = 'Miriam Wiesner'
+	Author = 'Miriam Wiesner, Friedrich Weinmann'
 
 	# Company or vendor of this module
-	CompanyName = 'Miriam Wiesner'
+	CompanyName = ' '
 
 	# Copyright statement for this module
 	Copyright = 'Copyright (c) 2018 Miriam Wiesner'
@@ -27,7 +27,7 @@
 	# Modules that must be imported into the global environment prior to importing
 	# this module
 	RequiredModules = @(
-		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.0.12' }
+		@{ ModuleName = 'PSFramework'; ModuleVersion = '1.4.150' }
 	)
 
 	# Assemblies that must be loaded prior to importing this module
@@ -42,25 +42,28 @@
 	# Functions to export from this module
 	FunctionsToExport = @(
 		'Add-JeaModuleRole'
+		'Add-JeaModuleScript'
 		'ConvertTo-JeaCapability'
+		'Export-JeaModule'
+		'Export-JeaRoleCapFile'
 		'Import-JeaScriptFile'
+		'Install-JeaModule'
 		'New-JeaCommand'
 		'New-JeaModule'
 		'New-JeaRole'
 		'Read-JeaScriptblock'
 		'Read-JeaScriptFile'
-		'Export-JeaModule'
-		'Export-JeaRoleCapFile'
+		'Test-JeaCommand'
 	)
 
 	# Cmdlets to export from this module
-	CmdletsToExport = ''
+	# CmdletsToExport = ''
 
 	# Variables to export from this module
-	VariablesToExport = ''
+	# VariablesToExport = ''
 
 	# Aliases to export from this module
-	AliasesToExport = ''
+	# AliasesToExport = ''
 
 	# List of all modules packaged with this module
 	ModuleList = @()

JEAnalyzer/changelog.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 1.2.10
+
+- New: Command Install-JeaModule - Installs a JEA module on the target computer
+- New: Command Add-JeaModuleScript - Adds a script to a JEA module
+- New: Command Test-JeaCommand - Test an individual command for safety to publish in an endpoint.
+- Upd: New-JeaModule - Added parameters for PreImport and PostImport scripts
+- Upd: New-JeaModule - New parameter `-RequiredModules` enables specifying prerequisites
+- Upd: New-JeaCommand - New parameter: `-CommandType` allows picking the type of command for unresolveable commands.
+- Upd: JeaModules - all roles will now automatically import the jea module, irrespective of commands used
+- Fix: Export-JeaModule - Does not write preimport and postimport scripts
+- Fix: New-JeaCommand - Fails for unknown commands
+- Fix: Export-JeaModule - New JEA modules will only try to load ps1 files on import.
+
+## 1.1.0 (???)
+
+- Pre-History

JEAnalyzer/en-us/strings.psd1

@@ -1,39 +1,37 @@
 @{
-	# General
-	'General.BoundParameters'				   = 'Bound parameters: {0}'
-
-	# Validation
-	'Validate.FileSystem.Directory.Fail'	   = 'The input object could not be identified as a directory: {0}'
-
-	# Assembly
-	'Assembly.Parameter.MissingName'		   = 'Could not convert from hashtable, must contain a "Name" element!'
-
-	# Command Add-JeaModuleRole
-	'Add-JeaModuleRole.RolePresent'		       = 'Role {0} already exists in {1}! Use -Force to replace the existing role.'
-	'Add-JeaModuleRole.AddingRole'			   = 'Adding role {0} to module {1}'
-
-	# Command ConvertTo-Capability
-	'ConvertTo-Capability.CapabilityNotKnown'  = 'Could not convert to capability: {0}'
-
-	# Command Export-JeaModule
-	'Export-JeaModule.Folder.ModuleBaseExists' = "The module's base folder already exists: {0}"
-	'Export-JeaModule.Folder.ModuleBaseNew'    = 'Creating new module folder: {0}'
-	'Export-JeaModule.Folder.VersionRoot'	   = 'Creating version specific module path: {0}\{1}'
-	'Export-JeaModule.Folder.Content'		   = 'Creating subfolder: {0}'
-	'Export-JeaModule.Folder.RoleCapailities'  = 'Creating the folder to store Role Capability Files: {0}\RoleCapabilities'
-	'Export-JeaModule.Role.NewRole'		       = 'Creating new Role: {0} ({1} Published Command Capabilities)'
-	'Export-JeaModule.Role.VisibleCmdlet'	   = '[Role: {0}] Adding visible Cmdlet: {1}{2}'
-	'Export-JeaModule.Role.VisibleFunction'    = '[Role: {0}] Adding visible Function: {1}{2}'
-	'Export-JeaModule.File.Create'			   = 'Creating File: {0}'
-
-	# Command Import-JeaScriptFile
-	'Import-JeaScriptFile.ProcessingInput'	   = 'Processing file for import: {0}'
-	'Import-JeaScriptFile.ParsingError'	       = 'Parsing error for file: {0}'
-	'Import-JeaScriptFile.UnknownError'	       = 'Unknown error when processing file: {0}'
-
-	# Command New-JeaModule
-	'New-JeaModule.Creating'				   = 'Creating JEA Module object for: {0} (v{1})'
-
-	# Command New-JeaRole
-	'New-JeaRole.Creating'					   = 'Creating Role: {0}'
+	'Add-JeaModuleRole.AddingRole'			   = 'Adding role {0} to module {1}' # $roleItem.Name, $Module.Name
+	'Add-JeaModuleRole.RolePresent'		       = 'Role {0} already exists in {1}! Use -Force to replace the existing role.' # $roleItem.Name, $Module.Name
+
+	'ConvertTo-Capability.CapabilityNotKnown'  = 'Could not convert to capability: {0}' # $inputItem
+
+	'Export-JeaModule.File.Create'			   = 'Creating File: {0}' # $Path
+	'Export-JeaModule.Folder.Content'		   = 'Creating subfolder: {0}' # $folder
+	'Export-JeaModule.Folder.ModuleBaseExists' = "The module's base folder already exists: {0}" # $moduleBase.FullName
+	'Export-JeaModule.Folder.ModuleBaseNew'    = 'Creating new module folder: {0}' # $moduleBase.FullName
+	'Export-JeaModule.Folder.RoleCapailities'  = 'Creating the folder to store Role Capability Files: {0}\RoleCapabilities' # $rootFolder.FullName
+	'Export-JeaModule.Folder.VersionRoot'	   = 'Creating version specific module path: {0}\{1}' # $moduleBase.FullName, $moduleObject.Version
+	'Export-JeaModule.Role.NewRole'		       = 'Creating new Role: {0} ({1} Published Command Capabilities)' # $role.Name, $role.CommandCapability.Count
+	'Export-JeaModule.Role.VisibleCmdlet'	   = '[Role: {0}] Adding visible Cmdlet: {1}{2}' # $role.Name, $commandName, $parameterText
+	'Export-JeaModule.Role.VisibleFunction'    = '[Role: {0}] Adding visible Function: {1}{2}' # $role.Name, $commandName, $parameterText
+
+	'FileSystem.Directory.Fail'			       = 'Not a directory: {0}' # <user input>, <validation item>
+
+	'General.BoundParameters'				   = 'Bound parameters: {0}' # ($PSBoundParameters.Keys -join ", ")
+
+	'Import-JeaScriptFile.ParsingError'	       = 'Parsing error for file: {0}' # $file
+	'Import-JeaScriptFile.ProcessingInput'	   = 'Processing file for import: {0}' # $file
+	'Import-JeaScriptFile.UnknownError'	       = 'Unknown error when processing file: {0}' # $file
+
+	'Install-JeaModule.Connecting.Sessions'    = 'Connecting via WinRM to {0}' # ($ComputerName -join ", ")
+	'Install-JeaModule.Connections.Failed'	   = 'Failed to connect to {0}' # ($failedServers.TargetObject -join ", ")
+	'Install-JeaModule.Connections.NoSessions' = 'No successful sessions established, terminating.' # 
+	'Install-JeaModule.Copying.Module'		   = 'Copying JEA module {0} to {1}' # $moduleObject.Name, $session.ComputerName
+	'Install-JeaModule.Exporting.Module'	   = 'Exporting JEA module {0}' # $moduleObject.Name
+	'Install-JeaModule.Installing.Module'	   = 'Installing JEA module {0}' # $moduleObject.Name
+
+	'New-JeaCommand.DangerousCommand'		   = 'Dangerous command detected: {0}. Interrupting, use "-Force" to accept insecure commands.' # $Name
+
+	'New-JeaModule.Creating'				   = 'Creating JEA Module object for: {0} (v{1})' # $Name, $Version
+
+	'New-JeaRole.Creating'					   = 'Creating Role: {0}' # $Name
 }

JEAnalyzer/functions/construct/Add-JeaModuleScript.ps1

@@ -0,0 +1,82 @@
+function Add-JeaModuleScript
+{
+<#
+	.SYNOPSIS
+		Adds a script to a JEA module.
+	
+	.DESCRIPTION
+		Adds a script to a JEA module.
+		This script will be executed on import, either before or after loading functiosn contained in the module.
+		Use this to add custom logic - such as logging - as users connect to the JEA endpoint.
+	
+	.PARAMETER Module
+		The JEA module to add the script to.
+		Use New-JeaModule to create such a module object.
+	
+	.PARAMETER Path
+		Path to the scriptfile to add.
+	
+	.PARAMETER Text
+		Script-Code to add.
+	
+	.PARAMETER Name
+		Name of the scriptfile.
+		This parameter is optional. What happens if you do NOT use it depends on other parameters:
+		-Path : Uses the filename instead
+		-Text : Uses a random guid
+		This is mostly cosmetic, as you would generally not need to manually modify the output module.
+	
+	.PARAMETER Type
+		Whether the script is executed before or after the functions of the JEA module are available.
+		It needs to run BEFORE loading the functions if defining PowerShell classes, AFTER if it uses the functions.
+		If neither: Doesn't matter.
+		Defaults to: PostScript
+	
+	.EXAMPLE
+		PS C:\> Add-JeaModuleScript -Module $Module -Path '.\connect.ps1'
+	
+		Adds the connect.ps1 scriptfile as a script executed after loading functions.
+#>
+	[CmdletBinding(DefaultParameterSetName = 'File')]
+	Param (
+		[Parameter(Mandatory = $true, Position = 0)]
+		[JEAnalyzer.Module]
+		$Module,
+
+		[Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'File')]
+		[PsfValidateScript('PSFramework.Validate.FSPath.File', ErrorString = 'PSFramework.Validate.FSPath.File')]
+		[Alias('FullName')]
+		[string]
+		$Path,
+
+		[Parameter(Mandatory = $true, ParameterSetName = 'Text')]
+		[string]
+		$Text,
+
+		[string]
+		$Name,
+
+		[ValidateSet('PreScript','PostScript')]
+		[string]
+		$Type = 'PostScript'
+	)
+
+	process
+	{
+		if ($Path)
+		{
+			$file = [JEAnalyzer.ScriptFile]::new($Path)
+			if ($Name) { $file.Name = $Name }
+		}
+		else
+		{
+			if (-not $Name) { $Name = [System.Guid]::NewGuid().ToString() }
+			$file = [JEAnalyzer.ScriptFile]::new($Name, $Text)
+		}
+		switch ($Type)
+		{
+			'PreScript' { $Module.PreimportScripts[$file.Name] = $file }
+			'PostScript' { $Module.PostimportScripts[$file.Name] = $file }
+		}
+	}
+}

JEAnalyzer/functions/construct/Import-JeaScriptFile.ps1

@@ -145,7 +145,7 @@ function {0}
 			#region Case: Parse Error
 			elseif ($testResult.ErrorType -eq 'ParseError')
 			{
-				Stop-PSFFunction -String 'Import-JeaScriptFile.ParsingError' -StringValues $file -Continue
+				Stop-PSFFunction -String 'Import-JeaScriptFile.ParsingError' -StringValues $file -Continue -EnableException $EnableException
 			}
 			#endregion Case: Parse Error
 
@@ -165,13 +165,9 @@ function {0}
 			#region Case: Unknown State (Should never happen)
 			else
 			{
-				Stop-PSFFunction -String 'Import-JeaScriptFile.UnknownError' -StringValues $file -Continue
+				Stop-PSFFunction -String 'Import-JeaScriptFile.UnknownError' -StringValues $file -Continue -EnableException $EnableException
 			}
 			#endregion Case: Unknown State (Should never happen)
 		}
 	}
-	end
-	{
-
-	}
 }

JEAnalyzer/functions/construct/New-JeaCommand.ps1

@@ -23,6 +23,11 @@
 		By default, the command object will just be returned by this function.
 		If you specify a role, it will instead only be added to the role.
 	
+	.PARAMETER CommandType
+		The type of command to add.
+		Only applies when the command cannot be resolved.
+		Defaults to function.
+	
 	.PARAMETER Force
 		Override the security warning when generating an unsafe command.
 		By default, New-JeaCommand will refuse to create a command object for commands deemed unsafe for use in JEA.
@@ -49,6 +54,9 @@
 		[JEAnalyzer.Role]
 		$Role,
 
+		[System.Management.Automation.CommandTypes]
+		$CommandType = [System.Management.Automation.CommandTypes]::Function,
+
 		[switch]
 		$Force,
 
@@ -72,8 +80,10 @@
 
 		$resultCommand = New-Object -TypeName 'JEAnalyzer.CapabilityCommand' -Property @{
 			Name = $commandData.CommandName
-			CommandType = $commandData.CommandObject.CommandType
 		}
+		if ($commandData.CommandObject) { $resultCommand.CommandType = $commandData.CommandObject.CommandType }
+		else { $resultCommand.CommandType = $CommandType }
+
 		foreach ($parameterItem in $Parameter)
 		{
 			$resultCommand.Parameters[$parameterItem.Name] = $parameterItem

JEAnalyzer/functions/construct/New-JeaModule.ps1

@@ -37,6 +37,25 @@
 		The version of the JEA Module.
 		A higher version will superseed all older versions of the same name.
 	
+	.PARAMETER PreImport
+		Scripts to execute during JEA module import, before loading functions.
+		Offer either:
+		- The path to the file to add
+		- A hashtable with two keys: Name & Text
+	
+	.PARAMETER PostImport
+		Scripts to execute during JEA module import, after loading functions.
+		Offer either:
+		- The path to the file to add
+		- A hashtable with two keys: Name & Text
+	
+	.PARAMETER RequiredModules
+		Any dependencies the module has.
+		Note: Specify this in the same manner you would in a module manifest.
+		Note2: Do not use this for modules you cannot publish in a repository if you want to distribute this JEA module in such.
+		For example, taking a dependency on the Active Directory module would be disadvised.
+		In this coses, instead import them as a PreImport-script.
+	
 	.EXAMPLE
 		PS C:\> New-JeaModule -Name 'JEA_ADUser' -Description 'Grants access to the Get-ADUser command'
 		
@@ -62,13 +81,18 @@
 		$Company = (Get-PSFConfigValue -FullName 'JEAnalyzer.Company'),
 
 		[version]
-		$Version = '1.0.0'
+		$Version = '1.0.0',
+
+		[JEAnalyzer.ScriptFile[]]
+		$PreImport,
+
+		[JEAnalyzer.ScriptFile[]]
+		$PostImport,
+
+		[object]
+		$RequiredModules
 	)
 
-	begin
-	{
-		Write-PSFMessage -Level InternalComment -String 'General.BoundParameters' -StringValues ($PSBoundParameters.Keys -join ", ") -Tag 'debug', 'start', 'param'
-	}
 	process
 	{
 		Write-PSFMessage -String 'New-JeaModule.Creating' -StringValues $Name, $Version
@@ -80,6 +104,10 @@
 			Company	    = $Company
 		}
 		if ($Identity) { $module.Roles[$Name] = New-JeaRole -Name $Name -Identity $Identity }
+		if ($RequiredModules) { $module.RequiredModules = $RequiredModules }
+		foreach ($scriptFile in $PreImport) { $module.PreimportScripts[$scriptFile.Name] = $scriptFile }
+		foreach ($scriptFile in $PostImport) { $module.PostimportScripts[$scriptFile.Name] = $scriptFile }
+
 		$module
 	}
 }