Configuration

Syscollector is configured in the agent's ossec.conf file using the <wodle name="syscollector"> section. The module supports both basic inventory collection and advanced synchronization features for persistent inventory state management.

Important: Starting in version 5.0, vulnerability detection is handled by a separate Vulnerability Detector module. Syscollector focuses exclusively on inventory collection (packages, OS, hotfixes, etc.), while vulnerability detection and CVE correlation are performed independently.

Basic Configuration

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

    <!-- Inventory categories -->
    <hardware>yes</hardware>
    <os>yes</os>
    <network>yes</network>
    <packages>yes</packages>
    <ports all="yes">yes</ports>
    <processes>yes</processes>
    <users>yes</users>
    <groups>yes</groups>
    <services>yes</services>
    <browser_extensions>yes</browser_extensions>
    <hotfixes>yes</hotfixes> <!-- Windows only -->

    <!-- Rate limiting -->
    <max_eps>50</max_eps>                        <!-- Stateless/real-time inventory event rate limit -->
    <notify_first_scan>no</notify_first_scan>    <!-- First scan notification -->

    <!-- Advanced synchronization settings -->
    <synchronization>
        <enabled>yes</enabled>                    <!-- Enable/disable persistence -->
        <interval>300</interval>                  <!-- Sync interval in seconds -->
        <response_timeout>60</response_timeout>   <!-- Response timeout in seconds -->
        <max_eps>50</max_eps>                    <!-- Max sync events per second (0 = unlimited) -->
        <integrity_interval>86400</integrity_interval>  <!-- Integrity check interval in seconds (24 hours) -->
    </synchronization>
</wodle>

Configuration Options

Basic Module Settings

Inventory Categories

Note: The ports element accepts an optional all attribute:

• <ports all="yes">: Scan all ports
• <ports all="no">: Scan only listening ports

Synchronization Configuration

The synchronization feature enables persistent inventory state management through the Agent Sync Protocol.

Synchronization Configuration Parameters

Configuration Details

Enable/Disable Persistence

The enabled parameter controls whether Syscollector uses persistence or falls back to legacy behavior:

<synchronization>
    <enabled>yes</enabled>
</synchronization>

Implementation:

unsigned int enable_synchronization:1;  /* Enable database synchronization */

When disabled, Syscollector only generates stateless events without persistence.

Synchronization Interval

Controls how frequently the agent attempts to synchronize pending inventory events:

<synchronization>
    <interval>300</interval>  <!-- 5 minutes -->
</synchronization>

Implementation:

uint32_t sync_interval;  /* Synchronization interval */

Considerations:

• Lower values provide faster synchronization but increase manager load
• Higher values reduce network traffic but delay inventory delivery
• Should account for inventory scan frequency to avoid overwhelming sync queue

Response Timeout

Defines how long to wait for manager acknowledgments during synchronization:

<synchronization>
    <response_timeout>60</response_timeout>
</synchronization>

Implementation:

uint32_t sync_response_timeout;  /* Minimum interval for the synchronization process */

Considerations:

• Should be adjusted based on network latency
• Too low may cause unnecessary retries
• Too high may delay error detection
• Inventory payloads can be larger than FIM events, may need higher timeouts

Sync Events Per Second

Controls the rate of synchronization messages sent to the manager:

<synchronization>
    <max_eps>50</max_eps>
</synchronization>

Implementation:

uint32_t sync_max_eps;  /* Maximum sync events per second */

Purpose:

• Prevents overwhelming the manager with inventory synchronization traffic
• Separate from stateless inventory event rate limiting
• Set to 0 for unlimited (not recommended for production)

Integrity Check Interval

Controls how frequently each inventory table's integrity is verified with the manager:

<synchronization>
    <integrity_interval>86400</integrity_interval>  <!-- 24 hours -->
</synchronization>

Implementation:

uint32_t integrity_interval;  /* Time between integrity checks per table (seconds) */

Behavior:

• Each of the 13 inventory tables (osinfo, hwinfo, packages, processes, ports, network_iface, network_protocol, network_address, users, groups, services, browser_extensions, hotfixes) is checked independently
• When integrity_interval elapses for a table:
  1. Agent calculates checksum-of-checksums for the table
  2. Sends checksum to manager for validation
  3. If checksums match: integrity confirmed, last_sync_time updated
  4. If checksums mismatch: full table recovery initiated
• Recovery process involves sending all table rows to the manager

Considerations:

• Default: 86400 seconds (24 hours) - balances reliability and performance
• Each table tracks its own last_sync_time independently

Recovery on Mismatch: When checksums don't match, the agent performs full table recovery:

1. Increases version number for all table entries
2. Retrieves all rows from the table
3. Sends each row to the manager for synchronization
4. Manager compares with its database and resolves differences
5. Updates last_sync_time after successful recovery

First Scan Notification

Controls whether Syscollector generates events during the initial inventory scan:

<notify_first_scan>no</notify_first_scan>

Implementation:

unsigned int notify_first_scan:1;  /* Generate events on first scan */

Behavior:

• When yes: Generates events for all inventory items found during initial scan
• When no (default): Suppresses events during first scan, only reports changes after baseline establishment

Stateless Inventory Event Rate Limit

Controls the maximum rate of stateless inventory events sent to the manager:

<max_eps>50</max_eps>

Implementation:

uint32_t max_eps;  /* Maximum events per second for stateless inventory */

Purpose:

• Limits immediate inventory change notifications
• Separate from synchronization event rate limiting

Event Rate Control

Dual Rate Limiting

Syscollector implements separate rate controls for different event types:

Stateless Inventory Events

<max_eps>50</max_eps>  <!-- Outside synchronization block -->

Controls:

• Stateless immediate inventory change alerts
• Higher priority than sync messages

Synchronization Events

<synchronization>
    <max_eps>50</max_eps>  <!-- Inside synchronization block -->
</synchronization>

Controls:

• Stateful persistence messages sent during sync sessions
• Batch inventory state synchronization

Configuration Examples

High-Frequency Environments

For environments with frequent inventory changes:

<wodle name="syscollector">
    <max_eps>100</max_eps>
    <notify_first_scan>no</notify_first_scan>

    <synchronization>
        <enabled>yes</enabled>
        <interval>120</interval>         <!-- Sync every 2 minutes -->
        <response_timeout>60</response_timeout>
        <max_eps>25</max_eps>           <!-- Higher sync throughput -->
        <integrity_interval>1h</integrity_interval>  <!-- Check integrity every hour -->
    </synchronization>
</wodle>

Minimal Configuration (Performance Optimized)

<wodle name="syscollector">
    <disabled>no</disabled>
    <interval>24h</interval>
    <hardware>yes</hardware>
    <os>yes</os>
    <packages>yes</packages>
    <!-- Disable resource-intensive scans -->
    <processes>no</processes>
    <ports>no</ports>
    <browser_extensions>no</browser_extensions>
</wodle>

Security-Focused Configuration

<wodle name="syscollector">
    <disabled>no</disabled>
    <interval>1h</interval>
    <packages>yes</packages>
    <services>yes</services>
    <users>yes</users>
    <groups>yes</groups>
    <hotfixes>yes</hotfixes>
    <ports all="yes">yes</ports>
</wodle>

High-Frequency Monitoring

<wodle name="syscollector">
    <disabled>no</disabled>
    <interval>5m</interval>
    <processes>yes</processes>
    <ports>yes</ports>
    <synchronization>
        <max_eps>50</max_eps>
    </synchronization>
</wodle>

Platform Notes

• Windows: hotfixes category is Windows-specific
• Linux: Package collection varies by distribution (RPM, DEB, etc.)
• macOS: Includes .pkg files and Homebrew packages
• All platforms: Browser extensions support major browsers

Testing Configuration

Validate configuration syntax:

/var/ossec/bin/wazuh-agentd -t

Monitor for errors:

tail -f /var/ossec/logs/ossec.log | grep syscollector