Migrating from the Wazuh API 3.X
Wazuh API 4.0 introduces several new endpoints and also modifies or removes some of the old ones. The biggest change for all existing endpoints is the new response format. Endpoint responses have been changed according to the new RBAC standard and will no longer have items
and totalitems
fields. Most responses will have the following structure instead:
{
"data": {
"affected_items": [],
"total_affected_items": 0,
"total_failed_items": 0,
"failed_items": [],
},
"message": "",
"error": 0
}
Migrating users
The Wazuh API users are not migrated when upgrading the Wazuh API from 3.X to 4.0. There are numerous security changes to the Wazuh API in 4.0 and it is not advisable. However, using the following API calls it is easy to create new users and assign the administrator role to it (substitute <username> and <password>):
Create new user (POST /security/users)
# curl -k -X POST "https://localhost:55000/security/users" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d "{\"username\":\"<username>\",\"password\":\"<password>\"}"
{
"data": {
"affected_items": [
{
"id": 3,
"username": "<wazuh>",
"allow_run_as": false,
"roles": []
}
],
"total_affected_items": 1,
"total_failed_items": 0,
"failed_items": []
},
"message": "User was successfully created",
"error": 0
}
Assign administrator role (POST /security/users/{user_id}/roles)
# curl -k -X POST "https://localhost:55000/security/users/3/roles?role_ids=1" -H "Authorization: Bearer $TOKEN"
{
"data": {
"affected_items": [
{
"id": 3,
"username": "<wazuh>",
"allow_run_as": false,
"roles": [
1
]
}
],
"total_affected_items": 1,
"total_failed_items": 0,
"failed_items": []
},
"message": "All roles were linked to user <wazuh>",
"error": 0
}
Equivalence table
Wazuh API 4.0 introduces several changes to existing endpoints. It is therefore important to review those changes when migrating to 4.0
.
The following tables contain the equivalencies between old API 3.x and API 4.0 endpoints:
Active Response
Action |
API 3.x |
API 4.0 |
Changes |
---|---|---|---|
Run an AR command in the agent |
|
The new Active Response endpoint runs commands in all agents by default. Use the |
Agents
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Delete agents |
|
Removed Use the If no |
|
Delete an agent |
|
Use the |
|
Remove all agents groups |
|
Added Removes the agent from all groups by default or a list of them if |
|
Remove a single group of an agent |
|
No changes. |
|
Remove a single group of multiple agents |
|
Use the |
|
Delete a list of groups |
|
The new endpoint can delete all groups or a list of them. Use the |
|
Remove a group |
|
The new endpoint can delete all groups or a list of them. Use the |
|
Get all agents |
|
Return information about all available agents or a list of them. Added parameter Added parameter With this new endpoint, you won't get a 400 response in agent name cannot be found, you will get a 200 response with 0 items in the result. |
|
Get an agent |
|
Use the |
|
Get active configuration |
|
No changes. |
|
Get sync status of agent |
|
No changes. |
|
Get agent key |
|
No changes. |
|
Get upgrade result from agent |
|
No changes. |
|
Get groups |
|
The new endpoint works the same way by default. Removed |
|
Get agents in a group |
|
Use the To get all agents in a group use GET /groups/{group_id}/agents. |
|
Get group configuration |
|
The new endpoint works the same way by default. |
|
Get group files |
|
The new endpoint works the same way by default. |
|
Get a file in group |
|
GET /groups/{group_id}/files/{file_name}/json or GET /groups/{group_id}/files/{file_name}/xml |
The new endpoint allows the user to get the specified group file parsed to JSON or XML. |
Get an agent by its name |
|
Use the |
|
Get agents without group |
|
No changes. |
|
Get outdated agents |
|
Added |
|
Get distinct fields in agents |
|
No changes. |
|
Get agents summary |
|
The new Endpoint works the same way by default. |
|
Get OS summary |
|
Removed |
|
Add agent |
|
Renamed |
|
Add a list of agents to a group |
|
Use PUT instead of POST and specify the group id using the |
|
Put configuration file (agent.conf) into a group |
|
The new endpoint works the same way but using PUT. |
|
Upload file into a group |
|
The new endpoint is used to update the group configuration. Use PUT instead of POST. |
|
Insert agent |
|
Renamed |
|
Restart a list of agents |
|
Works the same way but using PUT instead of POST. |
|
Add agent group |
|
No changes. |
|
Restart an agent |
|
No changes. |
|
Upgrade agent using online repository |
|
Changed parameter type |
|
Upgrade agent using custom file |
|
No changes. |
|
Add agent (quick method) |
|
Use POST instead of PUT and the |
|
Create a group |
|
Use POST instead of PUT and the |
|
Restart agents which belong to a group |
|
The new endpoint works the same way by default. |
|
Restart all agents |
|
Added Restarts all agents by default or a list of them if |
Cache
Action |
API 3.x |
API 4.0 |
Changes |
---|---|---|---|
Delete cache index |
|
None |
Not needed anymore. Cache is managed by the cluster. |
Clear group cache |
|
None |
Not needed anymore. Cache is managed by the cluster. |
Get cache index |
|
None |
Not needed anymore. Cache is managed by the cluster. |
Return cache configuration |
|
The current cache configuration for any API can now be retrieved with the cluster endpoint. |
Ciscat
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get CIS-CAT results from an agent |
|
No changes. |
Cluster
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Delete a remote file in a cluster node |
|
No changes. |
|
Get active configuration in node node_id |
|
GET /cluster/{node_id}/configuration/{component}/{configuration} |
No changes. |
Get node node_id’s configuration |
|
No changes. |
|
Check Wazuh configuration in a cluster node |
|
Use this endpoint to check if Wazuh configuration is correct for al cluster nodes or use |
|
Get local file from any cluster node |
|
Removed |
|
Get node_id’s information |
|
No changes. |
|
Get ossec.log from a specific node in cluster. |
|
Renamed |
|
Get summary of ossec.log from a specific node in cluster. |
|
No changes. |
|
Get node node_id’s stats |
|
Changed response in order to use an Changed date format from YYYYMMDD to YYYY-MM-DD for |
|
Get node node_id’s analysisd stats |
|
Changed response in order to use an |
|
Get node node_id’s stats per hour |
|
Changed response in order to use an |
|
Get node node_id’s remoted stats |
|
Changed response in order to use an |
|
Get node node_id’s stats per week |
|
Changed response in order to use an Parameter |
|
Get node node_id’s status |
|
No changes. |
|
Get the cluster configuration |
|
Use the |
|
Check Wazuh configuration in all cluster nodes |
|
Added Return whether the Wazuh configuration is correct or not in all cluster nodes
or a list of them if parameter |
|
Show cluster health |
|
Renamed |
|
Get local node info |
|
Use the |
|
Get nodes info |
|
Get information about all nodes in the cluster or a list of them Added |
|
Get node info |
|
Use the |
|
Get info about cluster status |
|
No changes. |
|
Update local file at any cluster node |
|
Use |
|
Restart a specific node in cluster |
|
Use the |
|
Restart all nodes in cluster |
|
Added Restarts all nodes in the cluster by default or a list of them if |
Decoders
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get all decoders |
|
Added Added Renamed Renamed |
|
Get decoders by name |
|
Use the |
|
Get all decoders files |
|
Removed Renamed Renamed |
|
Get all parent decoders |
|
Added |
Experimental
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Clear syscheck database |
|
Added If no |
|
Get CIS-CAT results |
|
Added Removed |
|
Get hardware info of all agents |
|
Added Renamed Renamed Renamed Renamed Renamed |
|
Get network address info of all agents |
|
Added |
|
Get network interface info of all agents |
|
Added Changed the type of Renamed Renamed Renamed Renamed Renamed Renamed Renamed Renamed |
|
Get network protocol info of all agents |
|
Added |
|
Get os info of all agents |
|
Added Renamed Renamed |
|
Get packages info of all agents |
|
Added |
|
Get ports info of all agents |
|
Added Renamed Renamed Renamed |
|
Get processes info of all agents |
|
Added |
Lists
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get all lists |
|
Added Added Renamed |
|
Get paths from all lists |
|
Added Added |
Manager
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Delete a local file |
|
No changes. |
|
Get manager active configuration |
|
No changes. |
|
Get manager configuration |
|
No changes. |
|
Check Wazuh configuration |
|
No changes. |
|
Get local file |
|
Removed |
|
Get manager information |
|
Parameter |
|
Get ossec.log |
|
Renamed |
|
Get summary of ossec.log |
|
Return a summary of the last 2000 wazuh log entries instead of the last three months. |
|
Get manager stats |
|
Changed response in order to use an Changed date format from YYYYMMDD to YYYY-MM-DD for |
|
Get analysisd stats |
|
Changed response in order to use an |
|
Get manager stats per hour |
|
Changed response in order to use an |
|
Get remoted stats |
|
Changed response in order to use an |
|
Get manager stats per week |
|
Changed response in order to use an Parameter |
|
Get manager status |
|
No changes. |
|
Update local file |
|
The new endpoint works the same way but using |
|
Restart Wazuh manager |
|
No changes. |
Rootcheck
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Clear rootcheck database |
|
None |
Deprecated. |
Clear rootcheck database of an agent |
|
None |
Deprecated. |
Get rootcheck database |
|
None |
Deprecated. |
Get rootcheck CIS requirements |
|
None |
Deprecated. |
Get last rootcheck scan |
|
None |
Deprecated. |
Get rootcheck pci requirements |
|
None |
Deprecated. |
Run rootcheck scan in all agents |
|
None |
Deprecated. |
Run rootcheck scan in an agent |
|
None |
Deprecated. |
Rules
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get all rules |
|
Added Added Renamed Renamed |
|
Get rules by id |
|
Use the |
|
Get files of rules |
|
Renamed Renamed Removed |
|
Get rule gdpr requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule gpg13 requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule groups |
|
No changes. |
|
Get rule hipaa requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule nist-800-53 requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule pci requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule tsc requirements |
|
Use the new GET /rules/requirement endpoint. |
|
Get rule mitre requirements |
|
Use the new GET /rules/requirement endpoint. |
Security Assesment Configuration
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get security configuration assessment (SCA) database |
|
No changes. |
|
Get security configuration assessment (SCA) checks database |
|
No changes. |
Summary
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get a full summary of agents |
|
Use the new GET /overview/agents endpoint instead. |
Syscheck
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Clear syscheck database of an agent |
|
No changes. |
|
Get syscheck files |
|
No changes. |
|
Get last syscheck scan |
|
No changes. |
|
Run syscheck scan in all agents |
|
No changes. |
|
Run syscheck scan in an agent |
|
Use the |
Syscollector
Action |
API 3.x usage |
API 4.0 usage |
Changes |
---|---|---|---|
Get hardware info |
|
No changes. |
|
Get hotfixes info |
|
No changes. |
|
Get network address info of an agent |
|
No changes. |
|
Get network interface info of an agent |
|
Changed the type of Renamed Renamed Renamed Renamed Renamed Renamed Renamed Renamed |
|
Get network protocol info of an agent |
|
No changes. |
|
Get os info |
|
No changes. |
|
Get packages info |
|
No changes. |
|
Get ports info of an agent |
|
Added Renamed Renamed Renamed |
|
Get processes info |
|
No changes. |