Integration Author
Guidance for developers and integrators building tooling, adapters, and documentation-linked workflows for WitnessOps.
This page defines the integration-author lane for developers who design and maintain tooling, adapters, and runbook interfaces in WitnessOps.
1. Problem this page solves
Integrations become unsafe and unauditable when interface boundaries, evidence behavior, and failure handling are implicit.
This page gives the first-pass build path so integration decisions remain governable, auditable, and receipt-compatible.
2. What you should understand after reading
After this page, you should understand:
- the role boundary: define interface contracts and integration behavior, not live incident judgments
- what must be explicit before implementation starts
- which integration decisions you own
- how to separate observed interface behavior from inferred operational confidence
- what to read first and what to defer initially
3. Mechanism-first role path
Must know first before implementation
Before writing or approving integration code/docs, require:
- an explicit integration boundary and non-goals
- a clear interface contract for inputs, outputs, errors, and permission requirements
- defined evidence/receipt compatibility expectations
- governed failure and escalation behavior for blocked scope, approval stalls, tool failure, and evidence mismatch
Read first (in order)
Decisions you own in this role
| Decision | What you own | Primary pages |
|---|---|---|
| Boundary and non-goal definition | Declare allowed actions, explicit non-goals, and prohibited implicit behavior | Integrations, Governance |
| Interface contract design | Define stable input/output shape, error semantics, and permission/approval expectations | Runbooks, Authorization Model |
| Evidence compatibility | Ensure emitted artifacts and metadata can be captured and linked in receipts | Receipt Spec, What Evidence Is Required? |
| Failure and escalation behavior | Encode operator-visible handling for scope denial, approval pause, tool failure, and evidence mismatch | Runbooks, Do I Need to Escalate? |
Defer initially
Defer these until interface and evidence contracts are stable:
- operator and defender workflow playbooks not required for the integration contract
- scenario deep-dives not tied to the current interface decision
- non-essential feature expansion outside the declared integration boundary
4. Observed vs inferred
| Layer | What is observed | What is inferred |
|---|---|---|
| Interface execution | declared input/output schema, runbook step behavior, permission gates, explicit exit states | that the interface is sufficient for every operational context |
| Evidence behavior | emitted artifacts, hashes, timestamps, receipt-linked fields, explicit failure records | that captured evidence is complete for all future investigations |
| Operational impact | documented escalation triggers and blocked-path handling | that integration correctness implies correct operator or incident decisions |
Treat inferred claims as assumptions requiring validation, not as observed guarantees.
5. Role-specific trust assumptions
Operate with these assumptions explicit:
- Host/tool integrity and key custody are external assumptions: compromised runtime or key handling invalidates contract guarantees.
- Integration correctness is not operational correctness: a technically correct interface can still support poor incident or business decisions.
- Proof compatibility depends on artifact-contract adherence: missing or inconsistent artifact semantics break verification and auditability.
- Scope and approval enforcement remain configuration-backed: incorrect policy or boundary configuration produces incorrect integration behavior.
See Threat Model for the full trust boundary map.
6. Next-page handoff
Next, read Scenarios to validate these integration contracts against end-to-end investigation flows.