PS /mkellerman>

Introducing PSTwitterAPI - a PowerShell module for the Twitter API

2019-01-25T00:00:00+00:00

Introducing PSTwitterAPI

<salespitch>Ever wanted to get twitter notifications on your build jobs? Or collect some tweets for a report? Or automate some tweets for your blog post? All in PowerShell? This is the module for you! </salespitch>

Seriously, for whatever the reasons you need to interact with the Twitter’s API, this is the most complete solution available out there!

Twitter API Helper functions

I originally created the module InvokeTwitterAPIs that is sitting in the PowerShell Gallery, but a lot has changed since then. I wanted to refactor the whole project and make it easier/faster overall. It wasn’t complete, and many endpoints where missing.

Instead of writing each endpoint by hand, I created a Script to scrape the Twitter API documentation, get the resource URL, description and parameters. It then uses this to generate all the helper functions dynamically. You can go check it out here: GitHub: APIHelper

It’s not pretty, but it does the job!

Example 1: Get Twitter user information

Import-Module PSTwitterAPI

# Provide Authentication for the Twitter API
# https://twittercommunity.com/t/how-to-get-my-api-key/7033
Set-TwitterOAuthSettings -ApiKey $env:ApiKey -ApiSecret $env:ApiSecret -AccessToken $env:AccessToken -AccessTokenSecret $env:AccessTokenSecret

# Get user twitter profile
Get-TwitterUsers_Lookup -screen_name 'mkellerman'

Provide authentication token to the module
Use one of the +120 helper functions to get/send requests to Twitter
Profit

Example 2: Create WordCloud from your recent tweets

Import-Module PSTwitterAPI
Import-Module PSWordCloud

Set-TwitterOAuthSettings -ApiKey $env:ApiKey -ApiSecret $env:ApiSecret -AccessToken $env:AccessToken -AccessTokenSecret $env:AccessTokenSecret

# Request the last 200 tweets from the desired user.
$TwitterStatuses = Get-TwitterStatuses_UserTimeline -screen_name 'mkellerman' -count 200

# Get list of stop words that should be excluded from the world cloud.
$ExcludeWord = (Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/Alir3z4/stop-words/master/english.txt' -UseBasicParsing).Content -Split "`n"

# Generate a word cloud from the text in your tweets.
New-WordCloud -InputObject $TwitterStatuses.text -Path ".\TwitterStatuses.png" -ExcludeWord $ExcludeWord -ImageSize 720p

Provide authentication token to the module
Get last 200 tweets from your user
Get stop words to be excluded from the world cloud
Generate word cloud
Profit

PSWordCloud for @mkellerman using PSTwitterAPI

Open Source: Come and help!

I’ve built the foundation, but there are many things left to do:

Test each helper function (Manual/Pester).
If you see a missing API endpoint, create an Issue.
Any improvements you can suggest/make please make a PR!

You are using Twitter via Powershell? Join me on the PowerShell Slack/Discord #PSTwitterAPI channel!

And as always, go check it out and let me know what you think!

Copy-xItem to Remote Session

2019-01-02T00:00:00+00:00

Copying a file/function/module to a Powershell Remote Session

Most of the time I write my script locally. I then add a second layer to run it remotely, and make sure everything works well. Building my scripts like a cake.

I’ve build a few tools to help me copy files, functions and modules over to a remote machine. I didn’t want to go the UNC share to copy files over the conventional way.. because <insert valid, but pointless reason here>.

In PS 5.1, Copy-Item got a new property: -ToSession. I thought that was brilliant! I wish more Cmdlets had this property. I then decided to implement my own version of this, so i can use it in older environments.

Copy-xItem

Import-Module Copy-xItem
$Session = New-PSSession -ComputerName $ComputerName -Credential $Credential
Copy-xItem -Session $Session -Path 'C:\Workspace' -Destination 'C:\Workspace' -Recurse -Force

Invoke-Command -Session $Session -ScriptBlock { Get-ChildItem 'C:\Workspace' }

Copy-xFunction

Import-Module Copy-xItem
Import-Module .\Get-PendingReboot.ps1

$Session = New-PSSession -ComputerName $ComputerName -Credential $Credential
Copy-xFunction -Session $Session -Name 'Get-PendingReboot'

Invoke-Command -Session $Session -ScriptBlock { Get-PendingReboot }

Copy-xModule

Import-Module Copy-xItem
Import-Module .\Get-PendingReboot.ps1

$Session = New-PSSession -ComputerName $ComputerName -Credential $Credential
Copy-xModule -Session $Session -Name 'Get-PendingReboot'

Invoke-Command -Session $Session -ScriptBlock { Get-PendingReboot }

Conclusion

So there you have it.. little duck tape, a couple paperclips, and presto, my own little script to copy over files, functions and modules to a remote PowerShell Session.

You really need to see the source to appreciate it. I’ll dump the source of Copy-xItem, Copy-xFunction and Copy-xModule, on GitHub.

https://github.com/mkellerman/Copy-xItem

Go check it out and let me know what you think! And dont be shy to make PRs!

Import functions in remote sessions

2018-07-29T00:00:00+00:00

Want to use a custom function inside a PSSession or BackgroundJob, use this one-liner to do all the heavy lifting.

Invoke-Expression ${Using:Function:<functionname>}.Ast.Extent.Text

Here’s a simple example:

function Invoke-HelloWorld {
    Write-Warning "Hello World"
}

$ScriptBlock = {
    Invoke-Expression ${Using:Function:Invoke-HelloWorld}.Ast.Extent.Text
    Invoke-HelloWorld
}

Start-Job -ScriptBlock $ScriptBlock | Receive-Job -Wait -AutoRemoveJob

How does it work? Let’s break it down:

${} : Curly braces in PowerShell variable names allow for arbitrary characters in the name of the variable.
$Using:<VariableName> : Using Local variables in remote session.
$Function:<FunctionName> : Provides access to the functions defined in Windows PowerShell.

We are basically doing some kind of inception, pulling the function definition from our local session.

But why ${}.Ast.Extent.Text? my head hurts…

We dont want the scriptblock inside the function. We want the entire function definition as a string.

Hope this helps!

And dont forget to msg me on Twitter (@mkellerman), love getting your feedback!

References:

About Remote Variables: Link
Function Provider: Link

Start-Job like a boss

2018-07-16T00:00:00+00:00

Ever wanted to Start Background Jobs (Start-Job) with some Throttle? Or with a Timeout? And how about loading your local user session functions inside your Background Job?

I use Start-Job daily. Managing +300 VMs for our QA environment in VCenter (VMWare) and SCVMM (Hyper-V). It’s a breeze when you know how to do things in parallel. Many scripts/modules are out there to help you do it quickly and efficiently. Most of them, are built around Runspaces and for good reasons. Using Runspaces are blazing fast! But in some cases, using Runspaces isn’t the right option. For those times, I’ve built Invoke-Job.

I wanted to replicate the Start-Job cmdlet, but add a few extra parameters:

ImportFunctions
Throttle
Timeout
PassThru

Link: https://github.com/mkellerman/Invoke-Job

Let’s make a simple example:

Import-Module .\Invoke-Job.ps1

function Invoke-HelloWorld { 
    Write-Warning 'Hello World'
}

(1..10) | Invoke-Job -ScriptBlock { Invoke-HelloWorld } -ImportFunctions -Throttle 3 -All

This example shows how to invoke a custom function, inside of the background job, without having to do anything to load that function. It does it all for me. the -All parameter will show be jobs when they are starting and when they are completed. If you remove that parameter, you’ll only see when they are done. As a DevOps, i like seeing things start/stop. ;)

Now that we get the basics, let’s bump it up a notch:

Import-Module .\Invoke-Job.ps1

# Load a script in this user session
# https://gallery.technet.microsoft.com/scriptcenter/Get-PendingReboot-Query-bdb79542
Import-Module .\Get-PendingReboot.ps1

# Make a simple ScriptBlock that will receive the computername from the pipeline and execute the script against the remote computer. In this case, Get-PendingReboot that we've loaded in this current session.

$ScriptBlock = {
  Process {
    
    # Collect the InputObject sent through the Pipeline.
    $ComputerName = $_
    
    Try   { 
    
      # Because Get-PendingReboot has been imported into this session, I can call the function directly.
      # I'm also $Using variables from the parent session. Everything works as expected.
      
      Invoke-Command -ComputerName $ComputerName -Credential $Using:Credential -ScriptBlock ${function:Get-PendingReboot} 
    
    } Catch { 
    
      Write-Error $_.Exception.Message 
    
    }
  
  }
}

# Get list of computers and set the credential used for the remote execution.

$Computers = Get-Content -Path '.\computers.txt'
$Credential = Get-Credential

# Start-Job 4 jobs at a time, with a timeout of 30 seconds, and return the results (not the Job object). And beautify it by presenting the results in a table.

$Computers | Invoke-Job -ScriptBlock $ScriptBlock -Throttle 4 -Timeout 30 -ImportFunctions -PassThru | Format-Table

This example shows how to execute a function against many computers, but with a throttle and a timeout. And output the results directly.

And here you go. Simple and easy to read code. If I had to put the code here to handle the Throttle, the Timeout, ImportFunctions and the PassThru, it would have been +250 lines of code and hard for someone else to read and maintain.

Let me know what you guys think!

Msg me on Twitter, love getting your feedback!

Link: https://github.com/mkellerman/Invoke-Job

Death to PsExec

2018-04-12T00:00:00+00:00

As a first technical blog post, I’ve decide to document some of the work I did to move away from PsExec in our environment.

But why… What’s wrong with PsExec?

Currently we use PsExec to remotely execute our NUnit tests against our test environment. It works most of the time, but when there is any network interruption or connectivity issue, the session drops, but the actual process continues on the remote machine. You then have to implement tons of error handling to re-connect and try to continue where you left off, or pick up the test results… it’s simply a nightmare.

Why not use PowerShell Remote Sessions?

Have you heard of the Double-Hop issue? Ashley McGlone (@GoateePFE) has a great article explaining the issue and offering tons of solutions.

So why not implement one of those solutions?

Simple: I wanted to point my script to an IPAddress, and magically have it ‘work’. I didn’t want to have to setup an AD environment, or configure anything on the remote box.

Marc… You’re too damn difficult.

I want a simple implementation that replicated the Invoke-Command cmdlet, but add a -As $Credential to provide the <PSCredential> I want that <ScriptBlock> to run on the remote machine. But have the connectivity benefits of the Powershell Remoting Session.

What I want it to look like:

Invoke-CommandAs -Session <Session> -ScriptBlock <ScriptBlock> -As <PSCredential>

First step, establish a Powershell Remote Session to the remote machine, and execute a process with a different set of credential… and return a powershell object? ¯\(ツ)/¯

Should be simple enough…

Executing a process with a different set of credentials? Easy peasy lemon squeezy…

I wanted to try out an replicated the RunAs.exe command, to start my powershell.exe process under another set of credentials. But I wasn’t able to launch it remotely and provide the credentials to the console.

Invoke-CmdAs

A colleague of mine found a Jetbrains/runAs project that replicates the RunAs.exe utility, but allows the credentials to be passed in the command line. View my wrapper here: Invoke-ExpressionAs

But having binaries being copied over is definitely not elegant.

Invoke-RunAs

I then found Invoke-RunAs by Ruben Boonen (@FuzzySec) that uses Add-Type to load the DLL and invoke ‘Advapi32::CreateProcessWithLogonW’ the same way RunAs.exe is doing. View my wrapper here: Invoke-RunAs

Start-ProcessAsUser

Also, verify similarly, Start-ProcessAsUser by Matthew Graeber (@mattifestation) with modifications by Lee Christensen (@tifkin_) uses Reflection to load the DLL and invoke ‘Advapi32::CreateProcessWithLogonW’ the same way RunAs.exe is doing. View my wrapper here: Start-ProcessAsUser

All these implementations required some code wizardry to return a PowerShell Objects.

Invoke-ScheduledTask

Alternatively, one solution that is very often talked about is to create a Scheduled Task on the remote machine, and let ‘SYSTEM’ (or any supplied credential) execute your process. It’s simple, and after some digging around, i found out it creates a ScheduledJob, and you can Receive-Job the result as a Powershell Object.

So i created a Invoke-ScheduleTask cmdlet to help simplify this and created a wrapper to copy the implementations above. View my wrapper here: Invoke-ScheduledJob

Simpler is better

After playing around with all these solutions for a while, I’ve decided to implement the Invoke-ScheduleJob into my final solution, as it returns native PowerShell Objects, and doesn’t break any of the output streams.

Go check it out here: Invoke-CommandAs.

It’s also in the PowerShell Gallery!

# Install Module
Install-Module -Name Invoke-CommandAs

# Execute Locally.
Invoke-CommandAs -ScriptBlock { Get-Process }

# Execute As different Credentials.
Invoke-CommandAs -ScriptBlock { Get-Process } -As $Credential

# Execute Remotely using ComputerName/Credential.
Invoke-CommandAs -ComputerName 'VM01' -Credential $Credential -ScriptBlock { Get-Process }

# Execute Remotely using PSSession.
Invoke-CommandAs -Session $PSSession -ScriptBlock { Get-Process }

# Execute Remotely on multiple Computers at the same time.
Invoke-CommandAs -ComputerName 'VM01', 'VM02' -Credential $Credential -ScriptBlock { Get-Process }

# Execute Remotely as Job.
Invoke-CommandAs -Session $PSSession -ScriptBlock { Get-Process } -AsJob

I’m sure there is tons of other ways to do this, or some scenarios that makes one solution better than others, and would love to hear about them!

Msg me on Twitter!

Update:

2018-04-12: Reddit user kusuriya pointed to Invoke-TokenManipulation to impersonate another users Logon Token.

Look ma’, i’m a blogger!

2018-04-11T00:00:00+00:00

I’m at the PSSummit 2018, and everyone has a blog… so here I am!

Note to future me: What where you thinking?

More notes to self: Have your wife spell check all them things

¯\(ツ)/¯