Documentation of ImmyBot Functions

General
1

It would be great if there were some more thorough documentation for the ImmyBot functions and their parameters with examples. I’ll copy and paste a few I was grabbing for my reference. I was going to copy and paste these internally, but I figured better to make it available to the community here. Hopefully one of these days the ImmyBot crew can publish one of those fancy sites with all the functions, params, and examples. That’d be radical.

If these are available somewhere other than running get-help in an ImmyBot terminal, then I would love to be enlightened. Also, knowing what context they need to be ran in would be great as well. The below will all run in the metascript context.

NAME
    Start-ProcessWithLogTail
    
SYNTAX
    Start-ProcessWithLogTail [-Path] <string> [[-ArgumentList] <string[]>] -LogFilePath <string> [-TimeoutSeconds <int>] [-RegexActions <hashtable>] [-RegexFilter <string>] [-WorkingDirectory <Object
    >] [<CommonParameters>]
    
    Start-ProcessWithLogTail [-Path] <string> [[-ArgumentList] <string[]>] -LiteralLogFilePath <string> [-TimeoutSeconds <int>] [-RegexActions <hashtable>] [-RegexFilter <string>] [-WorkingDirectory 
    <Object>] [<CommonParameters>]
    

ALIASES
    None
    

REMARKS
    None

PROGRESS: Completed - Get-Help


NAME
    Start-ProcessWithLogTail
    
SYNTAX
    Start-ProcessWithLogTail [-Path] <string> [[-ArgumentList] <string[]>] -LogFilePath <string> [-TimeoutSeconds <int>] [-RegexActions <hashtable>] [-RegexFilter <string>] [-WorkingDirectory <Object
    >] [<CommonParameters>]
    
    Start-ProcessWithLogTail [-Path] <string> [[-ArgumentList] <string[]>] -LiteralLogFilePath <string> [-TimeoutSeconds <int>] [-RegexActions <hashtable>] [-RegexFilter <string>] [-WorkingDirectory 
    <Object>] [<CommonParameters>]
    
    
PARAMETERS
    -ArgumentList <string[]>
        
        Required?                    false
        Position?                    1
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      Args
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -LiteralLogFilePath <string>
        
        Required?                    true
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           NoExpandLogFilePath
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -LogFilePath <string>
        
        Required?                    true
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           ExpandLogFilePath
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -Path <string>
        
        Required?                    true
        Position?                    0
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      PSPath, FilePath
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -RegexActions <hashtable>
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -RegexFilter <string>
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -TimeoutSeconds <int>
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -WorkingDirectory <Object>
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216). 
    
    
INPUTS
    None
    
    
OUTPUTS
    System.Object
    
ALIASES
    None
    

REMARKS
    None

NAME
    Install-MSI
    
SYNTAX
    Install-MSI [-Path] <string> [[-MSIParameters] <string>] [<CommonParameters>]
    
    
PARAMETERS
    -MSIParameters <string>
        
        Required?                    false
        Position?                    1
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -Path <string>
        
        Required?                    true
        Position?                    0
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216). 
    
    
INPUTS
    None
    
    
OUTPUTS
    System.Object
    
ALIASES
    None
    

REMARKS
    None

NAME
    Get-ImmyComputer
    
SYNTAX
    Get-ImmyComputer [[-TargetGroupFilter] {All | Servers | Workstations | PortableDevices | WorkstationsAndPortableDevices | DomainControllers | PrimaryDomainControllers}] [[-InventoryKeys] {Antivir
    us | WindowsSystemInfo | ExternalIp | InternalIp | ExternalHostnames | LogicalDisks | NetworkAdapters | Partitions | PhysicalDisks | PhysicalMemory | Processes | RebootPending | Software | Logged
    OnUser | LoggedOnUserSID | DuplicateComputerResolver}] [[-DeviceId] <guid>] [-IncludeOffline] [-OnboardingOnly] [-IncludeTags] [<CommonParameters>]
    
    
PARAMETERS
    -DeviceId <guid>
        
        Required?                    false
        Position?                    2
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -IncludeOffline
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -IncludeTags
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -InventoryKeys <string[]>
        
        Required?                    false
        Position?                    1
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -OnboardingOnly
        Limit the results to only onboarding computers
        
        Required?                    false
        Position?                    Named
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    -TargetGroupFilter <TargetGroupFilter>
        
        Required?                    false
        Position?                    0
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      None
        Dynamic?                     false
        Accept wildcard characters?  false
        
    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216). 
    
    
INPUTS
    None
    
    
OUTPUTS
    System.Collections.IDictionary
    
    
ALIASES
    None
    

REMARKS
    None
2 Likes
2

Agreed. In the mean time, one of the ways I learn is by going to the script library and typing the function into the search box under “Action”. It will filter the list to only scripts that use that function, so you can kind of get a sense of how it’s used

3

Is this not what the intellisense shows?

4

Intellisense covers how, but not really why or when to use a function. I’m sure I’ve done my own redundant fixes with known powershell functions and Invoke-ImmyCommand, simply because I have no idea how to use a certain immy function or what I should expect it to do on the target.

1 Like
5

For inspiration I would check out docs of PSUniversal, PSGsuite, PSFalcon, or the many examples of Microsoft documentation out there.

The problem I see with making the most of ImmyBot is that we don’t know what we don’t know. I don’t think someone fairly fluent in PowerShell can just walk off the street and intuitively learn how to use ImmyBot. Being able to see all of the functions listed with examples and various scopes would be a great resource for your customers to make the most of the product without spending excessive time spinning our wheels. :grin:

2 Likes
6

Not sure if I ever told you @Jesse_G , but I literally did not know powershell before I started using Immy. Personally, I’d take a working example of something and intellisense over a written paragraph.

I think this is more about comfort with powershell than it is with documentation–and there are docs for the uninitiated at Scripting Guide | ImmyDocs

7

Not all the functions are that easy or straight-forward, though. I can’t use Get-Module “ImmyBot” for a list of functions, and not everything is in the script library. For example, Get-ImmyComputer.

A lot of the documentation is also “Coming soon” and I’d really love to know the difference between RegistryShould-Be and HKCUShould-Be. Does the former not work on HKCU keys?

8

Working examples are great, intellisense is also great. You know what else is great? Good documentation :slight_smile: Why not all the things!?

I’d love to see all of the ImmyBot functions available to me. You’re suggesting I scour through the existing scripts and figure out what exists, how they work, and what they do. But I don’t know what I don’t know. What if I don’t know about a particular function? Not all of us have the luxury of living and breathing ImmyBot all day long.

Part of what I love about Powershell is you can figure out most of this on your own with 2 functions, Get-Command and Get-Help. Not everyone has the same workflow, different strokes for different folks. Just a suggestion to something that would be appreciate by myself, and I’m sure many others. I’m saying this as someone who is extremely comfortable with PowerShell.

1 Like
9

We are adding this in 0.56

image
image451×716 18 KB

3 Likes