Express
Install
1
npm i @botbye/express
1
yarn add @botbye/express
Requires express >= 4 as a peer dependency.
Configuration
Call phishing.init once at application startup, before serving any catcher requests. Anti-phishing is identified by its own clientKey (available in your Phishing Project in the Dashboard), not the server key used by evaluate.
1
2
3
4
5
6
import { phishing } from "@botbye/express";
phishing.init({
// clientKey from your Phishing Project in the Dashboard
clientKey: "00000000-0000-0000-0000-000000000000",
});
| Option | Type | Required | Description |
|---|---|---|---|
| clientKey | string | Yes | clientKey from your Phishing Project in the Dashboard |
| url | string | No | Override BotBye API endpoint (default: https://verify.botbye.com) |
| logger.level | string | No | Log level: error, warn, info, debug, log (default: info) |
| logger.logger | TLogger | No | Custom logger implementing { error, warn, info, debug, log } |
| timeouts.fetchCatcher | number | No | Timeout in milliseconds for each fetchCatcher call |
Usage
Anti-phishing needs two routes on your own origin, each proxied through fetchCatcher:
SVG route — serves the SVG catcher. This is the URL your client code passes to getCatcher({ url }).
PNG route — serves the PNG that the SVG references (via innerPngUrl).
The paths are arbitrary — name the routes however you like. Pass the raw request as request and the format. For the SVG, innerPngUrl must be the absolute URL of your PNG route — the browser loads that PNG directly from your origin.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { phishing } from "@botbye/express";
// Absolute URL of your PNG endpoint — the SVG catcher references it through innerPngUrl.
const PNG_CATCHER_URL = "https://your-site.example/botbye-catcher.png";
// SVG catcher (this URL goes into the catcher element on your pages)
app.get("/botbye-catcher.svg", async (req, res) => {
const catcher = await phishing.fetchCatcher({
request: req,
format: "svg",
innerPngUrl: PNG_CATCHER_URL,
});
res.status(catcher.status).set(catcher.headers).send(Buffer.from(catcher.body));
});
// Companion PNG the SVG above references via innerPngUrl
app.get("/botbye-catcher.png", async (req, res) => {
const catcher = await phishing.fetchCatcher({ request: req, format: "png" });
res.status(catcher.status).set(catcher.headers).send(Buffer.from(catcher.body));
});
We recommend embedding the SVG catcher: it is designed to keep tracking even when a phishing site copies all of your assets to its own infrastructure (the PNG route exists because the SVG catcher relies on it).
Multiple instances
phishing is a ready default instance. Use phishingFactory() to create isolated instances for multiple projects.
1
2
3
4
import { phishingFactory } from "@botbye/express";
const phishing = phishingFactory();
phishing.init({ clientKey: "00000000-0000-0000-0000-000000000000" });