Categories

Secure Parameter Validation in PowerShell

Parameter validation in PowerShell is an extremely useful and easy way to alert a user as early as possible that incorrect input was provided to a function or cmdlet. The following attributes are available to you for performing explicit parameter validation (taken from MSDN):

ValidateCount
Specifies the minimum and maximum number of arguments that a parameter can accept. For more information about the syntax used to declare this attribute, see ValidateCount Attribute Declaration.

ValidateLength
Specifies the minimum and maximum number of characters in the parameter argument. For more information about the syntax used to declare this attribute, see ValidateLength Attribute Declaration.

ValidatePattern
Specifies a regular expression that validates the parameter argument. For more information about the syntax used to declare this attribute, see ValidatePattern Attribute Declaration.

ValidateRange
Specifies the minimum and maximum values of the parameter argument. For more information about the syntax used to declare this attribute, see ValidateRange Attribute Declaration.

ValidateSet
Specifies the valid values for the parameter argument. For more information about the syntax used to declare this attribute, see ValidateSet Attribute Declaration.

When validating parameters, it is important to make sure your validation attributes make sense though. For example, consider the following simple function that returns the status of a TCP connection:

Those comfortable with networking should recognize that the ValidateRange attribute doesn’t make sense since a port number is an unsigned, 16-bit value – i.e. 0-65535. You would be surprised to see how many built-in PowerShell cmdlets use nonsensical ValidateRange arguments. Naturally, it would make more sense to provide the following ValidateRange attribute:

[ValidateRange(1, 65535)]

Now, the validation attributes are nice and they certainly have their place but often times they are not necessary. By choosing proper data types as parameters to your functions, you will often get parameter validation for free (i.e. implicit validation). Consider the following improvement to the Test-TcpConnection function:

By making the IPAddress parameter an IPAddress object, it will automatically parse the IP address provided. No complicated regular expressions required! For example, it will throw an error upon attempting to execute the following command:

Test-TcpConnection 0.0.0.300 80

It is also worth noting that the ValidateRange attribute is still necessary for the Port parameter because the “connect” method will not accept a port number of 0.

Starting in PowerShell v3, you also get automatic tab completion if you use the ValidateSet attribute or use an enum type as one of your parameters. Consider the following contrived example:

Only colors defined in the ConsoleColor enum will be accepted (in theory… more on this in a moment).

You will get automatic tab completion when typing in the colors in PS v3 and v4- e.g. Get-Poem Re[TAB] Blu[TAB]

Now, there is a subtle characteristic of enums in .NET that can lead to undefined behavior: you can call the Parse method on an enum and have it return to you an undefined enum value. Consider the following example:

Obviously, I never intended for this behavior to occur. In fact, most people would think that they would be explicitly preventing this sort of thing from happening! If you were truly concerned about ensuring proper parameter validation, you would need to provide the following validation attribute for each parameter:

[ValidateScript({ [Enum]::IsDefined($_.GetType(), $_) })]

This ensures that the enum value you provided is an actual, defined value.

Now, to put things into perspective, I’ll provide an example of a built-in cmdlet introduced in PowerShell v3 that exhibits a lack of parameter validation that ultimately leads to undefined behavior – Resolve-DnsName.

Resolve-DnsName allows you to query individual DNS records of various types. You specify the record type through the “Type” parameter which accepts an enum of type [Microsoft.DnsClient.Commands.RecordType]. To view all of the defined record types, run the following:

When I saw the list of record types, I noticed that a specific type was missing – AXFR (zone transfer). Penetration testers will often attempt to perform a zone transfer on a potentially misconfigured DNS server in order to get a listing of every DNS record in the zone specified. A successful unauthorized zone transfer is a potential treasure trove of actionable intelligence for an attacker. Naturally, I would have liked it if Resolve-DnsName would let you perform zone transfers (like nslookup.exe does) but unfortunately, there is no “AXFR” defined in the RecordType enum. Fortunately, we can use our new trick to force AXFR (0xFC) to be used:

If you ran this command, you would find that it only returns a single SOA entry. If you ran the command with Wireshark running, however, you would see that a zone transfer was actually performed. Unfortunately, Resolve-DnsName wasn’t designed to parse multiple records from a zone transfer but this is undefined behavior, nonetheless.

Like this:

About the author: Matt Graeber

Matt is a malware reverse engineer, security professional, and PowerShell MVP who is always finding new ways to incorporate PowerShell into his workflow. As one of just a handful of security-minded PowerShell hackers, he also promotes PowerShell as an attack platform in an effort to raise awareness of its security implications in the enterprise. Matt frequently writes about esoteric uses of PowerShell, reverse engineering, and security research on his blog - www.exploit-monday.com.