Kansa: Get-Started

Last week I posted an introduction to Kansa, the modular, Powershell live response tool I've been working on in preparation for my presentation at the SANS DFIR Summit.

Please do me a favor and click the DFIR Summit link. :)

My previous post was a high level overview. This one will dive in. If you'd like to try it out, you'll need a system or systems that are configured for Windows Powershell remoting and you'll need an account with permissions to run remote jobs on those hosts.

Getting a copy of Kansa is easy, this link will pull down a zipped copy of the master repository. Simply download it and extract it to a location of your choice. On my machine I've extracted the files to C:\tools\Kansa. As of this writing the main directory of the archive consists of the following files and folders:

Kansa.ps1 is the script used for kicking off data collection.

The Analysis folder contains Powershell scripts for conducting basic analysis of the collected data. It's really just a starting point as of this writing and more analysis scripts will be added as I have time to create and commit them. Many of the Analysis scripts require Logparser, but much of the data collected by Kansa could be imported directly into your database of choice for analysis.

The lib folder contains some common code elements, but as of yet, none of it is in use elsewhere in Kansa.

The Modules folder contains the plugins that Kansa will invoke on remote hosts. As of this writing, the modules folder consists of the following:

I like to think of the modules as collectors. They follow the Powershell Verb-Noun naming convention and I'm guessing you can tell what most of them do based on their names. Most of them are very simple scripts, however, some may appear a bit complicated because they reformat the data they collect to make it ready for analysis. For example, the Get-Netstat.ps1 module calls Netstat.exe -naob on each remote host. Netstat's output when called with these flags is relatively unfriendly for analysis. Here's a sample:

Kansa's Get-Netstat.ps1 module reformats this data and the output becomes, well, first we have a bit of a diversion:

First, notice I'm running the Get-Netstat.ps1 module directly on the localhost. As of this writing, all of Kansa's modules may be run standalone, they don't have to be run within the framework. But more relevant to the screenshot above, when I try and run it, I get prompted by a "Security warning" because the script was downloaded from the internet. You should probably look through any script you download before running it in your environment, Powershell is trying to be helpful here. There are multiple ways around this, you can enter "R" or "r" here and the script will run once. You can view the properties of the files within Explorer and "unblock" them or you can use the Powershell Unblock-Files cmdlet as follows to unblock them all:

Now with the files unblocked, let's run Get-Netstat.ps1 again and see how the output is made more friendly for analysis:

What we have here are Powershell objects and Powershell objects can be easily manipulated into a variety of formats, XML, CSV, TSV, binary, etc. Most of the Kansa modules return Powershell objects and each module can include an "# OUTPUT directive" on their first line that directs Kansa how to treat the output. For example, Get-Netstat.ps1's OUTPUT directive is "# OUTPUT tsv", if that looks like a Powershell comment, well it is, but Kansa.ps1 looks for it on line one of each module and if it finds it, it will honor the directive, in this case it will convert the Powershell objects above into tab separated values and write the data out to a file on disk. If a module doesn't include an OUTPUT directive on line one, Kansa will default to treating the output as text.

The end result for Get-Netstat.ps1, when invoked by Kansa on a remote system, is that you'll have tab separated values for your Netstat -naob output, like this:

Click the image for original

That tab separated data can easily be imported into the database of your choice, you can run queries directly against it using Logparser, load it into Excel, etc.

Looking back at the Modules folder contents above, you'll notice a bin directory. There are a trio of modules that call binaries. At one point, I had functionality in Kansa to push binaries from this folder to remote hosts and I have it on the ToDo list for the project to get this back in. I just haven't found the perfect way to do it yet, so I've rolled it out. For now, the three modules that require binaries, expect those binaries to be in the $env:SystemRoot directory of each remote host, this is generally C:\Windows and also the ADMIN$ share. In practice today, I simply use Copy-Item to push binaries to remote hosts' ADMIN$ shares. A future version of Kansa will distribute these binaries at run time.

[Update: As of 2014-04-27, I've implemented a -Pushbin command line flag that will cause Kansa to try and copy required binaries to targets. See Get-Help -Full Kansa.ps1 for details. The Get-Autorunsc.ps1, Get-Handle.ps1 and Get-ProcDump.ps1 modules can be referenced as examples.]

Two other files in the Modules directory don't look like the others, default-template.ps1 is a template for building new modules. Mostly it gives some guidance. Reading it and some of the existing collectors should give you enough information to create your own.

Lastly, there's a modules.conf file in the Modules folder. This file controls which modules will be invoked on the remote systems and the order in which they will be invoked, this allows the user to execute collection in the order of volatility and to limit what is collected for more targeted acquisition. All modules are currently listed in the modules.conf file. To prevent a module from being executed, simply comment it out with the pound-sign/hashtag/octothorpe/#. If the modules.conf file is missing, all modules will be run in the default directory listing order.

Alright, so how do we run this thing? For most use cases, I recommend you create a text file containing the list of hosts you want to run modules on. For demonstration purposes, here is my hostlist file:

The script has been run on thousands of hosts at a time, so if you want to try it on a larger list, it should work fine, given you've satisfied two prerequisites: 1) your targets are configured for Windows Remoting, see the link above; 2) The account you're using has Admin access to the remote hosts.

If you don't use the -TargetList argument (see below), Kansa will query Active Directory for the list of computers in the domain and they will all be targeted, you can limit the number of targets with or without -TargetList with the -TargetCount argument.

Here's a sample run using the default modules.conf and my hostlist:

That's it. You'll see the same view if you run it over thousands of hosts, though it may take longer. Powershell's remoting has a default setting that limits it to running tasks on 32 hosts at a time, but it is configurable. Currently Kansa uses the default setting, but in a future version, I may make this a command line option.

Where does the output go? You can specify where you want the output written, but in this case I took the default, which is the Output folder within the Kansa folder. Let's see what's there:

Each collector's output is written to its own folder. Drilling down one more level, let's look in the Handle folder:

But wait you say, we ran this with two hosts in the hostlist file we provided to the -TargetList argument. Where's the data for the other host? Well, I ran this from an Admin command prompt and my local Admin account doesn't have permission to run jobs on Selfridge, so those jobs failed. Currently the user receives no warning or error when a job can't run on a remote host, fixing this is an item on the ToDo list. If I drop out of the admin command prompt and run it as a different user that has admin access to both my localhost and the remote host, the folder above would look like this:

Now, before you go running this in your environment and complain that you don't have handle data from your hosts, recall that the Get-Handle.ps1 module is one that has a binary dependency. If you want to run it, you'll first need to copy-item handle.exe to the ADMIN$ share of each target. This is easily accomplished with something like:

foreach($host in (gc hostlist)) { copy-item handle.exe \\$host\admin`$ }

from a Powershell prompt with the appropriate privileges to copy data to the remote hosts. I haven't tested that command, you may have to do some trickery to properly escape whack-whacks.

Incidentally, handle.exe, like netstat.exe with -naob, is another utility that has analysis unfriendly output. Luckily, Get-Handle.ps1 will return Powershell objects and direct Kansa to reformat the output as tsv, ready for import into your db or choice or for querying with Logparser.

Kansa was written with some help in the script, to view it, simply use the Powershell Get-Help -Full Kansa.ps1 command and you'll get something like the following:

That should be enough to get your started with Kansa. Please, take it for a spin and give me some feedback. Let me know what breaks, what sucks and what works. And if you have ideas for collectors, send them my way or if you want to contribute something, that would be welcome.

I've got a few more posts coming, so stay tuned and thanks! Oh, and if you found this interesting, useful, please take a moment to check out the SANS DFIR Summit where I'll be discussing Kansa and how it can be used to hunt at scale, or as I like to think of it, seine for evil.