Agents

Containment session

Also called: containment scope · protected session

DefinitionA containment session is the unit that binds a protected application, every process descended from it, and the policy and grants that apply to them, for as long as that application is running.

A PID is a terrible thing to attach a security policy to. It is a small integer the kernel reuses, it says nothing about what the process is, and it describes exactly one process at one moment.

A containment session is the durable thing underneath. When a protected application starts, BitShout opens a session and binds the process instance to it. Every descendant joins the same session. Grants attach to it. Evidence correlates on it. It ends when the application does.

What a session carries

  • Session identity and lifecycle state — starting, active, ended
  • The registered subject fingerprint that opened it — signing identity, Team ID, bundle identifier, executable identity, not a path
  • Membership for every descendant process instance
  • The security generation it was created under

Why sessions rather than processes

Three things follow from making the session the unit rather than the process.

Descendants are covered by construction. A shell spawned by the agent is in the session, so it is governed by the session’s policy. There is no hop count at which containment lapses — see process lineage.

Grants can be meaningfully temporary. “Allow for this session” is a real scope with a real end, rather than a euphemism for “until you remember to revoke it”. When the agent exits, the authority goes with it.

Evidence is correlatable. A hundred decisions across a dozen processes belong to one piece of work, and can be read as one story afterwards.

Security generations

The generation is the part people miss, and it is what stops stale authority quietly surviving a reset.

If protection locks and is recovered, or policy state is rebuilt, the security generation advances. Authority created under the old generation stops matching. A grant issued before a fail-lock event does not silently resume afterwards; recovery requires explicit revalidation, and the grant has to be re-established rather than reappearing.

This is also why a session’s identity is a fingerprint over signing evidence rather than a path. If the application is updated or replaced underneath, the fingerprint stops matching, the old session’s authority does not transfer to the new binary, and the replacement is recognised on its own merits.