Enrollment Process | EyeLog Docs

Overview

Enrollment establishes trust between an agent and the collector. After enrollment, all communication uses mTLS (mutual TLS) with certificates signed by the collector's internal CA and bound to the machine's hardware fingerprint.

Simplified Model: EyeLog uses a streamlined enrollment process without tokens. The trust model is asymmetric: the collector controls agents, not the reverse. A rogue agent can only send fake data or receive commands that execute on its own machine.

Enrollment Modes

The collector supports two enrollment modes:

Mode	Behavior	Use Case
`open`	Any agent auto-enrolls immediately	Development, trusted networks
`restricted`	Allowed IPs auto-enroll; others based on `unknown_action`	Production environments

Open Enrollment

# Collector config
enrollment:
  mode: open
  default_manifest: monitor

Any agent that connects is automatically enrolled and assigned the default manifest.

Restricted Enrollment

# Collector config
enrollment:
  mode: restricted
  default_manifest: monitor
  allowed:
    - 10.0.0.0/8
    - 192.168.1.0/24
    - 203.0.113.50
  unknown_action: pending  # or "reject"

unknown_action	Behavior
`pending`	Unknown IPs go to pending queue for admin approval
`reject`	Unknown IPs are rejected immediately

Enrollment Flow

      AGENT                                    COLLECTOR
        |                                          |
        |  1. Connect & send EnrollRequest         |
        |     - CSR (Certificate Signing Request)  |
        |     - Machine fingerprint                |
        |     - Agent version, hostname, OS        |
        | ---------------------------------------->|
        |                                          |
        |                          2. Validate     |
        |                          - Check mode    |
        |                          - Check IP      |
        |                          - Sign CSR      |
        |                                          |
        |  3. EnrollResponse                       |
        |     - Agent ID                           |
        |     - Signed certificate                 |
        |     - CA certificate                     |
        |     - Assigned manifest                  |
        |<-----------------------------------------|
        |                                          |
   4. Store certs                                  |
   5. Apply manifest                               |
   6. Connect with mTLS                            |
        |=========== OPERATIONAL =================>|

Machine Fingerprint

The agent's identity is bound to physical hardware through a machine fingerprint:

Machine Fingerprint = SHA-256(SMBIOS UUID | System Serial | Board Serial)

Component	Source	Why
SMBIOS Product UUID	Motherboard firmware	Primary identifier, set at manufacturing
System Serial Number	OEM assigned	Unique per machine from manufacturer
Board Serial Number	Motherboard	Additional uniqueness factor
Fallback: OS machine-id	Operating system	Weaker, changes on reinstall

Platform-specific collection:

Linux: /sys/class/dmi/id/*
macOS: IOKit (IOPlatformUUID, IOPlatformSerialNumber)
Windows: WMIC (csproduct, baseboard)

Certificate Binding

During enrollment, the fingerprint is embedded in the certificate's Subject Alternative Name (SAN):

Agent                           Collector
  |                                |
  |-- Enroll(CSR, fingerprint) -->|
  |                                |
  |                          Sign cert with fp
  |                          embedded in SAN
  |                                |
  |<---- Certificate(fp in SAN) ---|

This means:

Certificate is cryptographically bound to specific hardware
Stolen cert on different machine = fingerprint mismatch = rejected
Hardware change (motherboard replacement) = need new enrollment

Connection Validation

Validation happens at two levels:

TLS Handshake (connection level)
+-- Verify certificate signature (CA signed?)
+-- Check certificate expiry
+-- Check revocation list (is fingerprint revoked?)
+-- REJECT if any fail -> connection drops immediately

Application Level (first request)
+-- Agent sends live fingerprint in request
+-- Compare: cert.SAN.fingerprint == live_fingerprint
+-- MATCH -> proceed normally
+-- MISMATCH -> revoke cert, drop connection (theft detected)

Certificate Lifecycle

30-day validity (configurable)
Auto-renewal at 50% lifetime (15 days remaining)
Renewal requires fingerprint match
Revocation via collector (checked at TLS level)
Expired cert = must re-enroll

Certificate Storage

/etc/eyelog/           (Linux)
/Library/Application Support/EyeLog/  (macOS)
%ProgramData%\EyeLog\  (Windows)

+-- config.yaml       # Collector address, settings
+-- agent.crt         # Certificate (from enrollment)
+-- agent.key         # Private key (never transmitted)
+-- manifest.json     # Current signed manifest

Re-Enrollment Scenarios

Scenario	Outcome
Same machine, cert expired	Re-enroll, same agent_id, new certificate
Different machine, stolen cert	Fingerprint mismatch, rejected, cert revoked
VM clone	Different fingerprint, treated as new agent
Motherboard replacement	Different fingerprint, treated as new agent

Rate Limiting

To prevent DoS via mass fake enrollments:

Max enrollments per IP: 10/hour
Configurable in collector settings

Why No Tokens?

The trust model is asymmetric: collector controls agents, not the reverse.

A rogue agent can only:

Send fake data (pollutes dashboard, easily deleted)
Receive commands (executes on rogue machine, who cares)

A rogue agent cannot:

Access other agents
Control real infrastructure
Compromise the collector

Security is ensured through:

Machine fingerprint binds cert to hardware
mTLS for all post-enrollment communication
Manifest signatures prevent tampering

← Previous State Machine Next → Feature Specification