NVIDIA / NVIDIA/OpenShell

bug: align empty network binary scope semantics

Open
#3,476 0 comments 0 reactions 1 assignee View on GitHub

@pimlock is already working on this.

Since Sep 19, 2026.

area:policy topic:l7 topic:networking
Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

User Story

As an OpenShell policy maintainer, I want empty and omitted binary scopes to have one documented and enforced meaning, so that policy tooling and runtime authorization agree.

Problem Statement

OpenShell currently assigns two meanings to an empty NetworkPolicyRule.binaries list:

  • Policy merge, coverage, advisor reconciliation, L7RuleTarget.any_binary, and related documentation treat it as "any binary."
  • Runtime OPA enforcement requires a binary entry to match, so an empty list matches no binary and denies access.

The authored YAML schema defaults an omitted binaries field to an empty list and canonical serialization omits empty lists. Empty and omitted therefore cannot be distinguished later.

This issue is a low-urgency tracking item for follow-up next week, primarily to preserve the investigation and resolve the documentation and contract ambiguity.

Impact / Why This Matters

The disagreement can produce false-positive control-plane behavior. Coverage checks or the policy advisor may report that a binary authorization is present and loaded while the live proxy still denies it. Users reading the incremental-update documentation may also expect an empty list to authorize every binary.

The current workaround is to always provide an explicit, nonempty binaries list. That avoids the ambiguity but does not fix existing policies, advisor behavior, or misleading documentation.

Acceptance Criteria

  • Decide and document the canonical meaning of an empty or omitted binaries list.
  • Align runtime enforcement, policy merge and coverage logic, advisor reconciliation, CLI and SDK contracts, and published documentation with that decision.
  • Clarify or revise L7RuleTarget.any_binary according to the chosen representation.
  • Add tests covering explicit binaries, binaries: [], omitted binaries, and incremental L7 updates.
  • Ensure coverage and reload reporting cannot claim authorization that runtime enforcement denies.

Reproduction Steps

  1. Start a Docker-backed OpenShell gateway and sandbox.
  2. Apply a policy allowing index.crates.io:443 for /usr/bin/curl and confirm the request succeeds.
  3. Replace the binary list with binaries: [] and wait for policy activation.
  4. Repeat the request and observe that the runtime denies it.
  5. Apply the same policy with the binaries field omitted. The gateway reports the policy unchanged because it canonicalizes identically, and the runtime still denies it.
  6. Compare this result with binary_scope_covers, policy_covers_rule, merge handling, and the --any-binary documentation, which treat the empty list as any binary.

Environment

  • OpenShell: current main checkout on 2026-09-18
  • Runtime: Docker-backed standalone gateway with locally built gateway, supervisor, and sandbox binaries
  • Sandbox image: ghcr.io/nvidia/openshell-community/sandboxes/base:latest

Logs

RESULT label=explicit status=0 expected=allow
RESULT label=empty status=7 expected=deny
Policy unchanged (same hash after changing empty to omitted)
RESULT label=omitted status=7 expected=deny
LIVE_TEST_PASS

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.