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.

Security Advisory Enforcement

Zoi's policy engine can be used to enforce safety standards based on the decentralized security advisory system.

Automated Vulnerability Checks

By default, Zoi warns users when they attempt to install a package with a known vulnerability. In a hardened environment, you can lock this behavior:

# /etc/zoi/config.yaml
policy:
  advisory_enforcement_unoverridable: true

When this policy is active, Zoi will always check the local advisory database during install and update operations. While users can still choose to proceed after a warning (unless further restricted), the check itself cannot be disabled.

Auditing for Compliance

Administrators can use the zoi audit command to generate compliance reports for all machines in an organization.

# Audit all machines and save to a central log
zoi audit --all --registry zoidberg > security_report.txt

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.json. Administrators and users can view the history using the zoi history command:

zoi history

# Verify log chain integrity
zoi history --verify

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).

Package rules can be written as:

• name (e.g. hello)
• name:sub_package (e.g. linux:headers)
• @repo/name (e.g. @core/hello)
• @repo/name:sub_package
• #registry@repo/name (for explicit registry scoping)

Repo rule matching behavior:

• If a rule contains /, it is treated as an exact repo path (e.g. community/editors).
• If a rule does not contain /, it matches any repo segment with that name (e.g. community matches community/editors).

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).

License matching behavior:

• allowed_licenses evaluates SPDX expressions; MIT OR GPL-3.0-only is allowed if at least one branch is allowed.
• denied_licenses blocks if a denied SPDX identifier appears in the package expression.

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