Managed · Managed configuration

Managed configuration

A company can set one policy for every machine of its fleet: a managed.toml file, placed by an administrator (Ansible, a package, an MDM), that every Lock and lox read. The user can make a rule stricter in their own files, never looser, and no one can approve a loosening beyond it in lox run: the managed file is above the human at the console.

This page is for the administrator who writes, signs and deploys that file. It needs no code reading: every key, every refusal line and every command below is the released tools' own.

An older release ignores the file: see older tools.

• Where the file lives
• Trust
• Fail closed
• Rule kinds and precedence
• Violations
• Sections: top level and [family], [locksql], [lockmq], [lockssh], [lockfile], [lockhttp], [locklog], [lox], [lea]
• Example
• Commands
• Signing
• Deploying: Ansible, Debian and rpm packages, macOS
• Verifying a deployment
• Troubleshooting

The recipes and the example are in examples/managed/.

Where the file lives #

One directory for the whole family, with one section per tool, one fingerprint in the audit and one signature:

Windows comes when the family supports it. No environment variable or flag moves the file in a release build, so that a user cannot point a tool at a looser file. No file means no managed policy: every tool runs as without this page.

Locks in containers #

lox run reads the host's file and copies it into a volume mounted read-only at /etc/lockfamily in every Lock's container, whatever the host OS, beside the Lock's profile. When the file is signed, lox checks the signature on the host (a container has neither cosign nor the network for it) and adds signer.toml, the bundle and managed.toml.verified, a stamp of the three files the Lock trusts instead of calling cosign. Each Lock's own launcher (locksql, lockmq, … run outside lox) mounts the host directory read-only at the same place.

Trust #

• Ownership is mandatory. managed.toml, signer.toml and their directory must be owned by root (uid 0) and writable by root only (no group or other write bit). The file must be a regular file: a symbolic link is refused. A badly owned file or directory is a refusal to start, never a file ignored: breaking the file must not lift the policy.
• The signature is optional. When managed.toml.sigstore.json sits next to the file, it is verified with cosign against the identity in signer.toml; present and invalid is a refusal to start. Only keyless signing is supported, and cosign must be on the host's PATH. [family] require_signature = true makes the bundle mandatory.
• Fingerprint. The sha256 of the file's bytes is recorded with every approval (managed_sha256 in the console's approved policy, managed_fingerprint in lox's applied.json) and in every audit record, so an action can be tied to the company policy it ran under.
• No secrets. A key that looks like a secret (token, password, …) is refused: the file is readable by every user of the machine.

Remote distribution (managed_url) is for v2: in v1 the administrator places the file.

Fail closed #

A managed file that is present but not valid is a refusal to start, never a file or a key dropped. Each of these refuses:

• a file that is not valid TOML;
• version missing or other than 1;
• an unknown top-level section, or an unknown key in [family] or in the tool's own section;
• a value of the wrong type or out of its range (a string for a bool, a bad duration, an unknown tier or TLS mode);
• a default outside the bounds;
• a managed profile that itself violates the bounds.

While a console runs, it reads the file again at every policy check (2 s): a file that becomes unreadable or invalid ends its session.

Strictness per section #

Every tool checks the top level, [family], and that every top-level section names a tool of the family: locksql, lockmq, lockssh, lockfile, lockhttp, locklog, lox, lea. It decodes only its own section strictly: a typo in [lockmq.bounds] makes lockmq refuse to start, not locksql. A Lock's section may only hold bounds, defaults and profiles.

Older tools #

A release that predates managed support does not read the file at all and runs on the user's files alone. To keep such releases off the fleet, set [lox] image_min to the first managed release of each Lock (the table at the top of this page): lox then refuses to run an older image. An image too old to have managed check is not started when the file has a section for it: locksql v0.17.2 predates managed support: upgrade it or set [lox] image_min.

Rule kinds #

Every Lock's section has up to three tables:

An enforced value is a bound with a single allowed value (for example credentials = ["vault"]). There is no separate table for it.

Bounds #

A bound uses the name of the profile field it limits, as the tool's own config file spells it. The Lock compares each profile with the bounds through its own policy diff, the one that already marks a change as loosening in the console, so each Lock decides what "looser" means for its fields. The kinds that recur:

• ceiling: an ordered value (a tier, a limit, a duration) may be lower, not higher. tier = "write" allows read and write. A duration or a size beyond its bound is refused, never shortened silently; a bounded field left unset is often looser (credentials_ttl unset means the whole session, beyond any bound);
• floor: the reverse (tls, limits.k_anonymity): tls = "verify-full" allows only verify-full;
• allowed list: the profile's value must be in the list (credentials = ["vault", "ask"] forbids keychain); hosts is a list of host patterns (*.db.example.internal);
• required list: every entry must be in the profile (lockhttp deny, detectors);
• additive rules: managed PII masks and detectors are added to every profile; the user can add rules, not remove one, and a user allow rule that would show what a managed mask hides is refused.

Defaults #

A default replaces the built-in value of a field when neither the user's nor the project's file sets it. It has the same names as a profile key and must itself sit within the bounds.

Profiles #

A managed profile has the same keys as a profile of the tool's own config, and the managed defaults fill what it leaves unset. It wins as a whole: a user or project profile of the same name is refused (managed: profile "prod-erp" is provided by the company's managed configuration and cannot be redefined in the project config: rename yours). To use a company profile with stricter settings, define a profile of your own.

Precedence #

From the strongest to the weakest:

hard-coded floor (lockhttp's decide rules)
  > managed bounds and profiles
    > project file > user file
      > managed defaults > built-in defaults

The merged result is always checked against the bounds, whatever file a value came from.

Violations #

A violation names the managed key, the bound, the profile and its value, in one of these forms:

blocked by company policy: <key> = <bound> (profile <p>: <field> = <value>)
blocked by company policy: <key> does not allow <value> (profile <p>: <field> + <value>)
blocked by company policy: <key> requires <value> (profile <p>: <field> - <value>)

For example, from the released tools on the example:

blocked by company policy: locksql.bounds.tier = write (profile dev: tier = ddl)
blocked by company policy: lockmq.bounds.hosts = *.mq.example.internal (profile dev: url = rabbitmq.dev.example.org)
blocked by company policy: lockssh.bounds.exec = false (profile dev: exec = true)
blocked by company policy: lockfile.bounds.max_object_bytes = 10485760 (profile docs: limits.max_object_bytes = 52428800)
blocked by company policy: lockhttp.bounds.trusted does not allow github.com (profile default: trusted + github.com)
blocked by company policy: lockhttp.bounds.deny requires pastebin.com (profile default: deny - pastebin.com)
blocked by company policy: locklog.bounds.kinds does not allow sources.system.kind = journald (profile staging; allowed: file, loki)
blocked by company policy: family.vault.required = true (profile dev: credentials = ask)

• At start, a violation is a refusal with no Apply? prompt, audited refused-managed: a human cannot approve beyond the company policy. The console exits 3.
• While running, the console's policy check (every 2 s) refuses a loosening beyond the bounds and audits it refused-managed: it never becomes pending, and :review shows it as not approvable. A tightening by the user is accepted as today.
• When the managed file changes, it is read again at the same check and audited managed-changed. A policy in force beyond the new bounds is replaced at once by the files' policy when that one is within them (a changed connection field ends the session, as any tightening), else the session ends. In lox run, a change of the managed file alone recreates the Locks without an Apply? question: the administrator decided it.
• In lox run, each Lock's managed check runs on its reviewed profile before the Lock starts. A Lock beyond the bounds is not started, the others are: lock crm: not started: blocked by company policy: locksql.bounds.tier = write (profile p: tier = ddl) (the other locks are).

Sections #

Top level and [family] #

These apply to every tool:

[locksql] #

[locksql.bounds]:

[locksql.defaults] and [locksql.profiles.<name>] take the profile keys of locksql's configuration, limits.* included.

[lockmq] #

[lockmq.bounds]:

[lockmq.defaults] and [lockmq.profiles.<name>] take the profile keys of lockmq's configuration.

[lockssh] #

[lockssh.bounds]:

[lockssh.defaults] and [lockssh.profiles.<name>] take the profile keys of lockssh's usage, limits.* and auto included (lockssh's managed keys).

[lockfile] #

lockfile's limits are flat keys, as in its config file. [lockfile.bounds]:

[lockfile.defaults] takes the profile keys plus max_workspace_bytes; [lockfile.profiles.<name>] takes exactly the profile keys of lockfile's configuration. lockfile has no PII rule to add.

[lockhttp] #

[lockhttp.bounds]:

hold and inject cannot be bounded: either key in [lockhttp.bounds] is refused. Managed rules are evaluated above the user's:

• a managed deny is refused like the deny list: no rule, grant or shadow mode lifts it;
• a managed ask makes a request that would pass, or that auto mode could answer, wait for a human; a stricter decision stands (a user deny, the floor);
• at the domain (a CONNECT not decrypted), a managed rule with methods or a path asks, since the gate cannot see the requests the tunnel carries.

[lockhttp.defaults] takes mode, heuristics, buffer_limit, hold (5m at most), connect_grant, idle_timeout, max_session and production. [lockhttp.profiles.<name>] takes the keys of a [profiles.<name>] table of lockhttp's configuration. [family] vault has no effect on lockhttp.

[locklog] #

[locklog.bounds]; a scalar bound takes only the value shown:

[locklog.defaults] takes the scalar profile keys, auto and limits.*, not sources. [locklog.profiles.<name>] takes every profile key, sources included, of locklog's usage.

[lox] #

lox reads the host's file, shows it in the review (managed: Example Corp sha256:… signed), applies [family] vault, runs each Lock's managed check and mounts the file in the Locks' containers (Locks in containers). A file lox refuses stops lox run before anything starts, with exit code 3.

[lea] #

Planned: lea does not read the managed file yet. Its keys are designed in lea#399 and this page documents them when it is released. Today every tool accepts a [lea] section and none applies it: do not count on it.

Example #

The same file is examples/managed/managed.toml. Every released tool of the table at the top of this page reads it (<tool> managed show exits 0) and accepts the profiles within it.

# /etc/lockfamily/managed.toml
version = 1
organisation = "Example Corp"

[family]
require_signature = false
vault = { address = "https://vault.example.com", required = true }

[locksql.bounds]
tier = "write"                       # never ddl or admin
tls = "verify-full"
credentials = ["vault"]
hosts = ["*.db.example.internal"]
credentials_ttl = "8h"
write_functions = "allowlist"
auto = { ddl = "deny", unmask = "ask" }
detectors = ["email", "iban"]
limits.max_rows = 10000
limits.max_session = "8h"

[[locksql.bounds.pii_mask]]
column = "*.*.email"
mode = "email"

[locksql.defaults]
limits.statement_timeout = "30s"

[locksql.profiles.prod-erp]          # provided and locked
engine = "postgres"
host = "erp.db.example.internal"
database = "erp"
tls = "verify-full"
tier = "read"
production = true
credentials = "vault"
vault_path = "database/creds/erp-readonly"
credentials_ttl = "1h"
write_functions = "allowlist"
auto = { ddl = "deny", unmask = "ask" }  # within locksql.bounds.auto

[lockmq.bounds]
tier = "read"                        # never peek
tls = "verify-full"
credentials = ["vault"]
hosts = ["*.mq.example.internal"]
auto = { purge = "deny", delete = "deny", publish = "ask" }
limits.read_max = 100

[[lockmq.bounds.pii_mask]]
queue = ["*/*"]
body = "$.customer.email"

[lockssh.bounds]
hosts = ["*.example.internal"]
known_hosts = "/etc/ssh/ssh_known_hosts"
auth = ["key"]
exec = false
auto = { connect = "ask", run = "ask", exec = "deny", unmask = "deny" }
limits.max_session = "4h"

[lockfile.bounds]
source = ["s3", "sftp"]
hosts = ["*.example.internal", "s3.eu-west-1.amazonaws.com"]
max_object_bytes = "10MiB"
marketplaces = ["official"]

[lockhttp.bounds]
mode = "enforce"                     # no shadow mode
trusted = ["*.example.com"]
deny = ["pastebin.com"]

[[lockhttp.bounds.rules]]
id = "no-prod-writes"
host = "api.example.com"
methods = ["POST", "PUT", "PATCH", "DELETE"]
verdict = "ask"

[locklog.bounds]
kinds = ["file", "loki"]
unmask = "never"
detectors = ["email"]

[lox]
auto_max = { ddl = "deny", write = "ask", policy = "ask" }
production_auto_max = { read = "ask" }
allow_no_upgrade = false
image_min = { locksql = "v0.18.0", lockmq = "v0.9.0", lockfile = "v0.9.0", lockhttp = "v0.9.0", lockssh = "v0.2.0", locklog = "v0.3.0" }

Commands #

Every Lock has two read-only commands; neither connects nor asks for a credential:

managed check takes --project DIR in lockmq, lockssh and locklog, and --config FILE in lockhttp; lockfile and lockhttp exit 1 when the tool's own config file is missing. lockhttp's managed show starts at path:. Without a file, each prints no managed configuration and exits 0. lox run runs each Lock's managed check before it starts it; its output and exit codes are a contract. lox managed show on the example:

Managed by Example Corp (sha256:a7948fe2424a)
path: /etc/lockfamily/managed.toml
organisation: Example Corp
fingerprint: sha256:a7948fe2424ab232b7fa7505701e64f01a2e3bc9e707c0b1f1ce1279224aacd1
signed: no
lox:
  auto_max.ddl = deny
  auto_max.policy = ask
  auto_max.write = ask
  production_auto_max.read = ask
  image_min.lockfile = v0.9.0
  image_min.lockhttp = v0.9.0
  image_min.locklog = v0.3.0
  image_min.lockmq = v0.9.0
  image_min.locksql = v0.18.0
  image_min.lockssh = v0.2.0
  allow_no_upgrade = false
vault from the managed configuration ([family] vault): https://vault.example.com, required
sections: lockfile, lockhttp, locklog, lockmq, locksql, lockssh