Agent Configuration

Configure Wazuh agents through the Dashboard, including group-based configuration, module settings, and policy management.

Introduction

The Wazuh Dashboard provides a comprehensive interface for viewing and managing agent configurations. Configuration can be applied at the individual agent level or through group-based policies, enabling centralized management of agent settings across your infrastructure.

Accessing Agent Configuration

Agent configuration can be accessed through multiple paths:

Individual Agent Configuration

1. Navigate to the Endpoints section
2. Select an agent from the table
3. Click on the “Configuration” tab

Navigation path: /agents?tab=configuration&agent={agent_id}

Configuration View

The configuration interface displays:

• Current active configuration
• Configuration source (local or group-based)
• Module-specific settings
• Synchronization status

Component implementation: configuration-main.js:1

Configuration Hierarchy

Configuration Sources

Agent configuration is determined by the following hierarchy (in order of precedence):

1. Local Agent Configuration: Settings in the agent’s local ossec.conf file
2. Group Configuration: Settings from assigned groups (most specific to least specific)
3. Default Group: Settings from the “default” group
4. Manager Defaults: Built-in default values

Group-Based Configuration

Groups enable centralized configuration management:

• Agents can belong to multiple groups
• Configuration from all groups is merged
• More specific groups override less specific ones
• Group assignments can be modified through the Dashboard

Managing Agent Groups

Viewing Group Assignments

Agent group memberships are displayed:

• In the agents table (“Group” column)
• In the agent details view
• In the agent welcome screen

Modifying Group Assignments

Single Agent

1. Select an agent from the agents table
2. Click the “Actions” menu
3. Select “Edit groups”
4. Modify group assignments
5. Save changes

Component implementation: edit-groups-modal.tsx:1

Multiple Agents (Bulk Operation)

1. Select multiple agents using checkboxes
2. Click “Edit groups” from the global actions menu
3. Choose operation:
   • Add groups: Add groups to selected agents
   • Remove groups: Remove groups from selected agents
   • Set groups: Replace all groups with specified groups
4. Confirm changes

Component implementation: edit-groups-modal.tsx:1 (global actions)

Group Assignment Permissions

Modifying group assignments requires:

• Action: group:modify_assignments
• Resource: group:id:*

Users without this permission will see disabled actions or authorization prompts.

Configuration Modules

The Wazuh agent supports configuration for various security modules:

Log Collector

Configures which log files and sources the agent monitors:

<localfile>
  <location>/var/log/syslog</location>
  <log_format>syslog</log_format>
</localfile>

Settings include:

• Log file locations
• Log format specifications
• Filtering rules
• Frequency of log reading

File Integrity Monitoring (FIM)

Defines files and directories to monitor for changes:

<syscheck>
  <directories check_all="yes">/etc</directories>
  <directories check_all="yes">/bin</directories>
  <frequency>43200</frequency>
</syscheck>

Settings include:

• Monitored directories and files
• Check frequency
• Attributes to monitor (permissions, ownership, content)
• File exclusions

Security Configuration Assessment (SCA)

Configures policy scans and compliance checks:

<sca>
  <enabled>yes</enabled>
  <scan_on_start>yes</scan_on_start>
  <interval>12h</interval>
</sca>

Settings include:

• Enabled policies
• Scan frequency
• Scan on start behavior
• Custom policy files

Vulnerability Detection

Configures vulnerability scanning behavior:

<vulnerability-detection>
  <enabled>yes</enabled>
  <interval>5m</interval>
</vulnerability-detection>

Settings include:

• Detection enablement
• Scan intervals
• Package managers to monitor
• CVE database updates

System Inventory (Syscollector)

Configures system inventory data collection:

<wodle name="syscollector">
  <disabled>no</disabled>
  <interval>1h</interval>
  <scan_on_start>yes</scan_on_start>
</wodle>

Collects:

• Hardware information (CPU, memory, serial numbers)
• Operating system details
• Installed packages
• Network interfaces
• Running processes
• Open ports

Data is displayed in the System Inventory panel: syscollector-metrics.tsx:1

Rootcheck

Configures rootkit and malware detection:

<rootcheck>
  <disabled>no</disabled>
  <frequency>43200</frequency>
</rootcheck>

Settings include:

• Scan frequency
• Rootkit databases
• System audit checks

Command Monitoring

Configures periodic command execution and monitoring:

<localfile>
  <log_format>command</log_format>
  <command>df -P</command>
  <frequency>360</frequency>
</localfile>

Settings include:

• Commands to execute
• Execution frequency
• Output handling

Configuration Synchronization

Sync Mechanism

Configuration synchronization ensures agents receive updates:

1. Configuration Change: Administrator modifies group or shared configuration
2. Manager Notification: Manager marks affected agents for synchronization
3. Sync Request: Agent requests updated configuration on next connection
4. Download: Agent downloads and applies new configuration
5. Restart: Agent modules reload with new settings

Sync Status Monitoring

Monitor configuration synchronization:

• Synced: Agent has the latest configuration
• Not Synced: Agent has pending configuration updates
• Syncing: Synchronization in progress

Sync status is displayed:

• In the agents table
• In the agent details view
• Through the agent sync component: agent-synced.tsx:1

Forcing Synchronization

To force configuration synchronization:

1. Restart the agent service
2. Wait for the next keep-alive interval
3. Verify sync status in the Dashboard

Alternatively, trigger synchronization through the manager:

/var/ossec/bin/agent_control -R -u <agent_id>

Configuration Validation

Server-Side Validation

The Wazuh manager validates configuration before distribution:

• XML syntax validation
• Schema validation
• Value range checks
• Dependency verification

Agent-Side Validation

Agents validate received configuration:

• XML parsing
• Module compatibility checks
• Permission verification
• Resource availability

Invalid configurations are:

• Rejected by the agent
• Logged in agent logs
• Reported to the manager

Agent Module Version Support

Version Compatibility

Different agent versions support different modules and features:

• The Dashboard checks agent version before displaying module options
• Unsupported modules display version requirement prompts
• Feature availability is validated: prompt-agent-feature-version.tsx:1

Module Support Detection

The Dashboard uses the hasAgentSupportModule() service to:

• Detect supported modules based on agent version
• Hide unsupported features from the interface
• Display appropriate prompts when features are unavailable

Component implementation: prompt-agent-no-support-module.tsx:1

Configuration Best Practices

Group Organization

Organize agents into logical groups:

• By Function: web-servers, database-servers, workstations
• By Environment: production, staging, development
• By Location: datacenter1, office-ny, cloud-aws
• By Compliance: pci-dss, hipaa, gdpr

Configuration Management

• Use group-based configuration for consistency
• Avoid agent-local configuration when possible
• Document group purposes and settings
• Test configuration changes on a subset before wide deployment

Security Considerations

• Restrict configuration modification permissions
• Audit configuration changes
• Use least privilege for agent permissions
• Validate configurations before deployment

Performance Tuning

• Adjust scan frequencies based on system load
• Balance security coverage with performance impact
• Monitor agent resource usage after configuration changes
• Use interval settings appropriate for the environment

Common Configuration Scenarios

Web Server Configuration

Group: webservers

Key settings:

• Monitor web server logs (Apache, Nginx)
• FIM on web root directories
• SCA policies for web server hardening
• Command monitoring for web service status

Database Server Configuration

Group: database-servers

Key settings:

• Monitor database logs (MySQL, PostgreSQL, Oracle)
• FIM on database configuration files
• SCA policies for database hardening
• Rootcheck for database-specific threats

Workstation Configuration

Group: workstations

Key settings:

• Monitor system logs (Windows Event Log, syslog)
• FIM on critical system directories
• SCA policies for workstation compliance
• Vulnerability detection for installed software

Cloud Instance Configuration

Group: cloud-instances

Key settings:

• Monitor cloud provider logs (CloudTrail, Azure Activity)
• FIM on application directories
• Syscollector for inventory tracking
• Vulnerability detection for package updates

Configuration Troubleshooting

Configuration Not Applied

Symptoms:

• Agent sync status: “Not Synced”
• Expected settings not active
• Modules not functioning as configured

Resolution:

1. Check agent sync status
2. Verify group assignments
3. Review agent logs for configuration errors
4. Manually trigger synchronization
5. Restart agent service

Module Not Working

Symptoms:

• Module appears disabled
• No data from configured module
• Module prompt displayed

Resolution:

1. Verify agent version supports the module: prompt-agent-feature-version.tsx:1
2. Check module configuration syntax
3. Review agent logs for module errors
4. Verify required permissions (file access, command execution)
5. Check resource availability (disk space, memory)

Configuration Conflicts

Symptoms:

• Unexpected configuration behavior
• Settings differ from group configuration
• Modules behaving inconsistently

Resolution:

1. Review configuration hierarchy
2. Check for local agent configuration overrides
3. Verify group assignment order
4. Examine merged configuration on agent
5. Remove conflicting local settings

Permission Issues

Symptoms:

• Cannot modify group assignments
• Configuration changes rejected
• “Edit groups” button disabled

Resolution:

1. Verify user has group:modify_assignments permission
2. Check resource-level permissions
3. Review RBAC configuration
4. Contact administrator for permission grants

Advanced Configuration

Labels

Assign labels to agents for better organization:

<labels>
  <label key="environment">production</label>
  <label key="region">us-east</label>
</labels>

Labels enable:

• Enhanced filtering in the Dashboard
• Custom reporting and analytics
• Integration with external systems

Client Buffer

Configure agent buffering for network resilience:

<client_buffer>
  <disabled>no</disabled>
  <queue_size>5000</queue_size>
  <events_per_second>500</events_per_second>
</client_buffer>

Settings:

• Buffer enablement
• Queue size
• Event rate limiting

Monitored through statistics: agent-stats.tsx:1

Enrollment Configuration

Configure agent enrollment behavior:

<client>
  <enrollment>
    <enabled>yes</enabled>
    <manager_address>manager.example.com</manager_address>
    <port>1515</port>
    <agent_name>custom-name</agent_name>
    <groups>group1,group2</groups>
  </enrollment>
</client>

Configuration Export and Backup

Exporting Configurations

While not directly available in the Dashboard, configurations can be:

• Backed up from the manager filesystem
• Version controlled (Git)
• Exported through API calls
• Documented in external systems

Configuration Locations

On the Wazuh manager:

• Shared Configuration: /var/ossec/etc/shared/
• Group Configurations: /var/ossec/etc/shared/<group_name>/
• Agent Configuration: /var/ossec/etc/shared/<group_name>/agent.conf

Related Documentation

• Agent Management Overview
• Agent Deployment
• Agent Monitoring
• System Inventory