Getting started

HTTP basic authentication

HTTP basic authentication is one of the simplest methods of accessing the Wazuh indexer API. The client provides credentials as a username and password with every request in this mechanism. These credentials are included in the Authorization header of the HTTP request. While this makes implementation straightforward and compatible with most tools and systems, it is less secure as the risk of exposure is high.

HTTP basic authentication is enabled by default, and its settings are specified within the basic_internal_auth_domain section in the /etc/wazuh-indexer/opensearch-security/config.yml configuration file. The default setting is seen below:

basic_internal_auth_domain:
  description: "Authenticate via HTTP Basic against internal users database"
  http_enabled: true
  transport_enabled: true
  order: 4
  http_authenticator:
    type: basic
    challenge: true
  authentication_backend:
    type: intern

The format to authenticate to the Wazuh indexer API using basic authentication is below. In this example, we use cURL to connect and authenticate:

# curl -k -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> https://localhost:9200/

{
  "name" : "node-1",
  "cluster_name" : "wazuh-cluster",
  "cluster_uuid" : "XUqydNCQTuCnvtXobnRZ8w",
  "version" : {
    "number" : "7.10.2",
    "build_type" : "deb",
    "build_hash" : "9fd1835bba77ae04d48550eb4dc9be4787070806",
    "build_date" : "2024-08-30T10:06:03.028357Z",
    "build_snapshot" : false,
    "lucene_version" : "9.10.0",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

JSON Web Token (JWT)

The JSON Web Token (JWT) is another method of authenticating to the Wazuh indexer API. JWT is an open standard (RFC 7519) that defines a compact and self-contained method for securely transmitting information between parties as a JSON object.

A JWT can be self-generated, and the validation key can be stored in the /etc/wazuh-indexer/opensearch-security/config.yml file or generated and validated through a JSON Web Key Set (JWKS) endpoint to retrieve the key from its location on the issuer’s server.

JWT authentication is not enabled by default, and its settings are specified within the jwt_auth_domain section in the /etc/wazuh-indexer/opensearch-security/config.yml configuration file. Follow the steps below to enable and log into the Wazuh indexer using JWT authentication:

1. Open the /etc/wazuh-indexer/opensearch-security/config.yml configuration file and update the highlighted settings:

   jwt_auth_domain:
     description: "Authenticate via Json Web Token"
     http_enabled: true
     transport_enabled: false
     order: 0
     http_authenticator:
       type: jwt
       challenge: false
       config:
         signing_key: "<ENCODED_SIGNING_KEY>"
         jwt_header: "Authorization"
         jwt_url_parameter: null
         jwt_clock_skew_tolerance_seconds: 30
         roles_key: <ROLES_KEY>
         subject_key: <SUBJECT_KEY>
     authentication_backend:
       type: noop
   

   Note

   Replace <ENCODED_SIGNING_KEY> with your base64 encoded HMAC key or public RSA/ECDSA pem key. Update the values of <ROLES_KEY> with the name of a backend user the JWT should attach to, and <SUBJECT_KEY> to a descriptive subject name that identifies the JWT. For example, setting the values to admin and automationUser respectively will attach the JWT to the internal admin user and name the JWT as automationUser.

2. Run the /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh script to load the configuration changes made in the /etc/wazuh-indexer/opensearch-security/config.yml file:

   # export JAVA_HOME=/usr/share/wazuh-indexer/jdk/ && bash /usr/share/wazuh-indexer/plugins/opensearch-security/tools/securityadmin.sh -f /etc/wazuh-indexer/opensearch-security/config.yml -icl -key /etc/wazuh-indexer/certs/admin-key.pem -cert /etc/wazuh-indexer/certs/admin.pem -cacert /etc/wazuh-indexer/certs/root-ca.pem -h 127.0.0.1 -nhnv
   

3. Authenticate to the Wazuh indexer API using your JWT, as seen below. In this example, we use cURL to connect and authenticate:

   # curl -k -XGET "https://localhost:9200" -H "Authorization: Bearer <WAZUH_INDEXER_JWT>"
   

   Replace <WAZUH_INDEXER_JWT> with your JWT. The expected output is as seen below:

   {
     "name" : "node-1",
     "cluster_name" : "wazuh-cluster",
     "cluster_uuid" : "XUqydNCQTuCnvtXobnRZ8w",
     "version" : {
       "number" : "7.10.2",
       "build_type" : "deb",
       "build_hash" : "9fd1835bba77ae04d48550eb4dc9be4787070806",
       "build_date" : "2024-08-30T10:06:03.028357Z",
       "build_snapshot" : false,
       "lucene_version" : "9.10.0",
       "minimum_wire_compatibility_version" : "7.10.0",
       "minimum_index_compatibility_version" : "7.0.0"
     },
     "tagline" : "The OpenSearch Project: https://opensearch.org/"
   }
   

Optionally, you can use your JWT as an environment variable.

You can access any API endpoint using the below structure. Replace <METHOD> with the desired method, <ENDPOINT> with the string corresponding to the endpoint you wish to access, and <WAZUH_INDEXER_JWT> with your JWT. If you are using an environment variable, replace <WAZUH_INDEXER_JWT> with your environment variable, for example $TOKEN.

# curl -k -X <METHOD> "https://localhost:9200/<ENDPOINT>" -H "Authorization: Bearer <WAZUH_INDEXER_JWT>"

Using Python

The Python requests library allows us to send HTTP requests to the Wazuh Indexer API endpoints. With a Python script, we can automatically handle authentication, parse, and manipulate the Wazuh indexer responses within the script. In the check_wazuh_indexer_health.py script below, we query the Wazuh indexer health status using Python.

import requests
from requests.auth import HTTPBasicAuth

# Base URL and endpoint
Wazuh_indexer_url = "https://localhost:9200"
endpoint = "/_cluster/health"

# Full URL
url = wazuh_indexer_url + endpoint

# Credentials for authentication
username = "<WAZUH_INDEXER_USERNAME>"
password = "<WAZUH_INDEXER_PASSWORD>"

# Disable SSL warnings
requests.packages.urllib3.disable_warnings()

try:
    # GET request to check cluster health
    response = requests.get(url, auth=HTTPBasicAuth(username, password), verify=False)

    # Check if the request was successful
    if response.status_code == 200:
        # Parse and print the response JSON data
        cluster_health = response.json()
        print("Cluster Health Status")
        print(f"Status: {cluster_health['status']}")
        print(f"Number of Nodes: {cluster_health['number_of_nodes']}")
        print(f"Active Primary Shards: {cluster_health['active_primary_shards']}")
        print(f"Active Shards: {cluster_health['active_shards']}")
    else:
        print(f"Failed to retrieve cluster health. Status Code: {response.status_code}")
        print(response.text)

except Exception as e:
    print("Error connecting to Wazuh Indexer:", e)

Replace <WAZUH_INDEXER_USERNAME> and <WAZUH_INDEXER_PASSWORD> with the correct credentials. Follow the steps below to run the script.

1. Install the Python requests module:

   # python3 -m pip install requests
   

2. Run the check_wazuh_indexer_health.py Python script:

   # python3 check_wazuh_indexer_health.py
   

   Cluster Health Status
   Status: green
   Number of Nodes: 1
   Active Primary Shards: 16
   Active Shards: 16
   

Using Bash

You can also interact with the Wazuh indexer API using a bash script. A bash script is preferable when you do not want to install additional programs like Python. In the following check_wazuh_indexer_health.sh bash script, we query the Wazuh indexer API to retrieve the cluster health status.

#!/bin/bash

# Base URL and endpoint for Wazuh Indexer API
WAZUH_INDEXER_URL="https://localhost:9200"
ENDPOINT="/_cluster/health"
FULL_URL="${WAZUH_INDEXER_URL}${ENDPOINT}"
USERNAME="<WAZUH_INDEXER_USERNAME>"
PASSWORD="<WAZUH_INDEXER_PASSWORD>"

# Make the API request using basic authentication
response=$(curl -s -k -u "$USERNAME:$PASSWORD" "$FULL_URL")
# Check if the request was successful
if [ $? -eq 0 ]; then
  echo "Cluster Health Status:"
  # Check if jq is installed
  if command -v jq > /dev/null; then
    echo "$response" | jq .
  else
    echo "Warning: 'jq' is not installed. Displaying raw JSON response:"
    echo "$response"
  fi
else
  echo "Error: Failed to retrieve cluster health."
fi

Run the check_wazuh_indexer_health script:

# ./check_wazuh_indexer_health

Cluster Health Status:
{
  "cluster_name": "wazuh-cluster",
  "status": "green",
  "timed_out": false,
  "number_of_nodes": 1,
  "number_of_data_nodes": 1,
  "discovered_master": true,
  "discovered_cluster_manager": true,
  "active_primary_shards": 30,
  "active_shards": 30,
  "relocating_shards": 0,
  "initializing_shards": 0,
  "unassigned_shards": 0,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks": 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 100
}

GET

The following GET request retrieves basic information about the Wazuh indexer API, such as its cluster name, version, revision, hostname, and compatibility information.

curl -k -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> -X GET https://localhost:9200/

{
  "name" : "node-1",
  "cluster_name" : "wazuh-cluster",
  "cluster_uuid" : "XUqydNCQTuCnvtXobnRZ8w",
  "version" : {
    "number" : "7.10.2",
    "build_type" : "deb",
    "build_hash" : "9fd1835bba77ae04d48550eb4dc9be4787070806",
    "build_date" : "2024-08-30T10:06:03.028357Z",
    "build_snapshot" : false,
    "lucene_version" : "9.10.0",
    "minimum_wire_compatibility_version" : "7.10.0",
    "minimum_index_compatibility_version" : "7.0.0"
  },
  "tagline" : "The OpenSearch Project: https://opensearch.org/"
}

PUT

The following PUT request to the Wazuh indexer API updates the Wazuh indexer cluster setting to change the value of search.max_buckets to 75000. The search.max_buckets setting controls the maximum aggregation buckets allowed in response to a single query.

# curl -k -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> -H "Content-Type: application/json" -X PUT "https://localhost:9200/_cluster/settings?pretty" -d '{"transient": {"search.max_buckets": 75000}}'

{
  "acknowledged" : true,
  "persistent" : { },
  "transient" : {
    "search" : {
      "max_buckets" : "75000"
    }
  }
}

DELETE

In this example, we use this DELETE request to remove documents from indexes from a specified time. First, we run a query to list the target indexes:

curl -X POST "https://localhost:9200/wazuh-alerts-4.x-2024*/_search?pretty" \
-H "Content-Type: application/json" \
-u "<WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD>" \
-k \
-d '{
  "query": {
    "range": {
      "@timestamp": {
        "gt": "2024-11-25T00:00:00Z"
      }
    }
  }
}'

In the query above, we query the index wazuh-alerts-4.x-2024 using a wildcard * to match all associated documents in the index pattern. We also use a timestamp query to filter and return only the documents with a timestamp greater than (gt) the specified value.

{
  "took" : 23,
  "timed_out" : false,
  "_shards" : {
    "total" : 30,
    "successful" : 30,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 8,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    ...

In the output above, we observe eight (8) documents matching the query. Next, we use DELETE to remove these documents from the index.

curl -X DELETE "https://localhost:9200/wazuh-alerts-4.x-2024*?pretty" -H "Content-Type: application/json" -u "$indexer_username:$indexer_password" -k -d '{
  "query": {
    "range": {
      "@timestamp": {
        "gt": "2024-11-25T00:00:00Z"
      }
    }
  }
}'

In the output, we see that the query ran successfully.

{
  "acknowledged" : true
}

To verify the documents are deleted, we run the initial query to search for the documents. As seen from the output, no matches indicate that the documents are deleted.

{
  "took" : 0,
  "timed_out" : false,
  "_shards" : {
    "total" : 0,
    "successful" : 0,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 0,
      "relation" : "eq"
    },
    "max_score" : 0.0,
    "hits" : [ ]
  }
}

cURL

cURL is a command-line tool for sending HTTP/HTTPS requests and commands. It comes pre-installed on many Linux, macOS, and Windows endpoints, allowing users to interact directly with the Wazuh indexer API from the command line. In the examples below, we store the Wazuh API credentials as environment variables and interact with different endpoints. For detailed instructions on obtaining authentication, please refer to the Logging into the Wazuh indexer API section.

Python

You can use a Python script to retrieve information about documents from any index in the Wazuh indexer. In this example, we query the wazuh-alerts* index to find the top three (3) users with the most successful logins via SSH on monitored endpoints. The script authenticates with the Wazuh indexer API using any authentication method (we use JWT in this example). Then, it makes a POST request to retrieve the required information.

Save the following Python script as top_successful_login.py:

import requests
import json

# Base URL and endpoint
indexer_url = "https://localhost:9200"
endpoint = "/wazuh-alerts*/_search"
url = indexer_url + endpoint

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <WAZUH_INDEXER_JWT>"
}

# Query payload
payload = {
    "size": 0,
    "query": {
        "match": {
            "rule.description": "PAM: Login session opened."
        }
    },
    "aggs": {
        "successful_logins_by_user": {
            "terms": {
                "field": "data.dstuser",
                "size": 3,
                "order": {
                    "_count": "desc"
                }
            }
        }
    }
}

# Disable SSL warnings
requests.packages.urllib3.disable_warnings()

# Execute the API request
try:
    response = requests.post(url, headers=headers, data=json.dumps(payload), verify=False)
    response.raise_for_status()  # Raise an exception for HTTP errors
    result = response.json()  # Parse the JSON response

    # Process and display the results
    print("Top three (3) Users with Most Successful Login Sessions:")
    if "aggregations" in result and "successful_logins_by_users" in result["aggregations"]:
        buckets = result["aggregations"]["successful_logins_by_users"]["buckets"]
        if buckets:
            for user in buckets:
                print(f"User: {user['key']}, Count: {user['doc_count']}")
        else:
            print("No data found for the query.")
    else:
        print("Unexpected response format.")
except requests.exceptions.RequestException as e:
    print(f"Error querying Wazuh API: {e}")

Replace <WAZUH_INDEXER_JWT> with your JWT. An output similar to the one below is observed. In the output, we can see the top three (3) users with the most amount of successful logins recorded:

Top three (3) Users with Most Successful Login Sessions:
User: root(uid=0), Count: 22
User: wazuh(uid=1000), Count: 3
User: test(uid=2000), Count: 2

Bash

In this example, we query the wazuh-alerts* index to find the top three (3) users with the most failed login attempts. The script authenticates with the Wazuh indexer API using the JWT authentication method. In this example, we demonstrate how to export the JWT as an environment variable to avoid putting the token inside the script.

Follow the steps below.

1. Export your JWT as an environment variable:

   # export JWT_AUTH_TOKEN="<WAZUH_INDEXER_JWT>"
   

   Replace <WAZUH_INDEXER_JWT> with your appropriate JWT.

2. Verify that the token is exported:

   # echo $JWT_AUTH_TOKEN
   

3. Save the following script as top_failed_login.sh:

   #!/bin/bash
   
   # Wazuh indexer API URL
   WAZUH_INDEXER_URL="https://localhost:9200/wazuh-alerts*/_search"
   
   # JSON query payload
   PAYLOAD=$(cat <<EOF
   {
     "size": 0,
     "query": {
       "match": {
         "rule.description": "PAM: User login failed."
       }
     },
     "aggs": {
       "failed_logins_by_user": {
         "terms": {
           "field": "data.dstuser",
           "size": 3,
           "order": {
             "_count": "desc"
           }
         }
       }
     }
   }
   EOF
   )
   
   # Execute the API request
   RESPONSE=$(curl -s -k -X POST "$WAZUH_INDEXER_URL?pretty" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $JWT_AUTH_TOKEN" \
     -d "$PAYLOAD")
   
   # Check if the response contains valid data
   if [[ $? -ne 0 || -z "$RESPONSE" ]]; then
     echo "Error: Failed to fetch data from Wazuh indexer API"
     exit 1
   fi
   
   echo "Top three (3) Users with Most Failed Login Session"
   echo "$RESPONSE"
   

4. Make the script executable:

   # chmod u+x top_failed_login.sh
   

5. Run the top_failed_login.sh script:

   # ./top_failed_login.sh
   

   ...
           {
             "key" : "root",
             "doc_count" : 19
           },
           {
             "key" : "test",
             "doc_count" : 9
           },
           {
             "key" : "nobody",
             "doc_count" : 4
           }
         ]
       }
     }
   }