Agent Management Overview

​

Introduction

The Wazuh Dashboard provides comprehensive agent management capabilities that enable administrators to monitor, configure, and maintain security agents deployed across their infrastructure. The agent management interface serves as a centralized platform for overseeing all registered agents, their status, and operational metrics.

​

Agent Management Interface

The agent management interface is accessed through the Endpoints section of the Wazuh Dashboard. This section provides a unified view of all agents registered with the Wazuh manager.

​

Endpoints Summary Dashboard

The Endpoints Summary Dashboard displays critical metrics and statistics about your agent fleet:

• Agent Status Distribution: Visual representation of agents by status (Active, Disconnected, Pending, Never Connected)
• Operating System Distribution: Breakdown of agents by platform (Linux, Windows, macOS)
• Agent Groups: Distribution of agents across configured groups
• Total Agent Count: Overall number of registered agents

The dashboard uses interactive donut charts that allow filtering the agent table by clicking on specific status categories or operating systems. Component implementation: endpoints-summary-dashboard.tsx

​

Agent Status Categories

Agents in the Wazuh Dashboard are classified into the following status categories:

• Active: Agents that are currently connected and sending data to the manager
• Disconnected: Agents that were previously connected but are no longer communicating
• Pending: Agents that are registered but awaiting initial configuration
• Never Connected: Agents that have been registered but have never established a connection

Each status is color-coded in the interface:

• Active: Green (success)
• Disconnected: Red (danger)
• Pending: Yellow (warning)
• Never Connected: Gray (disabled)

Status implementation: agent-status.tsx:1

​

Agent Information Display

Each agent displays the following key information in the agents table:

• Agent ID: Unique identifier assigned to the agent
• Agent Name: Configurable name for the agent
• IP Address: Network address of the agent
• Operating System: Platform and version information
• Wazuh Version: Version of the Wazuh agent software
• Group Assignments: Groups to which the agent belongs
• Last Keep Alive: Timestamp of the last communication
• Status: Current connection status
• Sync Status: Synchronization state with the manager

​

Agent Welcome Screen

When viewing an individual agent, the welcome screen provides an at-a-glance overview of the agent’s security posture:

​

Agent Information Panel

Displays comprehensive agent details including:

• Agent version
• Operating system details
• Registration date
• Last keep alive timestamp
• IP address
• Group memberships

​

Security Dashboards

The welcome screen includes multiple security-focused visualizations:

• Vulnerability Panel: Displays vulnerability count and severity distribution
• Security Configuration Assessment: Recent SCA scan results
• File Integrity Monitoring: Recent FIM events
• MITRE ATT&CK: Top tactics and techniques detected
• Events Count: Real-time event statistics across different categories
• Compliance Requirements: PCI DSS, GDPR, NIST, and other regulatory framework compliance

Component implementation: agents-welcome.js:1

​

System Inventory Metrics

The System Inventory panel displays hardware and software information collected from the agent:

• Cores: Number of CPU cores
• Memory: Total system memory
• CPU: Processor model and specifications
• Hostname: System hostname
• Serial Number: Hardware serial number

This data is collected through the Syscollector module and displayed using the InventoryMetrics component. Component implementation: syscollector-metrics.tsx:1

​

Quick Module Access

The agent welcome screen provides quick navigation to security modules supported by the agent:

• Vulnerability Detection: View and analyze detected vulnerabilities
• Security Configuration Assessment: Access SCA scans and policy compliance
• File Integrity Monitoring: Monitor file and registry changes
• MITRE ATT&CK: Analyze threat intelligence and attack patterns
• Threat Hunting: Investigate security threats and anomalies
• Configuration: View and modify agent configuration

The interface dynamically displays only modules supported by the agent’s version and configuration.

​

Agent Table Features

​

Search and Filtering

The agents table supports advanced filtering capabilities:

• WQL (Wazuh Query Language): Powerful query syntax for complex filters
  • Status filtering: status=active
  • OS filtering: os.platform~Linux
  • Group filtering: group=webservers
  • Null value filtering: group=null or os.platform=null
• Search Bar: Free-text search across agent fields
• Column Sorting: Sort by any column in ascending or descending order
• Filter Persistence: Table filters are preserved in session storage

​

Bulk Operations

The table supports bulk operations on selected agents:

• Edit Groups: Modify group assignments for multiple agents
• Upgrade Agents: Initiate upgrades for selected agents
• Remove Agents: Delete agents from the manager

Selection options include:

• Individual agent selection via checkboxes
• Select all agents on current page
• Select all agents matching current filters

Table implementation: agents-table.tsx:1

​

Authorization and Permissions

Agent management operations require specific permissions:

• Read Agents: agent:read permission on agent:id:* or agent:group:* resources
• Create Agents: agent:create permission
• Modify Groups: group:modify_assignments permission
• Upgrade Agents: Appropriate task permissions
• Delete Agents: Agent deletion permissions

Users without required permissions will see authorization prompts or disabled actions.

​

Agent Upgrade Management

The dashboard provides upgrade management capabilities:

​

Upgrade Monitoring

• Upgrades in Progress: Panel showing active upgrade tasks
• Task Status: Real-time status of upgrade operations
• Task History: View completed upgrade tasks
• Upgrade Notifications: Visual indicators for successful or failed upgrades

​

Upgrade Requirements

• Manager API version must be 4.2.0 or higher for upgrade features
• Agents must be in “Active” status to initiate upgrades
• Users must have task:status permission to view upgrade tasks

Component implementation: upgrade-agent-modal.tsx:1

​

API Integration

Agent management features interact with the following Wazuh API endpoints:

• GET /agents: Retrieve agent list with filtering and pagination
• GET /agents/{agent_id}: Get detailed agent information
• GET /agents/{agent_id}/stats/agent: Retrieve agent statistics
• GET /agents/{agent_id}/stats/logcollector: Get log collector statistics
• POST /agents: Register new agents
• PUT /agents/{agent_id}/group: Modify agent group assignments
• DELETE /agents: Remove agents from the manager
• PUT /agents/upgrade: Initiate agent upgrades

All API requests are handled through the WzRequest service, which manages authentication, error handling, and response processing.

​

Best Practices

​

Agent Organization

• Use meaningful agent names that reflect the system’s purpose or location
• Organize agents into logical groups based on function, environment, or location
• Regularly review and remove agents that are no longer in use
• Monitor “Never Connected” agents and investigate registration issues

​

Monitoring

• Set up alerts for agents transitioning to “Disconnected” status
• Regularly review agent keep alive timestamps
• Monitor agent version distribution and plan upgrades
• Use the dashboard filters to identify agents requiring attention

​

Maintenance

• Keep agents updated to the latest compatible version
• Review and update group assignments as infrastructure changes
• Regularly audit agent configurations for compliance
• Use bulk operations for efficient management of multiple agents

​

Related Documentation

• Agent Deployment
• Agent Monitoring
• Agent Configuration
• System Inventory