Device Agent API

Agentul de dispozitiv API este protocolul JSON utilizat de probo-agentPuteți implementa acest protocol pentru a înregistra dispozitive și a raporta postura de la sisteme de operare, aparate sau medii pe care agentul oficial nu le acceptă încă.

Dispozitivul inițiază fiecare cerere; platforma nu poate trimite comenzi, scripturi sau verifica definiții la acesta.

Base URL

Append /api/agent/v1 la originea implementării platformei în care a fost creat dispozitivul.

Deployment	Base URL
US cloud	https://us.probo.com/api/agent/v1
EU cloud	https://eu.probo.com/api/agent/v1
Self-hosted	https://probo.example.com/api/agent/v1

API este destinat agenților nativi, nu clienților browser-ului și nu expune accesul browser-ului de origine încrucișată.

Device states

Fiecare înregistrare a dispozitivului se mișcă printr-o mașină de stat mic. Numai Agentul dispozitivului API și revocarea administratorului schimbă aceste stări după creare.

State	Meaning
PENDING	Enrollment token issued; no successful heartbeat yet
ACTIVE	Prima bătăi ale inimii a reușit; bătăile inimii și postura sunt permise
REVOKED	încheiat de către un administrator sau de către /unenroll

The first successful /heartbeat activates a PENDING device. /postures requires ACTIVEUn dispozitiv revocat nu poate fi nerevocat; creați un dispozitiv nou și înscrieți-vă din nou.

Protocol lifecycle

Diagrama de secvență arată înscrierea, ritmul cardiac independent și programele de postură și cele două moduri în care se încheie înscrierea unui agent.

sequenceDiagram
  actor Admin as Organization administrator
  participant Probo as Probo server
  participant Agent as Device agent

  Admin->>Probo: Create device
  Probo-->>Admin: Server URL and one-shot enrollment token
  Admin->>Agent: Configure server URL and token

  Agent->>Probo: POST /enroll with token
  Probo-->>Agent: Device API key
  Agent->>Probo: POST /heartbeat with API key
  Probo-->>Agent: Device ID, heartbeat interval, posture interval, server time

  par Heartbeat schedule
    loop Every heartbeat_interval_seconds
      Agent->>Probo: POST /heartbeat with device identity
      Probo-->>Agent: Updated intervals and server time
    end
  and Posture schedule
    loop Every posture_interval_seconds
      Agent->>Agent: Run local posture checks
      Agent->>Probo: POST /postures with results
      Probo-->>Agent: 204 No Content
    end
  end

  alt Device is revoked
    Agent->>Probo: POST /heartbeat or /postures
    Probo-->>Agent: 401 Unauthorized
    Agent->>Agent: Stop reporting and delete API key
  else Agent is removed
    Agent->>Probo: POST /unenroll
    Probo-->>Agent: 204 No Content
    Agent->>Agent: Delete local credentials
  end

Intervalele de bătăi ale inimii și de postură sunt valori separate returnate de fiecare bătăi ale inimii reușite. Tratați fiecare ca pe un temporizator propriu. Serverul returnează metadatele de programare, dar nu trimite niciodată lucrări dispozitivului. ZebraByte Device Agent security Frontiera de securitate și modelul de amenințare.

Implementation checklist

• Acceptați originea platformei și tokenul de înscriere ca intrări separate.
• Necesită HTTPS în afara dezvoltării locale și respinge URL-urile serverului care conțin credențiale, șiruri de interogări sau fragmente.
• Stochează cheia dispozitivului API într-un magazin secret corespunzător sistemului de operare sau într-un fișier care poate fi citit numai de contul de serviciu.
• Trimite Content-Type: application/json and Accept: application/json.
• Identificarea implementării cu o User-Agent, such as my-probo-agent/1.0.0.
• Send a successful /heartbeat Înainte de prima /postures request.
• Onorați intervalele returnate de fiecare bătăi ale inimii reușite ca temporizatori separați.
• Batch nu mai mult de 100 de posturi rezultate într-o singură solicitare.
• Nu înregistrați jetoane de înscriere, chei API sau dovezi de postură sensibile.
• On 401 Unauthorized după activare, opriţi raportarea şi ştergeţi cheia dispozitivului API

Reference implementation

Utilizați agentul oficial ca referință de lucru atunci când implementați protocolul:

• cmd/probo-agent
• pkg/deviceagent

Preferați să contribuiți la agentul oficial atunci când schimbarea aparține binarului partajat. Contribuiți la platforma Agent pentru căile sursă, cerințele DCO și cronologia de revizuire a securității. Cererile de retragere care ating agentul dispozitivului pot dura mai mult pentru a fuziona, deoarece le revizuim pe scară largă pentru securitatea punctului final.

Dacă aveți nevoie de asistență mai devreme decât permite ciclul oficial de lansare, implementați acest API în propriul agent.

Next steps

Authentication Schimbați un token de înregistrare și protejați cheia dispozitivului API

Endpoints Implement enrollment, heartbeat, posture, and unenrollment

Contributing Contribuiți la agentul oficial și ce să așteptați de la revizuire