Skip to content

D46 adversary review: design gaps to decide before the restructure (plugin loader, gate isolation, signed-vs-reviewed) #48

Open

Description

@djbclark

Summary

A post-hoc adversary security review of merged PR #46 (D46: plugin layout and plugin trust), at head 40cf93a, gave the verdict BLOCK: needs a design change before the restructure. No release pipeline exists yet, so nothing can be exploited today. These are design gaps that the restructure (the plugin loader) and Step 6 (the release pipeline) would otherwise build in. #46 was merged without the adversary verdict required before a PR; this issue records that review.

Decide before or in the restructure PR

  • D-a (F5). How the loader proves a plugin is in-tree: by where its module file sits under the gate-1-verified tendcf tree, not by distribution name or metadata. Supervisor renderers are found through a static import table, never through entry points.
  • D-b (F4). Nix evaluation limits: restrict-eval or pure-eval, no import-from-derivation, empty allowed-uris, no network. Either a Guix sandbox, or a rule that foreign and site-shared inputs are YAML/JSON data only.
  • D-c (F1). What "separate environment" means concretely: a different machine, VM or throwaway container, under an identity that can't read the key or write the gate tooling. The key could also live on a hardware token or a separate signer.
  • D-d (F2, F3). How what is signed is tied to what was reviewed.

Decided 2026-11-13: #48 (comment)

Findings

  1. F1 HIGH: the rule that gates and signing run apart from plugins can't be enforced as written.

    1. docs/architecture/plugin-layout.md:179-187 says the gates and signing run in "a separate environment", but docs/architecture/change-process.md:291 puts the targets key on the builder. A plugin running in gate 2 could:
      1. read the key file;
      2. tamper with the gate tool environment, for example with a .pth file;
      3. rewrite goal files between gates 3-5 and signing (a time-of-check to time-of-use gap);
      4. persist on the builder.
    2. In-tree plugins ship inside the single tendcf distribution, so no environment that installs tendcf is "plugin-free".
    3. The compiler and the gates share pyyaml, jsonschema and rfc8785 (compiler/pyproject.toml:12-16, bin/schema_lint.py:4, bin/projector.py:4), so one compromised dependency defeats both.
    4. The guide states the rule in the present tense.

    Fixes:

    1. Make the boundary concrete (D-c).
    2. Make gate 2's only output goal-file bytes plus digests, passed one way, and sign exactly the digests that were checked.
    3. Build the gate environment from the source tree with a hash-locked dependency closure, without installing the tendcf package.
    4. Mark the rule "planned, Step 6" in the guide, the map and plugin-layout.md.
  2. F2 HIGH: nothing ties what gets signed to what was reviewed.

    1. On operator hosts the only human check is the PR's preview diff (plugin-layout.md:175-177, guide:243-245). The merge run compiles again and signs whatever comes out. A plugin can tell the PR run from the merge run, and compiles aren't checked for being hermetic.
    2. Nothing requires site-private changes to go through a reviewed PR at all.

    Fixes:

    1. Compare each host's goal-file digest at merge with the digest from the approved PR, or promote and sign the PR's own artifacts.
    2. Use branch protection on site-private.
    3. Make the compile hermetic.
    4. Until then, call the preview diff advisory.
  3. F3 HIGH: a PR run executes code the PR chose, before review.

    1. Gate 1 checks rev/tree but not url (change-process.md:107-126, 265-271).
    2. A site-private PR can repoint the tendcf pin at a fork, so "in-tree" (plugin-layout.md:198-202) becomes whatever the attacker's tree contains.
    3. Gate 2 runs it in the PR's CI, which is possibly the signing host.

    Fixes:

    1. Run PR gate runs on throwaway runners with no key and no secrets.
    2. Treat these changes as privileged, needing the gate-5 ceremony marker: a changed url, a tendcf pin that doesn't descend from the previous one, and a changed plugin set.
    3. Optionally, allowlist the tendcf URL.
  4. F4 MEDIUM-HIGH: frontend inputs are code.

    1. Nix and Guile recipes from site-shared and foreign sites run during compile.
    2. compiler/nix2cf/cli.py:155-160 runs nix-instantiate --eval --strict --json with no restrict-eval or pure-eval, so recipes can read files, fetch over the network, or use import-from-derivation.

    Fix: decide D-b and record it in plugin-layout §4 before the Nix frontend moves.

  5. F5 MEDIUM: entry-point collisions and dependency confusion.

    1. importlib.metadata.entry_points() drops a second distribution with the same name before listing entry points, so "a duplicate name is a compile error" (plugin-layout.md:189-202) never fires for a second distribution called tendcf.
    2. The PyPI names tendcf and nix2cf were unregistered on 2026-11-13. Placeholders are being registered; see the comment below.
    3. A private entry-point group for supervisors could be shadowed.
    4. The order of activation rules 1-3 is undefined.

    Fixes:

    1. Decide D-a.
    2. Define the activation algorithm: list every entry point without the by-name deduplication; refuse any duplicate name, and any non-tendcf entry point that uses a reserved name; then load only the named entry points.
    3. Release builds never resolve tendcf from an index.
  6. F6 MEDIUM: "installing a package activates nothing" is false.

    1. .pth files and sdist build backends run during install.
    2. Checking a hash at load time against the installed RECORD file proves nothing.
    3. Plugins' dependency closures aren't pinned.
    4. The gate tools resolve their dependencies from PyPI each time they run.

    Fixes:

    1. Reword rule 1 as "an unnamed plugin is not selected".
    2. Check hashes at install time from a hash-locked resolution, wheels only.
    3. Pin each plugin's dependency closure.
    4. Lock the gate tools' dependencies (uv lock --script) and run them offline.
  7. F7 MEDIUM: folding the compiler in removes the producer/checker independence.

    1. One tendcf commit can change both the compiler and its gates.
    2. Rolling the pin back also rolls back gate fixes.
    3. Nothing defines a rollback across a schema_version bump.

    Fixes:

    1. Treat changes to tools/, schema/ or the projector in a tendcf bump, and any backwards pin move, as privileged.
    2. Add CODEOWNERS for schema/, tools/ and policy/.
    3. Define or forbid rollback across a bump.
    4. List this cost in change-process §9.
  8. F8 LOW-MEDIUM: confidentiality is mentioned but not bounded.

    1. A plugin or recipe can copy host A's private data into a schema-valid string field of host B's goal file.
    2. Nothing in gates 3-5 looks for that.

    Fixes:

    1. Say this in the trust section.
    2. Have the projection lint check for values from other hosts' slices.
    3. Say who can read the release store.
  9. F9 LOW: some properties are stated flatly though nothing enforces them yet.

    1. Device-side validation, the activation loader and the gate separation are all unbuilt.
    2. TENDCF_DIR (compiler/nix2cf/cli.py:62-77) lets the environment choose which projector is executed.

    Fixes:

    1. Tag each claim "planned" where it is stated.
    2. Pin or refuse TENDCF_DIR in release builds.
  10. F10 LOW: activation leaves out importers and changes to the plugin set.

    1. No rule says which importer an operator may run.
    2. A changed plugin set is recorded but isn't a gate, so a "sleeper" plugin can be named now and change behaviour later.

    Fixes:

    1. Apply the same naming and pinning rules to importers.
    2. In gate 5, compare the plugin set with the previous release's.

Not covered by #47

The seven items #47's scope is missing are posted as a comment there.

Related: #46, #47, tracker #1.

🤖 Generated with Claude Code

Activity

  1. djbclark commented on Nov 13, 2026

    @djbclark
    CollaboratorAuthor

    F5 part 2 is done: the PyPI names are now reserved with 0.0.0 placeholders (no code, README points here) at https://pypi.org/project/tendcf/ and https://pypi.org/project/nix2cf/. The rule that release builds never resolve tendcf from an index (D-a / F5 fix 3) still stands.

    🤖 Generated with Claude Code

  2. djbclark commented on Nov 13, 2026

    @djbclark
    CollaboratorAuthor

    Decisions D-a to D-d (djbclark, 2026-11-13)

    These go into a docs PR that amends D46 and docs/architecture/plugin-layout.md §4/§7. That PR gets Astra, Fable and adversary reviews before it opens. The restructure stays blocked on that PR and on #41/#42.

    D-a (F5): in-tree proof.

    1. A plugin is in-tree when its module's realpath sits under the gate-1-verified tendcf tree.
    2. Every in-tree plugin (frontends, supervisors and importers) is found through a static import table, never through entry points.
    3. Entry points are read only for third-party plugins, after Plugins: OpenPGP web of trust and paseo-style tendcf plugin management #47:
      1. list every entry point, with no deduplication by name;
      2. refuse duplicate names and reserved names;
      3. load only the plugins site-private names.

    D-b (F4): frontend inputs are code.

    djbclark: "I want people to be able to easily share configurations, but they should be security-scanned before running them, including doing so with the help of AI. We can have a soft requirement that access to AI be present whenever an external import is attempted."

    1. Import, not fetch. External recipes (site-shared or foreign) are imported, never fetched at compile time. The import pins a recipe by content digest, runs a static scan and an AI review, and records the verdict with the pin.
      1. The static scan looks for network access, file reads outside the recipe, import-from-derivation, and exec-style escapes.
    2. Compile. Compile evaluates only pinned recipes whose recorded verdict matches their digest. Any change to a recipe means a new import and a new scan.
    3. Nix limits. Every Nix evaluation, own-site included, runs under restrict-eval (pure-eval where it works), with no import-from-derivation, empty allowed-uris and no network. The exact flags get tested in the docs PR.
    4. Guix. No Guix frontend until it has its own sandbox design.
    5. No AI reachable at import. The static scan still runs. The import needs an explicit operator acknowledgement, recorded in the pin as "reviewed by hand, no AI". The next import with AI present scans it again.
      1. djbclark: "Do 1, but make a toml config file option (or whatever format we are using) to allow different options/override and doc that."
      2. Setting: external_import.without_ai = require-human-ack (the default), warn or refuse.
      3. It lives in the site-private file that names plugins. That file's format is still open (plugin-layout §7); TOML unless decided otherwise.

    D-c (F1): what "separate environment" means.

    djbclark: "3, but we want to leave the unix user as a non-default option in the first real release."

    1. Interim. A separate Unix user on the builder holds the key and the gate tools.
    2. Default before the first real release: a two-job split.
      1. Job A runs on a throwaway runner with no secrets. It compiles, runs gate 2, and uploads the goal-file bytes plus a digest manifest.
      2. Job B runs in a protected signing environment. It builds the gate tools from the pinned source with hash-locked dependencies, without installing tendcf. It runs gates 3-5 and signs exactly the digests it checked.
    3. Signer backends in the first real release:
      1. the two-job CI with the key held as a GitHub environment secret: the default (lead's assumption: the dedicated signer VM variant was not chosen);
      2. a separate Unix user: a non-default option;
      3. a hardware token on the operator Mac: a non-default option, never required.
    4. Tag the rule "planned, Step 6" wherever it is stated.

    Cost shown when deciding: the two-job split is about 1-2 agent-days of work plus about $0.03 per release (Linux 2-core at $0.006/min, GitHub docs checked 2026-11-13). The Unix user is about half a day and $0, but it leaves persistence and pre-signing tampering open.

    D-d (F2, F3): binding what is signed to what was reviewed.

    1. Promote the PR's own artifacts. The PR run, on a throwaway runner with no secrets, produces goal files and a digest manifest, and reviewers approve that preview.
    2. At merge. If the merged tree equals the approved PR head tree, sign exactly those digests. Otherwise run the gates again and review again.
    3. Branch protection goes on site-private.
    4. Privileged changes. A changed pin url, a pin that does not descend from the previous one, or a changed plugin set requires the gate-5 ceremony marker.

    🤖 Generated with Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions