Configuration

The Vulnerability Scanner system is highly configurable using environment variables. This allows you to deploy the application in different environments (development, testing, production) without changing the code.

You can set these variables in two ways: 1. Environment Variables: Export them in your shell or define them in your container orchestration (e.g., Kubernetes, Docker Compose). 2. .env File: Create a file named .env in the project root. The application will automatically read this file.

Administrators with the application.configuration.manage permission can also manage supported application settings from Manage > Configuration > Application Settings. Environment variables remain the deployment defaults; GUI changes are stored as database overrides. Settings that affect middleware, database connectivity, or other startup-time behavior are marked as requiring a backend restart before they fully apply. The backend restart action is guarded by the system.restart permission; Security Admin receives this permission by default.

Note

For Docker Compose deployments, we recommend creating a .env file alongside your docker-compose.yml. The provided docker-compose.yml is configured to read from this file.

Core Configuration

These settings control the basic behavior and security of the application.

  • PROJECT_NAME: The name of the project (default: “Vulnerability Scanner”).

  • API_V1_STR: The API version string (default: “/api/v1”).

  • DEBUG: Set to true to enable debug mode (default: false).

  • SECRET_KEY: A secure random string used for signing JWT tokens and cryptographic operations. Change this in production! (default: “insecure-secret-key-replace-me”).

  • ACCESS_TOKEN_EXPIRE_MINUTES: Minutes before an access token expires (default: 30).

  • REFRESH_TOKEN_EXPIRE_DAYS: Days before an issued refresh token expires (default: 7). Interactive logins receive both an access token and a refresh token.

  • REPORT_RETENTION_HOURS: Hours a report magic link remains usable after the latest access (default: 24).

  • ALGORITHM: Encryption algorithm for tokens (default: “HS256”).

  • BACKEND_CORS_ORIGINS: A JSON-formatted list of origins allowed to access the API (e.g., ["http://localhost:3000", "https://my-app.com"]).

Database Configuration

Settings for connecting to the MariaDB/MySQL database.

  • DB_HOST: Hostname of the database server (default: “db”).

  • DB_PORT: Database port (default: 3306).

  • DB_USER: Database username (default: “user” in dev, via secrets in prod).

  • DB_PASSWORD: Database password.

  • DB_NAME: Database name (default: “vulnerabilityhub”).

  • DATABASE_URL: (Optional) Full connection string. Defaults to mysql+pymysql://USER:PASS@HOST:PORT/NAME.

Email Configuration

Settings for sending email notifications.

  • SMTP_SERVER: SMTP server hostname (default: “mailhog”).

  • SMTP_PORT: SMTP server port (default: 1025).

  • SMTP_USER: SMTP username (optional).

  • SMTP_PASSWORD: SMTP password (optional).

  • SMTP_SENDER: The email address showing in the “From” field (default: “VulnerabilityHub <noreply@localhost>”).

  • SMTP_USE_TLS: Set to true to use implicit TLS (typically port 465). (default: false).

  • SMTP_USE_STARTTLS: Set to true to use explicit STARTTLS (typically port 587). (default: false).

  • SMTP_TIMEOUT_SECONDS: Maximum seconds to wait for SMTP connect, TLS, authentication, and send operations (default: 10.0).

Email Automation

These settings control when report notification emails are sent automatically. They can also be managed from Manage > Configuration > Application Settings.

  • AUTO_EMAIL_ENABLED: Master switch for automated report emails (default: true).

  • AUTO_EMAIL_ON_REPORT_MATCH: Send report emails when uploaded XML and visual reports are matched (default: true).

  • AUTO_EMAIL_ON_CONTACT_CREATE_ASSIGNMENT: Send report emails when a newly created contact is assigned existing IPs or CIDRs (default: true).

  • AUTO_EMAIL_ON_CONTACT_UPDATE_ASSIGNMENT: Send report emails when an existing contact receives newly assigned IPs or CIDRs (default: true).

  • AUTO_EMAIL_ON_RESPONSIBILITY_TRANSFER: Send report emails when IP or CIDR responsibility is transferred to another contact (default: true).

  • AUTO_EMAIL_ON_DISPUTE_ASSIGNMENT: Send report emails when a dispute resolution completes a report responsibility assignment (default: true).

Rate Limiting

Control the rate limiting behavior for API endpoints.

  • RATE_LIMIT_STORAGE_URL: Connection string/type for rate limit storage. Defaults to memory:// (in-memory, per-process). Use redis://redis:6379 for distributed limiting.

  • REDIS_URL: (Deprecated/Legacy) Alternative way to specify Redis URL if used.

Other Settings

  • MAPPING_CONFIG_PATH: Path to the XML field mapping JSON used by the Greenbone parser (default: /app/config/mapping.json).

  • MAX_FILE_SIZE: Maximum accepted upload size in megabytes (default: 10).

  • INSTITUTION_FALLBACK_NAME: Name used when a finding IP cannot be matched to any configured institution mapping (default: Unknown Institution).

  • KEV_CATALOG_PATH: Optional path to a mounted Known Exploited Vulnerabilities catalog in JSON, CSV, or plain-text format. CVE IDs found in this file receive the Quick Wins KEV score bonus. If unset, the backend fetches the configured KEV catalog URL.

  • KEV_CATALOG_URL: URL for the CISA Known Exploited Vulnerabilities JSON feed (default: https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json).

  • KEV_FETCH_ENABLED: Whether the backend should fetch KEV_CATALOG_URL when no local catalog path is configured (default: True).

  • KEV_CATALOG_TIMEOUT_SECONDS: HTTP timeout for fetching the KEV catalog URL (default: 3.0).

  • KEV_CVE_LIST: Optional comma-separated CVE IDs for a small local KEV override or test list.

Optional LDAP Connection Defaults

LDAP connections can be created by administrators in the GUI. Once enabled, administrators can sync directory users into the local user list, and LDAP users authenticate against the configured directory on login. Local users keep using local passwords. LDAP-synced users are non-admins by default.

The following environment variables provide LDAP defaults for deployments that wire LDAP configuration through settings. The backend no longer creates or updates the database LDAP connection during application startup; use the GUI or an explicit maintenance/migration task to persist LDAP connection records.

  • LDAP_ENABLED: Whether the settings-backed LDAP connection should be active (default: False).

  • LDAP_CONNECTION_NAME: Display name for the connection (default: LDAP Directory).

  • LDAP_SERVER_URL: LDAP server URL, for example ldap://ldap.example.org:389 or ldaps://ldap.example.org:636.

  • LDAP_BIND_DN: Optional bind DN for read-only directory access.

  • LDAP_BIND_PASSWORD: Optional bind password. Can also be provided through a Docker secret named ldap_bind_password.

  • LDAP_USER_BASE_DN: Base DN used to find users, for example ou=users,dc=example,dc=org.

  • LDAP_USER_FILTER: LDAP filter used for user entries (default: (objectClass=person)).

  • LDAP_USERNAME_ATTRIBUTE: Attribute mapped to usernames (default: uid).

  • LDAP_EMAIL_ATTRIBUTE: Attribute mapped to email addresses (default: mail).

  • LDAP_FULL_NAME_ATTRIBUTE: Attribute mapped to full names (default: cn).

  • LDAP_USE_TLS: Whether STARTTLS should be requested for non-LDAPS connections (default: False).

Development LDAP Server

The Docker Compose dev profile includes a local LDAP server for development and demo data:

docker compose --profile dev up -d

By default, the backend can reach it at ldap://ldap:389 and the host can reach it at ldap://localhost:1389. The default bind DN is cn=admin,dc=example,dc=org with password admin.

These settings are optional and only affect the development LDAP container:

  • LDAP_PUBLISHED_PORT: Host port mapped to LDAP port 389 (default: 1389).

  • LDAP_DEV_ADMIN_PASSWORD: Development LDAP admin password (default: admin).

  • LDAP_DEV_CONFIG_PASSWORD: Development LDAP config password (default: config).

Demo LDAP Seeding

When generate_demo_data.py runs and the development LDAP server is reachable, it creates demo LDAP users and stores an enabled Demo LDAP Directory connection. The LDAP user password defaults to DemoPass123456!.

The following optional variables override the demo LDAP seeding defaults:

  • DEMO_LDAP_URL: LDAP server URL used by the demo script (default: ldap://ldap:389).

  • DEMO_LDAP_APP_URL: LDAP server URL saved in the app connection (default: DEMO_LDAP_URL).

  • DEMO_LDAP_BIND_DN: Bind DN used for seeding (default: cn=admin,dc=example,dc=org).

  • DEMO_LDAP_BIND_PASSWORD: Bind password used for seeding (default: LDAP_DEV_ADMIN_PASSWORD or admin).

  • DEMO_LDAP_BASE_DN: Directory base DN (default: dc=example,dc=org).

  • DEMO_LDAP_USER_BASE_DN: User container DN (default: ou=users,dc=example,dc=org).

  • DEMO_LDAP_USER_PASSWORD: Password assigned to seeded LDAP users (default: DemoPass123456!).