If you saw my blog post a couple weeks ago, you know that I like writing Aggressor scripts for Cobalt Strike. Aggressor allows you to add functionality to the framework, and make it even more useful for your purposes. This can be done in many different ways, but one thing that has caught my interest recently is the possibility offered by Cobalt Strike visualizations.

What are Visualizations?

Visualizations are the different views that Cobalt Strike offers to an operator, found in the View menu. The default visualizations are what you’re used to seeing in the top pane of Cobalt Strike: Sessions view, Targets view, and the Pivot Graph. Basically, they’re there to give you information about the engagement, and the current state of Cobalt Strike. But what if we could display more information to operators? What information is kept within the framework that isn’t as easy to see? More importantly, how can we display that to operators to allow them to use that information?

Visualizing Success

A few months ago, I was playing around with some Aggressor, and while browsing the official reference, I stumbled across a function I had never really paid attention to: addVisualization. My interest was piqued, because the Aggressor function reference only gives this:

Register a visualization with Cobalt Strike.

Arguments

$1 - the name of the visualization
$2 - a javax.swing.JComponent object

Example

$label = [new javax.swing.JLabel: "Hello World!"];
addVisualization("Hello World", $label);

Not much to go on. I wanted to find out more. What else could I do with addVisualization? Could I create anything useful? There was one problem… There weren’t any other examples of visualizations in Cobalt Strike. None. I looked exhaustively. There were Aggressor scripts that dealt with GUI elements — notably from @bluescreenofjeff and @harmj0y, both of which were extremely helpful for certain parts — but there were no scripts that I could find that actually created visualizations. Without other code to reference, I was in uncharted territory. Rather than give up, I fired up Cobalt Strike and started tinkering.

Hello, world!

The first step was to create a very simple visualization. I just wanted to make sure that I could add a visualization to the framework and display it. From there, I could build on that to make a visualization that actually displays useful data.

The code for this was fairly simple, and most of it is in the little snippet in the docs. First, you have to create a JComponent object. The example in the docs (posted above) uses a JLabel, so that’s what I started with. Here’s my first working visualization:

And here’s what that looks like when you load the script into Cobalt Strike:

Aggressor and Java

Before we go through this simple script, we need to talk a little bit about Java inside of Aggressor. If you haven’t dealt with Java in Aggressor before, Aggressor scripts can import any Java packages or libraries you want, and you can access them from within Aggressor with a slightly different syntax compared to what you might do in Java.

For example, to make a new JLabel in Java, we would use this syntax:

vis = new JLabel(“Hello, world!”);

To do this in Aggressor, we use the following syntax, as seen in line 6 of the helloworld.cna script:

$vis = [new JLabel: “Hello, world!”];

Converting Java constructors to Aggressor is fairly straightforward. Instead of new Object(arg1, arg2), you can use [new Object: arg1, arg2]. You use a similar syntax when calling methods on Java objects. I’ll show an example of that here, because we’ll use that later. Consider a Java object that we’ve created in Aggressor like this:

$obj = [new someObject];

Let’s say the someObject class has a doStuff(“argument”) method that will return a string. To get this string in Java, we’d do something like:

String str = obj.doStuff(“argument”);

To do the same thing in Aggressor, it looks like this:

$str = [obj doStuff: "argument"];

This syntax will let us convert Java to Aggressor, and thus create more advanced visualizations. Back to our simple visualization.

Creating and Displaying Visualizations

As seen in the docs for addVisualization, once we’ve created a visualization, we use addVisualization to register the visualization within Cobalt Strike. This still doesn’t display it to the user, though! The syntax for addVisualization that our script uses is this, on line 7:

addVisualization("hello", $vis);

In this case, “hello” is a label that we can use to reference our visualization now, and we use this label to display the visualization with showVisualization:

showVisualization("hello");

Pretty simple, right? …Right?

Making Useful Visualizations

While creating my first test visualization was pretty easy, the rest wasn’t so easy. Working without a good reference, I turned to the source code for Armitage, Raphael Mudge’s precursor to Cobalt Strike. Many parts of Cobalt Strike are based on Armitage, and luckily still utilize many similar components. By looking through the various Cortana scripts (the precursor to Aggressor), I managed to cobble together a basic visualization that allowed me to display a table of Beacons alongside a simple console display, vis.cna.

As you can see, it was fairly minimal, but it provided a good way to test out various things within Cobalt Strike visualizations. This visualization pulls information from the Cobalt Strike data model to populate the table of Beacons on the left, and displays web log hits and new Beacon events in the console on the right. There was one major issue with this visualization, but first let’s go through how it’s constructed.

Vis.cna Deconstructed

I started my work on a custom visualization by attempting to build a simple table, and to pull Beacon data into that table. To create a table, it first requires a GenericTableModel, which is what will populate our table with data. GenericTableModel is provided by the table package, built in to Cobalt Strike. To create a GenericTableModel, you provide an array of column names, a column to use as the lead column, and an expected size for the table.

$model = [new GenericTableModel: @(“user”, “host”, “bid”), “bid”, 16];

The next question is: How do we pass data into our GenericTableModel? In vis.cna the function that does that is updateTable(). This function is fairly straightforward. First, we clear the model. Next, we have to iterate through the Beacons that Cobalt Strike has information about, and create a hash with the appropriate user, host, and ID for each one.Then, we use the addEntry method of GenericTableModel to add the entry to the model. We’re not quite done yet, because we have to tell the ATable we’re populating with this GenericTableModel that the model has changed. That’s where fireListeners comes in.

Now that we’ve created our GenericTableModel to populate it with data, let’s create our ATable. First, we create a new ATable, with the GenericTableModel as an argument.

Next, we have to tell the ATable how to sort the data in the GenericTableModel, so that you can click the column headers to sort based on the data in those columns. First, we need to create a TableRowSorter to control how the data is sorted. Next, we need to use the setComparator method of this TableRowSorter to tell it how to sort each column. We have three columns: username, hostname, and Beacon ID. Usernames and hostnames are sorted alphabetically, but we need to sort Beacon IDs numerically. To sort the first column alphabetically, we need this snippet:

[$sorter setComparator: 0, { return $1 cmp $2; }];

To sort the Beacon ID numerically, we use this snippet:

[$sorter setComparator: 2, { return $1 <=> $2; }];

With that, we’ll be able to change the sort order of the table by clicking the column headers. After making sure we can sort the table, let’s add a secondary component to display certain events in the Cobalt Strike console. I chose a Display from the built-in console package in Cobalt Strike, because it will give us nice formatting options for the text, and it matches with the way information is displayed in the rest of the framework. Creating this is pretty simple:

$console = [new console.Display];

After we’ve created our ATable and Display, we need to create something to house both of these, because addVisualization takes a single object. For this, I chose a JSplitPane, which will allow us to have both components side by side, with a divider that we can drag to resize the size of either component. Here’s how we do that:

$content = [new JSplitPane: [JSplitPane HORIZONTAL_SPLIT], [new JScrollPane: $table], $console];

You might have noticed that we didn’t put $table directly into the JSplitPane. Instead, we first put it into a JScrollPane, to allow the table to be scrolled if there are more items than fit in the pane. We also specified the direction of the split as the first argument, using [JSplitPane HORIZONTAL_SPLIT]. In Java, this would be JSplitPane.HORIZONTAL_SPLIT, but we need to use Sleep’s Java syntax in this case. To make things look a little nicer, I chose to set the default divider location to have a bit of an offset with this line:

[$content setDividerLocation: 450];

The last thing we need to do before adding our new visualization is call our updateHosts function to populate data into the GenericTableModel. Then, we can finally add our visualization to Cobalt Strike with addVisualization(“Custom”, $content). Note that this doesn’t do anything with the visualization, it just registers it with the framework.

To actually view our new visualization, we can use showVisualization, like this:

showVisualization(“Custom”);

Visualizations are referenced by their title in Cobalt Strike, so we choose the title that we used in addVisualization as the argument in showVisualization. At the bottom of vis.cna, I have a short snippet to add the visualization to the View menu in the Cobalt Strike interface, which will allow us to quickly access the new visualization.

Wrapping Up

Hopefully this post has been useful if you’re interested in Cobalt Strike visualizations! This is just scratching the surface of what is possible, and I’m working on exploring these possibilities, but I wanted to share what I’ve learned so far in the hopes that others will see this post and decide to experiment as well. At the most basic, visualizations are just JComponent objects, and they can allow you to customize how information is displayed to operators in Cobalt Strike. I haven’t seen other public examples of Cobalt Strike visualizations, but check out my logvis.cna script for another example, and please let me know if you make anything with visualizations!

Even so, I’m obsessed with making our workflow even more efficient, and giving us the power to accomplish objectives even faster. One of the best ways to do this is with Aggressor Script, Cobalt Strike’s native scripting language. I should also add a caveat to this post: I am not a software developer. I do not have a formal background in developing, nor do I focus on efficiency or speed when I’m writing Aggressor.

Recently, I was able to attend the (excellent) SpecterOps Adversary Tactics: Red Team Operations course, which gave me the opportunity to talk to various red teamers, getting their perspectives on preferred tools, and how they use them. One of the things that surprised me somewhat was how few people make use of the power that Aggressor Script can provide. A sentiment that I heard a lot was that even red teams already paying for Cobalt Strike haven’t implemented much Aggressor Script into their workflows. I’d like to change that.

An Introduction to Aggressor

Aggressor Script is based on Sleep, a language created by Raphael Mudge (also the author of Cobalt Strike). Sleep is basically a Perl-like language which runs on the JVM. Before you start complaining, I believe that the power that Aggressor Script gives you in Cobalt Strike far outweighs any issues some might have with writing Perl, or dealing with Java.

This post will assume that you’re comfortable using Cobalt Strike, and that you know the various concepts behind operating with it. This will not be an introduction to Cobalt Strike.

With that out of the way, what does Aggressor Script actually look like? I find the syntax to be pretty simple, especially if you’re used to writing Perl, though many concepts will be perfectly understandable if you’ve written code before. Here’s a simple “Hello, world!” script, written in Aggressor:

Pretty easy. We create a new function named “hello” with sub hello {...} , and print text to the console with println("Hello, world!") . Statements in Aggressor must end with a semicolon, and functions must be defined before they’re called. Because the function doesn’t take any arguments, calling it with hello() will run the code.

Now that we have our first script, how do we actually use it? First, open up Cobalt Strike, and connect to your teamserver. Once your client is connected, go to View->Script Console, and type load /path/to/helloworld.cna (the full path is required). With that, you should see something like the following:

The cool thing about the script console is that it lets you test stuff out without having to write a full script, too. We can create the same function using the e command in the script console to evaluate Aggressor snippets. To do this, we can take the same code, and instead put it on a single line. In the script console, type e sub hello {println("Hello, world!");} , and hit enter. This won’t return anything, but we can then run our hello() function by running e hello() in the script console.

Just like that, we can test out bits of Aggressor. When I’m writing Aggressor scripts, I constantly use the script console to prototype small bits of code, and make sure they’re working before I pull them into a larger script. It’s a very useful tool to debug scripts, or to quickly run snippets that don’t necessarily constitute a full scripts.

Now that we’ve gone over how to run Aggressor scripts, let’s explore how to construct more useful scripts.

The Building Blocks

In order to build useful Aggressor scripts, we’ll need a bit more to go on than just printing stuff to the console. To do that, we need to learn about the various datatypes in Sleep, and how to work with them. The main datatypes in Sleep are strings, arrays, and hashes. Strings are denoted with $ , arrays with @ , and hashes with %.

If you’ve written code in another language, these datatypes should be familiar. Strings contain characters or strings of characters; arrays can hold multiple strings, arrays, or hashes (you can mix types in an array); and hashes contain multiple key-value pairs. What do these look like in practice?

This is a string with a few words:

$string = "This is a string.";

This is an array with three elements; a string, a number, and the $string variable that we defined before:

@array = @("The first element.", 2, $string);

This is a hash with three elements; key1 has a value of "value1", the value for key2 is the array we defined as @array, and key3 contains our $string variable.

%hash = %(key1 => "value1", key2 => @array, key3 => $string);

Using the x command in the script console, we can examine what these variables contain:

As you can see, Sleep has no issues combining datatypes, or dealing with nested arrays or hashes. In fact, it’s often very useful to nest arrays and hashes to create structures for storing things.

Before we start writing useful Aggressor scripts, I’ll go through how to access data stored in arrays and hashes. These two datatypes behave like they do in other languages. First, data contained in arrays can be accessed by its index, or its position in the array. Let’s define an array:

@array = @("First", "Second", "Third");

The index of the first element in an array is 0. To view this value, we can use @array[0] :

To access the other elements in the array, we can use their indices in the same way:

We can also use these in println statements to directly print the values. The dot operator will concatenate two values as a string:

Hashes work in a similar way, though instead of using the index of an item, you’ll use the key that the value is stored under. Here’s what that looks like:

The key values can be named whatever you’d like, and the value can be any type of data you want. Now that we’ve learned about the datatypes in Aggressor, how do we use this information to do useful things inside of Cobalt Strike?

Scripting Cobalt Strike

At the core of Cobalt Strike is the Cobalt Strike data model. This is where all of the information accessible to operators is stored, and it gives us a large amount of data to use for automating things in Cobalt Strike. The data collected in the data model includes information about the current beacons, credentials gathered from compromised systems, screenshots, downloaded files, and many other things.

For an example of how to use this data, let’s say we have a single beacon on a system. We can get an array of all the currently connected beacons by using the beacons() function, a built-in function in Aggressor. We can view this information with x beacons() in the script console.

If you try this, you’ll get a lot of information about each beacon. Beacons are arranged in an array, and each beacon is stored as a hash in this array. This is what that looks like with a single beacon in the data model:

So what can we do with the information in the data model? Let’s start with a fairly simple task that you might want to do: run a command on all of the beacons that you have connected to a teamserver.

Your First Aggressor Script

Let’s build this script out a piece at a time. First, we’ll start with creating a script to run a command on a single beacon. To do this, we’re going to use the bshell function, a built-in function of Cobalt Strike. Here’s the definition from the official Aggressor Script documentation:

bshell — Ask Beacon to run a command with cmd.exe

Arguments

$1 - the id for the beacon. This may be an array or a single ID.
$2 - the command and arguments to run

So how do we write a script to utilize this? We’re going to create an alias, or a command that you can type into any beacon console to execute custom Aggressor code. Here’s what that looks like:

If you haven’t written Aggressor before, you might be curious about the $1 and $2 variables we’re using in bshell. Whenever a function takes arguments in Aggressor, those arguments are passed to the function as numbered variables, named in the order in which they’re passed. For aliases, the first argument is the beacon ID that the alias is being used on, and any arguments after that are things you type after the alias when you run it from a beacon console. In this case, if you type shellcmd whoami into a beacon console, $2 will be "whoami". If you want to rename these variables to something that is easier to keep track of, you can assign them to other variables that you create. For more information on the functions available for use in Aggressor, and the arguments they take, check out this page.

To test this new alias out, save the script, and load it into Cobalt Strike (through the script console or through the script manager). You should now be able to type shellcmd <COMMAND> into a beacon console, and it will run the command for you! Note that you will also be able to tab-complete this alias.

Right now, this isn’t a very impressive script. It does the same thing as the built-in shell command, but you have to type more to use it. How can we make our script run a command on all beacons, not just a single beacon? First, let’s write a bit of Aggressor to run a set command on multiple beacons, and then we’ll modify it until we can run whatever command we want on multiple beacons.

To do this, we’ll first need to iterate through all the beacons connected to the teamserver. Cobalt Strike makes this pretty easy. Remember that beacons() function from earlier? We can use that to iterate through all beacons with a simple foreach loop. Here’s what that looks like:

Here, we’re using a foreach loop to iterate through every beacon returned by the beacons() function. Remember, beacon information returned by this function is stored as a hash for each beacon. From the hash, we’re selecting the id key with %beacon['id'], and printing this ID.

How can we modify this script to instead run a command on every beacon returned by beacons()? Let’s start by rewriting it to run whoami on every beacon.

Again, this is a pretty simple script, but we need to make it a little more useful. Instead of just running whoami on every beacon, let’s create a beacon alias that will run whatever command we want on every beacon. There are a couple ways to do this, but here’s a good start:

To run this script, type runall into a beacon console, followed by a command. Due to the way alias works in Aggressor, if you want to run a command with spaces in it, you’ll need to wrap it in double quotes. There are ways to get around this, but I wanted to keep this post as a basic introduction to Aggressor.

Hopefully this post has given you a better idea of how to write basic Aggressor scripts! This is just scratching the surface of what’s possible with Cobalt Strike. You can use events to automatically trigger actions. You can alter the Cobalt Strike GUI with additional menu items or even custom visualizations. Aggressor doesn’t have functionality you want? You can even use inline Java object expressions to incorporate functionality from any Java library!

It might not be the prettiest language, but Aggressor gives you a tremendous amount of power, and allows you to expand Cobalt Strike however you want to. If you’re a Cobalt Strike user and you’re not writing Aggressor, you’re missing out on one of the most powerful tools available to you. In future posts, I’ll go through more of what makes Aggressor so useful. Until then, I hope this has been a useful introduction.

Questions? Comments? Hit me up on Twitter, or come hang out in the BloodHound Slack, especially the #aggressor channel.