Settings
########

This is the settings page. Only relevant settings for DeepHunter are reported. For details about Django settings, please refer to the official Django documentation.

SECRET_KEY
**********
- **Type**: String
- **Description**: A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value. You can generate a new secret key using the following Python code:

.. code-block:: bash

	$ python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

- **Example**:

.. code-block:: python

	SECRET_KEY = 'i#nu(#b41!&62x4bv9zo)zz5c+!q13mm#b-qs@z=k)kdu%qgkj'

DEBUG
*****
- **Type**: Boolean
- **Possible values**: ``True`` or ``False``
- **Description**: Used to display debug information. Can be set to ``True`` in development environement, but always to ``False`` in a production environment.
- **Example**: ``DEBUG = True``

UPDATE_ON
*********

- **Type**: String
- **Description**: Choose how you should be notified about updates and what repository should be considered for updates. If you select ``commit``, you will be notified each time there is a new commit, and the upgrade script will download the very latest version of DeepHunter. If you select ``release``, you will only be notified about updates when a new version is released, and the upgrade script will download the latest release, instead of the latest commited code.
- **Possible values**: ``commit`` or ``release``
- **Example**:

.. code-block:: python

	UPDATE_ON = "release"

TEMP_FOLDER
***********

- **Type**: String
- **Description**: Used by the upgrade script. This is a temporary location where the current version of deephunter will be saved before upgrading. This can be used for easy rollback in case of error during the update process.
- **Example**:

.. code-block:: python

	TEMP_FOLDER = "/data/tmp"

VENV_PATH
*********

- **Type**: String
- **Description**: Used by the update script. This is your python virtual path.
- **Example**:

.. code-block:: python

	VENV_PATH = "/data/venv"

SHOW_LOGIN_FORM
***************
- **Type**: Boolean
- **Possible values**: ``True`` or ``False``
- **Description**: If set to ``True``, a login form with username/password fields will be shown to authenticate. If authentication is exclusively based on AD or PingID, it can be set to ``False``.
- **Example**: ``SHOW_LOGIN_FORM = True``

ALLOWED_HOSTS
*************
- **Type**: List of strings
- **Description**: A list of strings representing the host/domain names that this Django site can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server configurations.

AUTH_PROVIDER
*************
- **Type**: String
- **Description**: Authentication provider (in case you rely on an external authentication provider)
- **Possible values**: ``pingid`` or ``entraid`` (if external authentication provider), or empty string (if local authentication).
- **Example**:

.. code-block:: python

	AUTH_PROVIDER = 'pingid'

USER_GROUP
**********
- **Type**: string (format should be ``user:group``)
- **Description**: User and group. Used by the deployment script (``qm/scripts/upgrade.py``) to fix permissions.
- **Example**: 

.. code-block:: python
	
	USER_GROUP = "tomnook:users"

SERVER_USER
***********
- **Type**: string
- **Description**: User running the server service (e.g. `www-data` is running the Apache server). Used by the deployment script (``qm/scripts/upgrade.py``) to fix permissions.
- **Example**: 

.. code-block:: python
	
	SERVER_USER = "www-data"

GITHUB_URL
**********
- **Type**: string
- **Description**: GitHub URL used by the ``deploy.sh`` script to clone the repo.
- **Example**: 

.. code-block:: python

	GITHUB_URL = "https://token@github.com/myuser/deephunter.git"

GITHUB_LATEST_RELEASE_URL
*************************
- **Type**: string
- **Description**: GitHub URL to get the latest release.
- **Example**: 

.. code-block:: python

	GITHUB_LATEST_RELEASE_URL = 'https://api.github.com/repos/sebastiendamaye/deephunter/releases/latest'

GITHUB_COMMIT_URL
*****************
- **Type**: string
- **Description**: GitHub URL to get the latest commit ID.
- **Example**: 

.. code-block:: python

	GITHUB_COMMIT_URL = 'https://raw.githubusercontent.com/sebastiendamaye/deephunter/refs/heads/main/static/commit_id.txt'

DB_DATA_RETENTION
*****************
- **Type**: integer
- **Description**: number of days to keep the data in the local database. Default value: 90.
- **Example**:

.. code-block:: python

	DB_DATA_RETENTION = 90

RARE_OCCURRENCES_THRESHOLD
**************************
- **Type**: integer
- **Description**: Used to define the threshold for rare occurrences. If a threat hunting analytic matches less than the defined number of distinct hosts (in the full retention), it is considered a rare occurrence.
- **Example**:

.. code-block:: python

	RARE_OCCURRENCES_THRESHOLD = 5

CAMPAIGN_MAX_HOSTS_THRESHOLD
****************************
- **Type**: integer
- **Description**: Because hostname information is stored in the local database each day (campaigns), for each query, during a given number of days (retention), the database could quickly become too large if no threshold is defined. This threshold allows to define a maximum of hosts that would be stored for each query. Set to 1000 by default, as we may assume that a query that matches more than 1000 endpoints/day is not relevant enough for threat hunting.
- **Example**: 

.. code-block:: python

	CAMPAIGN_MAX_HOSTS_THRESHOLD = 1000

ON_MAXHOSTS_REACHED
*******************

- **Type**: dictionary, with following keys: ``THRESHOLD``: Integer, ``DISABLE_RUN_DAILY``: boolean, ``DELETE_STATS``: boolean.
- **Description**: If the threshold defined in ``CAMPAIGN_MAX_HOSTS_THRESHOLD`` is reached several times (defined by ``THRESHOLD``), it is possible to automatically remove the Threat Hunting Analytic from future campaigns (the ``run_daily`` flag will be set to ``False`` if ``DISABLE_RUN_DAILY`` is set), and/or delete the associated statistics (if ``DELETE_STATS`` is set).

.. note::

	The actions described above won't be applied to Threat Hunting analytics that have the flag ``run_daily_lock`` set. This is a way to protect some analytics from being automatically removed from the campaigns, or have the statistics deleted.

- **Example**: 

.. code-block:: python

	# Actions applied to analytics if CAMPAIGN_MAX_HOSTS_THRESHOLD is reached several times
	ON_MAXHOSTS_REACHED = {
		"THRESHOLD": 3,
		"DISABLE_RUN_DAILY": True,
		"DELETE_STATS": False
	}

ANALYTICS_PER_PAGE
******************

- **Type**: integer
- **Description**: Number of analytics displayed per page in the list view. This is used to paginate the list of analytics.
- **Example**:

.. code-block:: python
	
	ANALYTICS_PER_PAGE = 50

DAYS_BEFORE_REVIEW
******************

- **Type**: integer
- **Description**: Number of days before an analytic is considered for review.
- **Example**:

.. code-block:: python

	DAYS_BEFORE_REVIEW = 30

DISABLE_ANALYTIC_ON_REVIEW
**************************

- **Type**: boolean
- **Possible values**: ``True`` or ``False``
- **Description**: If set to ``True``, automatically disable analytics with status 'REVIEW'
- **Example**:

.. code-block:: python
	
	DISABLE_ANALYTIC_ON_REVIEW = False

AUTO_STATS_REGENERATION
***********************

- **Type**: boolean
- **Possible values**: ``True`` or ``False``
- **Description**: If set to ``True``, automatically regenerate stats when analytic query field is changed, or for new analytics
- **Example**:

.. code-block:: python

	AUTO_STATS_REGENERATION = True

REPO_IMPORT_CREATE_FIELD_IF_NOT_EXIST
*************************************

- **Type**: dictionary of booleans
- **Possible values**: ``True`` or ``False``
- **Description**: Defines the behavior for repo import when FK/M2M fields don't exist in your DB. If set to ``True``, the relation will be created automatically. Notice that Target OS and MITRE techniques won't be automatically created (If not in your database, analytics will be created with empty values). For vulnerabilities, the base score will default to 0.

- **Example**:

.. code-block:: python
	
	REPO_IMPORT_CREATE_FIELD_IF_NOT_EXIST = {
		"category": "false",
		"threats": "false",
		"actors": "false",
		"vulnerabilities": "false",
	}


REPO_IMPORT_DEFAULT_STATUS
**************************

- **Type**: string
- **Possible values**: ``DRAFT`` or ``PUB``
- **Description**: Default status when analytics are imported from a remote repo.
- **Example**:

.. code-block:: python

	REPO_IMPORT_DEFAULT_STATUS = "DRAFT"


REPO_IMPORT_DEFAULT_RUN_DAILY
*****************************

- **Type**: boolean
- **Possible values**: ``True`` or ``False``
- **Description**: If set to ``True``, the imported analytics (from a repo) will be included in the campaigns (``run_daily`` flag set).
- **Example**:

.. code-block:: python

	REPO_IMPORT_DEFAULT_RUN_DAILY = True

NOTIFICATIONS_RECIPIENTS
************************

- **Type**: dictionary
- **Description**: List of users and groups to send notifications to for each notification level.
- **Example**:

.. code-block:: python

	NOTIFICATIONS_RECIPIENTS = {
		'debug':   {'users': ['admin'], 'groups': []},
		'info':    {'users': ['admin'], 'groups': ['manager', 'viewer']},
		'success': {'users': [''], 'groups': ['manager']},
		'warning': {'users': [''], 'groups': ['']},
		'error':   {'users': [''], 'groups': ['']},
	}

AUTO_DELETE_NOTIFICATIONS_AFTER
*******************************

- **Type**: dictionary
- **Description**: Notifications auto deleted after x days for each notification level.
- **Example**:

.. code-block:: python

	AUTO_DELETE_NOTIFICATIONS_AFTER = {
		'debug':   1,
		'info':    7,
		'success': 7,
		'warning': 30,
		'error':   30,
	}

AI_CONNECTOR
************
- **Type**: string
- **Possible values**: ``gemini``, or empty string (to disable AI features)
- **Description**: Choose the AI connector to use for AI features (e.g., automatic identification of MITRE techniques based on query). If you don't want to use AI features, leave it as an empty string.
- **Example**:

.. code-block:: python

	AI_CONNECTOR = "gemini"


PROXY
*****
- **Type**: dictionary
- **Description**: Proxy settings for any Internet communication from DeepHunter, including API calls to S1.
- **Example**: 

.. code-block:: python

	PROXY = {
		'http': 'http://proxy:port',
		'https': 'http://proxy:port'
		}

AUTHENTICATION_BACKENDS
***********************
- **Type**: list
- **Description**: Keep ModelBackend around for per-user permissions and local superuser (admin).
- **Example**: 

.. code-block:: python

	AUTHENTICATION_BACKENDS = [
    	'django.contrib.auth.backends.ModelBackend',
	]

INSTALLED_APPS
**************
- **Type**: list
- **Description**: List of installed applications (initialized by django). Just make sure new DeepHunter modules are listed at the end (e.g., ``qm``, ``extensions``, ``reports``), and modules you are installing/using are also listed (e.g., ``dbbackup``).
- **Example**: 

.. code-block:: python

	# Application definition
	INSTALLED_APPS = [
		'django.contrib.admin',
		'django.contrib.auth',
		'django.contrib.contenttypes',
		'django.contrib.sessions',
		'django.contrib.messages',
		'django.contrib.staticfiles',
		'django_extensions',
		'dbbackup', # django-dbbackup
		'django_markup',
		'simple_history',
		'qm',
		'extensions',
		'reports',
		'connectors',
	]

MIDDLEWARE
**********
- **Type**: list
- **Description**: List of middleware to use. Make sure to keep the default ones.
- **Example**:

.. code-block:: python

	MIDDLEWARE = [
		'django.middleware.security.SecurityMiddleware',
		'django.contrib.sessions.middleware.SessionMiddleware',
		'django.middleware.common.CommonMiddleware',
		'django.middleware.csrf.CsrfViewMiddleware',
		'django.contrib.auth.middleware.AuthenticationMiddleware',
		'django.contrib.messages.middleware.MessageMiddleware',
		'django.middleware.clickjacking.XFrameOptionsMiddleware',
		'simple_history.middleware.HistoryRequestMiddleware',
		'django_auto_logout.middleware.auto_logout',
	]

ROOT_URLCONF
************
- **Type**: string
- **Description**: Main URL file used by DeepHunter. Default value: ``deephunter.urls``. Do not modify this value.
- **Example**: 

.. code-block:: python
	
	ROOT_URLCONF = 'deephunter.urls'

TEMPLATES
*********
- **Type**: list
- **Description**: List of templates to use. Make sure to keep the default ones.
- **Example**:

.. code-block:: python
	
	TEMPLATES = [
		{
			'BACKEND': 'django.template.backends.django.DjangoTemplates',
			'DIRS': [],
			'APP_DIRS': True,
			'OPTIONS': {
				'context_processors': [
					'django.template.context_processors.debug',
					'django.template.context_processors.request',
					'django.contrib.auth.context_processors.auth',
					'django.contrib.messages.context_processors.messages',
					'django_auto_logout.context_processors.auto_logout_client',
				],
			},
		},
	]

WSGI_APPLICATION
****************
- **Type**: string
- **Description**: WSGI application used by Django. Default value: ``deephunter.wsgi.application``. Do not modify this value.
- **Example**:

.. code-block:: python

	WSGI_APPLICATION = 'deephunter.wsgi.application'

DATABASES
*********
- **Type**: dictionary
- **Description**: Database settings. By default, configured to be used with MySQL/MariaDB. Refer to the Django documentation to use other backends.
- **Example**: 

.. code-block:: python

	DATABASES = {
		'default': {
			'ENGINE': 'django.db.backends.mysql',
			'NAME': 'deephunter',
			'USER': 'deephunter',
			'PASSWORD': 'D4t4b453_P455w0rD',
			'HOST': '127.0.0.1',
			'PORT': '3306'
		}
	}

AUTH_PASSWORD_VALIDATORS
************************
- **Type**: list of dictionaries
- **Description**: Password validation settings. These validators are used to enforce password complexity and security. https://docs.djangoproject.com/en/4.1/ref/settings/#auth-password-validators
- **Example**:

.. code-block:: python

	AUTH_PASSWORD_VALIDATORS = [
		{
			'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
		},
		{
			'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
		},
		{
			'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
		},
		{
			'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
		},
	]

Internationalization settings
*****************************
- **Description**: https://docs.djangoproject.com/en/4.1/topics/i18n/
- **Example**:

.. code-block:: python

	LANGUAGE_CODE = 'en-us'
	TIME_ZONE = 'Europe/Paris'
	USE_I18N = True
	USE_TZ = True

STATIC_URL and STATIC_ROOT
**************************
- **Type**: string
- **Description**: Related and absolute path for the static content (images, documentation, etc.).
- **Example**: 

.. code-block:: python

	STATIC_URL = 'static/'
	STATIC_ROOT = '/data/deephunter/static'

DEFAULT_AUTO_FIELD
******************
- **Description**: Default primary key field type (https://docs.djangoproject.com/en/4.1/ref/settings/#default-auto-field).
- **Example**:

.. code-block:: python

	DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'

LOGIN_URL
*********
- **Type**: string
- **Description**: URL to redirect to when logging out, or as first page when connecting. Shouldn't be changed.
- **Example**: 

.. code-block:: python

	LOGIN_URL = '/admin/login/'

DBBACKUP
********
- **Type**: dictionary (``DBBACKUP_STORAGE_OPTIONS``) and string (``DBBACKUP_STORAGE`` and ``DBBACKUP_GPG_RECIPIENT``)
- **Description**: ``DBBACKUP_STORAGE_OPTIONS`` is to specify the location of your backups. ``DBBACKUP_GPG_RECIPIENT`` should be the email address used by GPG for the encryption of the backups. Used by the ``./qm/scripts/backup.sh`` script.
- **Example**: 

.. code-block:: python

	### dbbackup settings (encrypted backups)
	DBBACKUP_STORAGE_OPTIONS = {'location': '/data/backups/'}
	DBBACKUP_STORAGE = 'django.core.files.storage.FileSystemStorage'
	DBBACKUP_GPG_RECIPIENT = 'email@domain.com'

AUTO_LOGOUT
***********
- **Type**: dictionary
- **Description**: Used for session expiration (recommended). In case of inactivity, your session should auto-expire and you should be automatically disconnected after some time (defined in minutes with the ``IDLE_TIME`` parameter).
- **Example**: 

.. code-block:: python
	
	# Logout automatically after 1 hour
	AUTO_LOGOUT = {
		'IDLE_TIME': timedelta(minutes=60),
		'REDIRECT_TO_LOGIN_IMMEDIATELY': True,
	}

CELERY
******
- **Type**: string
- **Description**: Defines the address of the Celery broker.
- **Example**: 

.. code-block:: python

	CELERY_BROKER_URL = "redis://localhost:6379"
	CELERY_RESULT_BACKEND = "redis://localhost:6379"