13.01 Settings Reference

Why this is a reference article

This article catalogs the settings table keys that operators most commonly need to know about. The full settings table contains hundreds of rows, including many that are internal-only or specific to inactive Extras. The catalog below covers the most-referenced settings; for a full listing, query the database (SELECT name, value FROM settings ORDER BY name;).

The settings table is one of the most-used surfaces for SimpleRisk operators. Most settings have a UI surface in the Settings Hub (reached from the Settings cog in the page header). The System category holds File Upload, Logging, Mail, Security, Health Check, About, Announcements, Register & Upgrade, and Queue Monitor; the Customization category holds Preferences (the system-wide defaults and behavioral toggles, with five tabs covering System, Risk Management, Governance, Compliance, and Asset Management), the AI configuration tile, Custom Names, Risk Configuration (Risk Levels, Risk Appetite, SLA Thresholds, the two risk formulas, and Review Settings), the Risk & Threat Catalog, and Add & Remove Values; the Maintenance category holds the backup-related tiles; the Users & Access category holds User / Role / Team Management; and the Extras chip surfaces each installed Extra's own configuration tile. Direct database manipulation is sometimes faster or necessary for bulk changes.

Instance identity and base URL

simplerisk_base_url

• Type: string (URL)
• Purpose: The instance's canonical absolute URL. Every generated link (notification and password-reset emails, the SAML entity ID / ACS / SLO URLs, the Swagger server field, questionnaire share links) is built from it, and it feeds several security checks (the CSRF referer gate, the CSP allowlist, the password-reset host anti-tamper check, and the safe-redirect targets). If the setting is empty, SimpleRisk falls back to the current session's stored value; if that's also empty, it derives one from the request and writes it back, so the first request that resolves this value freezes it going forward. The scheme is read from the request's HTTPS signal only — reverse-proxy headers like X-Forwarded-Proto are never consulted. Set it on the Settings cog → Settings Hub → Security tile (the UI requires the value to match the hostname you're currently connected on) or directly in the database for custom-domain and reverse-proxy deployments.

instance_id

• Type: string
• Purpose: 50-character random token uniquely identifying this install; used for licensing registration and fleet identity. Set during install Step 6.

ssl_certificate_check_simplerisk

• Type: boolean ('1'/'0')
• Purpose: Set during install Step 6 — '1' if the installer's HTTPS self-check passed, '0' otherwise.

update_channel

• Type: string
• Purpose: The update channel an administrator selected on the Register & Upgrade page: production (the default) or rc (Release Candidate). It is the third source SimpleRisk consults, after the UPDATES_URL / LICENSING_URL / BUNDLES_URL constants and the SIMPLERISK_UPDATE_CHANNEL constant in config.php, and either of those locks the selector. See Registration and Licensing.

Authentication and password policy

pass_policy_enabled

• Type: boolean
• Purpose: Master toggle for password policy enforcement.

pass_policy_min_chars

• Type: int
• Purpose: Minimum password length. Default 8.

pass_policy_alpha_required

• Type: boolean
• Purpose: Require at least one alphabetic character.

pass_policy_upper_required

• Type: boolean
• Purpose: Require at least one uppercase.

pass_policy_lower_required

• Type: boolean
• Purpose: Require at least one lowercase.

pass_policy_digits_required

• Type: boolean
• Purpose: Require at least one digit.

pass_policy_special_required

• Type: boolean
• Purpose: Require at least one non-alphanumeric.

pass_policy_max_age

• Type: int
• Purpose: Days before password expiration; 0 disables.

pass_policy_reuse_limit

• Type: int
• Purpose: Number of prior passwords to remember and reject reuse.

pass_policy_attempt_lockout

• Type: int
• Purpose: Failed attempts before account lockout. 0 disables lockout.

pass_policy_attempt_lockout_time

• Type: int
• Purpose: Minutes until auto-unlock. 0 means permanent until admin unlock.

mfa_required

• Type: boolean
• Purpose: Force MFA enrollment for all users.

session_activity_timeout

• Type: int
• Purpose: Idle session timeout in seconds. Default 3600.

session_absolute_timeout

• Type: int
• Purpose: Absolute session lifetime in seconds. Default 28800.

See Local Authentication and Password Policies, Multi-Factor Authentication, Session Management and Timeout.

API

api

• Type: boolean ('true'/'false')
• Purpose: Master API toggle.

api_v1

• Type: boolean
• Purpose: Legacy v1 API enable. Default off on fresh installs.

api_salt

• Type: string
• Purpose: Per-install salt for hashing API keys.

See Authentication and API Keys.

Risk scoring

risk_model

• Type: int (1-6)
• Purpose: The formula the Classic scoring method uses (the Risk Model). 1 = Likelihood x Impact + 2(Impact), 2 = Likelihood x Impact + Impact, 3 = Likelihood x Impact, 4 = Likelihood x Impact + Likelihood, 5 = Likelihood x Impact + 2(Likelihood), 6 = Custom. It does not choose a default scoring method, and does not affect the other methods.

need_risk_score_normalization

• Type: boolean
• Purpose: Normalize raw scores to 0-10 for display. Default true.

default_risk_score

• Type: int
• Purpose: Fallback for invalid inputs. Default 10.

count_of_likelihoods

• Type: int
• Purpose: Likelihood scale max. Typically 5.

count_of_impacts

• Type: int
• Purpose: Impact scale max. Typically 5.

next_review_date_uses

• Type: string
• Purpose: inherent or residual — which score drives review cadence.

sla_threshold_very_high

• Type: int
• Purpose: Days for Very High risks. Default 30.

sla_threshold_high

• Type: int
• Purpose: Days for High. Default 60.

sla_threshold_medium

• Type: int
• Purpose: Days for Medium. Default 90.

sla_threshold_low

• Type: int
• Purpose: Days for Low. Default 180.

sla_threshold_insignificant

• Type: int
• Purpose: Days for Insignificant. Default 180.

See Default Risk Scoring Method, The Risk Formula, Risk Review Cadence.

Asset Scoring

The eleven settings behind the weighted score on assets. Edit them through Settings cog → Settings Hub → Preferences tile → Asset Management tab → Asset Scoring, which validates the whole set together; a row written by hand that breaks one of the rules below makes SimpleRisk ignore all eleven and fall back to the defaults. None of the rows exists until an administrator saves a change there, and an absent row means its default. Numbers are stored as text with two decimals.

asset_scoring_weight_confidentiality

• Type: decimal (0–100)
• Purpose: Weight of Confidentiality in the weighted score. Default 1.00. 0 leaves it out of the score.

asset_scoring_weight_integrity

• Type: decimal (0–100)
• Purpose: Weight of Integrity. Default 1.00. Integrity and Availability can't both be 0.

asset_scoring_weight_availability

• Type: decimal (0–100)
• Purpose: Weight of Availability. Default 1.00.

asset_scoring_value_low

• Type: decimal (0.01–100)
• Purpose: Number a Low rating contributes. Default 1.00. Must be below Moderate.

asset_scoring_value_moderate

• Type: decimal (0.01–100)
• Purpose: Number a Moderate rating contributes. Default 2.00. Must be below High.

asset_scoring_value_high

• Type: decimal (0.01–100)
• Purpose: Number a High rating contributes. Default 3.00.

asset_scoring_threshold_moderate

• Type: decimal
• Purpose: Weighted score at which the Moderate band starts. Default 1.67. Must be above the Low value.

asset_scoring_threshold_high

• Type: decimal
• Purpose: Weighted score at which the High band starts. Default 2.34. Must be above the Moderate threshold and no higher than the High value.

asset_scoring_default_confidentiality

• Type: string
• Purpose: Rating the Add asset form pre-selects: low, moderate, high, not_applicable, or empty for none (the default).

asset_scoring_default_integrity

• Type: string
• Purpose: As above, without not_applicable.

asset_scoring_default_availability

• Type: string
• Purpose: As above, without not_applicable.

Scores and bands aren't stored anywhere, so a change to any of these re-scores every asset on the next read; there's nothing to recalculate. See Data Classification and Asset Criticality in the User Guide for what the settings mean.

One more asset row comes from the upgrade rather than from Preferences. asset_granular_permissions_granted lists the seven asset permissions (Able to Edit Assets, Able to Delete Assets, Able to Verify Assets, Able to Run Asset Discovery, and the three asset group permissions) that the upgrade has already granted to every user and role holding Asset Management access. It's written only after that grant finishes, so an upgrade interrupted half-way grants them on the next attempt, and a permission it lists is never granted again, so a user you've narrowed since keeps your choice. Leave it alone; deleting it makes a re-run of that upgrade hand all seven back to everyone with asset access.

Localization

default_language

• Type: string
• Purpose: System default locale code (e.g., en, fr, de).

default_date_format

• Type: string
• Purpose: Date display pattern (e.g., YYYY-MM-DD).

See Language and Localization.

Email and notifications

phpmailer_transport

• Type: string
• Purpose: smtp or sendmail.

phpmailer_host

• Type: string
• Purpose: SMTP server hostname.

phpmailer_port

• Type: int
• Purpose: SMTP port (587 for STARTTLS, 465 for implicit TLS).

phpmailer_encryption

• Type: string
• Purpose: tls, ssl, or none.

phpmailer_auth

• Type: boolean
• Purpose: SMTP authentication required.

phpmailer_username

• Type: string
• Purpose: SMTP username.

phpmailer_password

• Type: string (encrypted)
• Purpose: SMTP password.

mail_from

• Type: string
• Purpose: Sender email address.

NOTIFY_ON_NEW_RISK

• Type: boolean
• Purpose: Send notifications on new risk submission.

NOTIFY_ON_RISK_UPDATE

• Type: boolean
• Purpose: Send notifications on risk update.

NOTIFY_ON_NEW_MITIGATION

• Type: boolean
• Purpose: Send notifications on new mitigation.

NOTIFY_ON_MITIGATION_UPDATE

• Type: boolean
• Purpose: Send notifications on mitigation update.

NOTIFY_ON_RISK_REVIEW

• Type: boolean
• Purpose: Send notifications on risk review.

NOTIFY_ON_RISK_CLOSE

• Type: boolean
• Purpose: Send notifications on risk closure.

NOTIFY_ON_RISK_COMMENT

• Type: boolean
• Purpose: Send notifications on risk comment.

NOTIFY_ON_AUDIT_INITIATE

• Type: boolean
• Purpose: Send notifications on audit cycle initiation.

NOTIFY_ON_AUDIT_COMMENT

• Type: boolean
• Purpose: Send notifications on audit comment.

NOTIFY_ON_AUDIT_STATUS_CHANGE

• Type: boolean
• Purpose: Send notifications on audit status change.

See Email and the Notification Extra.

Encryption

encryption

• Type: boolean
• Purpose: Encryption Extra activation flag.

The master key isn't a setting — it lives in simplerisk/extras/encryption/includes/init.php. See The Encryption Extra Overview.

Authentication Extra (SAML / LDAP)

custom_auth

• Type: boolean
• Purpose: Authentication Extra activation flag.

custom_auth_method

• Type: string
• Purpose: Active auth method (typically local, saml, or ldap).

AUTHENTICATION_ADD_NEW_USERS

• Type: boolean
• Purpose: Auto-provision unknown SSO users.

LDAPHOST, LDAPPORT, LDAP_VERSION

• Type: mixed
• Purpose: LDAP connection details.

TLS, SASL

• Type: boolean
• Purpose: LDAP transport security and auth mode.

BIND_FIRST, BIND_ACCOUNT, BIND_ACCOUNT_PASS

• Type: mixed
• Purpose: LDAP service account binding.

USERDN, LDAP_USER_FILTER, AUTHENTICATION_LDAP_USER_ATTRIBUTE

• Type: mixed
• Purpose: LDAP user search.

GROUPDN, LDAP_GROUP_ATTRIBUTE, LDAP_MEMBER_ATTRIBUTE, LDAP_FILTER_FOR_GROUP, LDAP_MANAGER_ATTRIBUTE

• Type: mixed
• Purpose: LDAP group mapping.

SAML_METADATA_URL, SAML_METADATA_XML, SAML_METADATA_CACHE_TTL

• Type: mixed
• Purpose: SAML IdP metadata.

USERNAME_ATTRIBUTE, SAML_DISPLAY_NAME_ATTRIBUTE, SAML_EMAIL_ATTRIBUTE, SAML_ROLE_ATTRIBUTE, SAML_TEAMS_ATTRIBUTE

• Type: mixed
• Purpose: SAML attribute mapping.

SAML_SIGN_AUTHN_REQUESTS, SAML_WANT_ASSERTIONS_SIGNED, SAML_REQUIRE_ENCRYPTED_ASSERTIONS

• Type: boolean
• Purpose: SAML cryptographic options.

See The Authentication Extra Overview, Configuring SAML SSO, Active Directory and LDAP.

Customization Extra

customization

• Type: boolean
• Purpose: Customization Extra activation flag.

customization_asset_scoring_field_added

• Type: boolean
• Purpose: Set once the upgrade has added the Asset Scoring field and the Scoring card to every asset template group. While it's set, the upgrade doesn't add them again, so a template an administrator took Asset Scoring off stays that way. Leave it alone; deleting it makes the next page load add the field back to every asset template that lacks it.

Custom field definitions, their values, and the form layouts are stored separately from settings. See Custom Fields.

Separation Extra

team_separation

• Type: boolean
• Purpose: Separation Extra activation flag.

allow_owner_to_risk

• Type: boolean
• Purpose: Risk owners see their own risks.

allow_ownermanager_to_risk

• Type: boolean
• Purpose: Owner's manager sees the risk.

allow_submitter_to_risk

• Type: boolean
• Purpose: Submitter sees what they submitted.

allow_team_member_to_risk

• Type: boolean
• Purpose: Team members see the team's risks.

allow_stakeholder_to_risk

• Type: boolean
• Purpose: Additional stakeholders see the risk.

allow_all_to_risk_noassign_team

• Type: boolean
• Purpose: Unassigned-team risks visible to all.

Plus parallel allow_* settings for tests/audits and documents. See Separation of Duties.

Organizational Hierarchy Extra

organizational_hierarchy

• Type: boolean
• Purpose: Extra activation flag.

default_business_unit_id

• Type: int
• Purpose: The default business unit ID created at activation.

See Organizational Hierarchy.

ComplianceForge SCF Extra

extra_scf

• Type: boolean
• Purpose: SCF Extra activation flag.

extra_scf_status

• Type: string
• Purpose: installing, ready, or error.

extra_scf_version

• Type: string
• Purpose: Currently-installed SCF version.

extra_scf_auto_process_updates

• Type: boolean
• Purpose: Auto-pull SCF updates.

extra_scf_add_new

• Type: boolean
• Purpose: Auto-add new SCF controls on update.

extra_scf_update_existing

• Type: boolean
• Purpose: Auto-update existing SCF controls on update.

extra_scf_delete_removed

• Type: boolean
• Purpose: Delete removed SCF controls (vs archive).

extra_scf_legacy_framework_handler

• Type: string
• Purpose: archive or delete.

extra_scf_numbering_release

• Type: string
• Purpose: Set to 2026.3 once the install's SCF controls have been moved to the SCF 2026.3 numbering. Leave it alone: clearing it lets the next update renumber the controls a second time.

See The ComplianceForge SCF Extra.

Jira Extra

jira

• Type: boolean
• Purpose: Jira Extra activation flag.

JiraInstanceURL

• Type: string
• Purpose: Jira instance URL.

JiraUserEmail

• Type: string
• Purpose: Jira service account email.

JiraUserAPIKey

• Type: string
• Purpose: Jira API token.

JiraWebhookAuthToken

• Type: string
• Purpose: Generated 20-char token for inbound webhook authentication.

See The Jira Extra.

Workflows Extra

workflows

• Type: boolean
• Purpose: Workflows Extra activation flag.

Workflow definitions, executions, email templates live in dedicated tables. See What the Workflows Extra Does.

AI Extra

extra_artificial_intelligence

• Type: boolean
• Purpose: AI Extra activation flag.

ai_provider

• Type: string
• Purpose: Active provider (anthropic, openai, gemini, mistral, grok, ollama, custom).

ai_api_key

• Type: string (encrypted)
• Purpose: Provider API key.

ai_model

• Type: string
• Purpose: Active model name.

extra_ai_risk_suggestions

• Type: boolean
• Purpose: Enable AI-assisted risk FAIR analysis.

extra_ai_control_suggestions

• Type: boolean
• Purpose: Enable AI-assisted control-to-document matching.

extra_ai_document_suggestions

• Type: boolean
• Purpose: Enable AI-assisted document drafting.

ai_context_*

• Type: various
• Purpose: FAIR context settings (one-time questionnaire output).

ai_context_last_saved, ai_context_last_updated

• Type: timestamp
• Purpose: Context-management timestamps.

See The AI Extra Overview, Configuring AI Providers.

Assessments Extra

assessments

• Type: boolean
• Purpose: Assessments (Risk Assessment) Extra activation flag.

ASSESSMENT_MINUTES_VALID

• Type: integer (minutes)
• Purpose: How long a sent questionnaire link stays usable, and — less obviously — how far back the reminder job looks for uncompleted questionnaires to nudge. Seeded at 43200 (30 days) when the Extra is activated. A value under 1440 (one day) yields a zero-day reminder window, so reminder emails stop firing entirely.

ASSESSMENT_AUTOSAVE

• Type: boolean
• Purpose: Whether a respondent's in-progress answers are saved automatically. Seeded at 1.

ASSESSMENT_AUTOSAVE_INTERVAL

• Type: integer (seconds)
• Purpose: How often autosave fires while a respondent is answering. Seeded at 30; ignored when ASSESSMENT_AUTOSAVE is off.

ASSESSMENT_ASSET_SHOW_AVAILABLE

• Type: boolean
• Purpose: Whether the asset picker on an assessment lists available assets. Seeded at 0.

Deactivating the Extra deletes all four settings rows below the activation flag, so a deactivate/reactivate cycle returns them to the seeded values above rather than preserving what you had.

Notification Extra

notification

• Type: boolean
• Purpose: Notification Extra activation flag.

Plus the NOTIFY_ON_* per-event toggles listed under "Email and notifications" above.

Import-Export Extra

import_export

• Type: boolean
• Purpose: Import-Export Extra activation flag.

See Installing and Managing Frameworks.

API Extra

api_extra

• Type: boolean
• Purpose: API Extra activation flag (provides API key generation surface).

See API Key Management.

Debug logging

debug

• Type: boolean
• Purpose: Master debug log toggle.

debug_log_destination

• Type: string
• Purpose: file, database, or syslog.

debug_log_path

• Type: string
• Purpose: Path for file destination.

debug_log_level

• Type: string
• Purpose: Minimum level to log (debug/info/notice/warning/error/critical).

See The Debug Log.

Background task queue

QUEUE_RETENTION_COMPLETED_DAYS

• Type: int
• Purpose: Days a completed or canceled background task is kept before the daily cleanup deletes it. Default 30; 0 keeps them forever; maximum 3650.

QUEUE_RETENTION_FAILED_DAYS

• Type: int
• Purpose: Days a failed background task is kept. Default 90; 0 keeps them forever; maximum 3650.

PROMISES_PURGE_RETENTION_DAYS

• Type: int
• Purpose: Days the step details of a finished task are kept. Default 7. After that the Queue Monitor shows "Step details are not available for this task." even though the task itself is still listed.

Neither QUEUE_RETENTION_COMPLETED_DAYS nor QUEUE_RETENTION_FAILED_DAYS exists as a row until someone saves the Task retention dialog on the Queue Monitor; until then the defaults apply. Change them there (or through POST /api/v2/admin/queue/settings) rather than in the database, because the dialog validates the range. PROMISES_PURGE_RETENTION_DAYS has no UI; it's only read from the settings table, with 7 used when the row is absent. See Monitoring Background Tasks.

The workers' own tuning (memory limits, lifetime, retry count and timing, how long before a running task counts as stuck) isn't stored in the settings table at all. Those values are optional define() lines in config.php, listed in The Cron Jobs.

Querying and modifying settings

-- Read a setting
SELECT value FROM settings WHERE name = '{setting-name}';

-- Read settings matching a pattern
SELECT name, value FROM settings WHERE name LIKE 'pass_policy_%' ORDER BY name;

-- Update a setting
UPDATE settings SET value = '{new-value}' WHERE name = '{setting-name}';

-- Insert a new setting (rare; usually settings are pre-existing)
INSERT INTO settings (name, value) VALUES ('{setting-name}', '{value}');

Changing a setting through the SimpleRisk UI is what you want in almost every case: the application records the change in the audit trail and applies any side effects the setting carries. Editing the value directly in the database skips both.

Common pitfalls

A handful of patterns recur with settings.

• Modifying settings directly without understanding side effects. Some settings have downstream behavior (e.g., changing risk_model doesn't recompute existing risks). Use the UI when possible; for direct DB changes, understand the implications.

• Confusing setting types. Some settings are 'true'/'false' strings; some are '1'/'0'; some are integers. Match the type the application expects.

• Modifying internal-only settings. Some keys are application internals (counters, last-run timestamps). Modifying them produces unpredictable behavior.

• Storing per-install secrets in plain settings. Most settings are stored as plain text. For secrets (API keys, passwords), the application typically encrypts them; verify before storing.

• Forgetting to clear PHP opcache after settings changes. Some settings are read once at request boot and cached. Restart PHP-FPM or clear opcache after non-UI changes.

• Querying SELECT * FROM settings and dumping results. Hundreds of rows; some contain encrypted/sensitive content. Filter what you display.

Related

• Database Schema Overview
• Cron Jobs Reference
• Default Roles and Permissions
• Known Limitations
• Monitoring Background Tasks
• The Debug Log