PALO policy impact runtime

Version 0.2.0, 5 September 2026. This implementation consumes public PolicyWatcher observations and connects them to a private, authenticated system inventory. It records applicability assessments and canonical gate decisions. It does not execute actions, revoke runtime capabilities or provide production admission for PALO-AI.

The static Stack Explorer remains an illustrative preview. This service is a separate application with durable SQLite storage, a browser review workspace and a JSON API. Actual inventory and organizational identity settings are supplied by the operator; no fictional inventory or approvals are loaded on startup.

Run locally#

Requires Node 22.13 or later within the repository's supported Node 22-24 range. The service uses Node's bundled SQLite API, which emits an experimental warning on Node 22. It uses an isolated dependency lockfile and does not change the existing PALO-AI runtime's database.

npm run impact:install
npm run impact:start

The workspace opens at http://127.0.0.1:57901. Startup creates .palo-impact/local-operator.json with a randomly generated bearer credential and restrictive file permissions. Open that file using the workspace's credential-file input. The browser keeps the token only in tab memory. The local principal is an explicitly configured operator identity, not an organization-verified human identity.

The private .palo-impact/ directory is excluded from Git and the public static build. It contains the credential, SQLite database and journal files. Store and back up this directory as private application data. A host administrator with database-file access remains inside the trust boundary; hashes and SQL triggers are not external attestation.

Live ingestion#

The connector polls https://policywatcher.online/api/v1/change-events?limit=5&lang=en. For every publication it retrieves the exact evidence packet and /api/v1/integrations/palo/signal?changeId=...&lang=en. The latter was verified on the live service during implementation and already emits PALO's native monitoring-signal contract.

Before committing a page, the consumer checks event IDs and ordering, the cursor, publication state, packet digest, snapshot identities, native signal schema, and matching change/policy/company identifiers. URLs are constructed under the fixed PolicyWatcher origin; source-provided URLs are never fetched. Requests have time and size bounds and reject redirects.

Observations and the next cursor commit in one transaction. Failure leaves the checkpoint unchanged. Concurrent polls use a checkpoint revision check. The initial truncated-window flag is retained permanently as a coverage boundary. An absent old snapshot is reported as unavailable evidence rather than inferred to be a first baseline. Published screening statements remain source observations, not verified interpretations.

Manual polling is limited to once per minute per tenant per server process. To enable a background worker, set PALO_IMPACT_POLL_TENANT to the tenant to populate before startup. It polls at one-minute intervals and backs off up to fifteen minutes after failures. This is an operator-configured service identity. Multiple service replicas need shared scheduling/rate coordination beyond this single-process worker.

Inventory and mapping workflow#

1. Import an inventory using the existing palo-dependency-graph schema. Include services, system versions, governance cases, controls, gates and evidence references. Use stable IDs and provide provenance. Imported knowledge timestamps are stamped at receipt.
2. The import requires palo:admin, a matching authenticated tenant and expectedRevision. It preserves earlier inventory revisions and rejects derived signal, policy-version, reviewer and decision nodes.
3. A reviewer with palo:review accepts or withdraws an exact observed policy-to-service mapping with a rationale and expected mapping revision. Mapping records preserve reviewer identity and the service definition fingerprint.
4. Inspect an observation's dependency impact. Only accepted mappings to unchanged service definitions propagate impact. An inventory revision or mapping change invalidates stale review input. A changed service definition requires a new mapping review.
5. Select the affected system and governance case. Record purpose, jurisdictions, applicability, authority basis, rationale, supporting evidence claims, conditions and the gate outcome.

The current inventory adapter is authenticated JSON import. It does not yet synchronize an organization's CMDB, cloud inventory or service catalog automatically. Every imported relationship remains an accountable assertion by the authenticated inventory administrator.

Decisions and history#

Review requires palo:review and palo:read. The server binds reviewer identity and tenant to authentication, never a caller-supplied actor label. Scopes apply across a tenant; per-case reviewer assignment is not implemented in this version.

The submitted impact digest must match the current inventory revision, observation, mappings and active dependency context. The expected prior decision digest must match the latest gate decision. Stable request IDs make retries idempotent and reject reuse with changed content. An inconclusive applicability assessment permits only hold or unresolved outcomes.

This endpoint accepts gates scoped to one system version. Multi-system gate decisions require a future assessment-set workflow and are rejected here. Evidence claims must support controls in the selected system and case. A gate identity cannot be reused for a different case after decisions have been recorded.

Assessment, decision input snapshot and decision commit atomically. Decisions validate against palo-gate-decision-record.schema.json and include the input snapshot hash, decision hash, actor, authority basis and rationale. Later decisions carry sequence, previous digest and superseded decision ID. SQL triggers reject update/delete operations on inventory, observations, mappings, reviews and decisions.

The browser exposes the full impact report and recorded decision behind expandable details. It does not automatically populate a rationale, approve a mapping or submit a governance decision.

Authenticated API#

All API routes require a bearer token. Origin and Host checks apply, and responses are not cacheable. The server does not accept authentication in query strings or cookies.

Returned _record fields describe the storage envelope; exclude _record when recomputing its digest. Canonical decision recordDigest is computed over the decision without recordDigest or _record, using SHA-256 of JavaScript JSON.stringify output, matching the existing example-contract convention. Persisted serialization order must be retained for verification.

Organization OIDC configuration#

Set PALO_IMPACT_OIDC_CONFIG to a private JSON configuration file:

{
  "issuer": "https://identity.example.org/realms/palo",
  "jwksUri": "https://identity.example.org/realms/palo/protocol/openid-connect/certs",
  "audience": "palo-policy-impact",
  "allowedTenantIds": ["your-tenant-id"],
  "allowedClientIds": ["your-review-client-id"],
  "tenantClaim": "tid",
  "clientClaim": "azp"
}

These are placeholders. The organization must supply actual issuer, audience, claims and allowlists. Tokens require a verified signature, issuer, audience, subject and expiry, plus allowed tenant and client claims. The scope claim must grant palo:read, palo:admin or palo:review as appropriate; realm roles are not implicitly elevated. Configure the identity provider to emit these scopes.

Remote binding additionally requires PALO_IMPACT_PUBLIC_ORIGIN=https://... and an HTTPS reverse proxy that preserves the configured Host header. Local operator mode refuses non-loopback binding. No organization identity provider or remote deployment is activated by the local startup command.

Other settings: PALO_IMPACT_HOST, PALO_IMPACT_PORT, PALO_IMPACT_STATE_DIR, and initial local credential fields PALO_IMPACT_TENANT and PALO_IMPACT_OPERATOR. Changing those last two does not rewrite an existing credential file.

Verification#

npm run impact:test

Tests exercise persistent restart and checkpoints, failed-ingestion rollback, packet and signal binding, destination restrictions, concurrency, tenant isolation, identity stamping, revision conflicts, stale mapping/input handling, canonical decisions, retry idempotency, evidence scope, HTTP boundaries and OIDC validation. Live connectivity and real organization integration are separate evidence levels.