bettercap

github/bettercap

Fork 0

mirror of https://github.com/bettercap/bettercap.git synced 2024-11-03 04:00:07 -08:00

Table of Contents

Routes

GET /api/session
GET /api/session/ble

optional args

GET /api/session/env
GET /api/session/gateway
GET /api/session/interface
GET /api/session/lan

optional args

GET /api/session/options
GET /api/session/packets
GET /api/session/started-at
GET /api/session/wifi

optional args

POST /api/session
GET /api/events
DELETE /api/events

A RESTful API server to script and/or interact with the session, starts on HTTP and unauthenticated by default, can be switched to HTTPS and basic auth by using the proper parameters.

Commands

command	description
`api.rest on`	Start the REST API server.
`api.rest off`	Stop the REST API server.

Parameters

parameter	default	description
`api.rest.certificate`		API TLS certificate (will be auto generated if not existing), fill to enable HTTPS.
`api.rest.key`		API TLS key (will be auto generated if not existing), fill to enable HTTPS.
`api.rest.certificate.bits`	`4096`	Number of bits of the RSA private key of the generated HTTPS certificate.
`api.rest.certificate.commonname`	`bettercap`	Common Name field of the generated HTTPS certificate.
`api.rest.certificate.country`	`US`	Country field of the generated HTTPS certificate.
`api.rest.certificate.locality`		Locality field of the generated HTTPS certificate.
`api.rest.certificate.organization`	`bettercap devteam`	Organization field of the generated HTTPS certificate.
`api.rest.certificate.organizationalunit`	`https://bettercap.org/`	Organizational Unit field of the generated HTTPS certificate.
`api.rest.address`	`<interface address>`	Address to bind the API REST server to.
`api.rest.port`	`8081`	Port to bind the API REST server to.
`api.rest.username`		API HTTP basic auth username.
`api.rest.password`		API HTTP basic auth password.
`api.rest.websocket`	`false`	If true the `/api/events` route will be available as a websocket endpoint instead of HTTPS.
`api.rest.alloworigin`	`*`	Value of the Access-Control-Allow-Origin header of the API server.

Routes

Clients can authenticate using HTTP basic authentication, these are the available API routes.

GET /api/session

Get a JSON of the state of the current session, example response:

{
	"options": {
		"InterfaceName": "",
		"Caplet": "../caplets/netmon.cap",
		"Debug": false,
		"Silent": false,
		"NoHistory": false,
		"Commands": "",
		"CpuProfile": "",
		"MemProfile": ""
	},
	"interface": {
		"ipv4": "192.168.1.17",
		"ipv6": "-",
		"mac": "-",
		"hostname": "enx18fffffff",
		"alias": "",
		"vendor": "Dell",
		"first_seen": "2018-02-23T06:28:43.565053179+01:00",
		"last_seen": "2018-02-23T06:28:43.565053179+01:00",
		"meta": {
			"values": {}
		}
	},
	"gateway": {
		"ipv4": "192.168.1.1",
		"ipv6": "",
		"mac": "-",
		"hostname": "gateway.",
		"alias": "",
		"vendor": "Technicolor",
		"first_seen": "2018-02-23T06:28:43.649440315+01:00",
		"last_seen": "2018-02-23T06:28:43.649440315+01:00",
		"meta": {
			"values": {}
		}
	},
	"env": {
		"data": {
			"$": "{by}{fw}{cidr} {fb}\u003e {env.iface.ipv4} {reset} {bold}» {reset}",
			"api.rest.address": "\u003cinterface address\u003e",
			"api.rest.certificate": "~/.bcap-api.rest.certificate.pem",
			"api.rest.key": "~/.bcap-api.rest.key.pem",
			"api.rest.password": "bcap",
			"api.rest.port": "8083",
			"api.rest.username": "bcap",
			"arp.spoof.targets": "\u003centire subnet\u003e",
			"dhcp6.spoof.domains": "microsoft.com, goole.com, facebook.com, apple.com, twitter.com",
			"dns.spoof.address": "\u003cinterface address\u003e",
			"dns.spoof.all": "false",
			"dns.spoof.domains": "*",
			"events.stream.filter": "",
			"gateway.address": "192.168.1.1",
			"gateway.mac": "e0:b9:e5:17:22:e4",
			"http.port": "80",
			"http.proxy.address": "\u003cinterface address\u003e",
			"http.proxy.port": "8080",
			"http.proxy.script": "",
			"http.server.address": "\u003cinterface address\u003e",
			"http.server.path": ".",
			"http.server.port": "80",
			"https.port": "443",
			"https.proxy.address": "\u003cinterface address\u003e",
			"https.proxy.certificate": "~/.bettercap-ca.cert.pem",
			"https.proxy.key": "~/.bettercap-ca.key.pem",
			"https.proxy.port": "8083",
			"https.proxy.script": "",
			"iface.index": "6",
			"iface.ipv4": "192.168.1.17",
			"iface.ipv6": "-",
			"iface.mac": "-",
			"iface.name": "enx18fffffff",
			"log.debug": "false",
			"log.silent": "false",
			"mac.changer.address": "\u003crandom mac\u003e",
			"mac.changer.iface": "\u003cinterface name\u003e",
			"net.probe.throttle": "10",
			"net.sniff.filter": "not arp",
			"net.sniff.local": "false",
			"net.sniff.output": "",
			"net.sniff.regexp": "",
			"net.sniff.source": "",
			"net.sniff.verbose": "true",
			"ticker.commands": "clear; net.show",
			"ticker.period": "1",
			"wifi.recon.channel": ""
		}
	},
	"lan": {
		"hosts": [{
			"ipv4": "192.168.1.33",
			"ipv6": "",
			"mac": "-",
			"hostname": "",
			"alias": "nas",
			"vendor": "Noon Technology Co.",
			"first_seen": "2018-02-23T06:28:43.661773691+01:00",
			"last_seen": "2018-02-23T06:29:10.402653849+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.29",
			"ipv6": "",
			"mac": "-",
			"hostname": "osxvm",
			"alias": "",
			"vendor": "PCS Systemtechnik GmbH",
			"first_seen": "2018-02-23T06:28:43.661807871+01:00",
			"last_seen": "2018-02-23T06:28:43.661807871+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.22",
			"ipv6": "",
			"mac": "-",
			"hostname": "yamato",
			"alias": "",
			"vendor": "Apple",
			"first_seen": "2018-02-23T06:28:43.661869827+01:00",
			"last_seen": "2018-02-23T06:29:13.734671382+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.254",
			"ipv6": "",
			"mac": "-",
			"hostname": "",
			"alias": "gateway",
			"vendor": "",
			"first_seen": "2018-02-23T06:28:43.6617926+01:00",
			"last_seen": "2018-02-23T06:28:43.6617926+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.26",
			"ipv6": "",
			"mac": "-",
			"hostname": "winvm",
			"alias": "",
			"vendor": "PCS Systemtechnik GmbH",
			"first_seen": "2018-02-23T06:28:43.661830083+01:00",
			"last_seen": "2018-02-23T06:28:43.661830083+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.76",
			"ipv6": "",
			"mac": "-",
			"hostname": "pibak",
			"alias": "",
			"vendor": "Raspberry Pi Foundation",
			"first_seen": "2018-02-23T06:28:43.661833177+01:00",
			"last_seen": "2018-02-23T06:29:07.391079854+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.3",
			"ipv6": "",
			"mac": "00:17:88:29:97:bc",
			"hostname": "",
			"alias": "lights",
			"vendor": "Philips Lighting BV",
			"first_seen": "2018-02-23T06:28:43.661849075+01:00",
			"last_seen": "2018-02-23T06:29:14.306812147+01:00",
			"meta": {
				"values": {}
			}
		}, {
			"ipv4": "192.168.1.23",
			"ipv6": "",
			"mac": "-",
			"hostname": "pihole",
			"alias": "",
			"vendor": "Raspberry Pi Foundation",
			"first_seen": "2018-02-23T06:28:43.661854928+01:00",
			"last_seen": "2018-02-23T06:29:14.786637323+01:00",
			"meta": {
				"values": {}
			}
		}]
	},
	"wifi": {
		"aps": []
	},
	"packets": {
		"Stats": {
			"Sent": 1080,
			"Received": 213207,
			"PktReceived": 3549,
			"Errors": 0
		},
		"Protos": {
			"ARP": 2918,
			"DNS": 32,
			"Ethernet": 3549,
			"ICMPv4": 44,
			"IPv4": 631,
			"TCP": 394,
			"UDP": 193
		},
		"Traffic": {
			"192.168.1.0": {
				"Sent": 0,
				"Received": 215
			},
			"192.168.1.1": {
				"Sent": 0,
				"Received": 289
			},
			"192.168.1.13": {
				"Sent": 415,
				"Received": 289
			},
			"192.168.1.14": {
				"Sent": 0,
				"Received": 289
			},
			"192.168.1.17": {
				"Sent": 41356,
				"Received": 46456
			},
			"192.168.1.20": {
				"Sent": 2658,
				"Received": 2018
			},
			"192.168.1.22": {
				"Sent": 1426,
				"Received": 215
			},
			"192.168.1.23": {
				"Sent": 2220,
				"Received": 1747
			},
			"192.168.1.254": {
				"Sent": 120,
				"Received": 320
			},
			"192.168.1.255": {
				"Sent": 0,
				"Received": 1140
			},
			"192.168.1.26": {
				"Sent": 0,
				"Received": 215
			},
			"192.168.1.29": {
				"Sent": 0,
				"Received": 215
			},
			"192.168.1.3": {
				"Sent": 1438,
				"Received": 654
			},
			"192.168.1.33": {
				"Sent": 130,
				"Received": 355
			},
			"192.168.1.34": {
				"Sent": 2303,
				"Received": 2018
			},
			"192.168.1.43": {
				"Sent": 10756,
				"Received": 8721
			},
			"192.168.1.6": {
				"Sent": 497,
				"Received": 375
			},
			"192.168.1.76": {
				"Sent": 284,
				"Received": 172
			},
			"192.168.1.78": {
				"Sent": 284,
				"Received": 172
			}
		}
	},
	"started_at": "2018-02-23T06:28:43.650628576+01:00",
	"active": true
}

GET /api/session/ble

Get a JSON of the BLE devices in the current session, example response:

{
    "devices": [{
        "last_seen": "2018-02-23T06:28:43.650628576+01:00",
        "name": "Adafruit Bluefruit LE",
        "mac": "00:AA:BB:CC:DD:33",
        "vendor": "",
        "rssi": -68
    }, {
        "last_seen": "2018-02-23T06:28:43.650628576+01:00",
        "name": "",
        "mac": "-",
        "vendor": "",
        "rssi": -64
    }]
}

optional args

Mac address, eg. GET /api/session/ble/00:AA:BB:CC:DD:33 - return information of a single ble endpoint with the mac address of 00:AA:BB:CC:DD:33 (the Adafruit Bluefruit LE client from the above output).

GET /api/session/env

Get a JSON of the environment variables in the current session, example response:

{
    "data": {
        "$": "{by}{fw}{cidr} {fb}\u003e {env.iface.ipv4} {reset} {bold}» {reset}",
        "api.rest.address": "\u003cinterface address\u003e",
        "api.rest.certificate": "~/.bcap-api.rest.certificate.pem",
        "api.rest.key": "~/.bcap-api.rest.key.pem",
        "api.rest.password": "bcap",
        "api.rest.port": "8083",
        "api.rest.username": "bcap",
        "arp.spoof.targets": "\u003centire subnet\u003e",
        "dhcp6.spoof.domains": "microsoft.com, goole.com, facebook.com, apple.com, twitter.com",
        "dns.spoof.address": "\u003cinterface address\u003e",
        "dns.spoof.all": "false",
        "dns.spoof.domains": "*",
        "events.stream.filter": "",
        "gateway.address": "192.168.1.1",
        "gateway.mac": "e0:b9:e5:17:22:e4",
        "http.port": "80",
        "http.proxy.address": "\u003cinterface address\u003e",
        "http.proxy.port": "8080",
        "http.proxy.script": "",
        "http.server.address": "\u003cinterface address\u003e",
        "http.server.path": ".",
        "http.server.port": "80",
        "https.port": "443",
        "https.proxy.address": "\u003cinterface address\u003e",
        "https.proxy.certificate": "~/.bettercap-ca.cert.pem",
        "https.proxy.key": "~/.bettercap-ca.key.pem",
        "https.proxy.port": "8083",
        "https.proxy.script": "",
        "iface.index": "6",
        "iface.ipv4": "192.168.1.17",
        "iface.ipv6": "-",
        "iface.mac": "-",
        "iface.name": "enx18fffffff",
        "log.debug": "false",
        "log.silent": "false",
        "mac.changer.address": "\u003crandom mac\u003e",
        "mac.changer.iface": "\u003cinterface name\u003e",
        "net.probe.throttle": "10",
        "net.sniff.filter": "not arp",
        "net.sniff.local": "false",
        "net.sniff.output": "",
        "net.sniff.regexp": "",
        "net.sniff.source": "",
        "net.sniff.verbose": "true",
        "ticker.commands": "clear; net.show",
        "ticker.period": "1",
        "wifi.recon.channel": ""
    }
}

GET /api/session/gateway

Get a JSON of the interface gateway of the current session, example response:

{
    "ipv4": "192.168.1.1",
    "ipv6": "",
    "mac": "-",
    "hostname": "gateway.",
    "alias": "",
    "vendor": "Technicolor",
    "first_seen": "2018-02-23T06:28:43.649440315+01:00",
    "last_seen": "2018-02-23T06:28:43.649440315+01:00",
    "meta": {
        "values": {}
    }
}

GET /api/session/interface

Get a JSON of the main interface (wifi/lan) of the current session, example response:

{
    "ipv4": "192.168.1.17",
    "ipv6": "-",
    "mac": "-",
    "hostname": "enx18fffffff",
    "alias": "",
    "vendor": "Dell",
    "first_seen": "2018-02-23T06:28:43.565053179+01:00",
    "last_seen": "2018-02-23T06:28:43.565053179+01:00",
    "meta": {
        "values": {}
    }
}

GET /api/session/lan

Get a JSON of the lan devices in the current session, example response:

{
    "hosts": [{
        "ipv4": "192.168.1.33",
        "ipv6": "",
        "mac": "-",
        "hostname": "",
        "alias": "nas",
        "vendor": "Noon Technology Co.",
        "first_seen": "2018-02-23T06:28:43.661773691+01:00",
        "last_seen": "2018-02-23T06:29:10.402653849+01:00",
        "meta": {
            "values": {}
        }
    }, {
        "ipv4": "192.168.1.29",
        "ipv6": "",
        "mac": "-",
        "hostname": "osxvm",
        "alias": "",
        "vendor": "PCS Systemtechnik GmbH",
        "first_seen": "2018-02-23T06:28:43.661807871+01:00",
        "last_seen": "2018-02-23T06:28:43.661807871+01:00",
        "meta": {
            "values": {}
        }
    }, {
        "ipv4": "192.168.1.23",
        "ipv6": "",
        "mac": "00:AA:BB:CC:DD:11",
        "hostname": "pihole",
        "alias": "",
        "vendor": "Raspberry Pi Foundation",
        "first_seen": "2018-02-23T06:28:43.661854928+01:00",
        "last_seen": "2018-02-23T06:29:14.786637323+01:00",
        "meta": {
            "values": {}
        }
    }]
}

optional args

Mac address, eg. GET /api/session/lan/00:AA:BB:CC:DD:11 - return information of a single lan endpoint with the mac address of 00:AA:BB:CC:DD:11 (the pihole from the above output).

GET /api/session/options

Get a JSON of the options set for the current session, example response:

{
    "InterfaceName": "",
    "Caplet": "../caplets/netmon.cap",
    "Debug": false,
    "Silent": false,
    "NoHistory": false,
    "Commands": "",
    "CpuProfile": "",
    "MemProfile": ""
}

GET /api/session/packets

Get a JSON of the packet traffic for the current session, example response:

{
    "Stats": {
        "Sent": 1080,
        "Received": 213207,
        "PktReceived": 3549,
        "Errors": 0
    },
    "Protos": {
        "ARP": 2918,
        "DNS": 32,
        "Ethernet": 3549,
        "ICMPv4": 44,
        "IPv4": 631,
        "TCP": 394,
        "UDP": 193
    },
    "Traffic": {
        "192.168.1.0": {
            "Sent": 0,
            "Received": 215
        },
        "192.168.1.1": {
            "Sent": 0,
            "Received": 289
        },
        "192.168.1.34": {
            "Sent": 2303,
            "Received": 2018
        },
        "192.168.1.76": {
            "Sent": 284,
            "Received": 172
        },
        "192.168.1.78": {
            "Sent": 284,
            "Received": 172
        }
    }
}

GET /api/session/started-at

Get a JSON of the time the current session was started, example response:

"2018-02-23T06:28:43.650628576+01:00"

GET /api/session/wifi

Get a JSON of the wifi devices (clients and access points) in the current session, example response:

{
    "aps": [{
            "alias": "",
            "authentication": "PSK",
            "cipher": "TKIP",
            "clients": [],
            "encryption": "WPA2",
            "first_seen": "2018-02-23T06:28:43.650628576+01:00",
            "frequency": 2412,
            "hostname": "AP1",
            "ipv4": "0.0.0.0",
            "ipv6": "",
            "last_seen": "2018-02-23T06:28:43.650628576+01:00",
            "mac": "-",
            "meta": {
                "values": {}
            },
            "received": 0,
            "rssi": -20,
            "sent": 0,
            "vendor": ""
        },
        {
            "alias": "",
            "authentication": "PSK",
            "cipher": "TKIP",
            "clients": [],
            "encryption": "WPA2",
            "first_seen": "2018-02-23T06:28:43.650628576+01:00",
            "frequency": 2412,
            "hostname": "<hidden>",
            "ipv4": "0.0.0.0",
            "ipv6": "",
            "last_seen": "2018-02-23T06:28:43.650628576+01:00",
            "mac": "-",
            "meta": {
                "values": {}
            },
            "received": 0,
            "rssi": -16,
            "sent": 0,
            "vendor": ""
        },
        {
            "alias": "",
            "authentication": "PSK",
            "cipher": "TKIP",
            "clients": [],
            "encryption": "WPA2",
            "first_seen": "2018-02-23T06:28:43.650628576+01:00",
            "frequency": 2412,
            "hostname": "<hidden>",
            "ipv4": "0.0.0.0",
            "ipv6": "",
            "last_seen": "2018-02-23T06:28:43.650628576+01:00",
            "mac": "-",
            "meta": {
                "values": {}
            },
            "received": 0,
            "rssi": -21,
            "sent": 0,
            "vendor": ""
        },
        {
            "alias": "",
            "authentication": "PSK",
            "cipher": "CCMP",
            "clients": [{
                "alias": "",
                "authentication": "",
                "cipher": "",
                "encryption": "",
                "first_seen": "2018-02-23T06:28:43.650628576+01:00",
                "frequency": 2427,
                "hostname": "",
                "ipv4": "0.0.0.0",
                "ipv6": "",
                "last_seen": "2018-02-23T06:28:43.650628576+01:00",
                "mac": "00:AA:BB:CC:DD:22",
                "meta": {
                    "values": {}
                },
                "received": 0,
                "rssi": -31,
                "sent": 0,
                "vendor": ""
            }],
            "encryption": "WPA2",
            "first_seen": "2018-02-23T06:28:43.650628576+01:00",
            "frequency": 2427,
            "hostname": "AP2",
            "ipv4": "0.0.0.0",
            "ipv6": "",
            "last_seen": "2018-02-23T06:28:43.650628576+01:00",
            "mac": "-",
            "meta": {
                "values": {}
            },
            "received": 3100,
            "rssi": -31,
            "sent": 1040,
            "vendor": ""
        },
    ]
}

optional args

Mac address, eg. GET /api/session/wifi/00:AA:BB:CC:DD:22 - return information of a single wifi endpoint with the mac address of 00:AA:BB:CC:DD:22 (the connected client from the above output).

POST /api/session

Post a command to the interactive session, the JSON object being POSTed is expected to be:

{"cmd": "net.probe on"}

While the response will be:

{"success": true, "msg":""}

GET /api/events

Return a list of events ( the optional n GET parameter will limit the number ):

[{
	"tag": "sys.log",
	"time": "2018-02-22T16:57:39.449618552+01:00",
	"data": {
		"Level": 1,
		"Message": "Ticker running with period 1s."
	}
}, {
	"tag": "wifi.ap.new",
	"time": "2018-02-22T16:57:57.681938014+01:00",
	"data": {
		"ipv4": "0.0.0.0",
		"ipv6": "",
		"mac": "--",
		"hostname": "Some AP Name Here",
		"alias": "",
		"vendor": "",
		"first_seen": "2018-02-22T16:57:57.681877278+01:00",
		"last_seen": "2018-02-22T16:57:58.104218287+01:00",
		"frequency": 2427,
		"rssi": -56,
		"sent": 0,
		"received": 0,
		"encryption": "OPEN",
		"clients": []
	}
}]

DELETE /api/events

Will clear the events buffer.

Known Issues
Using with Docker
Compilation
Interactive Mode and Command Line Arguments
Changing the Prompt
Caplets

Modules

Core
- events.stream
- ticker
- api.rest
- update
- caplets
HID on 2.4Ghz (mousejacking)
- hid.recon / sniff / inject
Bluetooth Low Energy
- ble.recon / enum / write
802.11
- wifi.recon / assoc / deauth / ap
Ethernet and IP
- net.recon
- net.probe
- net.sniff / net.fuzz
- syn.scan
- wake on lan
- Spoofers
- Proxies
  - any.proxy
  - packet.proxy
  - tcp.proxy
    - modules
  - http.proxy
  - https.proxy
    - modules
Servers
- http.server
- https.server
Rogue Servers
- mysql.server
Utils
- mac.changer
- gps

bettercap.org | @bettercap | team