OpenResty
Installation
1
sudo luarocks install botbye-openresty
Configuration
Configure the botbye_phishing module in your nginx http block. On construction the client reports the server-side integration via a best-effort initRequest() handshake — it needs a botbye_state shared dict (the once-per-instance guard) and a call from init_worker_by_lua_block.
Getting clientKey
clientKey is the public, browser-safe identifier of your phishing project. It travels in the asset URL path, so it is safe to expose — no secret token and no Base64 encoding are required.
Find it on the Get Started screen of your phishing project in the BotBye dashboard.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
http {
# ...
lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
lua_ssl_verify_depth 3;
lua_shared_dict botbye_state 1m;
init_by_lua_block {
require("botbye_phishing").setConf({
endpoint = "https://verify.botbye.com",
client_key = "<public-client-key>",
})
}
init_worker_by_lua_block {
require("botbye_phishing").initRequest()
}
}
Usage
Expose a single location block that proxies phishing pixel requests.
When you use an SVG image, your application must also expose an endpoint on the client origin that handles requests to /{imageId}.png, where imageId is the value that arrives in the forwarded pixel query as image_id.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
location /api/phishing/image {
content_by_lua_block {
local phishing = require("botbye_phishing")
local origin = ngx.req.get_headers()["Origin"]
-- forward all incoming query params verbatim
local args, err_args = ngx.req.get_uri_args()
if not args then
args = {}
end
local res, err = phishing.fetchImage(origin, args)
if not res then
ngx.status = 502
ngx.say(err or "upstream error")
return ngx.exit(502)
end
ngx.status = res.status or 200
ngx.header["Content-Type"] = (res.headers and res.headers["Content-Type"]) or "image/png"
if res.body ~= nil then
ngx.print(res.body)
end
}
}
Settings
Configuration parameters for phishing integration:
| Setting | Description | Required | Default Value |
|---|---|---|---|
| endpoint | Host of the phishing API | no | https://verify.botbye.com |
| clientKey | Public client-key of your phishing project | yes | - |