Skip to main content

Risk Navigator Customization Guide (Company Overlay)

This guide explains how companies can customize Risk Navigator while staying aligned with upstream spec and UI behavior.

Goals​

  • Keep the viewer and dataset contract stable.
  • Replace input connectors with company-specific data sources.
  • Add enterprise metadata (owners, maintainers, org hierarchy) for better prioritization.
  • Maintain a local build that can track upstream updates safely.

1. Data responsibilities​

Each company should supply:

  • Project inventory (service/app/repo identifiers, project refs, releases).
  • Dependency edges per project (direct vs transitive).
  • CVE mapping source:
    • external (OSV + KEV + EPSS), or
    • internal merged catalog (if your security platform already unifies these).

The output requirement does not change:

  • Build data/<scope>.json compatible with the schema in SPEC.md section 4.1.

If this contract is preserved, the site behavior remains largely the same.

Add fields and joins that improve enterprise actionability:

  • owner and maintainer identities,
  • department / BU / platform team mappings,
  • org-chart hierarchy keys,
  • criticality and regulatory tags,
  • internal ticketing IDs or application portfolio IDs.

These should enrich filtering and reporting without breaking base fields used by the UI.

Project grouping guidance:

  • Default/demo behavior should use neutral heuristic grouping (not implied org departments).
  • Enterprise overlays should map projects to true org structures (department/BU/platform) and set grouping mode accordingly.

3. Pipeline adaptation strategy​

Keep the same high-level phases:

  1. Ingest vulnerability intelligence.
  2. Ingest org/project/dependency graph.
  3. Join + normalize to Risk Navigator schema.
  4. Validate and publish dataset(s).

You may fully replace extract/ingest adapters, but keep the join output contract stable.

Use an overlay repo with upstream as a submodule.

  • Upstream submodule: this Risk Navigator project.
  • Overlay repo: internal adapters, environment config, secrets handling, CI wrappers, deployment automation.
  • Pin a known upstream commit/spec version.
  • Upgrade upstream intentionally and run schema/visual regression checks.

This mirrors proven FINOS overlay patterns used in TraderX customization.

Reference architecture guidance:

5. Suggested overlay layout​

your-company-risk-nav-overlay/
  upstream/
    risk-nav/                 # git submodule pinned to upstream commit
  adapters/
    extract_from_internal_cmdb.py
    extract_dependency_edges.py
    ingest_internal_vuln_feed.py
  config/
    environments/
      dev.yaml
      prod.yaml
  pipelines/
    build_scope.sh
    refresh_external_signals.sh
  tests/
    test_schema_contract.py
    test_company_enrichments.py

6. Versioning and upgrade discipline​

  • Record the upstream commit SHA and spec version used by each release.
  • Keep a changelog of local customizations.
  • On upstream update:
    1. bump submodule,
    2. rerun pipeline,
    3. validate schema contract,
    4. validate UI workflows (filters/modes/top-fixes/cart/help docs).

7. Minimum acceptance checklist​

  • Dataset validates against schema contract.
  • Direct/transitive counts are correct and consistent.
  • Project references and ownership mappings render correctly.
  • Top fixes and detail panes still produce readable/structured output.
  • OpenRewrite cart behavior is clear (direct dependencies in current iteration).