Bait Box Beta

Overview

Bait Box runs as a single binary with an SQLite database and serves two HTTPS listeners:

• The registry, which Phishing Club reads from.
• The admin UI and API, where operators manage namespaces, packages, read tokens and other operators.

Content is organised in namespaces. Each namespace holds packages, and each package has one or more versions. Phishing Club authenticates with a read token that is scoped to the namespaces it may read.

The source and releases are on GitHub.

Install

For systemd distributions on AMD64 or ARM64, run the following on the server:

curl -fsSL https://raw.githubusercontent.com/phishingclub/baitbox/main/install.sh | bash

The script downloads the latest release for the server architecture, verifies the Ed25519 signature of the binary with OpenSSL 3, and then runs the binary with -install as root (through sudo when you are not root). It needs curl, tar and openssl.

To pass a different mode to the binary, add it after bash -s --:

curl -fsSL https://raw.githubusercontent.com/phishingclub/baitbox/main/install.sh | bash -s -- --install-non-interactive

The script accepts --install (default), --install-non-interactive and --reinstall.

Interactive install

The interactive installer asks for the settings below. F1 shows the basic fields and F2 the advanced ones. Leave a field empty to keep the value in brackets.

Installer questions

Question	Description	Default
Domain	Domain name of the registry, without https:// or a port. Also used for the admin UI unless Admin host is set.	None
Registry port	Port of the registry that Phishing Club connects to.	443
Admin port	Port of the admin UI and API. Must differ from the registry port. A host:port value such as 127.0.0.1:8443 binds one address only.	8443
Use auto TLS	true gets certificates from Let's Encrypt. false serves a self signed certificate, for running behind a TLS terminating front.	true
ACME email	Email for Let's Encrypt notices. Required when auto TLS is true.	None
Admin host (advanced)	Separate domain name for the admin UI. Passkeys are bound to it, so changing it later breaks them.	Same as domain
Admin allowed IPs (advanced)	Comma separated IPs or CIDR ranges allowed to use the admin. Empty allows all.	None
Trusted proxies (advanced)	Comma separated IPs or CIDR ranges of a front that forwards requests.	None
Trusted IP header (advanced)	Header that carries the real client IP, such as CF-Connecting-IP. Requires trusted proxies.	None

The installer creates a baitbox user and group, installs the binary and config to /opt/baitbox, stores data in /opt/baitbox/data, and sets up and starts the baitbox systemd service. It then prints the admin URL, the registry URL and the one time operator credentials.

Important: Copy the credentials. They are printed once and not saved to a file.

Non interactive install

-install-non-interactive installs the service with a config template and starts it. Edit /opt/baitbox/config.json to set the hosts and ACME email, then restart:

systemctl restart baitbox

The service prints the one time credentials to its log on first start:

journalctl -u baitbox

Reinstall and uninstall

-reinstall asks the questions again, starting from the installed config, and overwrites the binary, the systemd unit and the config file after you type YES. It keeps the database, operators, packages, blobs and certificates.

Warning: -uninstall removes the service, the config, all data (database, blobs and certificates) and the baitbox user and group. It cannot be undone.

Docker

Images for AMD64 and ARM64 are published as ghcr.io/phishingclub/baitbox. The repository has a production Docker Compose example:

services:
  baitbox:
    image: ghcr.io/phishingclub/baitbox:latest
    container_name: baitbox
    restart: unless-stopped
    volumes:
      - ./config.json:/app/config.prod.json:ro
      - baitbox-data:/app/data
    ports:
      - "443:443" # Registry
      - "8443:8443" # Admin interface

volumes:
  baitbox-data:

Create config.json from config.prod.json in the repository and fill in the hosts and ACME email. That file has tls_auto set to false; set it to true for Let's Encrypt certificates. The /app/data volume holds the database, the package blobs and the certificates. The container runs as a non root user.

The one time credentials are in the container log:

docker compose logs baitbox

First login

Open the admin URL and sign in with the one time credentials. The seeded account is named admin. On the first login you must set a new password of at least 12 characters and choose a username other than admin.

An operator created by another operator must also change the password at first login.

The forced change applies when env is prod, which is the value in the installer and the shipped configs.

Ports and listeners

Listeners

Listener	Config key	Default	Serves
Registry	registry.address	:443	The read API that Phishing Club installs from.
Admin	administration.address	:8443	The admin UI and API.

The two listeners must use different ports. Both serve HTTPS only.

Restrict the admin listener with a firewall or with ip_security.admin_allowed. Binding the admin to loopback, such as 127.0.0.1:8443, and using an SSH tunnel also works, but the browser must still open the admin by its administration.tls_host name, or passkeys and the certificate do not match.

Admin access can be turned off from Settings › Registry or with -disable-admin. The registry keeps serving. Only -enable-admin on the server, or setting administration.disabled to false and restarting, turns it back on.

Important: With tls_auto enabled, Let's Encrypt validates on port 443. Keep the registry on 443, or forward port 443 to it.

Configuration

The configuration is a JSON file passed with -config. The installer writes it to /opt/baitbox/config.json. Restart the service after a change.

{
  "env": "prod",
  "tls_auto": true,
  "acme": {
    "email": "[email protected]"
  },
  "administration": {
    "address": ":8443",
    "tls_host": "admin.example.com"
  },
  "registry": {
    "address": ":443",
    "tls_host": "registry.example.com",
    "max_download": 16777216,
    "max_file": 16777216,
    "max_unpacked": 33554432,
    "max_files": 2000,
    "public": false
  },
  "database": {
    "path": "/opt/baitbox/data/baitbox.sqlite3"
  },
  "blobs": {
    "path": "/opt/baitbox/data/blobs"
  },
  "ip_security": {
    "admin_allowed": [],
    "trusted_proxies": [],
    "trusted_ip_header": ""
  }
}

Configuration keys

Configuration Key	Default Value	Description
env	Required	prod or dev. Any other value is refused. Use prod.
tls_auto	false (installer: true)	true gets certificates for both listeners from Let's Encrypt. false serves a self signed certificate, for running behind a front that terminates the public certificate, such as Cloudflare.
acme.email	Empty	Email address for the Let's Encrypt account.
administration.address	127.0.0.1:8443 when the key is missing (installer and shipped configs: :8443)	Listen address of the admin UI and API.
administration.tls_host	Empty	Host name of the admin UI. Passkeys are bound to it, so changing it breaks registered passkeys.
administration.disabled	false	Turns the admin listener off. Set by -disable-admin or from the admin UI.
registry.address	:443	Listen address of the registry.
registry.tls_host	Empty	Host name of the registry. The registry URL shown in the admin UI is built from it and the registry port.
registry.max_download	16777216 (16 MiB)	Maximum size of one compressed package archive.
registry.max_file	16777216 (16 MiB)	Maximum size of one file inside a package archive.
registry.max_unpacked	33554432 (32 MiB)	Maximum total size of all unpacked files in a package archive. Raised to max_file when that is larger and this key is unset.
registry.max_files	2000	Maximum number of files in a package archive.
registry.public	false	Allows anonymous reads of public namespaces. See Private and public.
database.path	Installer: /opt/baitbox/data/baitbox.sqlite3	Path of the SQLite database. Must not contain ?, & or #. Certificates are stored in certs/acme next to it.
blobs.path	Installer: /opt/baitbox/data/blobs	Directory that holds the package content.
ip_security.admin_allowed	Empty array	IPs or CIDR ranges allowed to reach the admin listener. Empty allows all. An entry that is not an IP or CIDR range is refused at startup.
ip_security.trusted_proxies	Empty array	IPs or CIDR ranges of a front that forwards requests. Applies to both listeners.
ip_security.trusted_ip_header	Empty	Header that carries the real client IP, such as CF-Connecting-IP. Read only from trusted_proxies and ignored when that list is empty.

Note: When Bait Box runs behind a front, set trusted_proxies and trusted_ip_header. The admin allowlist, the login throttle and the allowed IP ranges of read tokens all use the resolved client IP.

Private and public

The registry is private by default. With registry.public set to false, every registry request needs a valid read token, and every namespace is private. Turning registry.public off makes every public namespace private.

With registry.public set to true, a namespace can be marked public. Anyone can read public namespaces without a token. Private namespaces still need a read token scoped to them.

A package in a public namespace may only depend on packages in public namespaces. A visibility change that would break this is refused.

Turning a public registry private

Set registry.public to false and restart. On startup every public namespace becomes private, and from then on every registry request needs a read token.

• Phishing Club connections without a read token can no longer browse, install or update. Add a read token to each connection. Packages already installed in Phishing Club keep working.
• Existing read tokens keep their access. Namespaces that were public are only readable with a token scoped to them, or with *.

Setting registry.public back to true keeps every namespace private. Mark each namespace public again on the Namespaces page.

Important: Bait Box has no request rate limits on the registry. Only login attempts are throttled. Put a CDN or reverse proxy in front of a public registry.

Namespaces

A namespace groups packages. A package address is namespace/name. Create namespaces on the Namespaces page with a name, description and color.

Rename

Renaming a namespace changes the address of every package in it. Bait Box shows the impact before you confirm: how many packages change address, which packages in other namespaces depend on it, and how many read tokens are scoped to it.

• Read tokens scoped to the old name are updated to the new name.
• Bundles inside the renamed namespace keep pointing at their packages.
• The old addresses stop working. There is no redirect, so Phishing Club installs from the old address must install again from the new one, and packages in other namespaces that depend on it must be published again.

Delete

A namespace can only be deleted when it holds no packages. Its name is removed from the scope of every read token.

Packages and versions

A package is one piece of Phishing Club content: an email, page, asset, attachment, script, proxy, allow or deny list, remote browser script, report template, domain, SMTP configuration, webhook, API sender, OAuth provider or campaign template. A bundle package groups other packages.

Packages are written, previewed and published in the admin editors. Unpublished work can be saved as a draft. Content can hold @@VAR@@ variables that are filled in when the package is installed.

Versions

• Versions use semver, such as 1.2.0.
• A published version is immutable. Publishing the same version again is refused.
• latest is the highest semver version that is not yanked.
• Yanking a version removes it from latest. Yanking can be undone.
• A version can be deleted, except the only version of a package.

Details and previews

Title, description, tags and preview images are edited on the package page and apply to every version.

Move and delete

A package can be moved to another namespace and renamed. Bait Box warns when packages depend on it, since their references break.

Deleting a package removes all its versions. Deleting a package that other packages depend on is refused, and the refusal names those packages.

Asset settings

Files shipped by asset, page, email, domain and report template packages can carry the same settings as assets in Phishing Club. In the editor, click Settings on a file to set:

• Name and Description.
• Content type. Empty uses the type from the file extension.
• Response headers, up to 50 per file.
• Allow / deny lists. Choose where the lists come from. With From namespace, search and pick allow or deny list packages from the same namespace. With Chosen at install, the installer picks one of their own lists, allow or deny. This adds the variable ALLOW_DENY_LIST.

Lists are their own packages. Publish each list as an allow or deny list package, then pick it on a file. The package then depends on the list package, so Phishing Club installs the list with it. Removing the last file that uses a list removes the dependency. A file uses either allow lists or deny lists, not both. A file uses either namespace lists or one list chosen at install, not both.

Rules checked on publish

• Headers that control the response itself, such as Content-Length, can not be set. Use the content type field instead of a Content-Type header.
• A file with lists can only have a Cache-Control header that contains no-store or private, and not public or s-maxage. This stops a cache from handing a filtered file to blocked visitors.
• Each file path can only have settings once per package.
• Only an allow or deny list package can declare lists. Any other package with an allowDenies block is refused.
• Every list a file uses must be declared by the latest version of an allow or deny list package in the same namespace that the package depends on, or be an installer pick.
• A package other than a bundle can only depend on allow or deny list packages in its own namespace. A list package can not have dependencies, and one list package can not declare the same list name twice.
• An installer pick is a required variable with the pick kind allowDeny. A file can have at most one, and no other lists with it. A plain variable with the same name is refused.
• A new version of a list package that removes or renames a list, or changes its kind in either direction, is refused while the latest version of a package that depends on it uses the list.
• Yanking or deleting a list package version is allowed, but shows the packages whose lists would stop resolving.
• A package that uses list packages can not be moved to another namespace. Move or recreate the list packages first. Renaming a namespace is fine.

In Phishing Club

• Package files are installed as shared assets, so they can only use global lists. The list packages a package depends on are installed with it, or reused when already installed. A list name that does not match one of those lists or an existing global list stops the install.
• An installed list package is reused at its installed version. If a file the install or update writes uses its lists and the package needs a newer version, it is refused and asks you to update the list package first. A list package nothing written uses never blocks it. A list whose kind does not match what the package expects also stops the install.
• A list from a list package is found through the list package, not by its name. You can rename the list in Phishing Club and packages that use it keep working. If the list was deleted, the install or update is refused until you reinstall the list package.
• For an installer pick, the install form offers your global allow and deny lists.
• Installing a bundle also installs the list packages its packages depend on, and updates and uninstalls them the same way as the packages of the bundle.
• A list package installed with a package is updated on its own row in Installed, like the packages of a bundle. Uninstalling the package removes it, unless another install uses it or you installed it directly.
• Uninstalling any package that another installed package depends on is refused and names that package. Uninstall or update that package first.
• A list is never deleted while a file outside the uninstall still uses it. It is kept and stops being tracked by the package, so a filtered file never becomes public.
• Two packages that ship the same file must ship it with the same content and settings, otherwise the second install is refused.
• A filtered file is only served once its lists are in place, so it is never public during an install or update.
• Name and description are set when the file is installed. Updates change the content type, headers and lists.
• If you changed the settings of an installed file and the new version changes them too, the update asks you to keep yours or overwrite them. Overwrite replaces the headers and lists, including any you added.
• An update that would remove lists from a file, for example when the file loses its last allow list, asks first, even when you did not edit it.
• The uninstall preview lists files that stay but lose a list, and warns when a file becomes reachable by everyone.

Read tokens

Phishing Club reads from the registry with a read token. Tokens are read only. Create them on the Tokens page, then enter the token when you connect the Bait Box in Phishing Club.

Token settings

Setting	Description
Name	Label for the token.
Namespaces	Comma separated namespaces the token may read, or * for all. Each named namespace must exist.
Allowed IPs	Comma separated IPs or CIDR ranges the token may be used from. Blank allows any. Can be changed after creation.
Expires	No expiry, 30 days, 90 days or 1 year.

Important: The token is shown once. Only its hash is stored, so copy it when it is created.

A token can be revoked or deleted. A revoked, expired or deleted token is refused, as is a token used from an IP outside its allowed ranges. Removing an operator revokes the tokens that operator created.

Operators and sign in

Operators are the admin accounts. Manage them under Settings › Users. The last operator cannot be deleted. Deleting an operator also removes its passkeys and sessions and revokes its read tokens.

Two factor and passkeys

Under Settings › Account, an operator can turn on TOTP two factor and register passkeys. After a correct password, an operator with a second factor must give a TOTP code or use a passkey before a session starts.

Step up

Sensitive actions require a fresh proof of identity in the current session: adding or removing a passkey, turning on two factor, creating or deleting an operator, and creating or editing a read token. The proof is a TOTP code or a passkey, or the password when the operator has no second factor.

Sessions

Changing the password, turning two factor on or off, or adding or removing a passkey ends every other session of that operator. The session that made the change stays signed in.

Login throttling

Wrong passwords, TOTP codes and passkey attempts are slowed down per account and client address, with a wait that grows after repeated failures.

Account recovery

On the server, as root:

# new password for the first operator, or the one named with -username
/opt/baitbox/baitbox -reset-admin
/opt/baitbox/baitbox -reset-admin -username alice

# turn off two factor, delete every passkey and sign out alice; the password is kept
/opt/baitbox/baitbox -reset-mfa alice

Both use the installed config when -config is not given, and both are written to the audit log.

Export and import

Under Settings › Registry, Export registry downloads the registry content as one .tar.gz file, and Import registry loads a file exported from Bait Box. Use it to move content to another registry or copy it between registries. A single package can be exported from its package page, with the latest version or all versions, and imported from the Packages page.

Export contents

Included	Not included
Namespaces, packages, every version, preview images, package details and tag colors	Operators, passkeys, read tokens and drafts

An import keeps what already exists. An existing package is updated only when the file carries a newer version of it, and its local details are not overwritten. The import summary lists what was added, updated, skipped and refused.

Note: An export is not a full backup of the server. To back up everything, stop the service and copy the data directory (/opt/baitbox/data, or the /app/data volume in Docker) and the config file.

Updates

Releases are signed with Ed25519. Bait Box checks GitHub for a new release a minute after it starts and then every 6 hours. Settings › Updates shows the running and the newest version, and Check now asks right away.

In app update

When Bait Box runs as the installed systemd service, Update now downloads the release, verifies its signature, installs it and restarts the service.

Update on the server

Otherwise run the update on the server:

sudo /opt/baitbox/baitbox -update

-update downloads the latest release, verifies the signature against the keys built into the binary, refuses a downgrade, swaps the binary and restarts the service.

In Docker, pull the new image and recreate the container.

Command line

Run without other flags, Bait Box serves with the config given by -config. Flags that install, update or uninstall must run as root.

Command line flags

Flag	Description
-config PATH	Path to the config file. Default config.json. -reset-admin, -reset-mfa, -disable-admin and -enable-admin use the installed config when it is not given.
-version	Print the version and exit.
-install	Install as a systemd service, asking for the settings interactively.
-install-non-interactive	Install as a systemd service with a config template to edit afterwards.
-reinstall	Overwrite the installed binary, unit and config after confirmation. Asks the questions again and keeps all data.
-config-only	Ask for the settings interactively and write them to -config without installing.
-update	Update the installed binary to the latest signed release and restart the service.
-uninstall	Uninstall the service, config, data, user and group, with a confirmation prompt.
-uninstall-non-interactive	Uninstall without a confirmation prompt.
-reset-admin	Reset the password of the first operator, or of -username, sign it out and print the new credentials.
-username NAME	With -reset-admin, the operator to reset.
-reset-mfa NAME	Turn off two factor, delete every passkey and sign out the named operator. The password is kept.
-disable-admin	Turn off the admin UI and API by setting administration.disabled, and restart the installed service.
-enable-admin	Turn the admin UI and API back on by clearing administration.disabled, and restart the installed service.

Audit log

Sensitive operations, such as logins, operator and token changes, package and namespace changes, exports and updates, are written as one JSON line each to the service log.

journalctl -u baitbox

-reset-admin and -reset-mfa run outside the service, so they also send their audit line to syslog under the baitbox identifier:

journalctl -t baitbox

In Docker, the audit lines are in docker compose logs baitbox.

Using Bait Box in Phishing Club

In Phishing Club, Bait Box in the top menu is where you connect one or more Bait Boxes, browse their packages, install them with your own values, and update or uninstall them later. Only users with global access can use it, and installed content is created as global content.

The page has two views:

• Browse shows the packages of the selected Bait Box as cards, with install and update actions.
• Installed lists every installed package from every Bait Box, including those whose Bait Box was removed or does not answer.

Each install remembers which items it created. Phishing Club uses this to update them in place, to spot items you edited, and to remove them again on uninstall. Items installed from a package show Installed from with the package address in their editor.

Connect a Bait Box

Click Add Bait Box and fill in the connection. Phishing Club contacts the Bait Box before it saves the connection and refuses one it cannot reach or whose token is refused.

Bait Box connection

Field	Description
Name	Label shown in the Bait Box selector.
URL	The registry URL of the Bait Box, such as https://baitbox.example.com. It must use https.
Token	A read token from the Bait Box. Leave it empty only to read public namespaces.
Allow self signed TLS	Accepts a self signed certificate on the Bait Box.

Edit and remove

The menu next to the selected Bait Box has Edit and Remove. When you edit, a blank Token keeps the stored token, and Remove token clears it. The connection is tested again before the change is saved.

Remove deletes the connection only. Content installed from it stays and is listed as Bait Box removed in the Installed view.

Connection status

The selected Bait Box shows its status next to the selector:

Connection status

Status	Meaning
Connected	The Bait Box answered and accepted the token.
Token refused	The token is missing, revoked or expired, not allowed from this IP, or not scoped to the namespace. Edit the Bait Box to enter a valid token.
Not reachable	The Bait Box did not answer. The reason is shown below, such as timed out, connection refused, host not found or TLS certificate not trusted.
Not compatible	The Bait Box requires a newer Phishing Club version. Update Phishing Club to use it.

Browse packages

Pick a Bait Box in the selector to list its packages. Only packages the token can read are listed. Each card shows the type, version, tags and the first preview image.

Toolbar

Control	Description
Search	Matches the package name, title, description and type.
Filter	All, Installed, Available (not installed), and Updates, which is offered only while packages from this Bait Box have an update.
Type	Shows one package type, with the number of packages of each type.
Update all	Shown with the number of updates when any installed package has one.

Package details

Click a card to open the package. The tabs depend on what the package holds:

• Details shows the type, version, address, status, description, the variables the package asks for and, for a bundle, the packages it references.
• A tab named after the package type holds its content files. HTML files switch between Source and Preview, which renders the page with its bundled images.
• Attachments, Assets and Manifest list those files.

Click a preview image to enlarge it. The arrow keys move between images.

Install a package

Click Install on a card or in the package details. The Install package dialog shows the package, the packages a bundle contains, and the values to fill in. Click Install to create the content.

A package from the same Bait Box can only be installed once. Update or uninstall the existing install instead.

Bundles

A bundle installs the packages it references at their latest version and links them to the bundle. A referenced package that is already installed from the same Bait Box is reused. The Installed view lists the referenced packages as Dependency.

A bundle that references a package which no longer exists on the Bait Box, or which the token cannot read, cannot be installed. The dialog names the packages.

When an install is refused

An install checks everything before it creates anything. If a write still fails, the items it created are removed again. Common reasons:

Install refusals

Reason	What to do
An item with the same name already exists	Rename or remove your item, then try again.
A global asset you added uses a path the package ships	Rename or delete the existing asset, then try again.
Another installed package already installed an asset at the same path with different content	Uninstall that package, then try again. Identical files are shared.
An attachment file name is already used	Rename or delete the existing attachment, then try again.
The package uses a domain that belongs to a company	A package can only use a global domain.
A referenced item does not exist	Install the package that provides it first.

Report templates

Phishing Club keeps one report template per kind, simulation and training. A package that ships one replaces your current template of that kind, so the Overwrite report template dialog asks you to confirm first. Uninstalling the package restores the content the template had before the install.

Values and variables

Package content can hold @@VAR@@ variables, such as a domain or a secret. The install dialog lists them under Values. A value is required unless it is marked optional, and an optional value left empty uses the package default. An enum variable offers a fixed list of options.

Pick variables

Some variables ask you to choose one of your own existing items instead of typing a value. The field lists your items of that kind:

• SMTP configuration
• Domain
• Email
• Page
• Proxy
• API sender
• OAuth provider

A pick has no default. When you have no item of the kind yet, the dialog shows Install is blocked with a Create one in a new tab link. Create the item, then open the install again.

Shared and per package values

In a bundle, a variable with the same name in several packages is filled once and used by all of them. The bundle author can turn this off, and then each package gets its own value.

Values that only the referenced packages declare are asked for in the Required values dialog after you click Install. When each package keeps its own value, the field shows the address of the package it belongs to. Click Continue to finish the install.

OAuth providers and API senders

An OAuth provider installed from a package starts unauthorized. Open it under OAuth Providers and authorize it before campaigns use it.

An API sender in a package can use an OAuth provider by name only when that provider was installed from the same namespace on the same Bait Box. To use any other provider, choose it through the package's OAuth provider variable in the install dialog. A package without such a variable is refused, and its author must add one.

When an update adds an API sender that uses an OAuth provider variable, the Required values dialog asks you to choose the provider again.

A package whose OAuth provider is still used by an API sender from outside the package cannot be uninstalled. Remove the API sender or point it at another provider first.

Update packages

An update is offered when the latest version on the Bait Box differs from the installed one. A latest version lower than the installed one is not offered.

Click Update on the card, in the package details or in the Installed view. The Update package dialog lists what is updated. The update reuses the values you gave at install and asks only for values the new version adds.

Local edits

The update compares each item with what was installed:

• An item only the new version changed is updated in place. Campaigns that use it keep working.
• An item only you edited keeps your edit.
• An item you edited and the new version also changed waits for your choice in the conflict dialog. See Update choices.
• An item you deleted is created again.

Items the new version drops

An item the new version no longer ships is removed. It is kept instead when you edited it, or when something outside the package still uses it, such as a campaign or another installed package. A kept item that is still used becomes your own and is left alone on uninstall.

A bundle version that no longer references a package removes that package, unless another installed bundle still uses it or you installed it directly. When you edited its content or use it outside the bundle, the update asks you to Keep installed or Uninstall it.

Update all

Update all updates every installed package that has an update, from every Bait Box, and keeps every local edit. It skips these packages and lists them in a message, so you update them one by one:

• Packages with a change that needs your choice, such as a new OAuth binding.
• Packages that need values.
• Packages that would overwrite your report template.

Update notes

After an update, messages list what happened beyond the normal update:

• Kept your local edits names the edited items that were kept.
• Kept your edited copies that the new version removed names edited items the new version dropped.
• Kept the current settings of names items you chose to keep for an OAuth related change.
• Update notes lists items that were removed, kept because they are still used, or could not be removed. An item that could not be removed stays tracked, and the next update tries again.

Update choices

When an update has items that need a choice, it changes nothing and opens a dialog with one choice per item. The dialog is Resolve local edits for edited items, Choose how to update when an item has a reason, and Resolve dropped packages for packages a bundle no longer references. Each choice starts on Keep mine, or Keep installed for a dropped package.

Choices

Choice	Result
Keep mine	Keeps the item as it is now. The package keeps using it instead of the new version.
Overwrite	Applies the new version to the item in place.
Keep both	Renames the current item to name (local), installs the new version fresh and points the package and its templates at the new copy. Not offered for domains, OAuth providers and report templates.

OAuth related reasons

Some changes wait for your choice even when you did not edit the item. The dialog shows the reason under the item:

• The new version would switch an API sender to another OAuth provider.
• The new version changes the request URL, headers or body of an API sender that uses an OAuth provider, since those requests can carry the OAuth token.
• The new version changes the authorization URL or token URL of an OAuth provider that is authorized.
• The new version points an API sender at an OAuth provider that was not installed from the same namespace on the same Bait Box. Only Keep mine is offered.

Uninstall

Choose Uninstall from the card menu, the package details or the Installed view. The Uninstall package dialog first checks what the uninstall affects and shows:

• The items that are deleted, counted by type.
• Active campaigns that use the content and will be closed.
• Active campaigns that already have a close time. They keep running without the content until then and will not work correctly.
• Active campaigns that keep running but lose a filter, deny page, webhook or script. A campaign that loses its IP filter is highlighted.
• Assets you added on a domain the uninstall deletes. They are deleted with the domain.
• Items you edited after the install. Your changes are lost.
• For a bundle, or a package that depends on list packages, the referenced packages that are removed with it.
• Lists that stay because files outside the uninstall still use them.

When another installed package depends on the package, the dialog names it and the uninstall is refused. Uninstall or update that package first.

What stays

• Assets that already existed, and assets another installed package uses.
• Identifiers.
• Packages a bundle referenced that another installed bundle still uses or that you installed directly.
• A report template the package overwrote gets back its earlier content. Edits made to it since the install are lost.
• A list that a file outside the uninstall still uses. It stops being tracked by the package and becomes your own list, so a filtered file never becomes public.

When some items cannot be removed, the uninstall reports them and they stay installed, so you can uninstall again.

Installed view

The Installed view lists every install with its package, version, Bait Box, how it was installed (Direct or Dependency) and its status. The row menu has Update when an update is available and always has Uninstall.

Install status

Status	Meaning
Update to vX	A newer version is on the Bait Box.
Up to date	The installed version is the latest.
Token refused	The Bait Box refused the token. Edit the Bait Box to enter a valid token.
Bait Box removed	The connection to the Bait Box this package came from was removed.
Unknown	The Bait Box did not answer or no longer lists the package.

Every install can be uninstalled, whatever its status, unless another installed package depends on it.