Using the registration service

The ossec-authd daemon allows to register agents automatically.

The manager uses ossec-authd to launch the registration service.
On the agent, agent-auth is used to connect to the registration service.

Launching the daemon on the manager with default options would allow any agent to register itself, and then connect to it. The secure methods provide some mechanisms to authorize the connections.

Type	Method			Description
Not secure	Simple method			The easiest method. There is no authentication or host verification.
Secure	Password authorization			Allows agents to authenticate via a shared password. This method is easy but does not perform host validation.
	Host verification using SSL	Manager verification using SSL		The manager's certificate is signed by a CA that agents use to validate the server. This may include host checking.
		Agent verification using SSL	With host validation	The same as above, but the manager verifies the agent's certificate and address. There should be one certificate per agent.
		Agent verification using SSL	Without host validation	The manager validates the agent by CA but not the host address. This method allows the use of a shared agent certificate.

Note

The secure methods can be combined for a stronger security during the registration process.

Prerequisites

The registration service requires an SSL certificate on the manager in order to work. If the system already has the openssl package, a new one will be generated automatically during the installation process. The certificate (and its key) will be available at /var/ossec/etc/.

It's possible to use a valid certificate with its key, just by copying them into the same path:

# cp <ssl_cert> /var/ossec/etc/sslmanager.cert
# cp <ssl_key> /var/ossec/etc/sslmanager.key

Otherwise, you can create a self-signed certificate using the following command:

# openssl req -x509 -batch -nodes -days 365 -newkey rsa:2048 -out /var/ossec/etc/sslmanager.cert -keyout /var/ossec/etc/sslmanager.key

Simple method

This is the easiest method to register agents. It doesn't require any kind of authorization or host verification. To do so, follow these steps:

On the agents, run the agent-auth program, pointing to the Wazuh manager address.

# /var/ossec/bin/agent-auth -m <MANAGER_IP>

Edit the Wazuh agent configuration to add the Wazuh manager address.

In the file /var/ossec/etc/ossec.conf, replace MANAGER_IP with the Wazuh manager address:
<client>
  <server>
    <address>MANAGER_IP</address>
    ...
  </server>
</client>
Or using sed to replace it with the Wazuh manager address, using 10.0.0.4 as an example IP:
# sed -i 's:MANAGER_IP:10.0.0.4:g' /var/ossec/etc/ossec.conf

Restart the agent.

For Systemd:

# systemctl restart wazuh-agent

For SysV Init:

# service wazuh-agent restart

Password authorization

You can protect the manager from unauthorized registrations by using a password. Choose one by yourself, or let the registration service generate a random password.

To allow this option, change the value to yes in the /var/ossec/etc/ossec.conf file:

<auth>
  ...
  <use_password>yes</use_password>
  ...
</auth>

To apply the changes, restart the manager:

For Systemd:

# systemctl restart wazuh-manager

For SysV Init:

# service wazuh-manager restart

To use a custom password, edit the /var/ossec/etc/authd.pass file and write it. For example, if we want to use TopSecret as a password:

# echo "TopSecret" > /var/ossec/etc/authd.pass

Then, restart the manager.

Host verification using SSL

Creating a Certificate of Authority (CA)

To use the registration service with SSL certification, you must create a Certificate of Authority that will be used to sign certificates for the manager and the agents. The hosts will receive a copy of this CA in order to verify the remote certificate:

# openssl req -x509 -new -nodes -newkey rsa:2048 -keyout rootCA.key -out rootCA.pem -batch -subj "/C=US/ST=CA/O=Manager"

Warning

The file rootCA.key that we have just created is the private key of the CA. It is needed to sign other certificates and it is critical to keep it secure. Note that we will never copy this file to other hosts.

Manager verification using SSL

Issue and sign a certificate for the manager, entering the hostname or the IP address that agents will use to connect to the server. For example, if the manager's IP is 192.168.1.2:

# openssl req -new -nodes -newkey rsa:2048 -keyout sslmanager.key -out sslmanager.csr -subj '/C=US/CN=192.168.1.2'
# openssl x509 -req -days 365 -in sslmanager.csr -CA rootCA.pem -CAkey rootCA.key -out sslmanager.cert -CAcreateserial

Copy the newly created certificate (and its key) to the /var/ossec/etc folder on the manager, and restart it:

# cp sslmanager.cert sslmanager.key /var/ossec/etc

# systemctl restart wazuh-manager

Copy the CA (but not the key) to the /var/ossec/etc folder on the agent, and run the agent-auth program:

For Linux systems:

# cp rootCA.pem /var/ossec/etc
# /var/ossec/bin/agent-auth -m 192.168.1.2 -v /var/ossec/etc/rootCA.pem

For Windows systems, the CA must be copied to C:\Program Files (x86)\ossec-agent:

# cp rootCA.pem C:\Program Files (x86)\ossec-agent
# C:\Program Files (x86)\ossec-agent\agent-auth.exe -m 192.168.1.2 -v C:\Program Files (x86)\ossec-agent\rootCA.pem

Agent verification using SSL

Agent verification (without host validation)

In this example, we are going to create a certificate for agents without specifying their hostname, so that the same certificate can be used by many of them. This verifies that agents have a certificate signed by our CA, no matter where they're connecting from.

Issue and sign a certificate for the agent. Note that we will not enter the common name field:

# openssl req -new -nodes -newkey rsa:2048 -keyout sslagent.key -out sslagent.csr -batch
# openssl x509 -req -days 365 -in sslagent.csr -CA rootCA.pem -CAkey rootCA.key -out sslagent.cert -CAcreateserial

Copy the CA (but not the key) to the /var/ossec/etc folder on the manager (if it's not already there) and start the registration service:

# cp rootCA.pem /var/ossec/etc
# /var/ossec/bin/ossec-authd -v /var/ossec/etc/rootCA.pem

Copy the newly created certificate (and its key) to the /var/ossec/etc folder on the agent, and run the agent-auth program. For example, if the manager's IP address is 192.168.1.2:

For Linux systems:

# cp sslagent.cert sslagent.key /var/ossec/etc
# /var/ossec/bin/agent-auth -m 192.168.1.2 -x /var/ossec/etc/sslagent.cert -k /var/ossec/etc/sslagent.key

For Windows systems, the CA must be copied to C:\Program Files (x86)\ossec-agent:

# cp sslagent.cert sslagent.key C:\Program Files (x86)\ossec-agent
# C:\Program Files (x86)\ossec-agent\agent-auth.exe -m 192.168.1.2 -x C:\Program Files (x86)\ossec-agent\sslagent.cert -k C:\Program Files (x86)\ossec-agent\sslagent.key

Agent verification (with host validation)

This is an alternative method to the previous one. In this case, we will bind the agent's certificate to its IP address as seen by the manager.

Issue and sign a certificate for the agent, entering its hostname or IP address into the common name field. For example, if the agent's IP is 192.168.1.3:

# openssl req -new -nodes -newkey rsa:2048 -keyout sslagent.key -out sslagent.csr -subj '/C=US/CN=192.168.1.3'
# openssl x509 -req -days 365 -in sslagent.csr -CA rootCA.pem -CAkey rootCA.key -out sslagent.cert -CAcreateserial

Copy the CA (but not the key) to the /var/ossec/etc folder on the manager (if it's not already there) and start the registration service. Note that we use the -s flag in order to enable agent host validation:

# cp rootCA.pem /var/ossec/etc
# /var/ossec/bin/ossec-authd -v /var/ossec/etc/rootCA.pem -s

Copy the newly created certificate (and its key) to the /var/ossec/etc folder on the agent, and run the agent-auth program. For example, if the manager's IP address is 192.168.1.2:

For Linux systems:

# cp sslagent.cert sslagent.key /var/ossec/etc
# /var/ossec/bin/agent-auth -m 192.168.1.2 -x /var/ossec/etc/sslagent.cert -k /var/ossec/etc/sslagent.key

For Windows systems, the CA must be copied to C:\Program Files (x86)\ossec-agent:

cp sslagent.cert sslagent.key C:\Program Files (x86)\ossec-agent
C:\Program Files (x86)\ossec-agent\agent-auth.exe -m 192.168.1.2 -x C:\Program Files (x86)\ossec-agent\sslagent.cert -k C:\Program Files (x86)\ossec-agent\sslagent.key

Additional configurations

By default, the registration service adds the agents with their static IP address. If you want to add them with a dynamic IP (like using any on the manage_agents tool), you must change the manager's configuration file (/var/ossec/etc/ossec.conf):

<auth>
  <use_source_ip>no</use_source_ip>
</auth>

Duplicate IPs are not allowed, so an agent won't be added if there is already another agent registered with the same IP. By changing the configuration file, ossec-authd can be told to force a registration if it finds an older agent with the same IP address. This will make the older agent's registration be deleted:

<auth>
  <force_insert>yes</force_insert>
  <force_time>0</force_time>
</auth>

The 0 on <force-time> means the minimum time, in seconds, since the last connection of the old agent (the one to be deleted). In this case, it means to delete the old agent's registration regardless of how recently it has checked in.