Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

01.06 Installing Extras

How SimpleRisk Extras are installed and activated — the directory structure, the activation pattern, the per-Extra schema migrations, the hosting-tier restriction model, and the operator workflow for bringing an Extra online.

Why this matters

Extras are how SimpleRisk extends Core capabilities without bloating the Core install. Each Extra is a self-contained module living under simplerisk/extras/ / with its own activation function, its own schema migrations, its own admin pages, and (often) its own permissions. Activating an Extra is a deliberate operator action; the activation creates the Extra's database tables, registers its permissions, adds its sidebar entries, and starts whatever ongoing processes the Extra requires.

The honest scope to know: this article covers the operator-side workflow for installing and activating Extras. The strategic question of which Extras to activate is answered in the User Guide's When and How to Bring in Extras. The deep-dive on individual Extras lives in their dedicated articles (the Vulnerability Management Extra in chapter 05, the Incident Management Extra in chapter 07, the AI Extra and Workflows Extra in chapter 10, etc.). This article is the activation workflow that's the same across all of them.

The other thing worth knowing: not every Extra is available on every install. SimpleRisk's hosting-tier model (hosting_tier setting, with values like internal, trial, small, medium, large, reseller) gates which Extras a given install can activate. Trial installs typically don't have access to paid Extras; reseller installs may have additional Extras unavailable elsewhere. The restricted_extra() helper enforces this at the activation page; if your install can't activate an Extra you expected, the hosting-tier restriction is usually the reason.

The third thing: Extras have schema migrations that run automatically. Each Extra has an upgrade.php file that runs on activation and on every page load (the upgrade_ _extra_database() function checks the Extra's version stamp and applies any pending migrations). This means the database schema for an Extra evolves between SimpleRisk releases, and the migration runs without operator intervention — but it does run on every page load when the Extra is enabled, which can affect page-load performance for installs with many Extras active.

Before you start

Have these in hand:

  • Admin access to the SimpleRisk install. The Extras administration is admin-only; the relevant pages live under /admin/.
  • A SimpleRisk install that's already up and running (the initial wizard completed; basic operations work).
  • A clear use case for the Extra you want to activate. Activating Extras "to see what they do" produces operational overhead with no benefit; only activate Extras the program will actually use. See When and How to Bring in Extras.
  • For paid Extras: confirmation that your install's licensing covers the Extra. The hosting-tier restriction will block the activation if not; verify with SimpleRisk if you're unsure.
  • For network-dependent Extras (Vulnerability Management Extra, AI Extra, ComplianceForge SCF Extra, UCF Extra, Notification Extra): the upstream credentials and network reachability the Extra needs.
  • A backup of the SimpleRisk database before activating major Extras. Some Extras' activation creates substantial schema additions and seed data; a clean backup gives you a recovery path if the activation goes badly.

Step-by-step

1. Open the Extras administration page

Sidebar: Configure → Extras opens /admin/extras.php. The page lists all Extras supported by the SimpleRisk version, with each Extra's current state (Activated / Not Activated) and an action button (typically Activate or Configure). The full Extras list as of recent versions:

  • Advanced Search Extra
  • API Extra
  • Artificial Intelligence Extra (the "AI Extra")
  • Custom Authentication Extra
  • Customization Extra
  • Encrypted Database Extra (the "Encryption Extra")
  • Import / Export Extra
  • Incident Management Extra
  • Jira Extra
  • Notification Extra
  • Organizational Hierarchy Extra
  • Risk Assessments Extra (the "Assessments Extra" — dual-labeled)
  • ComplianceForge SCF Extra
  • Team-Based Separation Extra
  • UCF Extra
  • Vulnerability Management Extra
  • Workflows Extra

If your install's hosting tier doesn't permit a specific Extra, the action button on that Extra's row may be unavailable or hidden, with a message explaining the restriction.

2. Navigate to the Extra's specific admin page

Each Extra has its own admin page at /admin/ .php (e.g., /admin/api.php for the API Extra, /admin/vulnmgmt.php for the Vulnerability Management Extra, /admin/incidentmanagement.php for the Incident Management Extra). The Extras list links to each Extra's specific page; click through to the one you want to activate.

The Extra's specific page typically shows:

  • The Extra's current state (Activated / Not Activated).
  • The Extra's version stamp (when activated).
  • An Activate button if not yet activated, or a Deactivate button (and configuration options) if activated.
  • For Extras with their own configuration (Vulnerability Management Extra's scanner settings, AI Extra's provider settings, etc.), the configuration form.

3. Click Activate

Click the Activate button. The activation form posts to /api/v2/admin/activate_deactivate_extra with the Extra's identifier and the activate operation. The activation handler:

  1. Verifies the operator has admin permission.
  2. Verifies the hosting-tier restriction allows this Extra.
  3. Calls the Extra's enable_ _extra() function (e.g., enable_api_extra() for the API Extra).
  4. Sets the Extra's enabled flag in the settings table (extra_ or _extra_enabled , varying by Extra).
  5. Runs the Extra's upgrade_ _extra_database() function to create the Extra's tables and seed data.
  6. Writes an audit-log entry recording the activation (typically write_log() with a specific log type).
  7. Sets the global $GLOBALS[' _extra'] flag to true so subsequent code paths in the same request see the Extra as active.

For most Extras, the activation completes synchronously in a few seconds. The exception is the ComplianceForge SCF Extra: activation queues an asynchronous job (scf_install_and_upgrade) that loads 200+ frameworks and their cross-mappings. The synchronous response indicates the queue submission; the actual data load takes minutes-to-hours depending on the server. See The ComplianceForge SCF Extra for the async-install behavior.

After activation, the Extra's sidebar entries become visible (some Extras add menu items only when permissions are also granted), the Extra's API endpoints become callable, and the Extra's configuration surfaces become available.

4. Configure the Extra (if applicable)

Many Extras need configuration after activation:

  • Vulnerability Management Extra: pick scanner platforms, enter API credentials, pick scan-scopes to import. See The Vulnerability Management Extra.
  • AI Extra: pick AI provider, enter API key, configure feature toggles. See Working with SimpleRisk AI and chapter 10's AI Extra articles.
  • Notification Extra: configure SMTP settings, configure event-routing toggles. See Notifications and Email Preferences.
  • Authentication Extra: configure SAML SSO / OIDC / LDAP settings. See chapter 04 of this guide.
  • UCF Extra: enter UCF API key, configure default tester. See The UCF Extra.
  • Workflows Extra: review the seeded system workflows; author custom workflows as needed. See Understanding SimpleRisk Workflows and chapter 10's Workflows articles.

Configuration without correct values produces an Extra that's activated but inert — the AI Extra without an API key doesn't return chat responses; the Vulnerability Management Extra without scanner credentials doesn't ingest data; the Notification Extra without SMTP settings doesn't send emails. Activating and configuring are the two-step process to make an Extra operational.

5. Grant permissions to the relevant users

Most Extras add their own permissions (e.g., the Incident Management Extra adds 15 permissions like im_incidents, im_submit_incidents, etc.). After activating the Extra, grant the appropriate permissions to the users who'll work with it; otherwise the users see no UI for the Extra even though it's active.

Permission grants happen through the standard user-management surface — see Managing Users, Teams, and Roles for the workflow. The Extras' specific permissions and what they gate are documented in Permission Reference and in the Extra's own user-guide article.

6. Verify the Extra is operational

Test the Extra end-to-end after activation and configuration. Common verification steps:

  • The sidebar entries the Extra adds are visible to a user with the appropriate permissions.
  • A simple operation in the Extra's surface succeeds (creating a test entity, sending a test message, running a test sync).
  • The Extra's logs (in simplerisk/logs/ for most Extras, or in the Extra's own log table for some) show no errors.
  • Where the Extra integrates with external systems (scanners, AI providers, email servers), the integration's connectivity is verified.

If the verification fails, check the SimpleRisk debug log first; most activation issues surface there with a clear error.

7. Plan for the Extra's ongoing operational concerns

Each activated Extra adds operational overhead:

  • Configurations to keep current as the upstream changes (scanner API endpoints change, AI provider models change, framework versions change).
  • Credentials to rotate periodically per the organization's credential-rotation policy.
  • Schema migrations to monitor — the Extra's upgrade_ _extra_database() runs on each page load and can introduce schema changes that affect performance or behavior.
  • External-API quotas to respect — the Vulnerability Management Extra makes scanner API calls; the AI Extra makes provider API calls; the Notification Extra sends email. All have their own rate-limiting and cost characteristics.
  • Logs to monitor — failed scanner syncs, failed AI calls, failed notification sends all surface in logs (or silently fail if logging isn't being watched).

Add the Extra-specific maintenance to the program's recurring operational schedule.

Common pitfalls

A handful of patterns recur with Extras installation.

  • Activating Extras the team doesn't use. Each activated Extra accumulates the operational overhead listed above. Activating "to see what it does" produces overhead without benefit. Only activate Extras the team has a current use case for; deactivate ones that fall out of use.

  • Forgetting that activation runs schema migrations. Some Extras (the SCF Extra is the headline example) make substantial schema changes on activation. Back up the database first; the schema changes are reversible only by restoring the backup.

  • Activating Extras without their prerequisites in place. The AI Extra needs an API key from the AI provider; the UCF Extra needs a UCF subscription with API credentials; the Vulnerability Management Extra needs scanner credentials. Activating without these produces an active-but-inert Extra; configure the prerequisites first, then activate.

  • Hitting the hosting-tier restriction unexpectedly. Trial installs and some other restricted tiers can't activate paid Extras. The activation button is hidden or returns an error in this case. Confirm with SimpleRisk that your installation's licensing covers the Extra you want before troubleshooting "why won't it activate."

  • Not granting the Extra's permissions to users. A common post-activation pitfall: the admin activates the Extra, the admin can see the new sidebar entries, but other users can't because the admin's role granted the new permissions and other roles didn't. Grant the Extra's permissions to the relevant roles after activation.

  • Async install (SCF Extra specifically) appearing to fail. The SCF Extra's activation queues a long-running job that loads 200+ frameworks. The activation page returns immediately; the data load happens over minutes-to-hours in the background. Looking at the Frameworks page right after activation shows it empty, which can look like a failure. Wait for the extra_scf_status setting to transition from installing to active before assuming the install failed.

  • Deactivating without backing up. Several Extras are destructive on deactivation — they cascade-delete the data they manage. The SCF Extra drops the SCF frameworks and their test history; the Workflows Extra deletes customer-authored workflows; the Incident Management Extra drops 35+ tables and the data they hold. Always back up before deactivating; the data isn't recoverable from the Extra after deactivation.

  • Treating the Extra as one-time setup. Most Extras need ongoing maintenance — credential rotation, configuration updates as the upstream changes, monitoring for failed syncs or failed integrations. Activated and unmaintained Extras drift; the symptom is "stopped working" months later when the API key expired or the upstream endpoint changed.

  • Forgetting to clear the application cache after activation. Some installations have a separate caching layer (Redis, Memcached, opcache) that may serve stale settings briefly after activation. Restart the relevant cache or clear it after activating the Extra to ensure subsequent requests see the new state.

  • Activating in production without testing first. Extras have variable installation behavior. Activate in a staging environment first to verify the activation completes cleanly and the configuration steps work as expected; then promote the activation to production with confidence.

Related

Reference

  • Permission required: check_admin (admin permission) — required to access /admin/extras.php and the per-Extra admin pages.
  • API endpoint(s): POST /api/v2/admin/activate_deactivate_extra — toggle Extra activation (admin-only). Per-Extra activation/version endpoints exist for some Extras (e.g., GET /api/v2/im/activate, GET /api/v2/vulnmgmt/activate, GET /api/v2/ai/activate).
  • Implementing files: simplerisk/admin/extras.php (the Extras list page); simplerisk/admin/ .php (per-Extra activation pages); simplerisk/extras/ /index.php (the enable_ _extra() and disable_ _extra() functions); simplerisk/extras/ /upgrade.php (per-Extra schema migrations); simplerisk/includes/functions.php (the _extra() check functions like vulnmgmt_extra(), the restricted_extra() hosting-tier gate).
  • Database tables: settings (Extra enabled flags as extra_ or _extra_enabled ; Extra version stamps as _extra_version ); per-Extra tables created by each Extra's upgrade_ _extra_database() function.
  • config_settings keys: hosting_tier (gates which Extras are available); extra_ (per-Extra enabled flag); _extra_version (per-Extra schema version stamp); plus per-Extra configuration keys (e.g., extra_vulnmgmt_*, extra_scf_*, extra_artificial_intelligence, ai_provider, ai_api_key, etc.).
  • External dependencies: Per-Extra: scanner APIs for Vulnerability Management; AI provider APIs for AI Extra; UCF API for UCF Extra; SMTP server for Notification Extra; SAML/OIDC IdP for Authentication Extra; Jira API for Jira Extra.