graylog-api-client 0.1.2__tar.gz

graylog_api_client-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chrxxxxs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graylog_api_client-0.1.2/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: graylog-api-client
+Version: 0.1.2
+Summary: A Python wrapper for the Graylog REST API
+License-Expression: MIT
+License-File: LICENSE
+Keywords: graylog,REST,API Wrapper
+Author: Chrxxxxs
+Author-email: 134285960+Chrxxxxs@users.noreply.github.com
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: requests (>=2.32.5,<3.0.0)
+Project-URL: Repository, https://github.com/Chrxxxxs/graylog_api_client
+Description-Content-Type: text/markdown
+
+### This is a low level Graylog API Wrapper heavily based on the guide by [pretzel](https://www.pretzellogix.net/2021/12/08/how-to-write-a-python3-sdk-library-module-for-a-json-rest-api/).
+As there are a lot of endpoints not all of them are implemented by now. I started by implementing the GET requests first.
+Also the API responses all follow very different schemas and an implementation of that into Python is probably not worth the effort which is why the responses from this API are so low-level.
+Feel free to add endpoints or schemas in PRs if you need them :)
+#### Last tested Graylog Version is: 6.3.4
+
+### Example Usage
+
+```python
+from graylog_api_client import GraylogAPI
+
+# Initialize the GraylogAPI client
+api = GraylogAPI(
+    host="https://localhost:9000/api",  # Replace with your Graylog server URL
+    api_key="your_api_key_here",       # Replace with your API key
+    ssl_verify=True                   # /path/to/cert for custom certificate
+)
+
+# Example: Fetch all streams
+streams = api.get_streams()
+
+# Print the result
+print("Streams:", streams.data)
+```
+
+Planned:
+1. Tests that run against a Graylog instance to check if the Wrapper works after Graylog Updates
+
+
+### Test Environment:
+1. Install docker and docker-compose
+2. Copy the sample docker-compose file by [Graylog](https://github.com/Graylog2/docker-compose) for the open-core (or enterprise if you want to see all API endpoints) and create a .env file with the needed values
+3. docker-compose up
+4. Log in and create an api-key

graylog_api_client-0.1.2/README.md

@@ -0,0 +1,34 @@
+### This is a low level Graylog API Wrapper heavily based on the guide by [pretzel](https://www.pretzellogix.net/2021/12/08/how-to-write-a-python3-sdk-library-module-for-a-json-rest-api/).
+As there are a lot of endpoints not all of them are implemented by now. I started by implementing the GET requests first.
+Also the API responses all follow very different schemas and an implementation of that into Python is probably not worth the effort which is why the responses from this API are so low-level.
+Feel free to add endpoints or schemas in PRs if you need them :)
+#### Last tested Graylog Version is: 6.3.4
+
+### Example Usage
+
+```python
+from graylog_api_client import GraylogAPI
+
+# Initialize the GraylogAPI client
+api = GraylogAPI(
+    host="https://localhost:9000/api",  # Replace with your Graylog server URL
+    api_key="your_api_key_here",       # Replace with your API key
+    ssl_verify=True                   # /path/to/cert for custom certificate
+)
+
+# Example: Fetch all streams
+streams = api.get_streams()
+
+# Print the result
+print("Streams:", streams.data)
+```
+
+Planned:
+1. Tests that run against a Graylog instance to check if the Wrapper works after Graylog Updates
+
+
+### Test Environment:
+1. Install docker and docker-compose
+2. Copy the sample docker-compose file by [Graylog](https://github.com/Graylog2/docker-compose) for the open-core (or enterprise if you want to see all API endpoints) and create a .env file with the needed values
+3. docker-compose up
+4. Log in and create an api-key

graylog_api_client-0.1.2/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "graylog-api-client"
+version = "0.1.2"
+description = "A Python wrapper for the Graylog REST API"
+authors = [
+    {name = "Chrxxxxs",email = "134285960+Chrxxxxs@users.noreply.github.com"}
+]
+keywords = ["graylog", "REST", "API Wrapper"]
+license = "MIT"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "requests (>=2.32.5,<3.0.0)",
+]
+
+[project.urls]
+Repository = "https://github.com/Chrxxxxs/graylog_api_client"
+
+[tool.poetry]
+packages = [{include = "graylog_api_client", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

graylog_api_client-0.1.2/src/graylog_api_client/__init__.py

@@ -0,0 +1,3 @@
+from graylog_api_client.graylog_api_client import GraylogAPI
+
+__all__ = ["GraylogAPI"]

graylog_api_client-0.1.2/src/graylog_api_client/data_structures.py

@@ -0,0 +1,14 @@
+from typing import List, Dict
+
+
+class GraylogApiResult:
+    def __init__(self, status_code: int, message: str = "", data: List[Dict] = None):
+        """Result returned from low-level RestAdapter
+
+        :param status_code: Standard HTTP Status code
+        :param message: Human readable result
+        :param data: Python List of Dictionaries (or maybe just a single Dictionary on error)
+        """
+        self.status_code = int(status_code)
+        self.message = str(message)
+        self.data = data if data else []

graylog_api_client-0.1.2/src/graylog_api_client/exceptions.py

@@ -0,0 +1,2 @@
+class GraylogApiException(Exception):
+    pass

graylog_api_client-0.1.2/src/graylog_api_client/graylog_api_client.py

@@ -0,0 +1,157 @@
+import logging
+from typing import List, Union, Dict
+
+from .rest_adapter import RestAdapter
+from .data_structures import GraylogApiResult
+
+
+class GraylogAPI:
+    def __init__(self, host: str, api_key: str, ssl_verify: Union[str, bool] = True, logger: logging.Logger = None):
+        """GraylogAPI client
+
+        :param host: The hostname of the Graylog API endpoint plus the protocol. Example: https://graylog.com/api
+        :param api_key: An API Key to authenticate with Graylog
+        :param ssl_verify: Enables or Disables TLS Certificate verification. For a custom certificate, this value must a path pointing to the certificate, defaults to True
+        :param logger: The logger being used by the Adapter, will use a new one if none is given, defaults to None
+        """
+        self._rest_adapter = RestAdapter(host=host, api_key=api_key, ssl_verify=ssl_verify, logger=logger)
+
+    # The endpoints grouped like they are in the api-browser
+    # /authz Authorization
+    def get_auth_grants_overview(self) -> GraylogApiResult:
+        overview = self._rest_adapter.get("authz/grants-overview")
+        return overview
+
+    def get_auth_roles(self, parameters: Dict = None) -> GraylogApiResult:
+        roles = self._rest_adapter.get("authz/roles", parameters)
+        return roles
+
+    def get_auth_roles_of_user(self, username: str, parameters: Dict = None) -> GraylogApiResult:
+        roles = self._rest_adapter.get(f"authz/roles/user/{username}", parameters)
+        return roles
+
+    def get_auth_role_by_id(self, role_id: str) -> GraylogApiResult:
+        roles = self._rest_adapter.get(f"authz/roles/{role_id}")
+        return roles
+
+    def get_auth_assignees_of_role(self, role_id: str, parameters: Dict = None) -> GraylogApiResult:
+        assignees = self._rest_adapter.get(f"authz/roles/{role_id}/assignees", parameters)
+        return assignees
+
+    # /ca
+    def get_ca(self) -> GraylogApiResult:
+        result = self._rest_adapter.get("ca")
+        return result
+
+    # /certificates
+    def get_certificates(self) -> GraylogApiResult:
+        result = self._rest_adapter.get("certificates")
+        return result
+
+    # /cluster
+    def get_cluster(self) -> GraylogApiResult:
+        result = self._rest_adapter.get("cluster")
+        return result
+
+    def get_processbufferdump(self, node_id: str = "") -> GraylogApiResult:
+        result = self._rest_adapter.get(f"cluster/{node_id}/processbufferdump".replace("//", "/"))
+        return result
+
+    def get_jvminfo(self, node_id: str) -> GraylogApiResult:
+        result = self._rest_adapter.get(f"cluster/{node_id}/jvm")
+        return result
+
+    # /contentstream
+    # /dashboards
+    # /datanodes
+    # /datanode
+    # /api-docs API-Documentation
+    # /enterprise
+    # /entitylists
+    # /entity_scopes
+    # /entity_suggestions
+    # /events
+    # /system/inputs/{inputId}/extractors Extractors
+    # /favorites
+    # /views/fields FieldTypes
+    # /system/indexer Indexer
+    # /search/universal/absolute Legacy Message Search
+    # /messages
+    # /migration
+    # /system/pipelines Pipelines
+    # /plugins
+    # /remote-reindex-migration
+    # /roles
+    # /views/search Search
+    # /search Search Options (Decorators, Export, Functions etc.)
+    # /views/searchjobs Searchjobs
+    # /sidecars
+    # /sidecar
+    # /startpage
+    # /system/inputs/{inputId}/staticfields Staticfields
+    # /streams
+    def get_streams(self) -> GraylogApiResult:
+        result = self._rest_adapter.get("streams")
+        return result
+
+    # /system Main System endpoints
+    # /telemetry
+    # /token_usage
+    # /users
+    def create_user(self, username: str, first_name: str, last_name: str, email: str, password: str, permissions: List[str], data: Dict = None) -> GraylogApiResult:
+        user_data = {
+            "username": username,
+            "first_name": first_name,
+            "last_name": last_name,
+            "email": email,
+            "password": password,
+        }
+        if permissions:
+            user_data["permissions"] = permissions
+        if data:
+            user_data.update(data)
+        result = self._rest_adapter.post("users", data=user_data)
+        return result
+
+    def get_users(self, parameters: Dict = None) -> GraylogApiResult:
+        result = self._rest_adapter.get("users", parameters)
+        return result
+
+    def get_users_paginated(self, parameters: Dict = None) -> GraylogApiResult:
+        result = self._rest_adapter.get("users/paginated", parameters)
+        return result
+
+    def get_user_by_id(self, user_id: str) -> GraylogApiResult:
+        result = self._rest_adapter.get(f"users/id/{user_id}")
+        return result
+
+    def get_user_by_username(self, username: str) -> GraylogApiResult:
+        result = self._rest_adapter.get(f"users/{username}")
+        return result
+
+    def get_user_tokens_by_id(self, user_id: str) -> GraylogApiResult:
+        result = self._rest_adapter.get(f"users/{user_id}/tokens")
+        return result
+
+    def delete_user_by_id(self, user_id: str) -> GraylogApiResult:
+        result = self._rest_adapter.delete(f"users/id/{user_id}")
+        return result
+
+    def delete_user_by_username(self, username: str) -> GraylogApiResult:
+        result = self._rest_adapter.delete(f"users/{username}")
+        return result
+
+    def change_user_status(self, user_id: str, status: str) -> GraylogApiResult:
+        if status not in ["enabled", "disabled", "deleted"]:
+            raise ValueError(f"Status must be either 'enabled', 'disabled' or 'deleted' but was: {status}")
+        result = self._rest_adapter.put(f"users/{user_id}/status/{status}")
+        return result
+
+    # /views Main Views Endpoints
+    def get_views(self, parameters: Dict = None) -> GraylogApiResult:
+        result = self._rest_adapter.get("views", parameters)
+        return result
+
+    def get_view_by_id(self, view_id: str) -> GraylogApiResult:
+        result = self._rest_adapter.get(f"views/{view_id}")
+        return result

graylog_api_client-0.1.2/src/graylog_api_client/rest_adapter.py

@@ -0,0 +1,100 @@
+import requests
+import logging
+from typing import Dict, Union
+
+from .exceptions import GraylogApiException
+from .data_structures import GraylogApiResult
+
+
+class RestAdapter:
+    def __init__(self, host: str, api_key: str, ssl_verify: Union[str, bool] = True, logger: logging.Logger = None):
+        """Constructor for RestAdapter
+
+        :param host: The hostname of the Graylog API endpoint plus the protocol. Example: https://graylog.com/api
+        :param api_key: An API Key to authenticate with Graylog
+        :param ssl_verify: Enables or Disables TLS Certificate verification. For a custom certificate, this value must a path pointing to the certificate, defaults to True
+        :param logger: The logger being used by the Adapter, will use a new one if none is given, defaults to None
+        """
+        self._logger = logger or logging.getLogger(__name__)
+        self.host = host + "/"
+        self._api_key = api_key
+        self._ssl_verify = ssl_verify
+        self._session = requests.Session()
+        self._session.headers.update({"Accept": "application/json", "X-Requested-By": "python-graylog-api-client"})
+        self._session.auth = (self._api_key, "token")  # Graylog uses the format Basic Auth: "<API-token>:token"
+        if not ssl_verify:
+            requests.packages.urllib3.disable_warnings()
+
+    def _do(self, method: str, endpoint: str, parameters: Dict = None, data: Dict = None) -> GraylogApiResult:
+        """Run the HTTP Requests.
+
+        :param method: The HTTP Method that this request will use.
+        :param endpoint: The API endpoint that this request goes to. Example: /streams.
+        :param parameters: Dictionary to be sent in the query string of the Request.
+        :param data: Dictionary to be sent in the body of the Request.
+        :raises GraylogApiException: Generic Exception for Errors caused within the Adapter.
+        :return: An object containing the Result of the API request.
+        """
+        url = self.host + endpoint
+        log_line_pre = f"method={method}, url={url}, parameters={parameters}"
+        log_line_post = ', '.join((log_line_pre, "success={}, status_code={}, message={}"))
+        try:
+            self._logger.debug(msg=log_line_pre)
+            response = self._session.request(method=method, url=url, verify=self._ssl_verify, params=parameters, json=data)
+        except requests.exceptions.RequestException as e:
+            self._logger.error(msg=str(e))
+            raise GraylogApiException("Invalid API Response") from e
+        try:
+            if response.content != b'':
+                data_out = response.json()
+            else:
+                data_out = None
+        except (ValueError, requests.exceptions.JSONDecodeError) as e:
+            self._logger.error(msg=log_line_post.format(False, None, e))
+            raise GraylogApiException("Bad JSON in response") from e
+        is_success = 299 >= response.status_code >= 200  # OK
+        log_line = log_line_post.format(is_success, response.status_code, response.reason)
+        if is_success:
+            self._logger.debug(msg=log_line)
+            return GraylogApiResult(status_code=response.status_code, message=response.reason, data=data_out)
+        self._logger.error(msg=log_line)
+        raise GraylogApiException(f"{response.status_code}: {response.reason}")
+
+    def get(self, endpoint: str, parameters: Dict = None) -> GraylogApiResult:
+        """Send a GET request to the API.
+
+        :param endpoint: The API endpoint that this request goes to. Example: /streams.
+        :param parameters: Dictionary to be sent in the query string of the Request.
+        :return: An object containing the Result of the API request.
+        """
+        return self._do(method="GET", endpoint=endpoint, parameters=parameters)
+
+    def post(self, endpoint: str, parameters: Dict = None, data: Dict = None) -> GraylogApiResult:
+        """Send a POST request to the API.
+
+        :param endpoint: The API endpoint that this request goes to. Example: /streams.
+        :param parameters: Dictionary to be sent in the query string of the Request.
+        :param data: Dictionary to be sent in the body of the Request.
+        :return: An object containing the Result of the API request.
+        """
+        return self._do(method="POST", endpoint=endpoint, parameters=parameters, data=data)
+
+    def delete(self, endpoint: str, parameters: Dict = None, data: Dict = None) -> GraylogApiResult:
+        """Send a DELETE request to the API.
+
+        :param endpoint: The API endpoint that this request goes to. Example: /streams.
+        :param parameters: Dictionary to be sent in the query string of the Request.
+        :param data: Dictionary to be sent in the body of the Request.
+        :return: An object containing the Result of the API request.
+        """
+        return self._do(method="DELETE", endpoint=endpoint, parameters=parameters, data=data)
+
+    def put(self, endpoint: str, parameters: Dict = None, data: Dict = None) -> GraylogApiResult:
+        """Send a PUT request to the API.
+
+        :param endpoint: The API endpoint that this request goes to. Example: /streams.
+        :param parameters: Dictionary to be sent in the query string of the Request.
+        :param data: Dictionary to be sent in the body of the Request.
+        :return: An object containing the Result of the API request.
+        """
+        return self._do(method="PUT", endpoint=endpoint, parameters=parameters, data=data)