Coming from a background in enterprise architecture and operations dominated by Microsoft products, many of my former coworkers are surprised how much I use Linux OSs. I spend an absurd amount of time in a bash prompt on my local OSX box, prefer Deep Security Manager deployments on Amazon Linux or RedHat, and of course support customers deploying our Deep Security Agent on a dizzying array of distros and versions. I’ve long held the opinion that there is a best tool for any given job, and while I still think Microsoft products are best suited for some tasks, in the public cloud a Linux OS is the best tool for many of my jobs. In fact, I suggest a non-MS solution so often that many of my coworkers are shocked to find that I’ve ever logged into a Windows machine at all!

These days even Microsoft is supporting the reality of a cross platform world in the cloud with great Linux support in Azure, open source contribution bringing openssh to Win32, and open sourcing powershell while porting it to OSX and Linux. If Microsoft can deliver Desired State Configuration for Linux, I think I can shed my bash-full-ness and admit to my latent MS predilection…

I love PowerShell. I could go on for quite a while about having dynamic typing, object oriented features, pipelining, the ability to use any .NET capability on the fly, great exception handling, sophisticated remoting, rich integrated contextual help ….. Ah.. where was I?

Oh right.. The point! Why this matters to Deep Security customers.

I churn out quite a bit of scripting against the Deep Security APIs and am regularly asked how I knock these out so fast, and why so often they’re in PowerShell (especially for someone who spends the vast majority of days ‘Windows-less’). The answer is: PowerShell lets me cheat.

Before we get to the API itself, one bit of housekeeping – if you’re running a self-signed certificate on the Deep Security Manager or don’t have the full CA chain available on your local box, we’ll need to tell .NET to ignore your SSL indiscretion.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback={$true}

* Note the pattern in which we’re referencing a .NET class inside <code>[]</code> square brackets, then assigning a value to a property of that class. This will be important later on.

With the pesky SSL detail out of the way, let’s dive in.

Find your WSDL URL (and enable the SOAP API!) in the Deep Security Manager console at ‘Administration -> System Settings -> Advanced’.

If you’re using Deep Security As a Service you won’t find this button but can take my word for it; the URL is 'https://app.deepsecurity.trendmicro.com:443/webservice/Manager?WSDL'
.

pic 1 powershell

The first bit of cheating with PowerShell is found in the New-WebServiceProxy cmdlet. I’ll let you wade through the full docs, but in short this cmdlet lets you take a remote WSDL and create a proxy to a .NET framework object representing the service. We’re going to generate the proxy, stash a reference, and [very important for later] we’re going to specify a Namespace so that we can find all out new types easily from now on.

$manager = app.deepsecurity.trendmicro.com

$Global:DSMSoapService = New-WebServiceProxy -uri "https://$manager/webservice/Manager?WSDL" -Namespace "CheatingWithPowershell" -ErrorAction Stop

Great – now what?

[Insert the sound of evil laughter here]

With a .NET Namespace that represents the Deep Security Manager’s Web Service (which you might want to rename from my example), every class and enum exposed by the web service is available with tab completion and typed returns. We’ll use the proxy first to create an instance of the ManagerService class, which has all of the methods for doing useful things with the interface. Then after configuring username and password variables (preferably prompting for password input with Read-Host -AsSecureString where appropriate), we’ll log into the Manager and get a token to use for subsequent calls.

$Global:DSM = New-Object CheatingWithPowershell.ManagerService

$Global:SID = $DSM.authenticate($user, $password)

If you’re using Deep Security As a Service similar to our example above, we’ll need to add a tenant parameter:

$Global:SID = $DSM.authenticateTenant($tenant, $user, $password)

… And now the good stuff…

How about an array of every computer object visible in the manager? (careful with this one – I really do mean ALL your hosts)

$allhosts = $DSM.hostRetrieveAll($SID)

Then echo your $allhosts to see what you’ve got.

$allhosts

Or, if you just pulled many tens of thousands of machines, you might prefer to take a peak at just the first HostTransport object in the array.

$allhosts[0]

We’ve pulled a bunch of data from the manager about our protected machines but what if we want to do something with a specific machine? Most of the methods operate on the internal unique identifier for a given host object, but I for one don’t know the table index of every host in my manager, so let’s get an individual machine by hostname, and while we’re at it let’s get a bit more detail.

$hostdetails = $DSM.hostDetailRetrieveByName("ec2-54-149-116-109.us-west-2.compute.amazonaws.com", [CheatingWithPowershell.EnumHostDetailLevel]::HIGH, $SID)

$hostdetails

I’m sure you’ve noticed the return of the [NAMEPSACE.CLASS]::PROPERTY design, but this time we’re referencing an enum. That seems like a pain to remember, but did I mention that since PowerShell has access to the namespace, we’ve got tab completion for these types? Check it out inline…[Cheating<tab>.EnumH<tab>]:: … very slick!

But how do I know what arguments are accepted by hostDetailRetrieveByName(STRING hostname, EnumHostDetailLevel detail, STRING sid)?

Or better asked, since I’m doing this all the time, how would you know? I guess you could read the documentation (and on the record, I definitely encourage you to do so!), but that hardly seems like cheating. Enter the PowerShell ISE. Let’s take our authentication example above, put it into a script, and add some error handling, and run the script. Notice that thanks to param handling, we get tab completion for our argument names or prompted for mandatory values if not supplied.

<#
.SYNOPSIS
Cheating with Powershell sample SDK for Deep Security Manager SOAP API
.LINK
https://www.trendmicro.com/aws
#>
param (
   [Parameter(Mandatory=$true)][string]$manager,
   [Parameter(Mandatory=$true)][string]$user,
   [Parameter(Mandatory=$false)][string]$tenant
)
$passwordinput = Read-host "Password for Deep Security Manager" -AsSecureString
$password = [Runtime.InteropServices.Marshal]::PtrToStringAuto([Runtime.InteropServices.Marshal]::SecureStringToBSTR($passwordinput))
[System.Net.ServicePointManager]::ServerCertificateValidationCallback={$true}
$Global:DSMSoapService = New-WebServiceProxy -uri "https://$manager/webservice/Manager?WSDL" -Namespace "CheatingWithPowershell" -ErrorAction Stop
$Global:DSM = New-Object CheatingWithPowerShell.ManagerService
$Global:SID
try {
   if (!$tenant) {
     $Global:SID = $DSM.authenticate($user, $password)
   }
else {
   $Global:SID = $DSM.authenticateTenant($tenant, $user, $password)
   }
}
catch {
   echo "An error occurred during authentication. Verify username and password and try again. `nError returned was: $($_.Exception.Message)"
   exit
}

Once executed within the ISE, our editor now knows wonderful things about the interface (by which I really mean everything about the interface). See what happens now when we start to type $DSM.  in the editor pane.

powershell pic 2

How about that hostDetailRetrieveByName method?

powershell pic 3

Intellisense here gives us not only access to methods within a class, but also properties on objects.

Take for example our $hostdetails object, a HostDetailTransport[].

Powershell pic 4

This way it’s incredibly easy to see what properties are available and their types. Seems likely some of those properties could be used directly within a method call to retrieve more objects, but that will have to wait for another time.

Can’t wait to see what you come up with. Look for the CheatingWithPowerShell.ps1 and other samples soon at ‘https://github.com/deep-security/‘, and in the meantime check out our Python SDK and other integration projects.

Drop us a line via aws@trendmicro.com for functionality you’d like to see in the next sample script, or to let us know what automation you’ve come up with!

P.S.

Almost forgot – Deep Security Manager will restrict the total number of concurrent sessions allowed for a user, so I will signoff this post in the most appropriate way I can imagine:

$DSM.endSession($SID)

Written by: Bryan Webster