06.04 Installing and Managing Frameworks

Why this matters

A framework in SimpleRisk is a set of compliance controls organized into a hierarchy. NIST CSF v2.0 has six functions and dozens of categories and subcategories; ISO/IEC 27001 has Annex A controls grouped into 14 control objectives; PCI DSS has its 12 requirements broken into testing procedures. The framework structure is what gives the program a control map — a place to assert "we have a control for X," "we test it on Y cadence," "the test pass-rate is Z."

Without frameworks, SimpleRisk's compliance side is unfilled. With them, you can map your operational controls (firewall configurations, access policies, training programs) to specific framework requirements and produce framework-based readouts ("our NIST CSF maturity is at 3.2 average," "our ISO 27001 audit is 87% pass-rate").

The honest scope to know up front: Core has framework management; bulk installation lives in Extras, and there are two production paths that solve different problems. The ComplianceForge SCF Extra (free with registration) brings the entire Secure Controls Framework — thousands of controls pre-mapped to NIST CSF, ISO 27001, PCI DSS, HIPAA, GDPR, SOX, FedRAMP, CMMC, and dozens of other authority documents — into your install in one activation. For programs that want comprehensive cross-framework coverage and the ability to say "this one operational control satisfies our SOC 2, our PCI, and our ISO obligations simultaneously," the SCF Extra is where most production deployments start; see The ComplianceForge SCF Extra. The Import-Export Extra's GitHub-based installer pulls one-off framework definitions from SimpleRisk's simplerisk-frameworks repository — useful when you need a specific framework that isn't in SCF's library, when you're publishing a custom industry-specific framework, or when you only need one or two frameworks and don't want SCF's full footprint. Core lets you manually create frameworks and add controls one at a time — fine for a custom internal framework, painful for installing all of NIST CSF v2.0 by hand.

The other thing worth knowing: frameworks support hierarchy. Each framework can name a parentcolumn referencing another framework (or0` for top-level). This lets you model nested structures like NIST CSF's Function → Category → Subcategory hierarchy. Custom frameworks can use the same hierarchy if it fits their structure.

The third thing: framework names and descriptions are encrypted at rest. A framework's name and description columns are stored encrypted (when the Encryption Extra is active). This protects framework metadata if the database is exfiltrated; it also means database-level queries against framework names produce encrypted blobs, not the human-readable values.

Before you start

Have these in hand:

Admin access to Governance → Define Control Frameworks, the framework management page at /governance/index.php. For GitHub-based bulk install, the Import-Export Extra must be active.
A list of the frameworks your program needs. Don't install everything; start with the 1–3 frameworks the program actually maps controls to. Each framework is a maintenance burden (controls need to stay current as the framework evolves); fewer is better.
Awareness of the Import-Export Extra licensing. Most pre-built framework definitions in the SimpleRisk GitHub repo are community-maintained; some have licensing constraints (NIST publications are public domain; ISO 27001's full text is copyrighted by ISO and is not redistributed). The repository contains control mappings and structures, not the proprietary text of the frameworks; if your auditor needs the actual ISO text, you still need an ISO subscription.
Awareness of the Customization Extra interaction. Custom frameworks built manually via the Core surface are the same kind of object as installed ones; the management UI doesn't distinguish. The Customization Extra adds form-customization for risk and mitigation, not for frameworks themselves; framework customization is via the standard governance UI.

Step-by-step

1. Identify your framework needs and pick a path

Common starting points:

NIST CSF v2.0 — broad cybersecurity framework; works for most security-focused programs.
NIST SP 800-53 — federal control catalog; appropriate for federal contractors and high-security programs.
ISO/IEC 27001 — international information-security management standard; common for international and certified programs.
SOC 2 Trust Services Criteria — for SaaS providers and B2B software companies handling customer data.
PCI DSS — required for any organization processing payment card data.
HIPAA Security Rule — for healthcare and business associates.
CIS Critical Controls — pragmatic, prioritized control set; good first framework for less-mature programs.

Pick what your auditors and customers ask for; don't install everything.

Then pick the install path. If you need two or more of the frameworks above and care about cross-mapping (the same operational control satisfying multiple audit obligations), go straight to the ComplianceForge SCF Extra — it ships with all of them and their interconnections out of the box. Free with registration, one activation, no per-framework setup. The detailed runbook is in The ComplianceForge SCF Extra; come back here if you also need to install a framework that isn't in SCF's catalog, or if you only need one framework and want the lighter footprint of the Import-Export path described below.

2. Install the Import-Export Extra

Settings cog (top-right of any page) → Settings Hub → Extras chip → Import-Export Extra tile → Activate. Activation enables:

The GitHub-based framework installer.
Bulk import/export of frameworks, controls, risks, and other entities (covered in Configuring Risk and Compliance and related articles).
A record of which frameworks it has installed, so it can track them.

Without the Extra, frameworks must be created manually one at a time.

3. Browse and install GitHub frameworks

With the Import-Export Extra active:

Settings cog → Settings Hub → Import-Export Extra tile, which opens /admin/importexport.php.
Open the Frameworks tab.
The page lists pre-built frameworks fetched from the SimpleRisk content repository at raw.githubusercontent.com/simplerisk/import-content.
Pick the framework; click Install. The same tab has an Uninstall button for reversing an install.
The Extra downloads the framework definition and creates the framework along with every one of its controls.

Installation can take a moment for large frameworks (NIST CSF v2.0 has 100+ controls). The page typically shows a progress indicator.

After installation, the framework appears in the rail on Governance → Define Control Frameworks with its control count beside the name. Select it to see its controls in the table on the right; from there they can be mapped to risks via the standard control-mapping flow.

4. Create a custom framework manually

For a framework not in the GitHub repo (an internal framework, a framework with proprietary structure):

Governance → Define Control Frameworks, then Add framework — the dashed row at the top of the framework rail. It drops a menu of three acquisition routes; pick Create one manually. The other two (Get one from the Secure Controls Framework, Import one from a spreadsheet) are always listed, and appear greyed and marked Locked with an unlock link when the instance isn't registered, the Extra isn't downloaded, or the Extra isn't activated. Non-administrators see them locked with no link, since every unlock step is a check_admin page.
Enter the Framework Name (required, 100 characters), pick a Status, and fill in the Framework Description. Status offers Active and Inactive and lands on Active; set it to Inactive here to create the framework without putting it in front of anyone yet. Manage framework status below covers what that changes.
Under Placement, pick a Parent Framework if hierarchical (or leave at top-level).
Under Statement of applicability, optionally fill in the Scope statement and Default inclusion justification. These are ISO 27001 clause 6.1.3(d) fields; see Control Applicability and the Statement of Applicability. The scope statement starts empty and is stored as NULL if you leave it that way. It's a rich-text field, so what lands in the framework's Scope Statement is HTML, sanitized with HTMLPurifier on the way in. Emptying the editor stores an empty string rather than the paragraph markup the widget submits, which is what keeps the report prompting for a scope nobody has written. The inclusion justification is pre-filled with a standard sentence, so a framework created through this form carries one unless you clear the box — and clearing it also stores NULL, which the report treats as "never answered" and prompts about.
Click Add.

Then add controls:

Select the framework in the rail.
Add Control, in the toolbar above the controls table.
Enter the control's Control Short Name (required) plus whatever else the framework needs — Control Number, Control Owner, Control Family, and the Mapped Control Frameworks rows under Mappings & guidance.
Click Add; repeat for each control. The per-row Clone action pre-fills this same modal from an existing control, mappings included, which is faster for a series of similar controls.

For frameworks with many controls, manual entry is tedious. The Import-Export Extra also supports bulk import via CSV — prepare a CSV with the framework structure, upload, and the controls populate.

5. Manage framework status

A framework's status is one of two values:

Active (1) — the framework appears in dropdowns, control-mapping UI, and reports.
Inactive (2) — the framework is hidden from active use but its data is preserved.

Use status (rather than deletion) to retire a framework. Deletion is destructive; status changes are reversible.

Set it from the Status field in the Add Framework and Edit Framework modals on the Define Control Frameworks page. The field offers Active and Inactive, defaults to Active on a new framework, and is prefilled from the stored value when you edit an existing one. Saving requires the Able to Modify Existing Frameworks (modify_frameworks) permission — the same permission that gates every other edit in that modal; creating a framework directly as Inactive requires Able to Add New Frameworks (add_new_frameworks) instead.

The rail's Active / Inactive / All dropdown is a separate control: it filters which frameworks the rail lists and does not change anything. Because the rail reloads against that filter after a save, a framework you set to Inactive while the filter reads Active drops out of the list immediately — switch the filter to Inactive or All to find it again.

Two behaviors are worth knowing before you deactivate a parent framework:

Deactivating a framework also deactivates every framework beneath it in the hierarchy.
Activating a framework also activates its parents, so it is never left as an active child of an inactive parent.

Inactive frameworks keep all of their controls, mappings, and applicability decisions. They are excluded from the control-mapping dropdown, from the governance dashboard's totals, and from framework attribution on the controls table — all of which scope to status = 1.

6. Scope a framework with per-control applicability

Status is a whole-framework lever. For the common case where most of a framework applies and a slice of it doesn't, the finer lever is per-control applicability, recorded per framework on the Define Control Frameworks page.

A control is Applicable by default, and the absence of a row is what means it. The two deviations are Not applicable (out of scope, requiring at least one reason from the applicability-reason list plus a written justification) and Inherited (performed by a third party, requiring a provider and a justification). Decisions carry the deciding user and a timestamp, and they're recorded against the framework and control together — deliberately not against the mapping between frameworks, so an SCF re-import can't destroy them.

Applicable is also a state you can record deliberately, not just the absence of a decision. ISO 27001 clause 6.1.3(d) asks for a per-control justification for inclusion as much as for exclusion, so an applicable control can carry its own reasons and narrative. A control you've never touched is still treated as applicable, and clearing a control's decision still returns it to the framework default. The narrative is genuinely optional: a control justified by its selected reasons alone doesn't need prose, and SimpleRisk keeps "no narrative written" distinct from "narrative deliberately left blank."

Reasons are multi-select, and they hang off the applicability decision rather than being a single value on it — which is what lets one exclusion cite several reasons at once. They're cleared automatically if the applicability decision itself is cleared. Older installs stored just one reason; the upgrade carries it forward into the new multi-select. The join table, and any value it held is copied across first. The cascade is what keeps delete-to-reset honest: clearing a control's decision takes its reasons with it.

Writing applicability requires the Able to Modify Existing Frameworks (modify_frameworks) permission; reading it needs governance. Bulk-setting from the selection bar can target either the current page or every control matching the active filters.

One API behavior is worth knowing before you script against it. POST /api/v2/governance/applicability treats an omitted field as "say nothing about it" and preserves what's stored; only an explicit '' or [] clears. So resetting a control to the framework default is {"state": "applicable", "narrative": "", "reason_ids": []}, not a bare {"state": "applicable"} — the bare form keeps the justification the caller believes it just removed. The page's own client sends every field on every submit for this reason.

SimpleRisk renders the Statement of Applicability from these decisions. The browser view is Core; both downloads — XLSX and PDF — are generated by the Import-Export Extra, and their buttons aren't built at all when it's inactive. The full practitioner treatment — the six implementation states, the overdue marker, the evidence and remediation columns, and the Basic/Detailed variants — is in Control Applicability and the Statement of Applicability.

7. Map controls to operational entities

Once frameworks are installed, the value comes from mapping framework controls to your operational controls, risks, and tests:

Control to operational control: the framework control "NIST 800-53 AC-2: Account Management" maps to your operational control "Quarterly user-access review process." See the relevant compliance articles in this guide.
Control to risk: a risk in the register can reference the framework controls that mitigate or relate to it.
Control to test: the test definition (in the Compliance Management workflow) references which control(s) it tests.

The mapping work is where the value of installing the framework comes from. Installing without mapping produces a framework that's just a control list; mapping turns it into an active compliance posture.

Two gaps to plan around. Cross-framework mappings can only be set when a control is created — the update modal neither shows nor saves them, and the control update endpoint ignores mapping fields in the body. And the Mapped Assets widget renders in the control modal but has no working handler on this page, so controls can't be mapped to assets from here.

8. Update frameworks when the standard updates

Frameworks evolve. NIST CSF v2.0 superseded v1.1 with significant changes; ISO 27001:2022 reorganized Annex A from 27001:2013. When the source standard updates:

The SimpleRisk frameworks repo eventually publishes the updated definition.
Re-install the framework via the Import-Export Extra (this typically creates a new framework rather than overwriting; retire the old one by setting it Inactive).
Re-map your operational controls to the new framework's controls (some mappings carry forward; others need re-thinking).

This is meaningful work. Don't update frameworks in flight without a plan; coordinate with audit cycles and re-mapping capacity.

9. Plan for framework-related backups

A backup needs to cover your frameworks, their controls, and the mappings between them. The standard database backup (see Database Backup and Restore) does. After major framework changes, take a backup before going live so the rollback path is one operation.

Common pitfalls

A handful of patterns recur with framework management.

Installing every framework "in case we need it." Each installed framework is a maintenance commitment; if not actively mapped, it's just clutter. Install what you actively use.
Trying to install proprietary framework text via the GitHub installer. The repo has structures and control IDs/names; it doesn't redistribute the full proprietary text of frameworks like ISO 27001. If your auditor wants you to demonstrate operational adherence to "ISO 27001 Annex A 5.18," they'll have the ISO text; SimpleRisk holds the structure.
Renaming installed framework controls without thinking. Renaming "NIST 800-53 AC-2" to "Account Management" loses the ID linkage to the standard. If you need both the standard ID and a friendly name, use the short-name field for the ID and the long-name for the description.
Deleting a framework that's referenced by mapped controls or risks. The mappings become orphaned; reports referencing the framework break. Set the framework Inactive instead.
Confusing manually-created frameworks with installed ones. Both are just frameworks; the management UI doesn't distinguish. Add a naming convention (e.g., prefix internal frameworks with "[Internal]") if the distinction matters operationally.
Not updating frameworks when the standard updates. A SimpleRisk install showing "NIST CSF v1.1 controls" five years after v2.0 shipped is operating against an outdated framework. Schedule periodic framework reviews.
Installing a framework before the Import-Export Extra. Without the Extra, the GitHub installer isn't available; you'd have to create the framework manually one control at a time. Activate the Extra first.
Mass-deleting controls "to clean up." Control deletion is permanent. Nothing in SimpleRisk restores a deleted control — controls that carry test history are flagged deleted rather than dropped from the table, but that exists to keep the test records referentially intact, not to give you a way back. Each deleted control also breaks any mapping that referenced it and removes it from every framework it belonged to, not just the one you were looking at. Verify no mappings exist before deleting; reassign first if they do. When the reason for the cleanup is "these don't apply to us," mark them Not applicable for the framework rather than deleting — that keeps the mappings and leaves an auditable record.
Reaching for bulk delete with "Select all" active. The selection bar's bulk delete operates on explicitly-checked rows only. Escalating the selection to every control matching the current filters is not supported for deletion, and the attempt is refused when you submit it. Delete a page at a time, or check specific rows. Bulk applicability, by contrast, does handle the whole filtered set.
Treating frameworks as policy documents. The framework structure isn't a policy. It's a reference for control structure. Your program's policies are separate documents (managed via the Managing Policies and Documents workflow); the framework is the control map.
Forgetting that framework names are encrypted at rest. Database queries against framework names won't match plaintext strings. Use the application's API or UI to query frameworks; don't try to grep the encrypted database.