Evidence contract
Unknown is a first-class result.
NetOkay Evidence is the single JSON EvidenceBundle that a CLI or Agent run
writes to stdout. It records the runtime that ran the check, the bounded policy decisions,
every observation with its facts and limitations, and what was redacted. A missing
observation is never promoted to a green check.
Get the current schema from the CLI with netokay schema; the tables below
summarise version 2.
Bundle fields
| Field | Type | Meaning |
|---|---|---|
schema_version |
string |
Schema major.minor, currently 2.x. Readers should reject other majors.
|
bundle_id |
string | Unique identifier for this run. |
run_status |
enum |
How the run ended: completed, rejected,
cancelled, or errored.
|
outcome |
enum |
Overall reading: ready, attention,
incomplete, rejected, or error.
|
started_at / completed_at |
string | UTC timestamps for the run. |
duration_ms |
integer | Wall-clock duration of the run. |
runner |
object |
cli_version, core_version, and
control_profile_version that produced the bundle.
|
execution_context |
object |
Where the check ran: process kind, agent_host,
os_family, architecture, container and proxy signals, and
agent_internal_runtime.
|
intent |
object |
Requested transport (http, https, sse, wss, mcp),
profile_id, and has_target.
|
policy |
object |
Policy version, run_decision,
target_decision, and the reasons behind them.
|
observations |
array | One entry per check stage; see the observation fields below. |
differentials |
array |
Pairwise comparisons between two observations, each with its own
limitations.
|
diagnoses |
array |
Interpretations: code, summary,
evidence_refs, possible_layers, limitations,
and suggested_next_steps.
|
redaction |
object |
Lists of what was not_collected, removed, or
truncated.
|
completeness |
object |
Whether the control and target checks finished, and what
is missing.
|
Observation fields
Each entry in observations describes one stage of one check. Read
status, result_code, facts, and
limitations together; a passed HTTPS baseline does not make the selected
transport check passed.
| Field | Type | Meaning |
|---|---|---|
check_id |
string |
Stable name of the check, for example control-self or
control-echo.
|
scope |
enum |
control for NetOkay's own service, target for the URL you
supplied.
|
transport |
enum |
http, https, sse, wss, or
mcp.
|
stage |
enum |
Where the observation was made: control, policy,
dns, tcp, tls, headers,
stream, or upgrade.
|
status |
enum |
passed, failed, incomplete,
skipped, not_observed, or cancelled.
|
result_code / reason_code |
string |
Machine-readable outcome, for example SSE_PASSED or
WSS_PASSED, with an optional reason.
|
facts |
object |
What was observed. Transport details live under facts.template_facts.
|
limitations |
array | Plain-language statements of what this observation cannot prove. |
source |
enum | local_runner or netokay_control. |
colo |
string | NetOkay edge location that answered, when known. |
What is not retained
NetOkay does not retain credentials, cookies, request bodies, full user-agent values, proxy URLs or credentials, certificate chains, target URLs after policy evaluation, or response bodies.
Agent runtime boundary
agent_internal_runtime remains not_observed. A caller-declared
host marker is not attestation. Evidence is local unless a human explicitly shares it.