There’s a story on Reddit I recall coming across that at the time reminded me of two incredibly important lessons.

• Comment Based Help (CBH) is necessary for all scripts anyone ever makes for a company
• NSFW sites really are NSFW (Not Safe For Work)

u/BaDumDumTish (I’ll now call “Tish”) received an email from a newly hired manager criticizing them in an email that was CC’d to the IT Group of some thirty people covering HQ and three other offices from the VP of IT down. This resulted in a high-priority ticket with their name on it.

The subject?

“Your stupid PowerShell script is broken”

Tish says it was regarding a simple piece of code “SiteReview.ps1.” You type in an email address and the OU (Organization Unit) site you want to be queried and it sends you the group member list of the AD (Active Directory) Groups in that site via email. The script is used by the security auditors to make sure the right people on that site are in the right OU’s

The script was in a shared folder that was accessible to management at the company. However, there was no readme file, or Comment-based Help, and Tish said that “The people who need it know how to use it.” The prompts are shown in the PS Window as:

**** Site Review v1.02 ****
**** In case of issues contact (tish@initech.corp) ****
Email: <Pause for input> 
Site: <Pause for input>

Tish continued reading the email and the newly hired manager criticized them saying they couldn’t get “any usable output” from the script then went on to berate them for “wasting their time” with “such unproductive software”. A very surprising message to receive considering security had been using it without any issues for the past 3 years.

So Tish dived into the logs to try and find the problem.  And oh boy, he found a problem.

The first part of the SiteReview.log was a typical, early test and past security output. After sliding down to the more recent time/date stamps what Tish found was:

Email: newbossman@initech.corp
Site: totallynsfw.xxx
Error message "Get-ADSite : Directory Object not found..."

Email: newbossman@initech.corp
Site: http://totallynsfw.xxx
Error message "Get-ADSite : Directory Object not found..."

Email: newbossman@initech.corp
Site: https://totallynsfw.xxx
Error message "Get-ADSite : Directory Object not found..."

Email: newbossman@initech.corp
Site: www.totallynsfw.xxx
Error message "Get-ADSite : Directory Object not found..."

-- snip 22 more entries involving four more totally NSFW sites --

Tish ended up forwarding the email to his boss and received a message later that day saying the ticket was closed and “not to worry about it.”

Preventative Measures

While absolutely hilarious, I can’t but help thinking how situations like this could be prevented:

1. Comment-Based Help

It’s fairly obvious the manager is to blame in Tish’s story. But in more normal work environments mistakes like this (not this perverse) can easily happen and be extremely frustrating to staff and management that have to use companywide scripts.

Read: What is Comment-Based Help and Why Your Scripts Need It

Scripts used at your office are company assets and should be treated as such. Comment-Based Help is a collection of descriptions and keywords enclosed in a block comment. Unlike normal comments, PowerShell can read COMMENT-BASED HELP and display it upon request using the “Get-Help” command. CBH can be as simple as adding in a single sentence before the .SYNOPSIS or .DESCRIPTION of a script that describes what it does.

2. Use a Tool like Otter

Otter would have shown Tish’s inappropriate manager the logs right away, stopping them from searching another 25 times for “XXX” sites. Otter automatically generates a UI around your PowerShell scripts and enables those who are less comfortable or familiar with PowerShell to run scripts without expert intervention.

Read: How to Run Parameterized PowerShell Scripts with Otter

You can easily create multiple variables and parameters in Otter that would prevent a (less mischievous) team member from making fatal server errors by misusing a PowerShell script.

3. Don’t Hire Weird People

Okay, I don’t have any advice on this, fairly obvious right? But there has to be some sort of interview question that someone can ask managers about their NSFW-browsing habits at work, right?

Your Stupid PowerShell Script Needs to Have Instructions

While Tish’s pervy manager was DEFINITELY misusing company property and scripts, I think it’s important to think about the responsibility we all have to our scripts. We are their caretakers and are responsible for enabling and empowering less technically capable team members to use them. I recommend using a tool like Otter and CBH – Or y’know…just ignore the advice and keep obscure scripts so you can have some fun stories like this too.

This is just one example of how you can enhance your PowerShell usage, mind you. For many more ways to give your PowerShell scripts and modules a boost, take a look at our free eBook, “Ultimate Powershell Levelup Guide”. Sign up for your copy today!