Administering Keen

Risk Ledger suppliers, risks and framework

Chapter 26 of 30

Risk Ledger

Risk Ledger is a pull ingester for the public alpha API. It brings connected suppliers in as vendors, organisation risks into the Risk Register, and the referenced assessment controls in as a framework, each backed by JSON evidence snapshots.

What the API provides

Risk Ledger data	Keen destination
Supplier details, assessment progress, compliance summaries and properties	JSON evidence snapshots; a vendor under People & Vendors when supplier import is enabled
Risks	JSON evidence snapshots and Risk Register entries, attached to supplier-service assets
Referenced or explicitly selected controls/domains	The Risk Ledger assessment framework, its controls and domain clauses
Assessment answers and attached evidence files	The documented public API has no endpoints for these resources

The public API exposes control and domain lookup by UUID and has no endpoint for enumerating every control, so the imported framework is labelled imported subset and its completeness depends on discovered and configured IDs. Supplier fields such as numEvidence are counts, which Keen retains as metadata. Supplier listing uses a read-only POST search; the other operations use GET.

Configure the API key

An organisation administrator generates the key in Risk Ledger Settings → API Keys. Set these values in Keen's environment and recreate the API, worker and beat containers:

KEEN_RISKLEDGER_ENABLED=true
KEEN_RISKLEDGER_API_KEY=your-api-key
KEEN_RISKLEDGER_POLL_SECONDS=3600
KEEN_RISKLEDGER_CONFIG_PATH=/app/config/riskledger.yml

The API key stays in the server environment and is sent as a Bearer credential; no credentials belong in collection JSON or YAML. The adapter uses the fixed HTTPS origin https://api.riskledger.com/alpha, verifies TLS, rejects redirects and ignores ambient HTTP proxy settings.

Create the collection

Open Sources & evidence mapping and its source/connection view. Select Risk Ledger and Add collection.
Choose organizations. Enter * in org to use the authenticated organisation, or its UUID to pin the expected account. An optional label becomes the event system.
Review the shared adapter settings below. Defaults import all connected suppliers and organisation risks, and discover referenced framework entries.
Use Ingest runners → Run Risk Ledger. Inspect counts and errors, then review the imported vendors, risks and framework.

Each connection holds one API key and its organisation input, so create a separate connection for each key. /organisations/me verifies the key's organisation before imports begin. Select the imported framework in Admin → Frameworks if organisation framework restrictions are configured.

Scope and shared settings

Edit shared adapter settings in the source/connection view. File-managed deployments can use config/riskledger.yml before creating a web-UI override:

organizations:
  - org: '*'
    label: Supplier assurance
import_suppliers: true
import_risks: true
import_framework: true
control_ids: []
domain_ids: []
framework_level_ids: []
page_size: 100
max_pages: 100
max_run_seconds: 300

Setting	Effect
`import_suppliers`	Creates native vendors. Suppliers are still read and captured when importing risks so supplier scope can be determined.
`import_risks`	Collects risks and creates native risk records.
`import_framework`	Retrieves and creates the framework, domains and controls. The explicit ID lists apply when it is enabled.
`control_ids`, `domain_ids`	UUIDs already known from Risk Ledger. Risk links discover associated controls; supplier domain-compliance and framework add-on data discover domains.
`framework_level_ids`	Filters suppliers by `riskledger → framework → level → id` (a supplier's Risk Ledger framework level). Empty includes all connected suppliers; with a filter, only risks belonging to included suppliers are imported. Listing is still paginated across the organisation and filtering happens locally.

Local records and subsequent pulls

Stable organisation and resource IDs prevent duplicate native records. Imports create missing vendors, supplier-service assets, risks, controls and domain links; existing local fields remain as edited. Changed upstream records produce additional evidence snapshots, absence upstream leaves local records and earlier evidence retained, and a deleted local imported record is recreated on a later enabled import.

Review imported ratings. Risk Ledger scores, impact, likelihood, owner names and numeric status are retained in snapshot fields and initial risk notes. Assign Keen ratings, owner and treatment state explicitly; its 5×5 scales and account identities have their own meanings, and no user accounts or People entries are created from upstream names.

Going deeper: names, controls and links

Vendor names are never used to merge unrelated records; a name collision receives a stable Risk Ledger suffix. Risks without an available imported supplier use an organisation/supplier context asset without inventing a vendor record. A risk's explicit control association creates a native risk/control link when that control is imported.

Controls use their upstream UUID as the stable reference. The title includes the domain letter and control number where supplied, the description retains the full question and guidance, and domain clauses group related controls. Imported control text is customer-fetched content, with source links retained.

Map the evidence snapshots

Choose source riskledger. Actions are supplier.snapshot, risk.snapshot, control.snapshot and domain.snapshot; outcome is info. The event timestamp records collection time, and original modification dates remain in the JSON payload.

Use Create mapping from this event or select structured fields. Useful paths include:

fields → supplier.id, fields → control.id, fields → organisation.id
riskledger → approvalStatus, riskledger → numEvidence
riskledger → framework → level → id
riskledger → likelihood, riskledger → impact, riskledger → riskType

For example, a supplier snapshot with the expected approval state can support a supplier-review mapping; review what that state means in your organisation. Snapshots demonstrate the information recorded in Risk Ledger at collection time, assessment-answer evidence needs the underlying answer or file access, and no automatic evidence-to-control mapping is asserted from a framework definition alone.

Operation and limits

Scheduled and manual runs share a lock, and pause/resume is available with the other source controls. Each run scans current API records and unchanged snapshots are deduplicated. The last successful run is recorded only after collection completes; a failed run keeps completed snapshots and reports a partial result, and the next run scans again.

Going deeper: bounds, failures and retention

Pages, response sizes, request timeouts and run duration are bounded. HTTP 429 or other API failures end the run without an immediate retry loop; review the error and wait for the next scheduled run or run it manually later. For large accounts, adjust page and run limits deliberately, because repeated early failures can prevent reaching later records until the underlying problem is resolved.

Standard Keen redaction applies before persistence, including native imported text. Snapshot artefacts use the configured local or S3 storage and existing evidence-retention rules. Native vendors, assets and risks have their own lifecycle; purging events does not delete these ISMS records.

API reference: Risk Ledger API, suppliers, risks and control lookup.