02.03 Installing a Framework

Why this matters

A fresh SimpleRisk installation comes with no installed frameworks. The compliance module renders, but there's nothing in it until the program adds the framework or frameworks the audit conversation expects. Installing the right framework is the first compliance step a new program takes, and it shapes everything that follows: which controls show up, which tests get scheduled, how reporting groups the work.

There are three paths to install a framework, and the right path depends on the framework. Common public frameworks (NIST CSF, ISO 27001, SOC 2, PCI DSS, the long list) live in the SimpleRisk GitHub content repository and install with one click. A custom or homegrown framework (your organization's internal control catalog) gets created by hand. And for programs running many frameworks at once, the ComplianceForge SCF Extra and the UCF Extra install large pre-mapped catalogs in bulk. This article walks the first two paths and points to the Extras for the third.

The other reason to read this first: framework installation isn't reversible without consequence. Deleting an installed framework cascades to the controls, the tests, the test results, and the evidence attached to those controls. The path back from "I installed the wrong version of ISO 27001" involves restoring from backup or reinstalling and re-mapping. Take the install seriously the first time.

Before you start

Have these in hand before you open the installation page:

The Able to Add New Frameworks permission on your account. Without it, the Add button on the Frameworks tab doesn't appear and the install attempt returns "You have no permission to add frameworks." (See Permission Reference.)
A clear answer to which framework you intend to install. "We need to do compliance" isn't an answer; "We need ISO 27001:2022 because our enterprise customers are asking for ISO certification" is. The framework is the first commitment that downstream work depends on.
Network access from the SimpleRisk server to https://raw.githubusercontent.com/simplerisk/import-content/. The GitHub install path fetches framework definitions from this URL at install time. An air-gapped install (or one behind a strict outbound firewall) needs the manual creation path instead.
For complex multi-framework programs: a decision on whether to use the ComplianceForge SCF Extra or UCF Extra rather than installing the frameworks one-by-one. Both Extras install hundreds of frameworks pre-mapped to a common backbone, which saves dramatic amounts of one-by-one install work. See The ComplianceForge SCF Extra and The UCF Extra.

Step-by-step

Path 1: Install from the SimpleRisk GitHub content repository

The GitHub path is the right answer for most public frameworks. SimpleRisk maintains a content repository of community-contributed framework definitions (NIST CSF, ISO 27001, SOC 2, PCI DSS, HIPAA, and many more) and the install process pulls the framework definition and its controls in one operation.

Open the Governance module. Sidebar: Governance → Frameworks opens /governance/index.php with the Frameworks tab active.
Open the framework install dialog. Click Add at the top of the Frameworks tab. The dialog offers three options: install from GitHub, create blank, or copy from an existing framework.
Pick "Install from GitHub". SimpleRisk fetches the catalog of available frameworks from https://raw.githubusercontent.com/simplerisk/import-content/master/Control%20Frameworks/frameworks.xml and presents them as a selectable list. The list includes the common public frameworks (NIST CSF v2.0, ISO 27001:2022, SOC 2, PCI DSS, HIPAA Security Rule, FedRAMP, NIST SP 800-171, the long list) plus contributed regional and industry-specific frameworks.
Select the framework version you want. ISO 27001:2013 and ISO 27001:2022 are different installs; pick the version your audit conversation expects. NIST CSF v1.1 and v2.0 are different installs (v2.0 added the Govern function — see The GRC Program Lifecycle); pick the version your stakeholders are reading from.
Click Install. SimpleRisk fetches the framework definition (the framework name, description, and the full list of controls with their family assignments) and writes them to the frameworks and framework_controls tables in one operation. The new framework appears in the Frameworks tab list with the seeded controls visible under the Controls tab.

The install is synchronous and atomic — either the whole framework lands or nothing does. If the GitHub fetch fails (network issue, missing framework, repo restructuring), the install returns an error and writes nothing.

Path 2: Create a framework by hand

The manual path is the right answer for custom or homegrown frameworks — your organization's internal control catalog, a regulator-specific control set the GitHub repo doesn't carry, or a "blank" framework you'll populate by importing controls from elsewhere.

Open the Governance module. Same path as above: Governance → Frameworks opens /governance/index.php.
Click Add. In the dialog, pick Create Blank (or whichever label your install renders for the manual-create option; the dialog wording varies slightly with theme).
Fill in the framework metadata. The form asks for: - Name — the framework's display name. Required; can't be empty (the form returns "The framework name can't be empty."). - Description — a longer description of the framework's scope and purpose. Optional but recommended. - Status — Active (default) or Inactive. Inactive frameworks are still in the database but hidden from the standard reporting and test-scheduling surfaces. - Parent Framework — optional; if this framework is a child of another framework (sub-frameworks are common in SCF-style hierarchies), pick the parent here. Most installs leave this blank.
Click Save. SimpleRisk writes the framework row and returns the success message "A new framework was added successfully."
Add controls to the framework. A blank framework has no controls. Switch to the Controls tab and click Add Control for each control in the framework. Each control needs a Control Number (the framework-native identifier, like "AC-2" or "5.1.1"), a Control Name, a Control Description, an Owner, a Family (the functional grouping), and optionally a Parent Control (for hierarchical frameworks). See Control Frameworks and Control Families for the abstractions.

For frameworks with more than a handful of controls, populating them one by one through the UI is impractical. Use the Import/Export Extra (see Importing and Exporting Risks — the same pattern applies to controls) to bulk-load from a spreadsheet, or use the v2 API to script the import.

The manual path is also how you'd extend a GitHub-installed framework: install the public framework, then add custom controls to it for organization-specific extensions. Custom controls coexist with public ones in the same framework; reporting treats them identically.

Path 3: Install via the SCF or UCF Extras

For programs running many frameworks at once with substantial overlap, the ComplianceForge SCF Extra and the UCF Extra install large pre-mapped catalogs in bulk. Both Extras install 200+ frameworks at activation with all the cross-framework mappings precomputed, which collapses what would otherwise be weeks of one-by-one install work into a single activation.

The SCF and UCF paths are documented in their own articles:

ComplianceForge SCF Extra (free with registration; ships the Secure Controls Framework and 200+ mapped frameworks) — The ComplianceForge SCF Extra.
UCF Extra (paid; ships the Unified Compliance Framework's regulatory-citation database) — The UCF Extra.

Use the Extras when the framework count is high and the cross-framework mapping is the load-bearing benefit; use the GitHub or manual paths when the framework count is small and the install fits in an afternoon.

Verifying the install

After any of the three paths, verify the install before relying on it:

Open the Frameworks tab and confirm the new framework appears in the list with the expected name, description, and status.
Open the Controls tab and filter to the new framework. Confirm the control count matches what the framework should contain (NIST CSF v2.0 has 106 subcategories; ISO 27001:2022 has 93 Annex A controls; SOC 2 has the Trust Services Criteria with their points of focus). A control count that's surprisingly low usually means the GitHub fetch was partial or the manual import dropped rows.
Spot-check one or two controls and confirm the control number, name, and description match the framework as published. Differences usually indicate either a stale GitHub repo or a manual edit that overrode the seeded values.

Common pitfalls

A handful of patterns recur when teams install frameworks.

Installing the wrong version of a framework. ISO 27001:2013 and ISO 27001:2022 share a name and a brand but have substantially different control sets and organization. Customers occasionally install the older version because it's first in the list and discover months later that their audit conversation expects the newer one. The recovery (installing the newer version, mapping every implementation effort to the new control numbers, retiring the old) is several days of work. Pick the version your auditor expects on the first pass.
Installing a framework "to see what it has" and forgetting to remove it. Test installs of frameworks the program isn't actually adopting clutter the Controls tab, the dashboards, and the test-scheduling surfaces. Mark experimental installs as Inactive during the evaluation; delete them when the evaluation is done. Inactive frameworks stay in the database but stop driving reporting noise.
Customizing a GitHub-installed framework heavily and then re-installing. Re-installing a GitHub framework doesn't merge — it overwrites the framework metadata. Heavy customizations (renamed controls, added owners, custom families) get clobbered if the framework gets re-installed for an update. Track customizations separately (a custom framework that extends the public one is the cleaner pattern) so re-installs don't lose the local work.
Forgetting that framework deletion cascades. Deleting a framework deletes its controls, which deletes the test history attached to those controls, which deletes the evidence files attached to those tests. The cascade is intentional but unforgiving. Before deleting any framework, confirm there's nothing in it the program depends on; consider marking it Inactive instead.
Network-dependent install on an air-gapped server. The GitHub install path requires outbound HTTPS to raw.githubusercontent.com. Air-gapped installations need the manual-create path with controls bulk-imported from a spreadsheet (or imported via the API from a local source). Trying to install from GitHub on an air-gapped server returns a network error, which sometimes gets misread as a SimpleRisk bug.
Skipping the parent-child relationship on hierarchical frameworks. When the framework's controls have a natural tree structure (NIST SP 800-53's enhancements, ISO 27001's sub-clauses), the GitHub install captures the hierarchy via framework_controls.parent. Manual creation of the same framework without using the parent field flattens the tree, which loses rollup behavior in reporting. Use parents when the framework has them.
Treating the seeded library as exhaustive. The SimpleRisk GitHub content repo carries common public frameworks but doesn't carry every framework that exists. If your audit conversation references a framework that isn't in the GitHub list, the manual creation path or the UCF Extra (which carries a much larger library, including regulatory citations beyond the standard frameworks) is the answer. Don't rule out the manual path because the GitHub list "should" cover everything.