03. Process Behaviour Policies (PBP)

A Process Behaviour Policy is the Agent Behaviour Policy model applied to a process. It is defined once, hashed, supplied from outside the agent, and enforced by the runtime, never by the process it constrains.

Policies are opt-in. With no policy supplied, sgit runs as 0.24.0 does: one process, no launcher, no components (05).

1. From ABP to PBP

ABP's four barrier kinds still apply: None, Expectation (prose), Setting (the subject can flip it), Boundary (enforced above the subject). For processes almost every line can be a Boundary, because the kernel enforces it. A process is the one case where unbounded excess can actually be driven to zero.

2. Who enforces decides the barrier kind

 platform / runtime ─── enforces ──►  agent ─── launches ──►  sgit-cli / fs / net / kms
        │                               │                        ▲
        │                               └── if the AGENT applies │ the locks: Boundary for the
        │                                   the locks, they are  │ components, but only a SETTING
        │                                   a Setting for itself │ for the agent (root can undo)
        └── if the PLATFORM applies them, they bind the agent too ──► Boundary all the way down

Prompt injection acts through the agent. So the agent must not be able to widen a policy. Two mechanisms:

1. The hash comes from outside. The person supplies the manifest hash out of band, or the manifest is signed by the root key (sha256:db7f79fdd87e030a). The launcher refuses anything else.
2. The platform enforces. End state: the agent hands the platform a manifest; the platform verifies the hash and applies it.

3. Fractal layers

The same schema at every layer and for every component. Each layer can only narrow the one above: the effective policy is the intersection.

 ┌─ L0 OS base ─────────────────────────────────────────────────────────────┐
 │  /usr /lib /etc ro; no device nodes; no raw sockets; no ptrace           │
 │ ┌─ L1 runtime: python 3.13 ────────────────────────────────────────────┐ │
 │ │  stdlib + site-packages ro; no pip; no compile cache writes          │ │
 │ │ ┌─ L2 application: sgit-ai 0.24.x (wheel hash pinned) ─────────────┐ │ │
 │ │ │  ~/.sg-send ro; vault server hosts; edges cli→fs, cli→net, net→kms│ │ │
 │ │ │ ┌─ L3 component: sgit-net ───────────────────────────────────────┐│ │ │
 │ │ │ │  egress only via proxy port; hosts send.sgraph.ai, kms host    ││ │ │
 │ │ │ │ ┌─ L4 subcommand: status ────────────────────────────────────┐ ││ │ │
 │ │ │ │ │  op=read only; endpoints GET …; no push                    │ ││ │ │
 │ │ │ │ │ ┌─ L5 invocation: this session, vault id X, folder /w ──┐  │ ││ │ │
 │ │ │ │ │ │  effective = L0 ∩ L1 ∩ L2 ∩ L3 ∩ L4 ∩ L5              │  │ ││ │ │
 │ │ │ │ │ └───────────────────────────────────────────────────────┘  │ ││ │ │
 └─┴─┴─┴─┴────────────────────────────────────────────────────────────┴─┴┴─┴─┘

Per-subcommand policies are where least privilege bites: status needs no write key, pki list needs only the key store, clone needs one host and one writable folder. One policy for "sgit" would have to cover its widest command.

4. Schema

Canonical JSON (RFC 8785, JCS) for hashing. Shown as YAML for reading.

pbp: 1
id: sgit-net/status
layer: subcommand
extends: [sha256:<L0>, sha256:<L1>, sha256:<L2>, sha256:<L3>]   # parents, by hash
subject:
  component: net
  code: { package: sgit-ai, version: 0.24.0, wheel_sha256: "…" }  # policy binds to what runs
  entry: [python3, -I, -m, sgit_ai.net]
identity:
  uid: ephemeral            # launcher creates sgit-net-<session>
  spiffe: spiffe://<session>/net
process:
  may_fork: false           # RLIMIT_NPROC=0
  may_exec: false           # seccomp: execve denied after start
  capabilities: []          # all dropped, bounding set empty
  no_new_privs: true
  dumpable: false
  max_memory_mb: 256
  max_runtime_s: 120
files:
  read:  [/usr, /lib, /lib64, /etc/ssl, /etc/hosts, <site-packages>]
  write: []                 # net never writes; fs does
  exec:  [/usr/bin/python3.13]
network:
  kernel:                    # what the kernel can see
    connect_tcp_ports: [<proxy port>, <kms port>]
  application:               # what sgit-net enforces as the TLS client
    hosts: [send.sgraph.ai]
    endpoints:
      - { method: GET,  path: "/api/vault/{vault_id}/…" }
    vault_ids: ["<X>"]
    redirects: deny
    ip_literals: deny
edges:
  accept_from: [cli]
  connect_to:  [kms]
syscalls: { allow: [read, write, openat, close, mmap, munmap, futex, epoll_wait, connect, sendto, recvfrom, getrandom, memfd_secret, keyctl, exit_group, …] }
business:
  ops: [read]               # KMS will be asked with op=read only
  require_fresh_approval_for: [write]
audit: { emit: [connect, kms_unwrap, deny], secrets: never }

Business rules for the other components follow the same shape:

• sgit-fs: write: [<clone root>]; refuse_content: [vault_key, pem_private_key, bearer_token] in .sg_vault/local/; symlinks: no-escape; exec_bits: strip.
• sgit-kms: files: {read: [], write: []} after start; network.kernel: {} (empty namespace); edges.accept_from: [net]; business: {ops: [unwrap, public, destroy], max_unwraps: 200, write_requires: approval}.
• sgit-cli: network: none; files.write: []; edges.connect_to: [fs, net]; business: {show_key: deny, plain_key_on_argv: deny}.

5. Enforcement map

Rule of thumb: a business rule is only a Boundary if it is enforced in a different process from the one it constrains. sgit-fs enforcing "no clear keys in .sg_vault/local" is a Boundary for the cli; the cli checking it for itself would be an Expectation.

6. Hashing, signing, distribution

 policies/                         manifest.json
   L0-os.json        sha256:a…       {
   L1-python.json    sha256:b…         "pbp_manifest": 1,
   L2-sgit.json      sha256:c…         "session_ca_cert_sha256": "…",      ← binds the edges to this CA
   L3-cli.json       sha256:d…         "layers": {"L0":"sha256:a…", …},
   L3-fs.json        …                 "components": {
   L3-net.json       …                   "cli": ["sha256:a…","sha256:b…","sha256:c…","sha256:d…"], …},
   L3-kms.json       …                 "edges": [["cli","fs"],["cli","net"],["net","kms"]],
   L4-net-status.json …                "code": {"sgit-ai":"<wheel sha256>"}
                                     }
                                     hash(manifest) = sha256:M   ← the ONE value the person supplies
                                     optional: sig_root(M) by sha256:db7f79fdd87e030a

Verification flow:

1. The person gives the agent sha256:M (in the instruction line, a QR, or signed by the root key).
2. The launcher canonicalises the manifest, hashes it, compares with M; refuses on mismatch.
3. Each component receives only its slice plus the manifest; it recomputes its slice hashes and checks them against the manifest before doing anything.
4. Each component reports policy_hash in every request (the KMS checks it, 02 §3.3) and in its audit lines.
5. The session CA certificate hash is in the manifest, so the edges cannot be satisfied by a different CA.

Policies can come from anywhere, the vendor (sgit ships L2–L4 with each release), the organisation (L0–L1) or the person (L5), because composition is intersection: no layer can grant what a parent denied.

7. Learning a policy (reverse-engineering the blast radius)

 per subcommand test suite ──► run under strace -f (file, network, process, ipc)
                                  │
                                  ▼
                       observed: paths, dirs, syscalls, execs, connects
                                  │
                                  ▼
                       draft mandate (folder-level for enforcement,
                                      file-level as inventory)
                                  │
                       human review │ diff against previous release
                                  ▼
                       ship with release; CI fails if footprint grows
                       without a matching policy change

Measured footprints (successful opens only):

The footprint is a quality signal. sgit --version opens 1,104 files because the CLI imports all 529 modules up front (146 ms). Lazy per-subcommand imports shrink the policy and speed up every command.

Cautions:

• A trace only covers the paths the tests exercised. Error paths and rare branches missing from the trace break in production. Generate from the full test suite, and run new policies in audit mode before enforce mode.
• Enforce at folder level (site-packages ro), list at file level (an SBOM of runtime behaviour).
• The kernel cannot filter host names; that layer is sgit-net's.

8. Prompt-injection walkthrough

9. Prior art (reuse, don't rebuild)

AppArmor complain mode / aa-genprof, SELinux audit2allow, systemd-analyze security, nsjail, bubblewrap, Docker/OCI seccomp profiles, Kubernetes securityContext + NetworkPolicy, SPIFFE/SPIRE and service-mesh authorization policies. What is new here is the ABP layer: a policy that describes rather than scores, a derived delta, intersection-composed layers that ship with the code, a hash the person controls, and business rules enforced by separate components.

This page as markdown · its source, admin/content/dev/sealed-vault-keys/03-process-behaviour-policy.md