> ## Documentation Index
> Fetch the complete documentation index at: https://devlookout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security architecture

> Understand Lookout's evidence model, telemetry plan, analytics, and safety boundaries.

> For the complete documentation index, see [llms.txt](https://devlookout.com/llms.txt). Markdown versions are available by appending `.md` to page URLs.

## Deterministic pipeline

Lookout's source of truth is a versioned, typed security knowledge graph. Assets are anchors, not the only nodes. The initial ontology includes assets, services, software, identities, credentials, network zones and paths, exposures, cloud resources, telemetry sources, and controls. Relationships carry direction and meaning (`runs`, `stores`, `administers`, `authenticates_to`, `reachable_from`, `observed_by`, and `protected_by`). Stable identifiers and sorted materialized outputs make the same survey produce the same plan. Operating systems, network products, and service vendors are attributes supplied by adapters; they never define the core model.

1. Survey facts are normalized into graph nodes and relationships, with provenance, observed time, confidence, and owner recorded for every inferred fact.
2. Applicability predicates match prioritized adversary behaviors to graph substructures. ATT\&CK identifiers are metadata, not prioritization targets.
3. Each behavior declares the evidence needed across time (ordering, window, historical context), terrain (identity, endpoint, service, zone, trust boundary), and behavior (action and causal chain). A behavior cannot be marked covered unless its required evidence capabilities, fields, and sensor-health checks are available. Coverage is computed from capabilities, not inferred from a product or operating-system name.
4. Rules are selected from maintained upstream sources where suitable, pinned to a revision, translated into the local schema, tested against positive and benign fixtures, and tuned through explicit overlays rather than editing vendored rules.
5. Baselines start with conservative role-based defaults. Live learning is bounded, versioned, reversible, resistant to poisoning, and never converts an anomaly directly into an incident.

The production Linux survey is recurring rather than installation-only. It inventories network listeners and their bind scope, service-manager state, package versions, local accounts and privilege indicators, SSH authorization-file metadata, mounted and conventionally sensitive storage, and observable security controls. It records no credential contents. The first successful scan establishes drift state; subsequent new listeners, accounts, persistent services, privilege grants, credential changes, stopped controls, and sensitive resources are emitted as normalized events for the rule engine. Unavailable commands, permissions, cloud APIs, and platform-specific evidence remain explicit capability gaps.

## Minimal telemetry plan

Collect durable evidence rather than every available event:

* Network: connection summaries with a stable flow identifier, DNS, TLS certificate/SNI metadata, DHCP, and sensor health. Protocol details are enabled only for observed services. Payload capture is off by default.
* Endpoints: collect authentication, privilege use, execution/ancestry, persistence and service changes, identity changes, software inventory, listening sockets, sensor health, and high-value resource changes wherever the platform exposes them. Linux, macOS, Windows, appliances, mobile devices, and embedded systems can provide different subsets. Lack of deep collection becomes a visible capability gap and can be supplemented with passive or control-plane evidence.
* Services: treat every service as its own securable entity regardless of what runs it. Prefer structured authentication, authorization, administrative/configuration changes, identity/token/key lifecycle, resource access, data movement, and audit events. Ingest through native APIs, webhooks, OpenTelemetry logs, syslog, files, or a small adapter. Access logs are retained at lower duration unless an analytic requires them.
* Control plane: firewall/NAT changes, exposure tests, identity/control changes, backup state, time synchronization, and collection pipeline health.

Every event uses a common envelope: event time, ingest time, site, sensor, event type/category, actor identity, source/target entities, action, outcome, session/flow/process correlation keys, and original-source reference. Raw events stay local by default; normalized alerts and compact evidence bundles are eligible for optional encrypted cloud replication.

## Generic adapter and capability model

Lookout does not require an endpoint agent or a particular network. Each adapter declares the evidence capabilities it can emit and its operating constraints. Adapter families are network overlay, passive network, endpoint, service, infrastructure/control plane, and explicit declaration. A printer observed only through DHCP and flows, an iPhone represented by identity/posture/network metadata, a Windows endpoint with an agent, a database with native audit logs, and a SaaS service with an API all use the same graph and evidence model.

The capability vocabulary includes inventory, identity, ownership, network policy and flow, route, DNS/TLS/HTTP transaction, authentication and privilege use, process execution, service state, configuration change, resource/file access, data movement, and sensor health. Behaviors and rules declare capabilities and required fields. Planning returns `full`, `partial`, or `gap` plus the exact missing evidence. Rules that cannot meet minimum evidence remain undeployed; Lookout must never imply coverage merely because an asset was discovered.

OCSF-compatible event classes and objects are the normalization target, with a small Lookout envelope for provenance, graph entity identifiers, parser version, ingest health, and original-event reference. OpenTelemetry logs and RFC 5424 syslog are transports or source formats, not the internal security ontology.

## Initial provider profile

The first production profile is a generic core with a Tailscale network adapter, a Linux endpoint collector, passive network formats, and generic service ingestion. Tailscale contributes node identity, users, tags, grants/ACLs, routes, subnet/exit-node state, sharing, configuration audit activity, and network-flow summaries when the plan and setting permit them. macOS, Windows, mobile, and appliance-specific collectors are not yet implemented; those systems remain graph nodes with explicit coverage gaps and can still contribute network, identity, posture, control-plane, and service-side evidence.

## Behavioral analysis

The initial models deliberately favor explainable robust statistics and graph features over opaque ML:

* Set membership and decayed frequency for new identity-to-host, host-to-host, process-to-destination, and resource-access relationships.
* Median and median absolute deviation by hour-of-week for counts and data volume.
* First-seen, prevalence, and time-decayed rarity for destinations, processes, services, and resources.
* Role/peer-group comparisons only after the role is explicit and the peer set is sufficiently large.

Learning has a warm-up state, minimum sample requirements, maximum update rate, schema/version identifier, and contamination guardrails. Maintenance windows and confirmed benign changes are context. Alerts show which features departed from baseline and by how much. Deterministic high-signal evidence such as unexpected exposure, sensor impairment, a service spawning a shell, or authentication followed by remote execution outweighs anomaly score.

## Safety and quality gates

* Local storage and detection must continue if cloud export fails. Cloud export is opt-in and cannot receive secrets, raw credentials, or packet payloads.
* Collection credentials are least-privileged, rotated, and separated from response credentials. Secrets never enter the graph as values; only metadata and secret-manager references do.
* Rule deployments require schema validation, fixture tests, expected-volume estimates, rollback metadata, and a sensor/data dependency check.
* Sensor silence and parsing failures are detections. Coverage degrades visibly when telemetry is stale or fields disappear.
* Exclusions are scoped overlays with owner, reason, expiry, and measured effect. Broad path, process-name, or identity exclusions are rejected.
* An incident requires correlated evidence and a reviewable causal chain. Anomaly-only alerts remain evidence.

## Implementation boundary

The backend implements the adapter contract, deterministic graph and planner, read-only Tailscale survey, Zeek/syslog/OpenTelemetry/Tailscale normalization, signed collectors, consistency-chained journals, deterministic and behavioral analytics, tuning overlays, a behavior-linked catalog and replay harness, Sigma-subset validation, authenticated encryption, migrations, encrypted backup/restore, API RBAC and audit, CLI, and an opt-in export boundary.

It deliberately does not perform automated response. Remaining assurance work is operational and continuous: broaden platform-specific collectors and replay corpora, measure false-positive rates against real deployments, add remotely anchored integrity proofs where required, and independently test upgrades, restore procedures, sensor failure modes, and each enabled adapter before relying on it for incident response.

## Alert quality policy

Lookout retains every deterministic and behavioral match as a finding for correlation. Only high- or critical-severity deterministic findings enter the standalone alert queue by default. Medium findings and behavioral anomalies are correlation-only evidence; they can contribute to an incident when a distinct high-confidence deterministic finding anchors the same entity chain within the correlation window. This preserves useful weak signals without asking an operator to review routine novelty.

Bounded behavioral models track identity-to-authentication-target, host-to-executable, process-to-destination, identity-to-privilege-target, identity-to-resource, identity hour-of-week, peer-group executable usage, endpoint-to-network-peer, resource-to-data-destination, and endpoint egress-volume patterns. Peer groups are derived deterministically from explicit endpoint role, then tags, then platform; unclassified endpoints remain in a separate group. Set models require repeated observations over time before trusting a relationship; robust numeric models use median absolute deviation and do not learn anomalous samples. Active-alert evidence is excluded from learning, and every model has fixed cardinality or sample limits.