@yiaany/ghostapi 0.1.9 → 0.2.1

package/docs/security/egress-threat-model.md

@@ -1,126 +1,126 @@
-# Egress Threat Model
-
-Last verified: 2026-08-06.
-
-## Security Claim
-
-GhostAPI 0.1.x includes a Linux-only `ghostapi run` backend that starts a command in fresh user, mount, network and PID namespaces with loopback only. It provides a fail-closed default-deny network boundary only after local `unshare`/`ip` preflight succeeds. `ghostapi doctor --egress` reports `NO PROCESS LAUNCHED`: it is a capability report, not proof that a specific run was isolated.
-
-Changing an SDK base URL, setting `HTTP_PROXY`, or instructing an agent to use GhostAPI is useful **accidental safety**. It is not a hostile-code sandbox and is not evidence that production egress was impossible.
-
-No design in this document claims protection from an administrator/root-equivalent actor, a compromised host, or a malicious process with control of the same user account outside a future containment boundary.
-
-## Assets And Security Goals
-
-- Prevent accidental calls to production providers while developers and AI agents test code.
-- Make attempted allowed and blocked connections attributable to one `ghostapi run` execution.
-- Prevent direct IP, alternate DNS, UDP/QUIC, local-network and subprocess bypasses when a supported enforcement backend is active.
-- Fail closed when the requested guarantee cannot be established.
-- Avoid persistent, system-wide proxy, DNS, routing, firewall or daemon state.
-
-## Threat Actors
-
-| Actor or path | Proxy guidance | Process/container enforcement target |
-| --- | --- | --- |
-| Incorrect application code | Usually caught only when it uses the configured local base URL. | Deny all non-explicit network paths. |
-| AI agent creates another HTTP client | Bypasses guidance. | Same child process remains constrained. |
-| `curl`, shell command, or subprocess | Bypasses guidance. | Descendants must remain in the containment boundary. |
-| Direct IP address | Bypasses hostname-based proxy/DNS policy. | No route/socket path unless explicitly allowed. |
-| Custom DNS resolver or DoH | Bypasses configured resolver assumptions. | Resolver traffic is denied with all other network traffic. |
-| UDP or QUIC | Often bypasses HTTP-only controls. | All socket families and protocols are denied by the boundary. |
-| Local-network target | Often omitted from production-focused allowlists. | Deny by default; allow only deliberate loopback transport. |
-| Malicious same-user process | Out of scope for guidance. | Cannot be contained by a boundary it does not enter; same-user hostile code is not a guarantee from Node permission flags. |
-
-## Guarantee Levels
-
-### HTTP Proxy Guidance
-
-GhostAPI configures or documents a local HTTP endpoint and can collect only traffic voluntarily sent there. It can reduce accidental provider calls, but cannot prevent a different HTTP library, an IP literal, custom DNS, subprocess, UDP/QUIC, or local-network request.
-
-This is the active guarantee on platforms without the Linux backend and when a Linux preflight fails.
-
-### Process-Level Enforcement
-
-A process launcher creates an OS-supported restricted execution boundary and starts the target only after a local preflight passes. The future boundary must cover children and inherited handles, deny all network by default, and expose GhostAPI through an intentionally configured loopback or private transport.
-
-On Linux, `ghostapi run -- <command>` now implements a loopback-only process boundary with fresh user, mount, network and PID namespaces. It does not transparently redirect provider TLS traffic and it does not support external network allowlist entries until a reviewed policy gateway exists.
-
-### Container Or Network-Namespace Enforcement
-
-The target runs in a separate container or network namespace with only loopback, no host networking, no privileged mode, and no mounted container-control socket. This can provide the strongest planned local guarantee, but still does not protect against the container runtime daemon, an administrator, a compromised host, or an explicitly reintroduced host-network path.
-
-This is not implemented in GhostAPI 0.1.x.
-
-### Unsupported Or Degraded
-
-If a native primitive is absent, a required privilege is unavailable, or GhostAPI has no reviewed launcher, the command must not claim isolation. It returns a clear degraded or unsupported result and recommends a reviewed container/VM backend where appropriate.
-
-## Platform Capability Model
-
-### Linux
-
-Linux network namespaces isolate network devices, IP stacks, routing tables, firewall state, sockets, and related networking resources. The Linux manual also documents that the kernel must be configured with `CONFIG_NET_NS`; namespace lifecycle can naturally clean up devices once the last process exits. [Linux network namespaces](https://man7.org/linux/man-pages/man7/network_namespaces.7.html)
-
-Implemented backend: an unprivileged parent performs local preflight, writes sanitized run evidence, and launches the target with fresh user, mount, network and PID namespaces. Only loopback is brought up and GhostAPI starts inside the namespace. The parent never creates a veth, route, firewall rule, proxy rule or global daemon. `--pid --fork --kill-child=SIGTERM` makes bootstrap termination kill the namespace init; when PID 1 exits, the PID namespace cannot retain target descendants. A preflight failure starts no target command.
-
-The boundary does not make arbitrary same-user code hostile-safe: a path-based UNIX socket already accessible to the same user, such as a Docker/Podman control socket, is not an IP route and can act as a privileged deputy. The backend does not mount a control socket itself, but it also does not yet construct a filesystem sandbox that hides every host socket.
-
-### Containers
-
-Docker documents `--network none` as a mode that creates only a loopback interface inside the container. [Docker none network driver](https://docs.docker.com/engine/network/drivers/none/)
-
-Planned backend: use an OCI runtime only when a bounded image/mount policy is available. `--network host`, privileged containers, mounted Docker/Podman sockets, and host credentials invalidate the intended boundary. GhostAPI will not start or configure a privileged daemon.
-
-### Windows
-
-Microsoft documents AppContainer as an isolation environment with network access granted only for explicitly allocated Internet, intranet, or server capabilities. [AppContainer isolation](https://learn.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation)
-
-Planned backend: a per-run AppContainer or LPAC launcher with no network capabilities and a dedicated writable directory. GhostAPI does not create profiles or launch AppContainers today, and a normal Win32 child process is not constrained. A future implementation must clean up its profile deterministically without changing global Windows Firewall state.
-
-### macOS
-
-Apple's App Sandbox is entitlement-based and intended for signed application bundles, not a general-purpose wrapper for arbitrary developer shell commands. [App Sandbox](https://developer.apple.com/documentation/security/app-sandbox)
-
-Planned backend: use an explicit container or VM backend before claiming egress enforcement for arbitrary child commands. GhostAPI must not report `isolated` solely because proxy environment variables or a deprecated sandbox wrapper exists.
-
-### Node.js Runtime
-
-Node's Permission Model is activated with `--permission`; a launched Node process without `--allow-net` is denied network access. Node explicitly describes the model as a seat belt for trusted code and says it does not provide security guarantees against malicious code. [Node.js Permissions](https://nodejs.org/api/permissions.html)
-
-GhostAPI reports this as a degraded auxiliary control only. It cannot contain non-Node children, is not the future `ghostapi run` hostile-sandbox boundary, and does not replace OS-level isolation.
-
-## Capability API And CLI Contract
-
-```bash
-ghostapi doctor --egress
-ghostapi doctor --egress --json
-```
-
-The JSON report is offline and deterministic apart from local runtime facts. It contains:
-
-- `schemaVersion` for machine consumers.
-- `isolated`, which is currently always `false`.
-- `currentGuarantee`, currently `http-proxy-guidance`.
-- Platform/runtime facts and one record per possible backend.
-- Backend status: `available`, `degraded`, `not-implemented`, or `unsupported`.
-- Required privileges/setup and remaining bypasses.
-- A `globalStateChanged: false` invariant.
-
-The diagnostic command does not open a network connection, change proxy settings, add firewall rules, create network namespaces, create an AppContainer profile, or contact a container daemon. `ghostapi run` performs the Linux namespace preflight and creates only child-owned namespaces.
-
-## Minimal Cross-Platform Architecture
-
-1. A platform-neutral policy compiler canonicalizes the allow/deny policy, local GhostAPI transport, command arguments, and run ID.
-2. An unprivileged parent creates evidence and validates the selected backend before spawning the target.
-3. The Linux backend implements `prepare`, `spawn`, lifecycle evidence and namespace cleanup; Windows AppContainer/LPAC and an explicit OCI/VM runner remain future reviewed backends.
-4. Each backend owns its resources by process or container lifetime. Crash cleanup relies on resource ownership, with bounded reconciliation only for leftovers that can be safely identified by a run-specific marker.
-5. A per-run recorder emits attempted connection metadata and a signed/finalized local evidence artifact. It must distinguish a setup failure from a blocked request and an unknown outcome.
-6. A backend that cannot prove the requested guarantee returns `unsupported` or `degraded`; it never silently falls back to proxy guidance for a command advertised as isolated.
-
-## Non-Goals For The First `ghostapi run`
-
-- Global firewall, global proxy, global DNS, hosts-file, routing-table, or system service changes.
-- Transparent interception of another user's process.
-- Protection from root/administrator, the host kernel, or a compromised container runtime.
-- Hidden installation of a privileged daemon.
-- A claim that Node permissions sandbox hostile code.
+# Egress Threat Model
+
+Last verified: 2026-08-06.
+
+## Security Claim
+
+GhostAPI 0.1.x includes a Linux-only `ghostapi run` backend that starts a command in fresh user, mount, network and PID namespaces with loopback only. It provides a fail-closed default-deny network boundary only after local `unshare`/`ip` preflight succeeds. `ghostapi doctor --egress` reports `NO PROCESS LAUNCHED`: it is a capability report, not proof that a specific run was isolated.
+
+Changing an SDK base URL, setting `HTTP_PROXY`, or instructing an agent to use GhostAPI is useful **accidental safety**. It is not a hostile-code sandbox and is not evidence that production egress was impossible.
+
+No design in this document claims protection from an administrator/root-equivalent actor, a compromised host, or a malicious process with control of the same user account outside a future containment boundary.
+
+## Assets And Security Goals
+
+- Prevent accidental calls to production providers while developers and AI agents test code.
+- Make attempted allowed and blocked connections attributable to one `ghostapi run` execution.
+- Prevent direct IP, alternate DNS, UDP/QUIC, local-network and subprocess bypasses when a supported enforcement backend is active.
+- Fail closed when the requested guarantee cannot be established.
+- Avoid persistent, system-wide proxy, DNS, routing, firewall or daemon state.
+
+## Threat Actors
+
+| Actor or path                        | Proxy guidance                                                  | Process/container enforcement target                                                                                       |
+| ------------------------------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Incorrect application code           | Usually caught only when it uses the configured local base URL. | Deny all non-explicit network paths.                                                                                       |
+| AI agent creates another HTTP client | Bypasses guidance.                                              | Same child process remains constrained.                                                                                    |
+| `curl`, shell command, or subprocess | Bypasses guidance.                                              | Descendants must remain in the containment boundary.                                                                       |
+| Direct IP address                    | Bypasses hostname-based proxy/DNS policy.                       | No route/socket path unless explicitly allowed.                                                                            |
+| Custom DNS resolver or DoH           | Bypasses configured resolver assumptions.                       | Resolver traffic is denied with all other network traffic.                                                                 |
+| UDP or QUIC                          | Often bypasses HTTP-only controls.                              | All socket families and protocols are denied by the boundary.                                                              |
+| Local-network target                 | Often omitted from production-focused allowlists.               | Deny by default; allow only deliberate loopback transport.                                                                 |
+| Malicious same-user process          | Out of scope for guidance.                                      | Cannot be contained by a boundary it does not enter; same-user hostile code is not a guarantee from Node permission flags. |
+
+## Guarantee Levels
+
+### HTTP Proxy Guidance
+
+GhostAPI configures or documents a local HTTP endpoint and can collect only traffic voluntarily sent there. It can reduce accidental provider calls, but cannot prevent a different HTTP library, an IP literal, custom DNS, subprocess, UDP/QUIC, or local-network request.
+
+This is the active guarantee on platforms without the Linux backend and when a Linux preflight fails.
+
+### Process-Level Enforcement
+
+A process launcher creates an OS-supported restricted execution boundary and starts the target only after a local preflight passes. The future boundary must cover children and inherited handles, deny all network by default, and expose GhostAPI through an intentionally configured loopback or private transport.
+
+On Linux, `ghostapi run -- <command>` now implements a loopback-only process boundary with fresh user, mount, network and PID namespaces. It does not transparently redirect provider TLS traffic and it does not support external network allowlist entries until a reviewed policy gateway exists.
+
+### Container Or Network-Namespace Enforcement
+
+The target runs in a separate container or network namespace with only loopback, no host networking, no privileged mode, and no mounted container-control socket. This can provide the strongest planned local guarantee, but still does not protect against the container runtime daemon, an administrator, a compromised host, or an explicitly reintroduced host-network path.
+
+This is not implemented in GhostAPI 0.1.x.
+
+### Unsupported Or Degraded
+
+If a native primitive is absent, a required privilege is unavailable, or GhostAPI has no reviewed launcher, the command must not claim isolation. It returns a clear degraded or unsupported result and recommends a reviewed container/VM backend where appropriate.
+
+## Platform Capability Model
+
+### Linux
+
+Linux network namespaces isolate network devices, IP stacks, routing tables, firewall state, sockets, and related networking resources. The Linux manual also documents that the kernel must be configured with `CONFIG_NET_NS`; namespace lifecycle can naturally clean up devices once the last process exits. [Linux network namespaces](https://man7.org/linux/man-pages/man7/network_namespaces.7.html)
+
+Implemented backend: an unprivileged parent performs local preflight, writes sanitized run evidence, and launches the target with fresh user, mount, network and PID namespaces. Only loopback is brought up and GhostAPI starts inside the namespace. The parent never creates a veth, route, firewall rule, proxy rule or global daemon. `--pid --fork --kill-child=SIGTERM` makes bootstrap termination kill the namespace init; when PID 1 exits, the PID namespace cannot retain target descendants. A preflight failure starts no target command.
+
+The boundary does not make arbitrary same-user code hostile-safe: a path-based UNIX socket already accessible to the same user, such as a Docker/Podman control socket, is not an IP route and can act as a privileged deputy. The backend does not mount a control socket itself, but it also does not yet construct a filesystem sandbox that hides every host socket.
+
+### Containers
+
+Docker documents `--network none` as a mode that creates only a loopback interface inside the container. [Docker none network driver](https://docs.docker.com/engine/network/drivers/none/)
+
+Planned backend: use an OCI runtime only when a bounded image/mount policy is available. `--network host`, privileged containers, mounted Docker/Podman sockets, and host credentials invalidate the intended boundary. GhostAPI will not start or configure a privileged daemon.
+
+### Windows
+
+Microsoft documents AppContainer as an isolation environment with network access granted only for explicitly allocated Internet, intranet, or server capabilities. [AppContainer isolation](https://learn.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation)
+
+Planned backend: a per-run AppContainer or LPAC launcher with no network capabilities and a dedicated writable directory. GhostAPI does not create profiles or launch AppContainers today, and a normal Win32 child process is not constrained. A future implementation must clean up its profile deterministically without changing global Windows Firewall state.
+
+### macOS
+
+Apple's App Sandbox is entitlement-based and intended for signed application bundles, not a general-purpose wrapper for arbitrary developer shell commands. [App Sandbox](https://developer.apple.com/documentation/security/app-sandbox)
+
+Planned backend: use an explicit container or VM backend before claiming egress enforcement for arbitrary child commands. GhostAPI must not report `isolated` solely because proxy environment variables or a deprecated sandbox wrapper exists.
+
+### Node.js Runtime
+
+Node's Permission Model is activated with `--permission`; a launched Node process without `--allow-net` is denied network access. Node explicitly describes the model as a seat belt for trusted code and says it does not provide security guarantees against malicious code. [Node.js Permissions](https://nodejs.org/api/permissions.html)
+
+GhostAPI reports this as a degraded auxiliary control only. It cannot contain non-Node children, is not the future `ghostapi run` hostile-sandbox boundary, and does not replace OS-level isolation.
+
+## Capability API And CLI Contract
+
+```bash
+ghostapi doctor --egress
+ghostapi doctor --egress --json
+```
+
+The JSON report is offline and deterministic apart from local runtime facts. It contains:
+
+- `schemaVersion` for machine consumers.
+- `isolated`, which is currently always `false`.
+- `currentGuarantee`, currently `http-proxy-guidance`.
+- Platform/runtime facts and one record per possible backend.
+- Backend status: `available`, `degraded`, `not-implemented`, or `unsupported`.
+- Required privileges/setup and remaining bypasses.
+- A `globalStateChanged: false` invariant.
+
+The diagnostic command does not open a network connection, change proxy settings, add firewall rules, create network namespaces, create an AppContainer profile, or contact a container daemon. `ghostapi run` performs the Linux namespace preflight and creates only child-owned namespaces.
+
+## Minimal Cross-Platform Architecture
+
+1. A platform-neutral policy compiler canonicalizes the allow/deny policy, local GhostAPI transport, command arguments, and run ID.
+2. An unprivileged parent creates evidence and validates the selected backend before spawning the target.
+3. The Linux backend implements `prepare`, `spawn`, lifecycle evidence and namespace cleanup; Windows AppContainer/LPAC and an explicit OCI/VM runner remain future reviewed backends.
+4. Each backend owns its resources by process or container lifetime. Crash cleanup relies on resource ownership, with bounded reconciliation only for leftovers that can be safely identified by a run-specific marker.
+5. A per-run recorder emits attempted connection metadata and a signed/finalized local evidence artifact. It must distinguish a setup failure from a blocked request and an unknown outcome.
+6. A backend that cannot prove the requested guarantee returns `unsupported` or `degraded`; it never silently falls back to proxy guidance for a command advertised as isolated.
+
+## Non-Goals For The First `ghostapi run`
+
+- Global firewall, global proxy, global DNS, hosts-file, routing-table, or system service changes.
+- Transparent interception of another user's process.
+- Protection from root/administrator, the host kernel, or a compromised container runtime.
+- Hidden installation of a privileged daemon.
+- A claim that Node permissions sandbox hostile code.

package/docs/security/inventory-threat-model.md

@@ -1,104 +1,104 @@
-# Agent Inventory And Attack-Path Graph Threat Model
-
-Applies to the local agent inventory layer: the persisted inventory store, attack-path graph, blast-radius analysis, detections, remediation workflow, open export, removal analysis, and ROI report.
-
-## Scope
-
-This threat model covers the inventory module added in the "agent inventory, attack-path graph, and indispensability" session:
-
-- `inventory.json` local persisted store under `.ghostapi/`, created by `getDataPaths().inventoryStore`.
-- Import of agents, tools, identities, providers, resources, side effects, credentials, and policies from `config`, `ci`, `gateway`, and `cloud` sources, each record carrying provenance (source, import time, importer) and freshness.
-- The attack-path graph (`agent -> identity -> tool -> provider -> resource -> side effect`) with persisted, provenance- and freshness-carrying edges.
-- Blast-radius analysis, detections, remediation proposals/applications, open export, removal analysis, and the ROI report.
-
-The inventory layer adds no provider, credential, network egress, or hosted control-plane surface. All of it is local-first and synthetic. ROI and removal numbers are derived from imported counters and local records only; nothing is invented, and the pilot entry gate (a real team/enterprise pilot) is not yet met.
-
-## Trust Boundaries
-
-| Boundary | In scope | Out of scope |
-| --- | --- | --- |
-| Operator identity | Every inventory action authenticates through an injectable authorizer and requires an explicit permission (`inventory.import` / `inventory.inspect` / `inventory.analyze` / `inventory.remediate` / `inventory.export`); the test authorizer binds issued identities by reference | Real authn/authz infrastructure |
-| Import sources | Imports declare a source (`config` / `ci` / `gateway` / `cloud`) that is recorded as provenance on every record and edge | Live provider or CI credentials; the layer never reaches out to a source |
-| Tenant isolation | All reads and writes are filtered by `tenantId`; graph, findings, export, attack paths, removal, and ROI are tenant-scoped | Multi-tenant federation |
-| Store | Regular non-symlink JSON file, owner-only on POSIX, bounded bytes and record counts | Remote/distributed storage |
-
-## Assets
-
-- Agent inventory records and graph edges (`inventory.json`).
-- Provenance and freshness metadata attached to every record and edge.
-- Findings and remediation state (proposals, applications, rejections).
-- The open export artifact (inventory, policies, eval scenario references, evidence metadata, removal analysis, ROI).
-- Import-run and import-source ledger.
-
-## Threats And Mitigations
-
-### T1. Unauthenticated or unauthorized inventory writes
-
-Every mutating and reading method calls `authorize` first: `validateOperator` on the authorizer result and an explicit permission check. The default authorizer (`createDisabledInventoryOperatorAuthorizer`) throws "not configured", so a controller with no authorizer cannot be used. Test identities are reference-bound; a plain `{}` is rejected as "not authenticated".
-
-### T2. A poisoned import poisons the graph
-
-`validateImportPayload` enforces strict schema, allowed source types, identifier/scope/hash/timestamp formats, bounded array sizes, and per-kind id uniqueness before anything is stored. Cross-references (e.g. an agent referencing an unknown identity) are validated against both the current import and the persisted state, and a reference to a record that does not exist rejects the whole import. Import payloads are canonicalized to a digest recorded on the import run and source.
-
-### T3. Tenant data leaks across the graph or export
-
-Every graph edge, record, finding, remediation, import run, and source is filtered by `operator.tenantId` in `snapshotFor`, `graphEdges`, `findAttackPaths`, `computeBlastRadius`, `computeFindings`, `computeCoverage`, `computeRemovalAnalysis`, `computeRoiReport`, and `export`. An edge can only be created from a record that belongs to the importing tenant. Cross-tenant leakage is covered by tests.
-
-### T4. Provenance or freshness is missing or forged
-
-Every record and edge carries `provenance` (`sourceId`, `sourceType`, `sourceName`, `importedAt`, `importedBy`) and `freshness` (`firstSeenAt`, `lastSeenAt`) built from the import payload source and the authenticated operator's principal id — never from client-supplied strings. `validateState` re-validates provenance/freshness on every read and write. Edge ids are derived from source/target/relation so re-imports refresh `lastSeenAt` instead of duplicating edges.
-
-Edges have a freshness lifecycle. Attack-path and blast-radius analysis only use edges whose `lastSeenAt` is within the configured `edgeStaleDays` window, so a long-unseen relationship cannot be cited as current reachability evidence. On every import the importing tenant's stale edges are garbage-collected from the store, keeping the graph from accumulating frozen relationships that were never refreshed.
-
-### T5. A remediation expands permissions instead of reducing them
-
-`reduce_scope` proposals are rejected at proposal time unless the reduced scope list is a strict subset of the credential's current grant scopes and removes at least one scope; the same invariant is enforced again at apply time. `revoke` only ever sets a credential to revoked. `assign_owner` only sets an owner id. `onboard_through_gateway` only sets the gateway-managed flag. `create_eval` only records an eval scenario reference — and, when an `evalScenarioExists` resolver is configured, the referenced scenario must actually exist before the proposal is accepted, so a remediation cannot paper over a finding by pointing at a deleted scenario. No remediation path adds scopes or relaxes a control.
-
-Applied remediations are re-verified on every analysis pass: a finding stays resolved only while the remediation remains effective. If a later import re-expands a reduced scope, revokes nothing, clears an assigned owner, un-gates an agent, or deletes the referenced eval scenario, the finding is re-opened instead of staying permanently marked resolved.
-
-Remediation targets are validated against the tenant's live data before a proposal is accepted: an `environment` target must actually be referenced by at least one agent, identity, provider, resource, credential, or policy of the tenant, so a remediation cannot be proposed against a stale or invented environment.
-
-### T6. The store is poisoned or exploded
-
-The store is validated on every read (`validateState`) and write (`atomicWriteJson(this.path, validateState(state))`). Store bytes are capped at 8 MiB; every collection is bounded (`maxAgents`, `maxEdges` 6,000, `maxFindings` 3,000, etc.), and `assertStoreBounds` rejects edges and findings over their caps on every mutation. Import runs are rotated per tenant at `maxImports` (256), keeping the oldest runs trimmed rather than failing the write. The store must be a regular non-symlink file. Oversized or non-JSON stores are rejected, not partially loaded.
-
-### T7. Secret-shaped or control-character data enters the inventory
-
-Identifiers, scopes, and text are validated by regexes and by `sanitizeSecretString`: any value that contains a recognizable secret shape (e.g. `sk_live_*`) or control characters is rejected. Evidence metadata and reasons are bounded text.
-
-### T8. ROI or removal analysis invents savings
-
-The ROI report is built only from imported counters (latest per source) and from actually applied remediations in the store; unmeasured counters are reported as `null` and listed in `notMeasured`, and `basis` is `local_inventory_data_only`. The removal analysis reports only numbers computed from the local store and states plainly when nothing verifiable depends on GhostAPI. The heuristic blast-radius classification is explicitly labeled advisory, not proof of exploitability.
-
-### T9. Attack-path graph is unbounded or cross-tenant
-
-Edges are created only from the importing tenant's records, are keyed by a derived edge id, and are bounded (`maxEdges` 6,000). Path finding is always scoped to the tenant and to a single agent id. Incomplete paths (a record reference missing from the store) are counted separately and reported as incomplete, not silently dropped.
-
-## Permissions And Capabilities Summary
-
-| Action | Check |
-| --- | --- |
-| Import | operator authorizer + `inventory.import` |
-| Inspect / graph / attack paths / blast radius / list remediations | operator authorizer + `inventory.inspect` |
-| Analyze / removal analysis / ROI | operator authorizer + `inventory.analyze` |
-| Propose / apply / reject remediations | operator authorizer + `inventory.remediate` |
-| Export | operator authorizer + `inventory.export` |
-
-## Limits
-
-| Resource | Limit |
-| --- | --- |
-| Store bytes | 8 MiB |
-| Import sources / import runs | 64 / 256 |
-| Agents / tools / identities | 500 / 500 / 500 |
-| Providers / resources / side effects | 200 / 1,000 / 2,000 |
-| Credentials / policies | 500 / 100 |
-| Graph edges | 6,000 |
-| Findings / remediations | 3,000 / 1,000 |
-| References / scopes per record | 64 / 32 |
-
-## Out Of Scope
-
-- Live provider, CI, or gateway ingestion (the layer consumes locally-supplied payloads only).
-- Hosted multi-tenant control plane and federated sources.
-- Automated kill-switch or revocation execution against real providers (remediations mutate the local inventory state only).
+# Agent Inventory And Attack-Path Graph Threat Model
+
+Applies to the local agent inventory layer: the persisted inventory store, attack-path graph, blast-radius analysis, detections, remediation workflow, open export, removal analysis, and ROI report.
+
+## Scope
+
+This threat model covers the inventory module added in the "agent inventory, attack-path graph, and indispensability" session:
+
+- `inventory.json` local persisted store under `.ghostapi/`, created by `getDataPaths().inventoryStore`.
+- Import of agents, tools, identities, providers, resources, side effects, credentials, and policies from `config`, `ci`, `gateway`, and `cloud` sources, each record carrying provenance (source, import time, importer) and freshness.
+- The attack-path graph (`agent -> identity -> tool -> provider -> resource -> side effect`) with persisted, provenance- and freshness-carrying edges.
+- Blast-radius analysis, detections, remediation proposals/applications, open export, removal analysis, and the ROI report.
+
+The inventory layer adds no provider, credential, network egress, or hosted control-plane surface. All of it is local-first and synthetic. ROI and removal numbers are derived from imported counters and local records only; nothing is invented, and the pilot entry gate (a real team/enterprise pilot) is not yet met.
+
+## Trust Boundaries
+
+| Boundary          | In scope                                                                                                                                                                                                                                                                          | Out of scope                                                             |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Operator identity | Every inventory action authenticates through an injectable authorizer and requires an explicit permission (`inventory.import` / `inventory.inspect` / `inventory.analyze` / `inventory.remediate` / `inventory.export`); the test authorizer binds issued identities by reference | Real authn/authz infrastructure                                          |
+| Import sources    | Imports declare a source (`config` / `ci` / `gateway` / `cloud`) that is recorded as provenance on every record and edge                                                                                                                                                          | Live provider or CI credentials; the layer never reaches out to a source |
+| Tenant isolation  | All reads and writes are filtered by `tenantId`; graph, findings, export, attack paths, removal, and ROI are tenant-scoped                                                                                                                                                        | Multi-tenant federation                                                  |
+| Store             | Regular non-symlink JSON file, owner-only on POSIX, bounded bytes and record counts                                                                                                                                                                                               | Remote/distributed storage                                               |
+
+## Assets
+
+- Agent inventory records and graph edges (`inventory.json`).
+- Provenance and freshness metadata attached to every record and edge.
+- Findings and remediation state (proposals, applications, rejections).
+- The open export artifact (inventory, policies, eval scenario references, evidence metadata, removal analysis, ROI).
+- Import-run and import-source ledger.
+
+## Threats And Mitigations
+
+### T1. Unauthenticated or unauthorized inventory writes
+
+Every mutating and reading method calls `authorize` first: `validateOperator` on the authorizer result and an explicit permission check. The default authorizer (`createDisabledInventoryOperatorAuthorizer`) throws "not configured", so a controller with no authorizer cannot be used. Test identities are reference-bound; a plain `{}` is rejected as "not authenticated".
+
+### T2. A poisoned import poisons the graph
+
+`validateImportPayload` enforces strict schema, allowed source types, identifier/scope/hash/timestamp formats, bounded array sizes, and per-kind id uniqueness before anything is stored. Cross-references (e.g. an agent referencing an unknown identity) are validated against both the current import and the persisted state, and a reference to a record that does not exist rejects the whole import. Import payloads are canonicalized to a digest recorded on the import run and source.
+
+### T3. Tenant data leaks across the graph or export
+
+Every graph edge, record, finding, remediation, import run, and source is filtered by `operator.tenantId` in `snapshotFor`, `graphEdges`, `findAttackPaths`, `computeBlastRadius`, `computeFindings`, `computeCoverage`, `computeRemovalAnalysis`, `computeRoiReport`, and `export`. An edge can only be created from a record that belongs to the importing tenant. Cross-tenant leakage is covered by tests.
+
+### T4. Provenance or freshness is missing or forged
+
+Every record and edge carries `provenance` (`sourceId`, `sourceType`, `sourceName`, `importedAt`, `importedBy`) and `freshness` (`firstSeenAt`, `lastSeenAt`) built from the import payload source and the authenticated operator's principal id — never from client-supplied strings. `validateState` re-validates provenance/freshness on every read and write. Edge ids are derived from source/target/relation so re-imports refresh `lastSeenAt` instead of duplicating edges.
+
+Edges have a freshness lifecycle. Attack-path and blast-radius analysis only use edges whose `lastSeenAt` is within the configured `edgeStaleDays` window, so a long-unseen relationship cannot be cited as current reachability evidence. On every import the importing tenant's stale edges are garbage-collected from the store, keeping the graph from accumulating frozen relationships that were never refreshed.
+
+### T5. A remediation expands permissions instead of reducing them
+
+`reduce_scope` proposals are rejected at proposal time unless the reduced scope list is a strict subset of the credential's current grant scopes and removes at least one scope; the same invariant is enforced again at apply time. `revoke` only ever sets a credential to revoked. `assign_owner` only sets an owner id. `onboard_through_gateway` only sets the gateway-managed flag. `create_eval` only records an eval scenario reference — and, when an `evalScenarioExists` resolver is configured, the referenced scenario must actually exist before the proposal is accepted, so a remediation cannot paper over a finding by pointing at a deleted scenario. No remediation path adds scopes or relaxes a control.
+
+Applied remediations are re-verified on every analysis pass: a finding stays resolved only while the remediation remains effective. If a later import re-expands a reduced scope, revokes nothing, clears an assigned owner, un-gates an agent, or deletes the referenced eval scenario, the finding is re-opened instead of staying permanently marked resolved.
+
+Remediation targets are validated against the tenant's live data before a proposal is accepted: an `environment` target must actually be referenced by at least one agent, identity, provider, resource, credential, or policy of the tenant, so a remediation cannot be proposed against a stale or invented environment.
+
+### T6. The store is poisoned or exploded
+
+The store is validated on every read (`validateState`) and write (`atomicWriteJson(this.path, validateState(state))`). Store bytes are capped at 8 MiB; every collection is bounded (`maxAgents`, `maxEdges` 6,000, `maxFindings` 3,000, etc.), and `assertStoreBounds` rejects edges and findings over their caps on every mutation. Import runs are rotated per tenant at `maxImports` (256), keeping the oldest runs trimmed rather than failing the write. The store must be a regular non-symlink file. Oversized or non-JSON stores are rejected, not partially loaded.
+
+### T7. Secret-shaped or control-character data enters the inventory
+
+Identifiers, scopes, and text are validated by regexes and by `sanitizeSecretString`: any value that contains a recognizable secret shape (e.g. `sk_live_*`) or control characters is rejected. Evidence metadata and reasons are bounded text.
+
+### T8. ROI or removal analysis invents savings
+
+The ROI report is built only from imported counters (latest per source) and from actually applied remediations in the store; unmeasured counters are reported as `null` and listed in `notMeasured`, and `basis` is `local_inventory_data_only`. The removal analysis reports only numbers computed from the local store and states plainly when nothing verifiable depends on GhostAPI. The heuristic blast-radius classification is explicitly labeled advisory, not proof of exploitability.
+
+### T9. Attack-path graph is unbounded or cross-tenant
+
+Edges are created only from the importing tenant's records, are keyed by a derived edge id, and are bounded (`maxEdges` 6,000). Path finding is always scoped to the tenant and to a single agent id. Incomplete paths (a record reference missing from the store) are counted separately and reported as incomplete, not silently dropped.
+
+## Permissions And Capabilities Summary
+
+| Action                                                            | Check                                       |
+| ----------------------------------------------------------------- | ------------------------------------------- |
+| Import                                                            | operator authorizer + `inventory.import`    |
+| Inspect / graph / attack paths / blast radius / list remediations | operator authorizer + `inventory.inspect`   |
+| Analyze / removal analysis / ROI                                  | operator authorizer + `inventory.analyze`   |
+| Propose / apply / reject remediations                             | operator authorizer + `inventory.remediate` |
+| Export                                                            | operator authorizer + `inventory.export`    |
+
+## Limits
+
+| Resource                             | Limit               |
+| ------------------------------------ | ------------------- |
+| Store bytes                          | 8 MiB               |
+| Import sources / import runs         | 64 / 256            |
+| Agents / tools / identities          | 500 / 500 / 500     |
+| Providers / resources / side effects | 200 / 1,000 / 2,000 |
+| Credentials / policies               | 500 / 100           |
+| Graph edges                          | 6,000               |
+| Findings / remediations              | 3,000 / 1,000       |
+| References / scopes per record       | 64 / 32             |
+
+## Out Of Scope
+
+- Live provider, CI, or gateway ingestion (the layer consumes locally-supplied payloads only).
+- Hosted multi-tenant control plane and federated sources.
+- Automated kill-switch or revocation execution against real providers (remediations mutate the local inventory state only).

package/docs/security/kill-switch-budgets-threat-model.md

@@ -1,37 +1,37 @@
-# Local Kill Switch, Budget, And Blast-Radius Threat Model
-
-## Scope
-
-The Session 27 safety controller is a local, persisted coordination layer for the existing `ghostapi-synthetic` action path. It implements local kill switches, budgets, circuit breakers, bounded queue/dead-letter state, authenticated emergency API calls, audit records, and a scheduled synthetic game-day test. It does not introduce a provider, provider SDK/client, provider account, vault, credential, external HTTP, webhook/email/Slack transport, hosted control plane, or production side effect.
-
-## Emergency Authority
-
-`stop()`, `reenable()`, `configureBudget()`, and `configureCircuit()` require an injected `SafetyEmergencyAuthorizer`. The API accepts only verifier-issued operator objects with a stable principal and explicit permission. `safety.stop`, `safety.reenable`, and `safety.configure` are separate permissions. Empty, secret-shaped, or oversized reasons fail closed and every emergency decision is chained into the bounded local audit log.
-
-There is intentionally no unauthenticated HTTP emergency endpoint, no CLI token parser, and no notification transport. A future deployment needs a separately reviewed identity authority and authenticated transport before exposing this emergency API remotely.
-
-## Enforcement Semantics
-
-- Switch scopes are `global`, `organization`, `project`, `environment`, `agent`, `workload`, `provider`, `operation`, and `risk_class`.
-- Admission serializes against the persisted controller store. Budgets reserve action costs before execution, so parallel callers cannot oversubscribe money, requests, messages, mutations, deletes, token cost, concurrency, or velocity limits.
-- A replay with the same idempotency key and action hash returns a replay lease without a second reservation. Reusing the key with a different action hash is denied.
-- The action gateway calls the controller after plan/simulate and before its attempt record. The synthetic world calls the controller's `commit()` while it holds its own world lock. `commit()` is two-phase: a first mutate re-checks the lease, expiry, and kill-switch/circuit state; only then is the operation executed; a second mutate re-checks the lease and persists the `action.final_check` audit record ("remained active through commit") before returning. A kill switch that wins before the first phase blocks the local mutation. If the lease expires between the phases, `commit()` throws even though the operation already ran — the caller must not treat the action as successfully admitted.
-- Leases are time-bounded: a reserved lease expires after `DEFAULT_LEASE_TTL_MS` (60 s by default, overridable via `leaseTtlMs`). Expired leases are pruned on the next admission, and both `assertActive()` and the `commit()` phases reject an expired lease. `complete()` is tolerant: it still records the outcome for a lease that expired after the operation, so the audit chain reflects what actually happened instead of dropping the terminal record.
-- Kill-switch denials carry the stable error code `SAFETY_KILL_SWITCH` (and admit/commit errors are `SafetyControllerError`), so callers — including the scheduled game day — detect a kill-switch block structurally instead of by parsing message text.
-- Queued actions have a fixed maximum of 100. A full queue returns backpressure. Stopping a matching scope moves queued records to the bounded dead-letter queue; no queued action is auto-retried. The dead-letter queue is also bounded, and when full the oldest entry is evicted so the store never grows without limit.
-- Already approved is not already executable: approval artifacts still pass current policy, identity, idempotency, safety admission, and final-commit checks. An in-flight action that has crossed the final commit cannot be undone; GhostAPI does not claim rollback. A real provider would require idempotency and reconciliation semantics before an equivalent boundary is enabled.
-- Failures, policy violations, latency threshold breaches, and reconciliation mismatches can open persisted circuit breakers. Open breakers deny new admission; no retry loop is created by the controller.
-
-## Persistence And Limits
-
-Critical state lives in `.ghostapi/safety-controller.json`, not process memory. It is strict-schema validated, bounded to 1 MiB, guarded as a regular non-symlink file, serialized with the existing file lock, atomically replaced, and covered by a bounded SHA-256 audit chain. This is local coordination and tamper evidence on one filesystem, not a distributed lock, immutable audit ledger, or defense against a malicious same-user actor who can modify both state and runtime.
-
-## Game Day And Runbook
-
-The scheduled GitHub workflow runs only `test/safetyController.test.ts`, which performs a local synthetic stop/re-enable drill and never creates a provider side effect. The operational procedure is in [`docs/operations/kill-switch-runbook.md`](../operations/kill-switch-runbook.md).
-
-## Remaining Limits
-
-- The controller does not authorize production execution, reconcile a provider outcome, revoke a provider credential, or prove a provider-side stop.
-- Budget units are caller-supplied typed action metadata for the one local synthetic action; a future real action needs independently derived and provider-verified amounts/costs.
-- Local timestamps use the process clock. A real deployment needs a trusted clock, durable audit sink, shared atomic store, reconciliation, and provider-specific final-side-effect guards.
+# Local Kill Switch, Budget, And Blast-Radius Threat Model
+
+## Scope
+
+The Session 27 safety controller is a local, persisted coordination layer for the existing `ghostapi-synthetic` action path. It implements local kill switches, budgets, circuit breakers, bounded queue/dead-letter state, authenticated emergency API calls, audit records, and a scheduled synthetic game-day test. It does not introduce a provider, provider SDK/client, provider account, vault, credential, external HTTP, webhook/email/Slack transport, hosted control plane, or production side effect.
+
+## Emergency Authority
+
+`stop()`, `reenable()`, `configureBudget()`, and `configureCircuit()` require an injected `SafetyEmergencyAuthorizer`. The API accepts only verifier-issued operator objects with a stable principal and explicit permission. `safety.stop`, `safety.reenable`, and `safety.configure` are separate permissions. Empty, secret-shaped, or oversized reasons fail closed and every emergency decision is chained into the bounded local audit log.
+
+There is intentionally no unauthenticated HTTP emergency endpoint, no CLI token parser, and no notification transport. A future deployment needs a separately reviewed identity authority and authenticated transport before exposing this emergency API remotely.
+
+## Enforcement Semantics
+
+- Switch scopes are `global`, `organization`, `project`, `environment`, `agent`, `workload`, `provider`, `operation`, and `risk_class`.
+- Admission serializes against the persisted controller store. Budgets reserve action costs before execution, so parallel callers cannot oversubscribe money, requests, messages, mutations, deletes, token cost, concurrency, or velocity limits.
+- A replay with the same idempotency key and action hash returns a replay lease without a second reservation. Reusing the key with a different action hash is denied.
+- The action gateway calls the controller after plan/simulate and before its attempt record. The synthetic world calls the controller's `commit()` while it holds its own world lock. `commit()` is two-phase: a first mutate re-checks the lease, expiry, and kill-switch/circuit state; only then is the operation executed; a second mutate re-checks the lease and persists the `action.final_check` audit record ("remained active through commit") before returning. A kill switch that wins before the first phase blocks the local mutation. If the lease expires between the phases, `commit()` throws even though the operation already ran — the caller must not treat the action as successfully admitted.
+- Leases are time-bounded: a reserved lease expires after `DEFAULT_LEASE_TTL_MS` (60 s by default, overridable via `leaseTtlMs`). Expired leases are pruned on the next admission, and both `assertActive()` and the `commit()` phases reject an expired lease. `complete()` is tolerant: it still records the outcome for a lease that expired after the operation, so the audit chain reflects what actually happened instead of dropping the terminal record.
+- Kill-switch denials carry the stable error code `SAFETY_KILL_SWITCH` (and admit/commit errors are `SafetyControllerError`), so callers — including the scheduled game day — detect a kill-switch block structurally instead of by parsing message text.
+- Queued actions have a fixed maximum of 100. A full queue returns backpressure. Stopping a matching scope moves queued records to the bounded dead-letter queue; no queued action is auto-retried. The dead-letter queue is also bounded, and when full the oldest entry is evicted so the store never grows without limit.
+- Already approved is not already executable: approval artifacts still pass current policy, identity, idempotency, safety admission, and final-commit checks. An in-flight action that has crossed the final commit cannot be undone; GhostAPI does not claim rollback. A real provider would require idempotency and reconciliation semantics before an equivalent boundary is enabled.
+- Failures, policy violations, latency threshold breaches, and reconciliation mismatches can open persisted circuit breakers. Open breakers deny new admission; no retry loop is created by the controller.
+
+## Persistence And Limits
+
+Critical state lives in `.ghostapi/safety-controller.json`, not process memory. It is strict-schema validated, bounded to 1 MiB, guarded as a regular non-symlink file, serialized with the existing file lock, atomically replaced, and covered by a bounded SHA-256 audit chain. This is local coordination and tamper evidence on one filesystem, not a distributed lock, immutable audit ledger, or defense against a malicious same-user actor who can modify both state and runtime.
+
+## Game Day And Runbook
+
+The scheduled GitHub workflow runs only `test/safetyController.test.ts`, which performs a local synthetic stop/re-enable drill and never creates a provider side effect. The operational procedure is in [`docs/operations/kill-switch-runbook.md`](../operations/kill-switch-runbook.md).
+
+## Remaining Limits
+
+- The controller does not authorize production execution, reconcile a provider outcome, revoke a provider credential, or prove a provider-side stop.
+- Budget units are caller-supplied typed action metadata for the one local synthetic action; a future real action needs independently derived and provider-verified amounts/costs.
+- Local timestamps use the process clock. A real deployment needs a trusted clock, durable audit sink, shared atomic store, reconciliation, and provider-specific final-side-effect guards.