Security Policy Manual

Zoi provides a robust policy engine designed for system administrators to enforce security and compliance across an organization. By using the policy object in the system-wide configuration file, you can restrict which packages are installed, verify their origins, and lock down user settings.

Policy Enforcement Mechanism

Policies can only be defined in the system-level config.yaml:

• Linux/macOS: /etc/zoi/config.yaml
• Windows: C:\ProgramData\zoi\config.yaml

Settings defined here are the "source of truth." When a policy field is marked as unoverridable, any attempts by a user to change that setting in their ~/.zoi/pkgs/config.yaml or a project-local config will be ignored.

Locking Down Configurations

The unoverridable flags allow you to freeze specific Zoi behaviors.

Registry Signing & Chain of Trust

Zoi's most powerful security feature is its ability to verify the entire state of a package registry using Git commit signatures. This prevents "Man-in-the-Middle" attacks where a malicious actor might try to push a tampered repo.yaml or malicious package definitions.

The Authority Mechanism

Trust is established by defining Authorities in your local configuration. An authority is a PGP fingerprint or key name that you trust to sign the registry.

# /etc/zoi/config.yaml
default_registry:
  handle: zoidberg
  url: https://gitlab.com/Zillowe/Zoidberg.git
  authorities:
    - "842293159C4B03357C8328D3A75793A3E674252E" # Official Zoidberg Key

When authorities are defined for a registry:

1. Zoi pulls the latest Git commits.
2. Zoi extracts the PGP signature from the latest commit (the HEAD).
3. Zoi verifies that the signer matches one of the fingerprints in your local authorities list.
4. If verification fails, the sync is aborted.

This ensures that even if the Git server is compromised, Zoi will refuse to process any package definitions that aren't signed by your trusted maintainers.

Audit Logging for Compliance

In enterprise environments, tracking who installed what and when is often a mandatory compliance requirement. Zoi's Audit Logging feature provides a tamper-evident record of all state-changing operations.

Configuration

Enable system-wide audit logging and lock it to prevent users from disabling it:

# /etc/zoi/config.yaml
audit_log_enabled: true

policy:
  audit_log_enabled_unoverridable: true

Log Storage and Viewing

Logs are stored in a structured JSON Lines format at ~/.zoi/audit.jsonl. Administrators and users can view the history using the zoi history command:

zoi history

Each entry includes:

• Timestamp: Precise date and time of the action.
• User: The system user who performed the action.
• Action: Install, Uninstall, or Upgrade.
• Metadata: Package name, version, repository, and registry origin.

Content Filtering (Allow/Deny Lists)

Administrators can control package installations based on names, sources, and legal compliance (licenses).

Package and Repo Filtering

• allowed_packages: If defined, Zoi will only install packages explicitly named in this list.
• denied_packages: A blacklist of packages that are prohibited.
• allowed_repos: Restricts installations to specific tiers (e.g. core, internal).
• denied_repos: Blocks specific tiers (e.g. test, archive).

License Compliance

Zoi uses SPDX identifiers to verify package licenses during resolution.

• allowed_licenses: Useful for ensuring only legally approved software (e.g. MIT, Apache-2.0) is used.
• denied_licenses: Blocks problematic licenses (e.g. GPL-3.0-only, AGPL-3.0-or-later).

Mandatory Signature Verification

For maximum security, you can enforce that Zoi only installs pre-built archives that have been digitally signed by your organization's trusted keys.

policy:
  signature_enforcement_unoverridable: true
  signature_enforcement:
    enable: true
    trusted_keys:
      - MyCorp-Release-Key
      - 842293159C4B03357C8328D3A75793A3E674252E # Admin Fingerprint

When enable is true:

1. Zoi will search for a .sig file for every .pkg.tar.zst archive.
2. It will verify the signature against the local PGP keyring.
3. If verification fails or the signature is missing, installation is aborted. Zoi will not fall back to building from source.

Enterprise Best Practices

1. Centralized Mirroring

Use default_registry_unoverridable to point Zoi to an internal Git mirror of Zoidberg. This allows you to audit package definitions before they reach your developers.

2. Disabling Raw Git Sources

In enterprise environments, raw Git sources (@git/) are a security risk as they bypass the registry's audit trail. Set git_repos_unoverridable: true and leave the git_repos list empty to disable this feature.

3. Automated Key Distribution

While you can distribute PGP public keys via a Zoi Extension, the most secure way to establish a Root of Trust is by embedding keys into the binary.

By placing your organization's .asc files in src/pkg/pgp/builtin/ before building Zoi, you ensure that every client starts with the necessary keys to verify your private registry, without requiring any manual setup.

Example: "Hardened" Configuration

This configuration enforces a "Private Registry Only" policy with strict license and signature checks.

# /etc/zoi/config.yaml

default_registry:
  handle: corp-db
  url: https://git.mycorp.internal/zoi/registry.git

repos:
  - core
  - security-tools

policy:
  # Lock the environment
  default_registry_unoverridable: true
  repos_unoverridable: true
  git_repos_unoverridable: true
  allow_deny_lists_unoverridable: true
  signature_enforcement_unoverridable: true

  # Security enforcement
  signature_enforcement:
    enable: true
    trusted_keys:
      - Security-Dept-Root-Key

  # Compliance
  allowed_licenses:
    - MIT
    - Apache-2.0
    - BSD-3-Clause

  denied_packages:
    - telnet
    - rsh-client