EDR Agent API

Technical reference for the four EDR agent endpoints — enrollment, heartbeat, event posting, and command polling. Required for custom agent development.

Route: /edr/agents

Agent API overview

API Reference

EDR Agent API Overview

The EDR agent communicates with GuardFoxCopilot via four endpoints. All agent requests must include:

X-GuardFox-Agent-Token: <token-from-enrollment>
Content-Type: application/json

Endpoint summary

Endpoint	Method	Purpose	Auth
`/api/edr/enroll`	POST	Register agent, get token	Enrollment key
`/api/edr/heartbeat`	POST	Check in every 30s, get commands	Agent token
`/api/edr/events`	POST	Post batch of security events	Agent token
`/api/edr/commands`	GET	Poll for pending commands	Agent token
`/api/edr/commands`	PATCH	Report command result	Agent token

Authentication flow

Agent installer calls /api/edr/enroll with the EDR_ENROLL_KEY
Server returns a per-agent token (stored as SHA-256 hash in DB)
All subsequent calls use X-GuardFox-Agent-Token: <token>
Token is cached in memory for 60s to reduce DB lookups

Posting events

API Reference

Posting Events to /api/edr/events

POST /api/edr/events
X-GuardFox-Agent-Token: <token>

{
  "hostname": "DESKTOP-WIN11-01",
  "events": [
    {
      "type":        "process_injection",
      "severity":    "critical",
      "description": "ETW: process hollowing in svchost.exe",
      "process":     "svchost.exe",
      "pid":         1284,
      "commandLine": "svchost.exe -k netsvcs",
      "hash":        "d41d8cd98f00b204...",
      "srcIp":       "192.168.1.10",
      "mitre":       "T1055 - Process Injection",
      "timestamp":   "2026-06-25T14:32:00.000Z"
    }
  ]
}

Auto-severity mapping

If you don't set severity, the server derives it from the event type:

Critical: ransomware_encrypt, vss_delete, lsass_dump, process_injection, yara_match, c2_beacon
High: ps_encoded, lolbin, lateral_smb, dc_sync, dll_hijack, scheduled_task
Medium: anything with "warn" or "suspicious" in the type
Low: everything else

Limits

Max 100 events per batch
All event detail goes into dataJson (Text field) — no individual columns for process/pid/hash
createdAt is set automatically by Prisma — don't send it
Original event timestamp is preserved inside dataJson.originalTimestamp

IOC cross-reference

Every batch is automatically checked against your ThreatIndicator table. If any srcIp, dstIp, hash, or domain from the events matches a known indicator, the event is tagged with iocMatchId and the agent's iocMatchCount is incremented.