Vulnsy Docs
Self-hosted

Licensing

How the self-hosted license works. Find your instance ID, get a license on the self-service page, install and renew it, read the license status, and see what the license controls.

A self-hosted installation runs on a license: a token, signed by Vulnsy, that is issued for one installation. The license sets the expiry date, the user limit, and the modules and features available. It takes the place of the subscription and billing pages on vulnsy.com.

How It Works

  1. On its first start, Vulnsy generates an instance ID for the installation.
  2. You request a license for that instance ID on www.vulnsy.com/offline-licensing, and a license token bound to it is emailed to you.
  3. You install the token, in .env or under Admin > License.

Admin > License (/admin/billing) is the license hub: status and expiry, seats in use against the licensed limit, which modules and features the license includes, the paste form, and the renewal link with your instance ID prefilled. The seat count is taken from this server's own database; nothing is sent to Vulnsy.

Without a license, or once it has expired or become invalid, only the sign-in page and the License page (/license) are available. That page shows the same status card and paste form, so an administrator can recover a locked installation.

Find Your Instance ID

The instance ID is shown under Admin > License and on the License page (https://reports.example.com/license), which also works while the installation is locked. Both have a copy button next to it.

The instance ID also appears in the app's log:

docker compose logs app | grep "instance id"

The instance ID is stored in the vulnsy_control database. It stays the same when you restart, when you upgrade, and when you restore a backup of the databases, even on a different server. A new, empty installation gets a new instance ID.

Get a License

Licenses are issued on the self-service page, www.vulnsy.com/offline-licensing:

  1. Enter your company name, your name and your work email. If you have a self-hosted agreement, use the email address on it. Personal email providers such as Gmail and Outlook are not accepted.
  2. Enter the instance ID of the installation (see Find Your Instance ID).
  3. Submit the request.

If the email address is on an active self-hosted agreement, the license token is emailed to that address within a few minutes. Licenses are only ever sent to the address on the agreement. Otherwise, the request is recorded and the Vulnsy team gets back to you within one business day.

The page shows the same confirmation in both cases. If no email arrives, check your spam folder, then contact luke@vulnsy.com.

Use the same page to renew a license and to license an installation on a new server. An agreement covers a set number of installations: a request for an instance ID beyond that number goes to the Vulnsy team instead of being issued straight away.

Install a License

  1. Sign in as an administrator.
  2. Open Admin > License (or, while the installation is locked, the License page at /license).
  3. Paste the token and install it.

The license applies straight away, without a restart.

Add the token to .env:

VULNSY_LICENSE=paste-your-license-token-here

Then recreate the app container so that it reads the new value:

docker compose up -d app

Keep the token in a file and mount the file into the app container. Save the token as vulnsy-license.txt in the install directory, then create docker-compose.override.yml next to docker-compose.yml:

services:
  app:
    volumes:
      - ./vulnsy-license.txt:/run/secrets/vulnsy-license:ro

In .env, point VULNSY_LICENSE_FILE at the path inside the container:

VULNSY_LICENSE_FILE=/run/secrets/vulnsy-license

The app runs as UID 1001, which must be able to read the file. Apply the change with docker compose up -d app.

A token installed on the License page takes precedence over VULNSY_LICENSE and VULNSY_LICENSE_FILE. Once you have installed a license on the page, install renewals there as well.

License Status

Admin > License and the License page show the status of the installed license.

StatusWhenWhat users seeWhat to do
ValidMore than 30 days before the expiry dateVulnsy works normallyNothing
Expiring soonIn the 30 days before the expiry dateVulnsy works, with a banner that shows the expiry dateAsk Vulnsy for a renewal and install it
Grace periodFor 7 days after the expiry dateVulnsy works, with a persistent banner that shows when access endsInstall a renewal before the grace period ends
ExpiredAfter the grace periodEvery page redirects to the License pageInstall a renewal
InvalidThe token is damaged, was issued for another installation, or the server clock has moved backEvery page redirects to the License page, which shows the reasonSee Troubleshooting
Not installedNo license has been installedOnly the sign-in page and the License page are availableInstall a license

What the License Controls

ItemEffect
Expiry dateWhen the license stops being valid, followed by the 7-day grace period
User limitThe maximum number of active users. Users with the Admin, Consultant, Viewer and Third Party roles count towards it; Client users, who only have portal access, do not. Vulnsy refuses to add a user once the limit is reached.
ModulesWhich of Client Portal, QA, Scoping and Disclosure are available
FeaturesWhether the REST API, the AI assistant and SSO are available

An administrator can switch off a module that the license includes, under Admin > Organization > Modules, but cannot switch on a module that the license does not include; such modules are shown as Not in your license. Admin > License lists every module and feature as included, not included, or switched off by you. Features the license excludes are disabled where they would be configured: the SSO switches under Users & Access > Security, and API key creation under Profile > API. For more users, modules or features, contact Vulnsy to change your agreement, then request a new license.

Renew a License

A renewal is a new token for the same instance ID. Once your agreement is renewed, request it on the licensing page, as in Get a License: the new token carries the new expiry date. Install it the same way as the first one. Install it before the grace period ends, and users keep working without interruption.

Offline Operation

Vulnsy verifies the license's signature on your server. It never contacts Vulnsy to check, renew or report on the license, so licensing needs no internet connection. The only step that involves Vulnsy is sending you a new token.

Moving to a New Server

How you move decides whether the license still applies:

  • Restore a backup on the new server. The instance ID is stored in the database, so it moves with your data and the existing license keeps working. See Backup & Restore.
  • Install from scratch on the new server. The new installation has a new instance ID. Request a license for it on the licensing page. If that takes you over the number of installations your agreement covers, the request goes to the Vulnsy team, who get back to you within one business day.

Server Clock

If the server clock is set back by more than a day, the license becomes invalid until the clock is corrected. Keep the clock synchronized with NTP.

When a License Expires

Expiry never deletes data. After the grace period, users are redirected to the License page, and everything stays in your databases and file store. As soon as a valid license is installed, access resumes. The health and version endpoints keep responding throughout, so monitoring is not affected.

On this page