Skip to content

application-settings.rst

Latest commit

 

History

History
512 lines (354 loc) · 15.9 KB

application-settings.rst

File metadata and controls

512 lines (354 loc) · 15.9 KB

Application Settings

Settings file

DejaCode is configured with environment variables stored in a .env file.

The .env file is created at the root of the DejaCode codebase during its installation. You can configure your preferences using the following settings in the .env file.

Note

DejaCode is based on the Django web framework and its settings system. The list of settings available in Django is documented at Django Settings.

Tip

Settings specific to DejaCode are all prefixed with DEJACODE_.

Restarting the services is required following any changes to .env:

docker compose restart web worker

DATABASE

The database can be configured using the following settings:

DEJACODE_DB_HOST=localhost
DEJACODE_DB_NAME=dejacode_db
DEJACODE_DB_USER=user
DEJACODE_DB_PASSWORD=password
DEJACODE_DB_PORT=5432

ALLOWED_HOSTS

A list of strings representing the host/domain names that this application can serve.

To enable this setting you need to have a proper host and domain name configured for your DejaCode installation.

This setting is a security measure to prevent an attacker from poisoning caches and password reset emails with links to malicious hosts by submitting requests with a fake HTTP Host header, which is possible even under many seemingly-safe webserver configurations.

Values in this list can be fully qualified names (e.g. 'www.example.com'), in which case they will be matched against the request's Host header exactly (case-insensitive, not including port).

A value beginning with a period can be used as a subdomain wildcard: '.example.com' will match example.com, www.example.com, and any other subdomain of example.com. A value of '*' will match anything; in this case you are responsible to provide your own validation of the Host header.

ALLOWED_HOSTS=*

EMAIL

This settings enables the email notification feature in DejaCode. If set, the provided username, password and email/SMTP server details are used to send email notifications to your DejaCode users.

# The SMTP user used for authentication on your SMTP server.
EMAIL_HOST_USER=''
# Password to use for the SMTP server defined in EMAIL_HOST.
# Can be empty on non-secured, test servers.
EMAIL_HOST_PASSWORD=''
# The SMTP server host to use to send emails.
EMAIL_HOST=''
# Port to use for the SMTP server defined in EMAIL_HOST.
EMAIL_PORT=587
# Default "FROM" email address to use when sending email notifications
DEFAULT_FROM_EMAIL=''
# Whether to use a TLS (secure) connection when talking to the SMTP server
# You should always use a secure connection.
EMAIL_USE_TLS=True

SITE_URL

The base URL of this DejaCode installation. This setting is required to build URLs that reference objects in the application. It is also used when including URLs in email notifications.

SITE_URL=http://www.yourdomain.com/

DEJACODE_SUPPORT_EMAIL

An optional email address to reach the support team of this instance. When defined, it will be displayed in various views and emails related to account registration, activation, and password reset.

DEJACODE_SUPPORT_EMAIL=support@nexb.com

ANONYMOUS_USERS_DATASPACE

One Dataspace can be designed as accessible to anyone in a view-only mode. Set this with an existing Dataspace name to enable view-only access to anonymous, no logged-in users.

ANONYMOUS_USERS_DATASPACE=DATASPACE_NAME

REFERENCE_DATASPACE

An administrative User in the Reference Dataspace can see and copy data from every Dataspace; otherwise, the User can only see data from his/her assigned Dataspace and copy from the Reference Dataspace. An administrative User in the Reference Dataspace can also maintain User definitions for all Dataspaces.

The default Reference Dataspace is always 'nexB' unless the following setting is set to another existing Dataspace. If set to an empty value or a non-existent Dataspace, 'nexB' will be considered the Reference Dataspace.

Caution: be careful when changing this setting as you may no longer have access to nexB-provided reference data.

REFERENCE_DATASPACE=nexB

SESSION

You can control whether the DejaCode session framework uses web browser-lifetime sessions vs. persistent sessions with the SESSION_EXPIRE_AT_BROWSER_CLOSE setting. If SESSION_EXPIRE_AT_BROWSER_CLOSE is set to True, DejaCode cookies will expire as soon as a user closes his or her web browser. Use this if you want the user to have to log-in every time they open a browser.

SESSION_EXPIRE_AT_BROWSER_CLOSE=True

The SESSION_COOKIE_AGE setting is the maximum age of DejaCode session cookies, in seconds. The DejaCode user session will expire if the user is "inactive" in the application for longer than this value.

# 1 hour, in seconds.
SESSION_COOKIE_AGE=3600

DEJACODE_PAGINATE_BY

The number of objects display per page for each object type can be customized with the following setting:

DEJACODE_PAGINATE_BY=product=20,package=100,license=100,report=50,request=50,scan=50

DEJACODE_LOG_LEVEL

By default, only a minimum of logging messages is displayed in the console, mostly to provide some progress about pipeline run execution.

Default: INFO

The DEBUG value can be provided to this setting to see all DejaCode debug messages to help track down configuration issues for example. This mode can be enabled globally through the .env file:

DEJACODE_LOG_LEVEL=DEBUG

CLAMD_ENABLED

When enabled, DejaCode will perform virus scanning on any and all files that a user attempts to import in the various places where data imports are supported. A file with a detected virus will be blocked from upload, and DejaCode will present a pertinent error message to the user when this occurs.

To enable anti-virus scan on file upload, set the CLAMD_ENABLED setting to True.

CLAMD_ENABLED=True

TIME_ZONE

A string representing the time zone for the current ScanCode.io installation. By default the US/Pacific time zone is used:

TIME_ZONE=US/Pacific

Note

You can view a detailed list of time zones here.

Job Queue and Workers

DejaCode leverages the RQ (Redis Queue) Python library for job queuing and background processing with workers.

By default, it is configured to use the "redis" service in the Docker Compose stack.

For deployments where Redis is hosted on a separate system (e.g., a cloud-based deployment or a remote Redis server), the Redis instance used by RQ can be customized using the following settings:

DEJACODE_RQ_REDIS_HOST=localhost
DEJACODE_RQ_REDIS_PORT=6379
DEJACODE_RQ_REDIS_DB=0
DEJACODE_RQ_REDIS_USERNAME=<username>
DEJACODE_RQ_REDIS_PASSWORD=<password>
DEJACODE_RQ_REDIS_DEFAULT_TIMEOUT=360

To enhance security, it is recommended to enable SSL for Redis connections. SSL is disabled by default but can be enabled with the following configuration:

DEJACODE_RQ_REDIS_SSL=True

AboutCode integrations

To integrate DejaCode with other applications within the AboutCode stack, you have the flexibility to configure and set up integrations using the following application settings.

It's important to understand that employing application settings will make these integrations globally accessible across all Dataspaces within your DejaCode instance.

Alternatively, if you wish to tailor the availability of these features to a specific Dataspace, you can define and set those values directly within the :ref:`dataspace` configuration. This can be done through the Dataspace admin UI, allowing you to scope the availability of these integrations exclusively to the designated Dataspace.

SCANCODEIO

Provide the URL and API key of your ScanCode.io instance.

SCANCODEIO_URL=https://your_scancodeio.url/
SCANCODEIO_API_KEY=insert_your_api_key_here

Note

You have the option to define and set those settings directly on your Dataspace. For detailed instructions, refer to :ref:`dejacode_dataspace_scancodeio`.

PURLDB

Provide the URL and API key of your PurlDB instance.

PURLDB_URL=https://your-purldb.url/
PURLDB_API_KEY=insert_your_api_key_here

Note

You have the option to define and set those settings directly on your Dataspace. For detailed instructions, refer to :ref:`dejacode_dataspace_purldb`.

VULNERABLECODE

You can either run your own instance of VulnerableCode or connect to the public one https://public.vulnerablecode.io/.

Note

Providing an API key is optional when using the public VulnerableCode instance.

VULNERABLECODE_URL=https://public.vulnerablecode.io/
VULNERABLECODE_API_KEY=insert_your_api_key_here

Note

You have the option to define and set those settings directly on your Dataspace. For detailed instructions, refer to :ref:`dejacode_dataspace_vulnerablecode`.

LDAP Integration

AUTHENTICATION_BACKEND

This setting enables users to authenticate against an LDAP server.

To enable the LDAP authentication, set the following value for the AUTHENTICATION_BACKENDS setting.

AUTHENTICATION_BACKENDS=dje.ldap_backend.DejaCodeLDAPBackend

An alternative setup is to allow the authentication in the system first using LDAP, and then using a DejaCode user account if the authentication through LDAP was not successful. For example, this can be useful if the LDAP server is down.

AUTHENTICATION_BACKENDS=dje.ldap_backend.DejaCodeLDAPBackend,django.contrib.auth.backends.ModelBackend

SERVER_URI

The URI of the LDAP server.

AUTH_LDAP_SERVER_URI=ldap://ldap.server.com:389

START_TLS

By default, LDAP connections are unencrypted. If you need a secure connection to the LDAP server, you can either use an ldaps:// URI or enable the StartTLS extension.

To enable StartTLS, set AUTH_LDAP_START_TLS to True.

AUTH_LDAP_START_TLS=True

BIND

AUTH_LDAP_BIND_DN and AUTH_LDAP_BIND_PASSWORD should be set with the distinguished name, and password to use when binding to the LDAP server.

Note

Use empty strings (the default) for an anonymous bind.

AUTH_LDAP_BIND_DN=""
AUTH_LDAP_BIND_PASSWORD=""

USER_DN

The following setting is required to locate a user in the LDAP directory. The filter parameter should contain the placeholder %(user)s for the username. It must return exactly one result for authentication to succeed.

AUTH_LDAP_USER_DN="ou=users,dc=example,dc=com"
AUTH_LDAP_USER_FILTERSTR="(uid=%(user)s)"

AUTOCREATE_USER

When AUTH_LDAP_AUTOCREATE_USER is True (default), a new DejaCode user will be created in the database with the minimum permission (a read-only user).

Enabling this setting also requires a valid dataspace name for the AUTH_LDAP_DATASPACE setting. New DejaCode users created on the first LDAP authentication will be located in this Dataspace.

AUTH_LDAP_AUTOCREATE_USER=True
AUTH_LDAP_DATASPACE=your_dataspace

Note

Set AUTH_LDAP_AUTOCREATE_USER to False in order to limit authentication to users that already exist in the database only, in which case new users must be manually created by a DejaCode administrator using the application.

AUTH_LDAP_AUTOCREATE_USER=False

USER_ATTR_MAP

AUTH_LDAP_USER_ATTR_MAP is used to copy LDAP directory information into DejaCode user objects, at creation time (see AUTH_LDAP_AUTOCREATE_USER) or during updates (see AUTH_LDAP_ALWAYS_UPDATE_USER). This dictionary maps DejaCode user fields to (case-insensitive) LDAP attribute names.

AUTH_LDAP_USER_ATTR_MAP=first_name=givenName,last_name=sn,email=mail

ALWAYS_UPDATE_USER

By default, all mapped user fields will be updated each time the user logs in. To disable this, set AUTH_LDAP_ALWAYS_UPDATE_USER to False.

AUTH_LDAP_ALWAYS_UPDATE_USER=False

Group permissions

User's LDAP group memberships can be used with the DejaCode group permissions system.

The LDAP groups that a user belongs to will be mapped with existing DejaCode groups using the Group name attribute. The permissions defined for each of the mapped DejaCode groups will be loaded for the LDAP user.

To enable and configure DejaCode to use LDAP groups you need to enable LDAP as explained above and also do these additional tasks:

  • In the reference nexB Dataspace, create the DejaCode groups and associated permissions through the DejaCode admin interface. From the Admin dashboard: Administration > Groups.
  • Configure DejaCode settings to enable LDAP groups retrieval by adding these lines to your DejaCode settings file. Set the proper AUTH_LDAP_GROUP_SEARCH values matching for your LDAP configuration.
AUTH_LDAP_FIND_GROUP_PERMS=True
AUTH_LDAP_GROUP_DN="ou=groups,dc=example,dc=com"
AUTH_LDAP_GROUP_FILTERSTR="(objectClass=groupOfNames)"

Configuration examples

Configuration 1

  • LDAP as the only way to log-in DejaCode.
  • Unencrypted connections with the LDAP server.
  • Anonymous bind to the LDAP server.
  • Users need to be manually created in DejaCode by an administrator first.
  • No mapping for users attributes is defined
  • Users field values in the database are not updated at authentication time.
  • Users are located using the uid attribute with the ou=users,dc=example,dc=com distinguished name.
AUTHENTICATION_BACKENDS=dje.ldap_backend.DejaCodeLDAPBackend
AUTH_LDAP_SERVER_URI=ldap://ldap.server.com:389
AUTH_LDAP_USER_DN="ou=users,dc=example,dc=com"
AUTH_LDAP_USER_FILTERSTR="(uid=%(user)s)"
AUTH_LDAP_AUTOCREATE_USER=False
AUTH_LDAP_ALWAYS_UPDATE_USER=False

Configuration 2

  • LDAP as the first way to log-in, and then using a DejaCode user account if the authentication through LDAP was not successful.
  • Encrypted connections with the LDAP server.
  • Binding to the LDAP server using cn=admin,ou=users,dc=example,dc=com for the distinguished name and pw the password.
  • Users are located using the cn attribute with the ou=users,dc=example,dc=com distinguished name.
  • Users will be automatically created or updated. New users will be located in the "nexB" dataspace.
  • Users attributes will be mapped according to the AUTH_LDAP_USER_ATTR_MAP values.
AUTHENTICATION_BACKENDSdje.ldap_backend.DejaCodeLDAPBackend,django.contrib.auth.backends.ModelBackend
AUTH_LDAP_SERVER_URI=ldaps://ldap.server.com:636
AUTH_LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=com
AUTH_LDAP_BIND_PASSWORD=pw
AUTH_LDAP_USER_DN="ou=users,dc=example,dc=com"
AUTH_LDAP_USER_FILTERSTR="(cn=%(user)s)"
AUTH_LDAP_AUTOCREATE_USER=True
AUTH_LDAP_DATASPACE=nexB
AUTH_LDAP_ALWAYS_UPDATE_USER=True
AUTH_LDAP_USER_ATTR_MAP=first_name=givenName,last_name=sn,email=mail