Discovery Authorization Contracts

Status

Contract Designed; Runtime-Lite Implemented In OP-035R

Related Requirements

• Client response references: active discovery with Nmap/SNMP/WMI where explicitly authorized, and passive discovery with DHCP/ARP/NetFlow from tenant-run network sources.
• ADR references: docs/adr/ADR-0012-discovery-authorization-contracts.md.
• Task board references: OP-035.

Problem Statement

OneProtect needs authorized tenant-environment discovery, but scanner/passive runtime would be unsafe without tenant/site policy, collector trust, safety limits, audit, redaction, and source-confidence contracts.

Architectural Intent

Discovery is tenant/site scoped and denied by default. Tenant admins approve methods and scopes through policy. Future collectors request authorization before producing active or passive observations. Authorized observations keep source confidence and can later project into asset events only after redaction and deterministic merge rules.

What Was Implemented

• ADR-0012 accepted the discovery authorization model.
• Architecture documentation defines policies, approved methods, source identity, collector trust, safety limits, redaction, audit, and failure modes.
• OpenAPI defines contract-only policy/status/admin endpoints.
• AsyncAPI and JSON Schema define discovery authorization lifecycle events.
• Contract validation covers the new event payloads.
• OP-035R adds runtime-lite storage, APIs, audit/events, tests, and a read-only console panel. See the Authorized Discovery Runtime-Lite feature note for implementation details.

Components Involved

• OpenAPI: specs/openapi.yaml
• AsyncAPI: specs/asyncapi.yaml
• Event schemas: specs/events/discovery.*.v1.schema.json
• Architecture docs: docs/architecture/discovery-authorization-contracts.md
• ADRs: docs/adr/ADR-0012-discovery-authorization-contracts.md

APIs / Events / Schemas

• API: GET /api/v1/discovery/policies
• API: POST /api/v1/discovery/policies
• API: GET /api/v1/discovery/policies/{policy_id}
• API: PATCH /api/v1/discovery/policies/{policy_id}
• API: GET /api/v1/discovery/authorizations
• API: GET /api/v1/discovery/status
• Runtime-lite API: POST /api/v1/discovery/authorizations
• Runtime-lite API: POST /api/v1/discovery/authorizations/{authorization_id}/observations
• Runtime-lite API: GET /api/v1/discovery/observations
• Event: discovery.policy.configured
• Event: discovery.authorization.granted
• Event: discovery.authorization.denied
• Event: discovery.observation.received

Deployment Notes

No deployment change. Runtime scanners, passive network ingestion, collector bridges, and topology mapping are future implementation work.

Security / Tenant Isolation

All policies, authorization decisions, observations, events, and future storage records are tenant-scoped. Source IP, hostname, subnet, and network location are not tenant identity. Raw scan/network payloads must be redacted or referenced before audit, UI, or auditor-safe reads.

Validation Steps

UI Validation

The Assets page now includes a read-only Discovery authorization panel backed by the runtime-lite APIs.

API Validation

make validate-contracts

Smoke Validation

make validate-contracts

Known Limitations

• No Nmap, SNMP, or WMI runtime.
• No DHCP, ARP, or NetFlow ingestion runtime.
• No osquery, Fleet, or OTel bridge implementation.
• No topology mapping.
• No command execution or broad RMM runtime.

Follow-Up Work

• Add authorization checks to future collector/scanner runtime.
• Add active discovery runtime only after safety-limit tests exist.
• Add passive discovery ingestion only after redaction and source-confidence tests exist.

Acceptance Criteria Mapping

Acceptance criterion	Evidence
Active methods are explicitly authorized	ADR-0012, DiscoveryMethod OpenAPI schema
Passive methods are explicitly authorized	ADR-0012, discovery event schemas
Source confidence and redaction are contract-defined	discovery.observation.received
Denials are auditable	discovery.authorization.denied