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
- On its first start, Vulnsy generates an instance ID for the installation.
- 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.
- You install the token, in
.envor 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:
- 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.
- Enter the instance ID of the installation (see Find Your Instance ID).
- 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
- Sign in as an administrator.
- Open Admin > License (or, while the installation is locked, the License page at
/license). - 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-hereThen recreate the app container so that it reads the new value:
docker compose up -d appKeep 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:roIn .env, point VULNSY_LICENSE_FILE at the path inside the container:
VULNSY_LICENSE_FILE=/run/secrets/vulnsy-licenseThe 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.
| Status | When | What users see | What to do |
|---|---|---|---|
| Valid | More than 30 days before the expiry date | Vulnsy works normally | Nothing |
| Expiring soon | In the 30 days before the expiry date | Vulnsy works, with a banner that shows the expiry date | Ask Vulnsy for a renewal and install it |
| Grace period | For 7 days after the expiry date | Vulnsy works, with a persistent banner that shows when access ends | Install a renewal before the grace period ends |
| Expired | After the grace period | Every page redirects to the License page | Install a renewal |
| Invalid | The token is damaged, was issued for another installation, or the server clock has moved back | Every page redirects to the License page, which shows the reason | See Troubleshooting |
| Not installed | No license has been installed | Only the sign-in page and the License page are available | Install a license |
What the License Controls
| Item | Effect |
|---|---|
| Expiry date | When the license stops being valid, followed by the 7-day grace period |
| User limit | The 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. |
| Modules | Which of Client Portal, QA, Scoping and Disclosure are available |
| Features | Whether 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.