# Endpoint Security Telemetry

Task OS can use endpoint telemetry to explain what a worker actually caused on an operator machine:
processes spawned, binaries executed, network listeners opened, files touched, and security controls present.

This lane is opt-in. It is not a default dependency for Company OS startup, beginner onboarding,
browser smoke, or local UI-only development. The smoke scripts detect available telemetry and write
evidence; they do not install, start, stop, or reconfigure security tools.

## Evidence Contract

Default marker:

```text
runs/security/endpoint-telemetry-smoke.json
```

Schema:

```json
{
  "schema": "company-os.endpoint-telemetry-smoke.v1",
  "passed": true,
  "generatedAt": "2026-06-06T00:00:00Z",
  "platform": { "kind": "darwin" },
  "telemetryState": "available",
  "requirePrimary": false,
  "tools": [
    {
      "id": "osquery",
      "command": "osqueryi",
      "role": "primary",
      "present": true,
      "note": "Queryable process/file/network telemetry when event tables are configured."
    }
  ]
}
```

Use `--require` or `-Require` only in a dedicated endpoint-security validation lane. Without that flag,
missing endpoint tooling is recorded as evidence instead of failing the normal harness.

## Windows Lane

Preferred primary tools:

- **Sysmon** with an operator-approved config such as SwiftOnSecurity's `sysmon-config`.
- **osquery** for queryable inventory, process, network, service, and event-log state.

Supplemental source:

- **Windows Event Log** via `Get-WinEvent`.

Smoke:

```powershell
powershell -ExecutionPolicy Bypass -File scripts/security-windows-endpoint-telemetry-smoke.ps1
```

The script is detect-only. It checks for `Sysmon64`, `Sysmon`, the Sysmon service, `osqueryi`,
and native event log access. It does not install services or apply Sysmon XML.

## macOS Lane

Preferred primary tools:

- **osquery** as the first harness choice because it is queryable and can expose evented telemetry
  when configured with the required macOS permissions.
- **Santa** when an operator wants binary authorization and monitoring backed by Apple Endpoint Security.

Supplemental sources:

- **Unified Logging** via `log`.
- **System extension inventory** via `systemextensionsctl`.

Smoke:

```bash
bash scripts/security-endpoint-telemetry-smoke.sh
```

Apple Endpoint Security is the native primitive behind stronger macOS endpoint telemetry, but using it
directly requires privileged software and Apple entitlements. Keep direct Endpoint Security clients out
of the default Task OS harness.

## Linux Lane

Preferred primary tools:

- **osquery** for queryable process/file/network telemetry.
- **Sysmon for Linux** when Sysmon-style event logs are preferred.
- **auditd/auditctl** when an operator already manages Linux Audit rules.
- **Falco** for runtime syscall/eBPF security events in a dedicated security validation lane.

Supplemental source:

- **journald** via `journalctl`.

Smoke:

```bash
bash scripts/security-endpoint-telemetry-smoke.sh
```

Falco and other eBPF/syscall monitors often require elevated Linux capabilities. Treat them as
operator-approved security infrastructure, not as a normal local development dependency.

## Task OS Use

Endpoint telemetry is useful for:

- proving which worker command spawned which process;
- detecting unexpected network listeners or child processes during a task;
- correlating task runs with OS audit evidence;
- making security posture explicit in support bundles.

Endpoint telemetry is not for:

- grading beginner onboarding;
- replacing browser or product smokes;
- silently enabling privileged monitoring;
- making cloud/frontier providers mandatory.

## References

- SwiftOnSecurity Sysmon config: <https://github.com/SwiftOnSecurity/sysmon-config>
- Microsoft Sysmon for Linux: <https://github.com/Sysinternals/SysmonForLinux>
- osquery documentation: <https://osquery.readthedocs.io/>
- Santa documentation: <https://santa.dev/>
- Apple Endpoint Security: <https://developer.apple.com/documentation/endpointsecurity>
- Falco documentation: <https://falco.org/docs/>
- Linux audit userspace: <https://github.com/linux-audit/audit-userspace>