CLI

@riavzon/bot-detector ships a CLI with four subcommands. You can run them with npx without a global install, or directly as bot-detector after installing the package.

npx @riavzon/bot-detector <command>

pnpm dlx @riavzon/bot-detector <command>

yarn dlx @riavzon/bot-detector <command>

bunx @riavzon/bot-detector <command>

init

Runs the installation wizard. init verifies that mmdbctl is installed and installs it automatically if it is not found. It then prompts for a BGP.tools contact string, which is required to download BGP and ASN data from their API.

Once dependencies are confirmed, the command compiles all data sources in parallel and writes them to _data-sources/ inside the package directory:

• BGP and ASN data
• City and geography databases
• Tor node lists
• Proxy and anonymizer lists
• FireHOL threat levels 1-4 and the anonymous feed
• Verified crawler IP ranges (Googlebot, Bingbot, Apple, Meta, and others)
• User-Agent pattern database (useragent.mdb)

npx @riavzon/bot-detector init

pnpm dlx @riavzon/bot-detector init

yarn dlx @riavzon/bot-detector init

bunx @riavzon/bot-detector init

To skip the interactive prompt in CI or automated environments, pass your contact string directly with the --contact flag:

npx @riavzon/bot-detector init --contact="MyApp - [email protected]"

pnpm dlx @riavzon/bot-detector init --contact="MyApp - [email protected]"

yarn dlx @riavzon/bot-detector init --contact="MyApp - [email protected]"

bunx @riavzon/bot-detector init --contact="MyApp - [email protected]"

refresh

Redownloads and recompiles all data sources using the configuration cached from the last init run. This command requires init to have been run at least once.

npx @riavzon/bot-detector refresh

pnpm dlx @riavzon/bot-detector refresh

yarn dlx @riavzon/bot-detector refresh

bunx @riavzon/bot-detector refresh

Run refresh at least once every 24 hours to keep threat intelligence feeds current. Add it to a cron job or a scheduled CI pipeline:

# Example: daily cron at 3am
0 3 * * * cd /your/app && npx bot-detector refresh

generate

Reads your database and compiles two custom MMDB files from your visitor history:

• banned.mmdb: Built from all rows in the banned table with a non-null IP address.
• highRisk.mmdb: Built from rows in the visitors table where suspicious_activity_score is greater than or equal to generator.scoreThreshold (default 70).

These files are written to _data-sources/ and are loaded by the enableKnownBadIpsCheck checker on startup. Once generated, previously identified threats are checked synchronously in the cheap phase, making repeat offenders extremely fast to reject.

Flags

The generate command accepts the following flags:

Example usage:

npx @riavzon/bot-detector generate --db mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb --mmdbctl=/usr/local/bin/mmdbctl --score=80 --delete

pnpm dlx @riavzon/bot-detector generate --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb --mmdbctl=/usr/local/bin/mmdbctl --score=80 --delete

yarn dlx @riavzon/bot-detector generate --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb --mmdbctl=/usr/local/bin/mmdbctl --score=80 --delete

bunx @riavzon/bot-detector generate --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb --mmdbctl=/usr/local/bin/mmdbctl --score=80 --delete

generate requires mmdbctl. When the binary cannot be found at the path configured in generator.mmdbctlPath, the command prompts you to install it and exits with instructions.

load-schema

Creates the required database tables (visitors and banned) in the database configured by defineConfiguration. Run this once after your first configuration before starting the server.

Flags

The load-schema command accepts these flags to select and configure the database connection used to create tables:

Example usage:

npx @riavzon/bot-detector load-schema --db mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb

pnpm dlx @riavzon/bot-detector load-schema --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb

yarn dlx @riavzon/bot-detector load-schema --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb

bunx @riavzon/bot-detector load-schema --db=mysql-pool --db-host=localhost --db-user=root --db-password=secret --db-name=botdb

load-schema reads the active defineConfiguration call to determine the database driver and connection. Your application entry point must export or call defineConfiguration before this command can resolve the connection.