https.proxy

A transparent HTTPS proxy with JavaScript scripting support.

When used with a spoofer, all HTTPS traffic redirects to this proxy. Port redirections are handled automatically.

Commands

`https.proxy on`

Start the HTTPS proxy server.

`https.proxy off`

Stop the HTTPS proxy server.

Parameters

Parameter	Default	Description
`https.port`	`443`	HTTPS port to redirect when the proxy is activated.
`https.proxy.address`	`<interface address>`	Address to bind the HTTPS proxy to.
`https.proxy.blacklist`		Comma separated list of hostnames to skip while proxying (wildcard expressions can be used).
`https.proxy.certificate`	`~/.bettercap-ca.cert.pem`	HTTPS proxy certification authority TLS certificate file.
`https.proxy.certificate.bits`	`4096`	Number of bits of the RSA private key of the generated HTTPS certificate authority.
`https.proxy.certificate.commonname`	`Go Daddy Secure Certificate Authority - G2`	Common Name field of the generated HTTPS certificate authority.
`https.proxy.certificate.country`	`US`	Country field of the generated HTTPS certificate authority.
`https.proxy.certificate.locality`	`Scottsdale`	Locality field of the generated HTTPS certificate authority.
`https.proxy.certificate.organization`	`GoDaddy.com, Inc.`	Organization field of the generated HTTPS certificate authority.
`https.proxy.certificate.organizationalunit`	`https://certs.godaddy.com/repository/`	Organizational Unit field of the generated HTTPS certificate authority.
`https.proxy.injectjs`		URL, path or javascript code to inject into every HTML page.
`https.proxy.key`	`~/.bettercap-ca.key.pem`	HTTPS proxy certification authority TLS key file.
`https.proxy.port`	`8083`	Port to bind the HTTPS proxy to.
`https.proxy.script`		Path of a proxy module script.
`https.proxy.sslstrip`	`false`	Enable or disable SSL stripping.
`https.proxy.whitelist`		Comma separated list of hostnames to proxy if the blacklist is used (wildcard expressions can be used).

Modules

The http.proxy and https.proxy modules can be scripted using JavaScript files. These files must declare at least one of the following functions:

// called when the script is loaded
function onLoad() {
  // ...
}

// called when the module is stopped
function onExit() {
  // ...
}

// called when the request is received by the proxy
// and before it is sent to the real server.
function onRequest(req, res) {
  // ...
}

// called when the request is sent to the real server
// and a response is received
function onResponse(req, res) {
  // ...
}

// called every time an unknown session command is typed,
// proxy modules can optionally handle custom commands this way:
function onCommand(cmd) {
  if (cmd == "test") {
    /*
     * Custom session command logic here.
     */

    // tell the session we handled this command
    return true;
  }
}

Modules can change the req request and res response objects.

For instance, the web-override.cap caplet uses the onRequest function. It overrides every request before execution with a fake response:

function onRequest(req, res) {
  res.Status = 200;
  res.ContentType = "text/html";
  res.Body = readFile("caplets/www/index.html");
  headers = res.Headers.split("\r\n");
  for (var i = 0; i < headers.length; i++) {
    header_name = headers[i].replace(/:.*/, "");
    res.RemoveHeader(header_name);
  }
  res.SetHeader("Connection", "close");
}

The login-man-abuse.cap caplet uses the onResponse handler. It injects a JavaScript file into every HTML response:

function onResponse(req, res) {
  if (res.ContentType.indexOf("text/html") == 0) {
    var body = res.ReadBody();
    if (body.indexOf("</head>") != -1) {
      res.Body = body.replace(
        "</head>",
        '<script type="text/javascript">' +
          "\n" +
          AbuserJavascript +
          "</script>" +
          "</head>"
      );
    }
  }
}

Builtin Functions

The JS interpreter is limited to ES5. This means no for/of, typed arrays, or classes.

Modules can use the following builtin functions:

Function	Description
`readDir("/path/")`	Return the contents of a directory as a string array.
`readFile("/path/to/file")`	Return the contents of a file as a string.
`writeFile("/path/to/file", "hello world")`	Write the string `hello world` to a file, returns `null` or an error message.
`log_debug("message")`	Log a message in the interactive session (its level will be `DEBUG`).
`log_info("message")`	Log a message in the interactive session (its level will be `INFO`).
`log_warn("message")`	Log a message in the interactive session (its level will be `WARNING`).
`log_error("message")`	Log a message in the interactive session (its level will be `ERROR`).
`log_fatal("message")`	Log a message in the interactive session (its level will be `FATAL`).
`log("message")`	Shortcut for `log_info("message")`.
`btoa("message")`	Encode a message to base64.
`atob("bWVzc2FnZQ==")`	Decode a message from base64.
`gzipCompress("plaintext data")`	Compress a string using gzip encoding.
`gzipDecompress(")9�\+�I��+I�(QHI,I��")`	Decompress a gzip encoded string.
`env("iface.ipv4")`	Read a variable.
`env("foo", "bar")`	Set a variable.
`run("command")`	Execute a shell command and return the output as a string.
`fileExists("/path/to/file")`	Return `true` if the file exists, otherwise `false`.
`loadJSON("/path/to/file.json")`	Load and parse a JSON file, returns a JS object.
`saveJSON("/path/to/file.json", object)`	Serialize and save a JS object as JSON to the specified file.
`saveToFile("/path.txt", "data")`	Save raw string data to a file.
`onEvent("event.tag", callback)`	Register a JS callback for the given session event tag.
`removeEventListener("event.tag")`	Remove a previously registered event listener for the given tag.
`addSessionEvent("tag", data)`	Trigger a session event from within the script with a custom tag and payload.