nordisk/holger

4. The RON

Holger is configured by one RON file, holger.ron. The first holger start writes one to ~/.holger/holger.ron (or $HOLGER_DATA/holger.ron); holger start --config <file> runs another.

An unknown key stops the start. Every block refuses a key it does not know, by name. A key Holger does not understand is a key it does not honour, and the worst case is a security control that reads as on in the file and is off in the process (server/lib/src/lib.rs, the root struct Holger; read_ron_config).

The blocks

Naming steps: and promotion: together is refused.

sources

sources: is a list. Each entry has a name, a kind and the fields its kind takes (server/lib/src/sources.rs, Source and SourceKind).

The fields of a pull-through source: url, credential: (username, password_env | password_file), select, max_files, platforms (OCI), max_bytes, refresh_secs, wait_secs (how long a request waits for its pull), gates and auto_approve.

gates

gates: on a source, and steps.gates (the defaults every source starts from). Every field is optional (sources.rs, Gates):

• provenance: require(identity: (issuer, subject), slsa_min: 2) | prefer | off
• sbom: require | off
• malware: on | off
• license: (deny: ["AGPL-3.0-only", …])
• cve: (max: info | low | medium | high | critical)
• secrets: block | warn | off
• block_formats: [ … ]

A gate may only tighten the floor. A gate that would loosen it, such as provenance: off under require_signed: true or cve: (max: critical) under cve_max: high, stops the load by name, with the rule it breaks. An artifact's effective policy is the floor plus its source's gates. It is fixed at ingest and shown by GetArtifactState, /-/intake/state and the audit trail.

rules: the floor

rules: is the global floor. Every field's default is the security gateway's default, so writing one rule never loosens another (sources.rs, Rules and its Default):

steps

steps: is the intake chain (sources.rs, Steps):

• incoming, quarantine, approved, production: the four repositories (those names are the defaults);
• scan: [...]: the scanner kinds that must report for every artifact (the floor adds its own);
• approvals: distinct approvers APPROVED needs, never the importer. Default 2. approvals: 1 is a choice the file writes down;
• transitions, inspect, advisory_db, allow_licenses, unknown_license (Hold by default, Block or Pass), trust_policy (the bundle trust policy of the import doors), npm, oci_push, secrets: (rules: "<file>"), sandbox, gates.

pull_through

The internet sources pulled through the steps, with their own floor (server/lib/src/pull_intake/mod.rs, PullThroughSettings):

pull_through: Some((
    sources: [
        (name: "pypi",  kind: python, url: "https://pypi.org/simple/"),
        (name: "npmjs", kind: npm,    url: "https://registry.npmjs.org/"),
        (name: "central", kind: maven, url: "https://repo1.maven.org/maven2/"),
        (name: "crates-io", kind: crates, url: "sparse+https://index.crates.io/"),
        (name: "goproxy", kind: go,   url: "https://proxy.golang.org/"),
        (name: "cgr",   kind: oci,    url: "https://cgr.dev", platforms: ["linux/amd64"]),
    ],
    rules: (cve_max: high),
    retry_after_secs: Some(2),
)),

The kinds are python, oci, npm, maven, crates, apk and go. retry_after_secs is the Retry-After a client gets while a pull is in flight (default 2 s). The pull-through needs the online build. The field test of 2026-11-01 ran these sources against the real registries with real clients. Clients reach a source at /production/<name>/ (chapter 3).

intel

The local advisory database the vulnerability scan reads (server/lib/src/intel.rs, IntelConfig). A scan never dials; it reads only this database.

network

network: is Auto when absent (server/lib/src/egress.rs, NetworkMode):

• Auto resolves at the start: Offline when the config names nothing that dials, Online when it names an upstream (a pull-through source with a url, a mirror, a twin's primary, a sync upstream, the intel feeds) or the build is an estate box. The start says which, and why.
• Online: upstreams, mirrors and twins may dial out.
• Offline: no outbound call at all. The start refuses a config that needs the network, and every dial is refused before a socket is opened.

In a downstream build, network: Offline that also names an upstream is refused at the start (holger-offline-2): an offline downstream makes no network call at all (chapter 10).

The one-way and export keys

• boundary: OneWay | Fetch: omitted, a downstream build is OneWay; Fetch needs the fetch build (chapter 8).
• domain: "<label>": printed by start and the CLI verbs, sent as X-Holger-Domain on every HTTP and gRPC answer, and shown in the console's top bar (holger-boundary-3 if it is not a label).
• trust: (first_import: Admin): the first import needs an admin's grant.
• export: Some((push_to: Some("<dir>"), every: "5m", vendor: "holger", product: "packages", signer_dir: None, expires_days: 30)): push signed bundles into a drop folder (the defaults shown; refused on a one-way downstream, holger-export-1).

Endpoints

Off loopback an endpoint needs an authentication method (else holger-listen-1) and ron_tls, or insecure: true where something else encrypts the wire (else holger-listen-2). ron_admin_url, ron_admin_http_url and ron_admin_allow put the admin plane on its own listener; ron_tls.crl checks client certificates against a CRL (chapter 10).

An example

(
    exposed_endpoints: [ (ron_name: "door", ron_url: "127.0.0.1:50051", ron_http_url: Some("127.0.0.1:8080")) ],
    storage_endpoints: [ (ron_name: "disk", ron_storage_type: "znippy", ron_path: "/var/lib/holger/store") ],
    repositories: [
        (ron_name: "incoming",   ron_repo_type: "raw", ron_upstreams: [], ron_in: None, ron_out: Some((ron_storage_endpoint: "disk", ron_exposed_endpoint: "door")), ron_data_dir: Some("/var/lib/holger/incoming")),
        (ron_name: "quarantine", ron_repo_type: "raw", ron_upstreams: [], ron_in: None, ron_out: Some((ron_storage_endpoint: "disk", ron_exposed_endpoint: "door")), ron_data_dir: Some("/var/lib/holger/quarantine")),
        (ron_name: "approved",   ron_repo_type: "raw", ron_upstreams: [], ron_in: None, ron_out: Some((ron_storage_endpoint: "disk", ron_exposed_endpoint: "door")), ron_data_dir: Some("/var/lib/holger/approved")),
        (ron_name: "production", ron_repo_type: "raw", ron_upstreams: [], ron_in: None, ron_out: Some((ron_storage_endpoint: "disk", ron_exposed_endpoint: "door")), ron_data_dir: Some("/var/lib/holger/production")),
    ],
    sources: [
        (name: "team", kind: upload, gates: (license: (deny: ["AGPL-3.0-only"]), cve: (max: medium))),
    ],
    steps: (approvals: 2),
    rules: (require_signed: true, require_provenance: true, slsa_min: 2),
)

The README's guide "Three products by hand" has a complete server RON with tokens, duties, the evidence signer and intel (chapter 3).

The flow picture

Holger draws the artifact flow from the running RON: the sources, the steps, the repositories, the gates, the estate (console, front, main, twin, every downstream by name) and a counter on every box. The fetches, bytes sent, pullers and promotion counters are the audit index's aggregates; a server without a readable audit log shows "not recorded". It has three zoom levels of one model: with no open it draws the machines and the upstream sources, ?open=main,lab-1 unfolds those machines with their part of the RON, and ?open=all is the full RON. It is served as GET /-/flow.svg (the model as JSON at GET /-/flow.json, schema holger.flow/v2), over gRPC as AdminService.FlowSvg (FlowSvgRequest.open), and by holger-cli flow (server/lib/src/flow.rs). The console's Flow page shows it (chapter 11).

Moved from v1

• The source kinds, gates, steps and the default floor of v1/README-v1.md, checked against sources.rs.