Skip to content

Security and deployment review

This page answers the questions an enterprise security reviewer should ask before a pilot. It describes the current boundaries, not a certification or a claim that a particular deployment is compliant.

Architecture at a glance

flowchart LR
    R[Recorder] --> B[Compiled bundle]
    B --> E[Local openadapt-flow engine]
    E --> T[Target GUI]
    E --> S[System-of-record verifier]
    E -. optional, explicit .-> V[On-prem VLM appliance]
    E -. approved derivative / minimized metadata .-> C[Hosted control plane]

The default browser replay path is local and model-free. Network traffic to the target application or a configured system-of-record verifier is workload traffic, not OpenAdapt telemetry. Model calls exist only when the operator enables model grounding and configures an appliance.

Data-boundary answers

Question Current answer
Which components see screenshots? The recorder and runner do. A configured model endpoint may receive a permitted crop or frame. Generic hosted upload admits only an approved sanitized derivative. The separate, explicitly initiated hosted recorder sees raw observations for public, non-regulated targets inside its declared hosted boundary.
Which components can transmit screenshots? Deterministic local replay does not transmit them. The optional model client can send permitted data to its configured endpoint. Generic hosted upload sends the manifest-bound derivative, never the source by assumption. The hosted recorder transmits its raw frames inside its declared non-regulated authoring boundary. PHI-bearing runtime screenshots stay inside the declared trusted execution boundary.
What can the sanitizer upload? Only the exact derivative whose inventory, transformations, rescan, unresolved findings, review state, destination, and hash satisfy policy. Unknown, symlinked, unsupported, or unresolved content aborts instead of passing through unchanged.
What does local review establish? It lets an authorized operator compare the sanitized derivative, correct redactions, and approve the exact hash. Review adds context but is not mathematical proof that no PHI remains. Any later modification invalidates approval.
Does Cloud independently witness sanitation review? No. Cloud accounts for every accepted ZIP byte and verifies the manifest/hash contract and submitting ingest token, but it does not observe the local viewer or rerun OCR/NER. Reviewer identity, separation of duties, and evidence custody remain deployment controls.
Can an uploader claim automatic sanitation approval? No. Automatic approval is disabled by default. If a deployment enables it, the exact approval envelope must carry an HMAC from a deployment-allowlisted key ID; the ingest token cannot enable or forge that capability by itself. This still proves signer possession, not independent de-identification.
What happens for an unknown deployment or destination? The request is refused before an egress policy is selected. It never falls back to the shared cloud lane. A verified customer endpoint can have a different policy from an OpenAdapt-managed endpoint.
Where are workflow secrets stored? Password fields and fields named with --secret are not written to recordings, bundles, event logs, or frames. Replay resolves them from OPENADAPT_FLOW_SECRET_<FIELD>. Deployment credentials should be injected from the operator's secret store, not committed to YAML.
Where is the hosted ingest token stored? Resolution order is the CLI flag, OPENADAPT_INGEST_TOKEN, OS keychain, then an existing config migration token. The current CLI requires an explicit flag before using plaintext config storage.
Which artifacts may contain PHI? Treat raw recordings, bundles, templates, report.json, checkpoints, live frames, OCR/accessibility text, model inputs, and effect evidence as PHI-bearing until the applicable policy proves otherwise. The sanitized derivative is separate from the source.
What leaves a regulated runner? Only destinations and artifact classes allowed by the deployment policy. Minimized control metadata and approved derivatives may cross an approved boundary; PHI-bearing runtime values and frames remain inside it. Target-app and verifier traffic remains deployment-specific.
What happens during model-assisted repair? The deterministic ladder runs first. If model grounding is explicitly allowed, a proposal is still subject to the identity and postcondition gates and is counted in the report. A model proposal is not an automatic safety exemption.
Can model inference run on-prem? Yes. The optional VLM service is designed for a private-LAN deployment with no retention. Keep model grounding disabled if the deployment does not need it.
Is upload code physically absent from regulated builds? The compiler does not currently publish a separate, verified "regulated binary" exclusion guarantee. Enforce no-egress at the host/network boundary and verify the installed artifact. The desktop recorder documents build-time exclusions for its own enterprise builds; that is not a blanket compiler guarantee.
What proves an uploaded bundle was tested? validate-hosted checks exact recording/bundle provenance, strict lint, policy certification, risk class, and a successful matching local run report, then signs their hashes with the ingest token under a one-time challenge. Cloud verifies exact policy/risk-class allowlists and consumes the challenge once. This is operator self-attestation, not independent observation or third-party certification.
Can a hosted workflow target a private service? Not through the managed browser lane. Admission requires public DNS names and the runner resolves them again, refusing literal IPs, special-use names, wildcards, and any private, loopback, link-local, reserved, or otherwise non-global answer. Provider resolver behavior and DNS-rebinding resistance remain live qualification items. Private applications require a qualified customer-controlled execution boundary rather than managed public egress.
How is the declared runtime boundary enforced? The qualified boundary ID is hashed into local replay evidence, persisted with the activated workflow, included in every job, installed independently in the runner, and returned by runner health. Cloud and the runner refuse a mismatch. This binds configuration; it does not independently certify that the named infrastructure satisfies a regulatory standard.
Can a retried run execute twice? Live clients supply a request-bound idempotency key, and the database permits one queued/running run per workflow. Dispatch is claimed once and the provider call ID is recorded. If acknowledgement is lost, the run remains reserved and single-flight for callback or operator/provider reconciliation; timeout alone does not authorize a refund and retry.

Approval applies to exact bytes

Compilation does not make a bundle PHI-free. Upload requires a sanitized derivative with a passing manifest and, when policy requires it, local approval of the exact derivative hash. If sanitation removes identity evidence needed for replay, parameterize it or keep the workflow in its trusted boundary; do not weaken verification to make an artifact shareable.

Approval also does not establish runnability. Register the exact approved recording, compile/lint/certify/replay locally, approve a semantics-preserved bundle derivative, then complete the challenge-bound validate-hosted gate and upload that exact attested bundle. If sanitation changed execution-bearing content, parameterize before compiling.

Self-attestation is not independent certification

The HMAC shows that the ingest-token holder signed a non-mutated envelope; Cloud did not witness the local test. The envelope binds approved artifact hashes, compiler/config and parameter-schema hashes, lint/certification evidence hashes, policy, derived risk class, report hash, environment hash, timestamp, and one-time challenge. Independent certification needs a separately controlled evaluator, evidence custody, and signing identity.

Audit and integrity

Every run produces a human-readable REPORT.md and machine-readable report.json. Reports expose resolution rungs, model calls, identity coverage, postconditions, effects, heals, and the halt reason. The on-prem queue adds a schema-minimized, append-only hash-chained audit log. Minimization reduces exposure but does not prove that operator detail or future schema changes cannot contain PHI; review and test the emitted schema.

A hash chain is tamper-evident only while its trusted head and access controls remain trustworthy. It is not an externally anchored signature service. The current durable approval record is also metadata, not yet a complete signed approval store. Design the deployment's retention, access, signing, and export controls around those limits.

Encryption and storage

Workflow.save(..., encrypt=True) with OPENADAPT_BUNDLE_KEY enables AES-256-GCM sealing for workflow.json, template crops, and durable checkpoints; encrypted loads decrypt them in memory. Plaintext remains the default compiler output, and OpenAdapt does not provide a KMS or key-rotation service. Keep operator-provisioned full-disk encryption for the complete storage root as defense in depth. The on-prem installer reminds the operator of this requirement but does not provision or attest LUKS, BitLocker, or FileVault.

Updates and rollback

Air-gapped deployments are intended to use operator-pulled, signed releases and never auto-update. The current deploy/on-prem/install.sh --update path is a documented stub: it prints the verification and atomic-swap procedure but does not apply an update. Define and test signing, verification, rollback, and recovery for the actual pilot before production use.

Hosted launch-candidate status

Managed browser execution is a Beta launch candidate with implemented Stripe Checkout, onboarding, organization isolation, browser runner orchestration, artifacts, reports, teaching, billing, and usage metering. Production explicitly selects live dependencies; a missing runner, storage, or billing dependency returns an operational failure and never substitutes mock success. Mock mode remains for development and is visibly synthetic. The bounded hosted recorder has passed a real-provider record-to-compile qualification; the clean-account paid acceptance lifecycle remains pending, so this is not a public availability statement.

Desktop, RDP, and Citrix retain their separate Experimental/Research maturity; the candidate browser subscription does not imply their availability. See Hosted browser execution and What works today.

Review checklist

  • Confirm which process can capture screens and inject input.
  • Restrict the desktop in-session agent to loopback or require OAFLOW_AGENT_TOKEN; its execute endpoint is remote code execution by design.
  • Enumerate every allowed egress destination and test that all other egress fails.
  • Treat bundles, crops, checkpoints, recordings, and report.json as sensitive; verify the sanitation manifest and exact approved derivative hash before any upload.
  • Verify full-disk encryption and backup/restore outside OpenAdapt.
  • Review identity coverage, effects, policy, and approval requirements for each consequential action.
  • Exercise halt, resume, duplicate write, partial save, stale write, and wrong record scenarios repeatedly.
  • Exercise double-submit, reused-key-with-different-parameters, concurrent run, lost dispatch acknowledgement, and delayed callback scenarios. Confirm that uncertain dispatch is investigated against provider history before any rerun.
  • Establish a signed update and rollback procedure; do not rely on the current stub.
  • Request current legal/compliance artifacts directly. Do not infer SOC 2, HIPAA, PHIPA, or BAA status from architecture documentation.

For implementation-level boundaries, use the engine's PRIVACY.md, SECURITY.md, and known limits.