Automatically deploying OSSEC on Windows using Wazuh API

| by Pedro de Castro | Wazuh 1.1
Post icon

In some environments the hardest part of the deployment process is the installation of OSSEC on Windows endpoints. Wazuh has created a tool to install, register and connect Windows agents using the capabilities of the RESTful API combined with a PowerShell script.

Prerequisites

  • Wazuh HIDS v2.0+
  • Wazuh RESTful API v2.0+
  • Powershell v2.0+ (built-in Windows Server 2008 R2 or superior)

Process explanation

The Powershell script covers two different processes in order to deploy an agent.
The first one is the installation. The script will run the agent installer, once complete, OSSEC will be installed by default at C:\ossec-agent\ folder.

The second one is the registering the agent, traditionally the process consists of manually adding the agent in the OSSEC Manager host (for example, using manage_agents), filling agent name and IP then exporting  the key into the Windows Agent then restarting.

Using the API we will accomplish the same process however it will completely automated. The PowerShell script will automatically send encrypted requests to the API, getting the hostname and IP, registering the agent and extracting the key. Then it will automatically import the key into the agent and do the agent restart.

Downloading the package

The full package consists in:

  • OSSEC Agent Installer.
  • Powershell deployment script.
  • Bat file for one-click-run the PS script.

Configuration

We have several options to configure and run the script, we need to specify four mandatory parameters:

api_ip: Your Wazuh API IP, usually it will be the same of your OSSEC Manager host IP.
api_user: Username set on your API.
api_password: Password set on your API
ossec_exe: Path to the OSSEC Agent installer, in this case it will be wazuh-winagent-v2.0.1-1.exe

Once the parameters are set, we can run the script, install and connect the agent, by default it will be installed on C:\ossec-agent. Next, the agent IP will be extracted from the request and the agent name will be the Windows hostname.

In case you want to specify any of these parameters, use “-help” to show the full options list.

Running

We have two different ways to run the script.
A. Open a new Powershell terminal as administrator, navigate to the script folder and run:

.\agent_deploy.ps1 -api_ip your_api_ip -username your_api_user -password your_api_password -ossec_exe wazuh-winagent-v2.0.1-1.exe

B. Configure file deploy.bat, open the and replace with your configuration(as you did on step 1), save and run it as administrator. The .bat file is useful in case you are using massive deployments tools like SCCM.

Once you run the script, you should have the follow expected output:

Starting
Certify OK
OSSEC Installed OK
Adding Agent OK
Getting KEY OK
Agent information:
ID:012
Name:Windows-Hostname
IP Address:83.54.xx.xx
Import Key into OSSEC OK
OSSEC SERVICE OK
AGENT INSTALLED SUCCESSFULLY

If you encounter any issues, check agent_deploy.log.

Troubleshooting

Agent name already exists or it is invalid

In case there is already an agent with the identical name, OSSEC won’t allow us to register the new one, try using the option “-prompt_agent_name 1” and the script will ask you to choose the name. Or use the option “-agent_name your_agent_name” to specify the agent name.

Duplicated IP for agent

The OSSEC manager cannot have two agents with the same IP, it will cause connectivity issues. If there is previously an agent with the same IP you won’t be able to add another one, please remove the old agent from your OSSEC Manager using manage_agents tool.
If you are behind a proxy, don’t forget to set up the API with “behindProxy” setting enable.

Unauthorized

There is a problem your API credentials, please verify that your API username and password are correct.

OSSEC Executable does not exists

The installer you specified on -ossec_exe argument can’t be found, please verify that it is on the same folder of Powershell script or enter the full path.

Conclusion

Wazuh RESTful API bring us a bunch of new possibilities, including agent management, using that we can develop new scripts in order to set up large deployments. The API also has built-in HTTPS encryption and authentication credentials so we can set up a safe and secure tool to for agent deployment.

If you have any questions about how to deploying OSSEC on Windows, join our Slack #community channel or contact us vía twitter! Our team and other contributors will help you.