Send shutdown event from the agent to the server

[vikman90]

Description

The Wazuh agent should send an event to the server when performing a graceful shutdown. This event will be a stateless message sent directly, bypassing the agent's queue.

This task presents a challenge: the agent must send the message while shutting down quickly. Therefore, an independent sending mechanism with a timeout will be implemented.

Requirements

• When the agent receives a shutdown signal, it must send to the server:
  • A stateless message indicating the shutdown.
  • A stateful message to update its status to "shut down."
• The agent must not re-authenticate after sending these messages.

Configuration

Proposed configuration option:

agent:
  shutdown_notify_timeout: 10s

Stateless message format

Metadata

{ "module": "agent" }

Data

{
  "event": {
    "original": "The agent is shutting down.",
    "created": "2025-02-10 11:30:01.000"
  }
}

Plan

1. Validate the stateless message format.
2. Propose the stateful message format, involving the Server and Indexer teams.
3. Add the shutdown_notify_timeout configuration option.
4. Develop the functionality to send both messages during the agent's shutdown routine.
5. Add tests for this use case.
6. Update technical documentation.

Definition of done

• The agent sends both stateless and stateful messages upon shutdown.
• Messages are sent without re-authentication.
• The shutdown_notify_timeout is configurable.
• Tests cover normal and edge cases.
• Documentation is updated accordingly.

Additional notes

• The stateful message format is yet to be defined.
• This design provides a "best effort" approach to mark the agent's status in the inventory. It does not guarantee the agent will be marked as disconnected after shutdown.
• The agent will also send these events when shutting down due to a system reboot.

[jr0me]

Update

Started issue by looking at requirements, created the requirement and looking into related code and involved parts.

[jr0me]

Update

• Made some small fixes and refactorings while assessing the Communicator and HttpClient tests
• Implemented a solution to the issue with placeholder event messages.

[jr0me]

Update

• Rebased due to changes to httpclient, some fixes had to be made.
• Removed start up message.

[jr0me]

Update

• Added timeout configuration setting.
• Replaced placeholder shutdown message. Current shutdown message on branch:

POST /api/v1/events/stateless HTTP/1.1
Host: localhost
User-Agent: WazuhXDR/5.0.0 (Endpoint; x86_64; Linux)
Accept: application/json
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJXYXp1aCIsImF1ZCI6IldhenVoIENvbW11bmljYXRpb25zIEFQSSIsImlhdCI6MTc0MDA1NzcyMiwiZXhwIjoxNzQwMDU4NjIyLCJ1dWlkIjoiMDlmODcyZGMtMTExYi00Mzg2LWFjMTktYTVmOGE3NmVmNGQxIn0.MEQCIGc5pB7R1iJ9XWy2Y_8hLf2oTnv59AGW8BKysSEzlo4hAiAw9zH_kWhi3SVDdXJzPNf1Id-4D9vt-i3hbC3_MEByVQ
Content-Type: application/json
Content-Length: 456

{"agent":{"groups":["validYaml","invalidYaml"],"host":{"architecture":"x86_64","hostname":"dell","ip":["192.168.0.10","fe80::fd02:ec4b:a7dc:9f60"],"os":{"name":"Ubuntu","type":"Linux","version":"22.04.5 LTS (Jammy Jellyfish)"}},"id":"09f872dc-111b-4386-ac19-a5f8a76ef4d1","name":"dummy","type":"Endpoint","version":"5.0.0"}}
{"module":"agent","operation":"shutdown"}
{"event":{"created":"2025-02-19T20:25:46.807Z","original":"The agent is shutting down."}}

[jr0me]

Update

Issue is now blocked, I cherry picked some small fixes and improvements from the branch, made from preliminary research of the involved components, into another one #617