Creating a simple script

When creating your first script, start with a small goal in mind and then build on it from there. If you try to do something really large and detailed, you may run into issues and get frustrated. Look at examples on the Internet to see how others have solved for the same issues, and experiment.

PowerShell scripts are always saved with a filetype of PS1. This tells your system that the file is a PowerShell script file and will suggest PowerShell or your favorite text editor to edit it or will open PowerShell to execute it.

If you ever find yourself in need of samples or you want to download pieces of code so that you’re crafting code from scratch, I highly recommend PowerShell Gallery (www.powershellgallery.com). It’s maintained by Microsoft and has modules, scripts, and even some examples of PowerShell DSC, which I talk about in Chapter 5 of this minibook. Figure 4-1 shows you the PowerShell Gallery homepage. At the time of this writing, you can see that there are 4,260 unique scripts and modules available from PowerShell Gallery. What I really like is that you can see how many downloads of each resource have been made, and any questions or comments that have been made to the authors of the scripts or modules.

Before I get into an example of a script, I want to add that you should always use comments when you’re writing a script. You can denote a comment in PowerShell by starting the line with a hash (#). Everything after the hash on that line is ignored and is treated like a comment. Comments are useful for you because they can form an outline of what you’re trying to accomplish. They can serve as documentation for you later and can assist your co-workers in either using the script or helping you write it.

In Chapter 3 of this minibook, I show you an example of how to create a new user in Active Directory using PowerShell instead of using the graphical Active Directory Users and Computers. The real power of that little bit of code becomes apparent when it’s put into a script that can take a CSV file (from HR perhaps) and import it into PowerShell, and then have PowerShell loop through each row and create each user.

In the following sections, I step through this script step by step. Then I show you the whole thing all together. Never fear! The script is on the GitHub repo created for this book, and you can download it from there, rather than having to retype it. The GitHub repository created for this book is located at https://github.com/sara-perrott/Server2022PowerShell.

Creating the CSV file

The CSV file is the most important piece of this whole exercise because it provides the input to the script. The column names are assigned in the first part of the script to variables so that they can be called when you get to the loop that processes each row in the CSV. Figure 4-2 shows you a sample of what the CSV should look like. After the CSV is complete, you can move on to the script.

As a working security professional, I have to point out that storing passwords in plaintext CSV files is not a good thing to do. I suggest setting complex temporary passwords and destroying the CSV when it’s complete. You can, of course, send the credentials to the supervisor of the new employee by whatever means is approved in your organization before destroying it. Don’t leave spreadsheets hanging around with passwords in them, though. They’re a treasure trove for hackers.

Running the script

The first time you run the script, I highly recommend that you run it within Visual Studio Code. Visual Studio Code is helpful in troubleshooting issues with scripts because you can do debugging and execute one line of code at a time. Plus, it highlights issues for you, which can make them easier to find. The usual culprits are those darn braces on the loops.

To open and run in PowerShell ISE, follow these steps:

1. Click Start, scroll down to Visual Studio Code, expand the folder and click Visual Studio Code.
2. Choose File ⇒ Open File.
3. Navigate to your script.
4. Select the script and click Open.
5. To run the script, choose Terminal ⇒ Run Active File.

When you’re sure that your script is working, there are two methods to run it:

• Right-click the script and select Run with PowerShell. I don’t like this method because the PowerShell window pops up but closes right away when you’re done, so you can’t see if it encountered any errors.
• Open a PowerShell window and run it by specifying the directory (Example 1) or running it from the same directory (Example 2):
  • Example 1: C:PSTempUserImport.ps1
  • Example 2: .UserImport.ps1

Playing with parameters

Advanced functions give you a lot of granularity when it comes to working with parameters that you just don't have with basic functions. These are placed in the parameter block where you define the parameters for your function. Here are a few of my favorites:

• Mandatory parameters: When you specify a parameter as mandatory, the function will not be able to run if that parameter is not provided. In the following example, I’ve set the parameter to be mandatory, and I’ve indicated that the value for the parameter will come from the pipeline.

  [Parameter(Mandatory,ValueFromPipeline)]

• Parameter validation: Parameter validation is very useful when you want to ensure that a parameter matches some form of expected input. This is done by typing ValidateSet, and then by specifying the strings you expect to see. If the parameter string does not match, then the function will not be able to run. See the following example:

  [ValidateSet('String1','String2')]

Creating the advanced function

Now that you know the basic building blocks of advanced functions, I’ll create an example of an advanced function. This advanced function will retrieve information about a system. I’ll start with the individual components of the function, and then I’ll show you the whole thing after it’s done. The function is also available for download from this book’s GitHub repository at https://github.com/sara-perrott/Server2022PowerShell.

First, to tell PowerShell that you want to create a function, you need to start the text in the file with function, followed by what you want to name your function. This absolutely has to follow the PowerShell syntax of verb–noun. Next up, you add [CmdletBinding()], which tells PowerShell that this is an advanced function and should be treated similarly to a cmdlet. In the Param block, you define any parameters you want to use. In this case, you're defining one parameter, which is a variable named computername.

function Get-ReconData
{
[CmdletBinding()]
Param (
[string[]] $computername
)

Next, I’ll add some text in a BEGIN block. I like to use this to see which system it's on currently. You probably won’t want to do this in production, especially if you have multiple systems that you’re running this function against. But it’s great for troubleshooting issues in your script.

BEGIN {
Write-Output "Gathering reconnaissance on $computername"
}

Next up is where the magic happens. The PROCESS block is where I’m telling the function what I want it to do. In this example, I’m telling it to run the code block for every object that is passed to it through the $computername variable. Each object is assigned to the $computer variable.

Now you can make use of Windows Management Instrumentation (WMI) classes to get the information that you want. In this case, I'm using two WMI classes to query for the data that I want. I’m using the Win32_OperatingSystem class and the Win32_ComputerSystem class. You can see a listing of the properties that you can work with on the Microsoft documentation pages. Win32_OperatingSystem can be found at https://docs.microsoft.com/en-us/windows/desktop/cimwin32prov/win32-operatingsystem and Win32_ComputerSystem can be found at https://docs.microsoft.com/en-us/windows/desktop/cimwin32prov/win32-computersystem.

To tell PowerShell that I want to use the two WMI classes, I use the PowerShell cmdlet Get-WmiObject to assign the desired WMI class to a variable. I then chose a few of the properties that I felt were most useful for gathering some information about the system. I created names for them, and then mapped the name to the WMI variable I created earlier and the property that I'm interested in. Finally, I’m telling it to write the output of the function to the screen. In a production environment, if you were running this against multiple systems, you could export the data to a file.

PROCESS {
foreach ($computer in $computername) {
$os = Get-WmiObject -class Win32_OperatingSystem -computerName $computer
$comp = Get-WmiObject -class Win32_ComputerSystem -computerName $computer
$prop = @{'ComputerName'=$computer;
'OSVersion'=$os.version;
'SPVersion'=$os.servicepackmajorversion;
'FreeMem'=$os.FreePhysicalMemory;
'OSType'=$os.OSType;
'Domain'=$comp.domain;
'Status'=$comp.Status}
$sysinfo = New-Object -TypeName PSObject -Property $prop
Write-Output $sysinfo}
}

The last block is simply the End{} block. In this case, you don’t need it to run anything after the function has ran, so it’s left blank.

Here is the final function in all its glory!

function Get-ReconData
{
[CmdletBinding()]
Param (
[string[]] $computername
)
BEGIN {
Write-Output "Gathering reconnaissance on $computername"
}
PROCESS {
foreach ($computer in $computername) {
$os = Get-WmiObject -class Win32_OperatingSystem -computerName $computer
$comp = Get-WmiObject -class Win32_ComputerSystem -computerName $computer
$prop = @{'ComputerName'=$computer;
'OSVersion'=$os.version;
'SPVersion'=$os.servicepackmajorversion;
'FreeMem'=$os.FreePhysicalMemory;
'OSType'=$os.OSType;
'Domain'=$comp.domain;
'Status'=$comp.Status}
$sysinfo = New-Object -TypeName PSObject -Property $prop
Write-Output $sysinfo}
}
END {}
}

Save your function as a .ps1 file just as you would a normal PowerShell script. Now let’s try it and see what it looks like when it is run.

Using the advanced function

You can run functions from your code editor of choice or from PowerShell. They’re all a little different as to how you should execute the code. In this section, I cover running the advanced function in VS Code, which you’ll most likely do while testing, and running it in PowerShell, which is the more realistic production method.

Running an advanced function in VS Code

Now that you’ve written the advanced function, you want to try it out and see if it works. I’ll use VS Code to test it. This is very common when wanting to validate that your function is working properly. I’ll use the names and parameters from my previous example.

1. Click the Start menu and scroll down to the Visual Studio Code folder.
2. Expand the folder and click Visual Studio Code to launch it.
3. Choose File ⇒ Open File.
4. Navigate to where your script is stored, select the file, and click Open.

5. In the Terminal, navigate to where you save your function.

   In my case this is my PSTemp directory, so I typed cd C:PSTemp.

6. Type a period, followed by a space, and then .Get-ReconData.ps1.

   This tells it that you want to run the script from the current directory. It should look like this: . .Get-ReconData.ps1.

7. Type Get-ReconData -computername <computername>.

The output you receive will contain all the information you asked the function to retrieve. In this case, server2022-svr3 is a Windows Server 2022 virtual machine, but you can see that I’m still able to get valuable information, shown in Figure 4-4.

Running an advanced function in PowerShell

In a production environment, it’s far more likely that you’ll choose to run the advanced function from PowerShell rather than a code editor. Here’s how to do this:

1. Right-click the Start menu and choose Windows PowerShell (Admin).

2. Navigate to the location where your function is saved.

   In my case, it’s in my PSTemp folder, so I typed cd C:PSTemp to get to it.

3. Type a period, followed by a space, and then .Get-ReconData.ps1.

   This tells it that you want to run the script from the current directory. It should look like this: . .Get-ReconData.ps1

4. Type Get-ReconData -computername <computername>.

After the function has run, the information you requested is output to the screen, as shown in Figure 4-5.

And that’s all there is to it. If you’ve followed along you just created your first advanced function. From here, the sky’s the limit. If you aren’t sure what information you want to pull, I highly recommend that you check out the links for the various WMI classes. There is a wealth of information that you can pull.