holmesgpt 0.13.2__py3-none-any.whl → 0.18.4__py3-none-any.whl

holmes/plugins/toolsets/runbook/runbook_fetcher.py

@@ -1,63 +1,174 @@
 import logging
+import os
 import textwrap
-from typing import Any, Dict, List, Optional
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union, cast
 
+from holmes.core.supabase_dal import SupabaseDal
 from holmes.core.tools import (
     StructuredToolResult,
+    StructuredToolResultStatus,
     Tool,
+    ToolInvokeContext,
     ToolParameter,
-    ToolResultStatus,
     Toolset,
     ToolsetTag,
 )
-
-from holmes.plugins.runbooks import get_runbook_by_path, DEFAULT_RUNBOOK_SEARCH_PATH
+from holmes.plugins.runbooks import (
+    DEFAULT_RUNBOOK_SEARCH_PATH,
+    get_runbook_by_path,
+    load_runbook_catalog,
+)
 from holmes.plugins.toolsets.utils import toolset_name_for_one_liner
 
 
-# TODO(mainred): currently we support fetch runbooks hosted internally, in the future we may want to support fetching
-# runbooks from external sources as well.
 class RunbookFetcher(Tool):
     toolset: "RunbookToolset"
+    available_runbooks: List[str] = []
+    additional_search_paths: Optional[List[str]] = None
+    _dal: Optional[SupabaseDal] = None
+
+    def __init__(
+        self,
+        toolset: "RunbookToolset",
+        additional_search_paths: Optional[List[str]] = None,
+        dal: Optional[SupabaseDal] = None,
+        custom_catalog_paths: Optional[List[Union[str, Path]]] = None,
+    ):
+        catalog = load_runbook_catalog(
+            dal=dal, custom_catalog_paths=custom_catalog_paths
+        )
+        available_runbooks = []
+        if catalog:
+            available_runbooks = catalog.list_available_runbooks()
+
+        if additional_search_paths:
+            for search_path in additional_search_paths:
+                if not os.path.isdir(search_path):
+                    continue
+
+                for file in os.listdir(search_path):
+                    if file.endswith(".md") and file not in available_runbooks:
+                        available_runbooks.append(f"{file}")
+
+        runbook_list = ", ".join([f'"{rb}"' for rb in available_runbooks])
 
-    def __init__(self, toolset: "RunbookToolset"):
         super().__init__(
             name="fetch_runbook",
             description="Get runbook content by runbook link. Use this to get troubleshooting steps for incidents",
             parameters={
-                # use link as a more generic term for runbook path, considering we may have external links in the future
-                "link": ToolParameter(
-                    description="The link to the runbook",
+                "runbook_id": ToolParameter(
+                    description=f"The runbook_id: either a UUID or a .md filename. Must be one of: {runbook_list}",
                     type="string",
                     required=True,
                 ),
             },
-            toolset=toolset,  # type: ignore
+            toolset=toolset,  # type: ignore[call-arg]
+            available_runbooks=available_runbooks,  # type: ignore[call-arg]
+            additional_search_paths=additional_search_paths,  # type: ignore[call-arg]
         )
+        self._dal = dal
+
+    def _invoke(self, params: dict, context: ToolInvokeContext) -> StructuredToolResult:
+        runbook_id: str = params.get("runbook_id", "")
+        is_md_file: bool = True if runbook_id.endswith(".md") else False
+
+        # Validate link is not empty
+        if not runbook_id or not runbook_id.strip():
+            err_msg = (
+                "Runbook link cannot be empty. Please provide a valid runbook path."
+            )
+            logging.error(err_msg)
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.ERROR,
+                error=err_msg,
+                params=params,
+            )
+
+        if is_md_file:
+            return self._get_md_runbook(runbook_id, params)
+        else:
+            return self._get_robusta_runbook(runbook_id, params)
 
-    def _invoke(
-        self, params: dict, user_approved: bool = False
-    ) -> StructuredToolResult:
-        link: str = params["link"]
+    def _get_robusta_runbook(self, link: str, params: dict) -> StructuredToolResult:
+        if self._dal and self._dal.enabled:
+            try:
+                runbook_content = self._dal.get_runbook_content(link)
+                if runbook_content:
+                    return StructuredToolResult(
+                        status=StructuredToolResultStatus.SUCCESS,
+                        data=runbook_content.pretty(),
+                        params=params,
+                    )
+                else:
+                    err_msg = f"Runbook with UUID '{link}' not found in remote storage."
+                    logging.error(err_msg)
+                    return StructuredToolResult(
+                        status=StructuredToolResultStatus.ERROR,
+                        error=err_msg,
+                        params=params,
+                    )
+            except Exception as e:
+                err_msg = f"Failed to fetch runbook with UUID '{link}': {str(e)}"
+                logging.error(err_msg)
+                return StructuredToolResult(
+                    status=StructuredToolResultStatus.ERROR,
+                    error=err_msg,
+                    params=params,
+                )
+        else:
+            err_msg = "Runbook link appears to be a UUID, but no remote data access layer (dal) is enabled."
+            logging.error(err_msg)
+            return StructuredToolResult(
+                status=StructuredToolResultStatus.ERROR,
+                error=err_msg,
+                params=params,
+            )
 
+    def _get_md_runbook(self, link: str, params: dict) -> StructuredToolResult:
         search_paths = [DEFAULT_RUNBOOK_SEARCH_PATH]
-        if self.toolset.config and "additional_search_paths" in self.toolset.config:
-            search_paths.extend(self.toolset.config["additional_search_paths"])
+        if self.additional_search_paths:
+            search_paths.extend(self.additional_search_paths)
+        # Validate link is in the available runbooks list OR is a valid path within allowed directories
+        if link not in self.available_runbooks:
+            # Check if the link would resolve to a valid path within allowed directories
+            # This prevents path traversal attacks like ../../secret.md
+            is_valid_path = False
+            for search_path in search_paths:
+                candidate_path = os.path.join(search_path, link)
+                # Canonicalize both paths to resolve any .. or . components
+                real_search_path = os.path.realpath(search_path)
+                real_candidate_path = os.path.realpath(candidate_path)
 
-        runbook_path = get_runbook_by_path(link, search_paths)
+                # Check if the resolved path is within the allowed directory
+                if (
+                    real_candidate_path.startswith(real_search_path + os.sep)
+                    or real_candidate_path == real_search_path
+                ):
+                    if os.path.isfile(real_candidate_path):
+                        is_valid_path = True
+                        break
 
+            if not is_valid_path:
+                err_msg = f"Invalid runbook link '{link}'. Must be one of: {', '.join(self.available_runbooks) if self.available_runbooks else 'No runbooks available'}"
+                logging.error(err_msg)
+                return StructuredToolResult(
+                    status=StructuredToolResultStatus.ERROR,
+                    error=err_msg,
+                    params=params,
+                )
+
+        runbook_path = get_runbook_by_path(link, search_paths)
         if runbook_path is None:
             err_msg = (
                 f"Runbook '{link}' not found in any of the search paths: {search_paths}"
             )
             logging.error(err_msg)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=err_msg,
                 params=params,
             )
-
-        # Read and return the runbook content
         try:
             with open(runbook_path, "r") as file:
                 content = file.read()
@@ -96,7 +207,7 @@ class RunbookFetcher(Tool):
                     </example>
                 """)
                 return StructuredToolResult(
-                    status=ToolResultStatus.SUCCESS,
+                    status=StructuredToolResultStatus.SUCCESS,
                     data=wrapped_content,
                     params=params,
                 )
@@ -104,29 +215,47 @@ class RunbookFetcher(Tool):
             err_msg = f"Failed to read runbook {runbook_path}: {str(e)}"
             logging.error(err_msg)
             return StructuredToolResult(
-                status=ToolResultStatus.ERROR,
+                status=StructuredToolResultStatus.ERROR,
                 error=err_msg,
                 params=params,
             )
 
     def get_parameterized_one_liner(self, params) -> str:
-        path: str = params.get("link", "")
+        path: str = params.get("runbook_id", "")
         return f"{toolset_name_for_one_liner(self.toolset.name)}: Fetch Runbook {path}"
 
 
 class RunbookToolset(Toolset):
-    def __init__(self, additional_search_paths: Optional[List[str]] = None):
-        # Store additional search paths in config
+    def __init__(
+        self,
+        dal: Optional[SupabaseDal],
+        additional_search_paths: Optional[List[str]] = None,
+    ):
+        # Store additional search paths in config for RunbookFetcher to access
         config = {}
         if additional_search_paths:
             config["additional_search_paths"] = additional_search_paths
 
+        # Compute custom catalog paths from additional search paths
+        custom_catalog_paths = None
+        if additional_search_paths:
+            custom_catalog_paths = [
+                os.path.join(search_path, "catalog.json")
+                for search_path in additional_search_paths
+                if os.path.isfile(os.path.join(search_path, "catalog.json"))
+            ]
+
         super().__init__(
             name="runbook",
             description="Fetch runbooks",
             icon_url="https://platform.robusta.dev/demos/runbook.svg",
             tools=[
-                RunbookFetcher(self),
+                RunbookFetcher(
+                    self,
+                    additional_search_paths,
+                    dal,
+                    cast(Optional[List[Union[str, Path]]], custom_catalog_paths),
+                ),
             ],
             docs_url="https://holmesgpt.dev/data-sources/",
             tags=[
@@ -134,6 +263,7 @@ class RunbookToolset(Toolset):
             ],
             is_default=True,
             config=config,
+            enabled=True,
         )
 
     def get_example_config(self) -> Dict[str, Any]:

holmes/plugins/toolsets/service_discovery.py

@@ -36,7 +36,7 @@ def find_service_url(label_selector):
         port = svc.spec.ports[0].port
         url = f"http://{name}.{namespace}.svc.{CLUSTER_DOMAIN}:{port}"
         logging.info(
-            f"discovered service with label-selector: `{label_selector}` at url: `{url}`"
+            f"Discovered service with label-selector: `{label_selector}` at url: `{url}`"
         )
         return url
     except Exception:

holmes/plugins/toolsets/servicenow_tables/instructions.jinja2

@@ -0,0 +1,83 @@
+## ServiceNow Tables Toolset
+
+This toolset provides access to ServiceNow tables for retrieving records and data.
+
+### Available Tools
+
+1. **servicenow_get_records**: Retrieve multiple records from a ServiceNow table with filtering capabilities
+2. **servicenow_get_record**: Retrieve a single record by its sys_id
+
+**IMPORTANT**: For servicenow_get_record, you MUST have a valid sys_id value that was either:
+- Provided by the user
+- Obtained from a previous servicenow_get_records call
+- Never guess or make up sys_id values - they are unique identifiers that must come from a legitimate source
+
+### Query Syntax
+
+The `sysparm_query` parameter supports a powerful query language:
+- Use `^` for AND conditions
+- Use `^OR` for OR conditions
+- Common operators:
+  - `=` (equals) - Use for exact matches, REQUIRED for reference fields
+  - `!=` (not equals)
+  - `LIKE` (contains) - Use for partial string matches on text fields only
+  - `STARTSWITH`
+  - `ENDSWITH`
+  - `CONTAINS`
+  - `ISNOTEMPTY`
+  - `ISEMPTY`
+  - `<`, `<=`, `>`, `>=` (comparisons)
+  - `BETWEEN` (for date ranges)
+
+Example: `active=true^priority=1^short_descriptionLIKEerror`
+
+**CRITICAL**: Reference fields (fields that link to other records) MUST use the `=` operator with the exact sys_id value. Never use `LIKE` with reference fields.
+- ✅ Correct: `cmdb_ci=b0ccabf1c0a80009001f14fd151d8df0`
+- ❌ Wrong: `cmdb_ciLIKE827b692d0ad337021abb72d3737ff401`
+
+**Date Queries - Best Practice**:
+Use `>=` and `<=` operators for date ranges. When using date-only format (YYYY-MM-DD), ServiceNow includes the entire day.
+- ✅ Recommended: `sys_created_on>=2024-01-01^sys_created_on<=2024-01-31` (includes all of Jan 31)
+- With time: `sys_created_on>=2024-01-01 00:00:00^sys_created_on<=2024-01-31 23:59:59`
+- Avoid BETWEEN operator as date handling can be inconsistent
+
+### Understanding Field Types
+
+In ServiceNow, fields can be of different types:
+- **Text fields**: Store plain text (use LIKE, CONTAINS, STARTSWITH for partial matches)
+- **Reference fields**: Store links to other records via sys_id (MUST use = for exact match)
+- **Boolean fields**: Store true/false values
+- **Date/Time fields**: Store timestamps (use comparison operators)
+
+How to identify reference fields:
+- When `sysparm_display_value=all`, reference fields return an object with {display_value, link, value}
+- The 'value' property contains the sys_id
+- Common reference fields: cmdb_ci, assigned_to, caller_id, company, location
+
+### Useful Tables
+
+- **cmdb_ci** - Configuration items (applications, servers, infrastructure). Search by name to get sys_id.
+- **change_request** - Links to CIs via cmdb_ci field. Use CI's sys_id to find who requested changes, when, and completion status.
+
+{# Additional tables can be added by user #}
+
+### Discovering Tables
+
+To discover available tables in ServiceNow, you can query the system table catalog:
+
+```
+table_name: sys_db_object
+sysparm_fields: name,label,description
+sysparm_query: nameSTARTSWITHincident
+```
+
+This will return tables with names starting with "incident". You can modify the query to search for other table patterns.
+
+**Note**: ServiceNow contains many tables, so it's recommended to filter your search using `STARTSWITH`, `CONTAINS`, or `LIKE` operators to find relevant tables efficiently.
+
+### Tips for Usage
+
+1. Use `sysparm_view=mobile` to get a concise set of fields when exploring data
+2. Use `sysparm_fields` to specify exactly which fields you need to reduce response size
+3. The default limit is 100 records; increase it if you need more data
+4. Display values are returned by default (human-readable format)