Running Headless Operator

A tutorial on running an API-first command and control center

Operator, by default, is a desktop application.

You download and install a client that runs on your desktop. It has a GUI with pretty buttons. It has click actions.

The goal of Operator is to make advanced security easier and more accessible than ever. But what if you want to use it without using it? That’s why we designed the Headless version.

Headless Operator is an API-only version of the exact same application, designed to run on any Linux server.

This guide will walk through how to use it.

Step 1

Download Headless Operator from Prelude’s website. Put this on any Linux desktop or server.

Step 2

Run it. You can do this either authenticated or unauthenticated (for the latter, run it without the email argument):

./headless --accountEmail me@prelude.org

This will fire off an email containing a token to prove you own the account. Enter this token into the command-line prompt to continue.

Did you know… if you use Operator’s desktop client, you can generate a token/secret pair which can be used to automate the login process on Headless, bypassing the email validation step. Check the Settings section for details.

Once your token is accepted, you’ll see an output like this:

What’s important:

• The workspace location is where your data is stored on disk. This includes all your TTPs, chains and more. Starting in version 1.6, it also includes an audit.log file which tracks all activity that occurs in the app.

• If you want the app to auto upgrade on restart (if applicable) run the app from the specified directory.

• Host: this is the public location of your Headless instance.

• Email: this is who you logged in as.

• Token: this is the API key for your app.

Step 3

Validate the app is running correctly.

Important: check out the full API documentation for all options.

I’ll start by saving my token as a temporary environment variable in my shell:

export TOKEN=”88bc48e5-ac58-45df-99f6-e572da844ad7”

Next, I’ll run a simple ping request:

curl -X GET -sk -H "Authorization: $TOKEN" "https://localhost:8888/v1/ping"

Note I included a pipe to json_pp, which converts the response to JSON data on a MacOS. As in, it makes it a little prettier to look at the output.

Perfect. This returns the version of the application running. Add the “extended” parameter to include more information, including any connected agents:

I can see a single connected agent, privateducky. Operator ships with an embedded agent (named after the hostname) which acts as a local/demo agent. You can connect additional remote agents, such as our flagship open-source Pneuma agent.

Step 4

Now it’s time to run an operation.

Let’s start by seeing what chains are available to me:

curl -X GET -sk -H "Authorization: $TOKEN" "https://localhost:8888/v1/chain"

Perfect. Time to run one. I’d suggest you start with File Hunter, which is a simple multi-platform chain that locates files modified in the last 24 hours and copies them to a staging directory. Read about this chain here.

I’ll run File Hunter against my privateducky agent with this command. The endpoint accepts a list of TTPs to run, which allows me to mix-and-match those from different chains if I want - but in this case I’ll stick to File Hunter’s TTPs:

curl -X POST -sk -H "Authorization: $TOKEN" -H "Content-Type: application/json" "https://localhost:8888/v1/schedule" -d '{
    "agents": ["privateducky"],
    "ttps": ["90c2efaa-8205-480d-8bb6-61d90dbaf81b", "4e97e699-93d7-4040-b5a3-2e906a58199", "300157e5-f4ad-4569-b533-9d1fa0e74d74", "6469befa-748a-4b9c-a96d-f191fde47d89"], 
    "ordered": false}'

The response should be the status code of my request, OK if successful.

So what happened? Let’s check the results from my agent:

Lots of data! As I scan through this, I should look for the links list. This list contains the results that the agent produced.

Did you know.. you can log into your desktop Operator and connect to your Headless version in order to view all this data in a more human way. Do this from the Connect section → Manual redirector page. If you have an Enterprise account, you can additionally, and automatically, publish these results to your SIEM.

---

And that’s it! Now you can deploy agents throughout your network (connecting them to your Headless app), run chains against them and track results from either Operator or your SIEM.

Our goal is to automate the execution of TTPs so you can spend more time on the important question: can you detect the behaviors that are now occurring in your environment?