chore: add docs, changes after review

Author: sgoral-splunk

docs/release_7_0_0.md

@@ -0,0 +1,46 @@
+# Removed usage of btool command from solnlib
+
+As of version 7.0.0, the `btool` command has been removed from solnlib. Configuration stanzas and keys should now be accessed via the REST API. 
+Additionally, the `splunkenv` module can only be used in environments where Splunk is installed, as it relies on Splunk-specific methods for making internal calls.
+
+## Session key is now mandatory in some of the functions
+
+The affected functions now require a valid `session_key` to operate correctly. While solnlib attempts to retrieve the `session_key` automatically, 
+there are scenarios—such as within a modular input script—where this is not possible. In such cases, you must explicitly provide the `session_key` 
+to ensure proper authorization. Affected functions are:
+
+* `get_splunk_host_info`
+* `get_splunkd_access_info`
+* `get_scheme_from_hec_settings`
+* `get_splunkd_uri`
+* `get_conf_key_value`
+* `get_conf_stanza`
+
+## Changed arguments in `get_conf_key_value` and `get_conf_stanza`
+
+As of version 7.0.0, the following changes have been made to the function:
+
+`get_conf_key_value` now requires 4 mandatory arguments:
+
+* `conf_name`
+* `stanza`
+* `key`
+* `app_name` (new)
+
+`get_conf_stanza` now requires 3 mandatory arguments:
+
+* `conf_name`
+* `stanza`
+* `app_name` (new)
+
+Both functions also accept the following optional arguments:
+
+* `session_key` - Used for authentication. If not provided, a 401 Unauthorized error may occur depending on the context.
+* `users` - Limits results returned by the configuration endpoint. Defaults to `nobody`.
+* `raw_output` - If set to `True`, the full decoded JSON response is returned. 
+This should be enabled when `app_name` is set to the global context `(/-/)`, as the Splunk REST API may return multiple entries in that case.
+
+## The `get_session_key` function has been removed from solnlib
+
+This function relied on reading the `scheme`, `host` and `port` using the deprecated btool utility, which is no longer supported.
+

mkdocs.yml

@@ -31,6 +31,7 @@ plugins:
 nav:
   - Home: index.md
   - Release 6.0.0: release_6_0_0.md
+  - Release 7.0.0: release_7_0_0.md
   - References:
       - modular_input:
           - "checkpointer.py": modular_input/checkpointer.md

solnlib/splunkenv.py

@@ -34,7 +34,7 @@
 except ImportError:
 
     def simpleRequest(*args, **kwargs):
-        return None, None
+        raise ImportError("This module requires Splunk to be installed.")
 
 
 try:
@@ -81,8 +81,6 @@ def msp(*args, **kwargs):
     os.path.join("var", "run", "splunk", "lookup_tmp"),
 ]
 
-use_btool = bool(use_btool)
-
 
 class SessionKeyNotFound(Exception):
     pass
@@ -242,7 +240,7 @@ def get_conf_key_value(
     key: str,
     app_name: str,
     session_key: Optional[str] = None,
-    user: Optional[str] = "nobody",
+    user: str = "nobody",
     raw_output: Optional[bool] = False,
 ) -> Union[str, List, dict]:
     """Get value of `key` of `stanza` in `conf_name`.
@@ -288,7 +286,7 @@ def get_conf_stanza(
     stanza: str,
     app_name: str,
     session_key: Optional[str] = None,
-    user: Optional[str] = "nobody",
+    user: str = "nobody",
     raw_output: Optional[bool] = False,
 ) -> dict:
     """Get `stanza` in `conf_name`.
@@ -379,7 +377,7 @@ def _get_conf_stanzas_from_splunk_api(
     conf_name: str,
     app_name: str,
     session_key: Optional[str] = None,
-    user: Optional[str] = "nobody",
+    user: str = "nobody",
     stanza: Optional[str] = None,
 ) -> dict:
     """Get stanzas of `conf_name` using splunk API:

tests/integration/conftest.py

@@ -21,3 +21,18 @@ def setup_env():
 @pytest.fixture(scope="session")
 def session_key():
     return context.get_session_key()
+
+
+def mock_splunk(monkeypatch):
+    def simple_requests(url, *args, **kwargs):
+        from splunk.rest import simpleRequest
+
+        return simpleRequest(url, *args, **kwargs)
+
+    def make_splunkn_home(url, *args, **kwargs):
+        from splunk.clilib.bundle_paths import make_splunkhome_path
+
+        return make_splunkhome_path(url, *args, **kwargs)
+
+    monkeypatch.setattr("solnlib.splunkenv.simpleRequest", simple_requests)
+    monkeypatch.setattr("solnlib.splunkenv.msp", make_splunkn_home)

tests/integration/context.py

@@ -35,18 +35,3 @@ def get_session_key():
     )
     content = response.json()
     return content["sessionKey"]
-
-
-def mock_splunk(monkeypatch):
-    def simple_requests(url, *args, **kwargs):
-        from splunk.rest import simpleRequest
-
-        return simpleRequest(url, *args, **kwargs)
-
-    def make_splunkn_home(url, *args, **kwargs):
-        from splunk.clilib.bundle_paths import make_splunkhome_path
-
-        return make_splunkhome_path(url, *args, **kwargs)
-
-    monkeypatch.setattr("solnlib.splunkenv.simpleRequest", simple_requests)
-    monkeypatch.setattr("solnlib.splunkenv.msp", make_splunkn_home)

tests/integration/test_conf_manager.py

@@ -15,6 +15,7 @@
 #
 
 import context
+import conftest
 import pytest
 from solnlib import conf_manager, soln_exceptions
 from unittest import mock
@@ -145,7 +146,7 @@ def test_conf_manager_update_conf_with_encrypted_keys():
 
 
 def test_get_log_level(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
     expected_log_level = "DEBUG"
@@ -162,7 +163,7 @@ def test_get_log_level(monkeypatch):
 
 
 def test_get_log_level_incorrect_log_level_field(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
     expected_log_level = "INFO"
@@ -178,7 +179,7 @@ def test_get_log_level_incorrect_log_level_field(monkeypatch):
 
 
 def test_get_proxy_dict(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
     expected_proxy_dict = VALID_PROXY_DICT
@@ -192,7 +193,7 @@ def test_get_proxy_dict(monkeypatch):
 
 
 def test_invalid_proxy_port(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
 
@@ -208,7 +209,7 @@ def test_invalid_proxy_port(monkeypatch):
 
 
 def test_invalid_proxy_host(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
 
@@ -236,7 +237,7 @@ def test_conf_manager_exception():
 
 
 def test_conf_stanza_not_exist_exception(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
 

tests/integration/test_hec_config.py

@@ -15,6 +15,7 @@
 #
 
 import context
+import conftest
 import os.path as op
 import sys
 
@@ -24,7 +25,7 @@
 
 
 def test_hec_config(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
     config = hec_config.HECConfig(session_key)

tests/integration/test_hec_event_writer.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 #
 import context
+import conftest
 import os.path as op
 import sys
 import time
@@ -26,7 +27,7 @@
 
 
 def test_hec_event_writer(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
 
@@ -43,7 +44,7 @@ def test_hec_event_writer(monkeypatch):
 
 
 def test_hec_event_writes_with_non_utf_8(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     # To test scenario listed in https://github.com/splunk/addonfactory-solutions-library-python/pull/112.
     test_name = "test_hec_event_writes_with_non_utf_8"

tests/integration/test_splunkenv.py

@@ -15,6 +15,7 @@
 #
 
 import context
+import conftest
 import os
 import os.path as op
 import sys
@@ -24,7 +25,7 @@
 
 
 def test_splunkenv(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     assert "SPLUNK_HOME" in os.environ
 

tests/integration/test_time_parser.py

@@ -15,6 +15,7 @@
 #
 
 import context
+import conftest
 import datetime
 import os.path as op
 import sys
@@ -25,7 +26,7 @@
 
 
 def test_time_parser(monkeypatch):
-    context.mock_splunk(monkeypatch)
+    conftest.mock_splunk(monkeypatch)
 
     session_key = context.get_session_key()
     tp = time_parser.TimeParser(session_key)