New tools enhancements

README.md

@@ -54,6 +54,7 @@ HolmesGPT integrates with popular observability and cloud platforms. The followi
 | [<img src="images/integration_logos/datadog_logo.png" alt="Datadog" width="20" style="vertical-align: middle;"> **Datadog**](https://holmesgpt.dev/data-sources/builtin-toolsets/datadog/) | Query logs, metrics, and traces |
 | [<img src="images/integration_logos/docker_logo.png" alt="Docker" width="20" style="vertical-align: middle;"> **Docker**](https://holmesgpt.dev/data-sources/builtin-toolsets/docker/) | Get images, logs, events, history and more |
 | [<img src="images/integration_logos/opensearchserverless-icon.png" alt="Elasticsearch" width="20" style="vertical-align: middle;"> **Elasticsearch / OpenSearch**](https://holmesgpt.dev/data-sources/builtin-toolsets/elasticsearch/) | Query logs, cluster health, shard and index diagnostics |
+| [<img src="images/integration_logos/freshservice-icon.png" alt="Freshservice" width="20" style="vertical-align: middle;"> **Freshservice**](https://holmesgpt.dev/data-sources/builtin-toolsets/freshservice/) | Tickets, problems, changes, assets and other ITSM records |
 | [<img src="images/integration_logos/gcpmonitoring-icon.png" alt="GCP" width="20" style="vertical-align: middle;"> **GCP**](https://holmesgpt.dev/data-sources/builtin-toolsets/gcp/) | Google Cloud Platform resources (MCP) |
 | [<img src="images/integration_logos/github_logo.png" alt="GitHub" width="20" style="vertical-align: middle;"> **GitHub**](https://holmesgpt.dev/data-sources/builtin-toolsets/github-mcp/) | Repositories, issues, and pull requests (MCP) |
 | [<img src="images/integration_logos/gitlab-icon.png" alt="GitLab" width="20" style="vertical-align: middle;"> **GitLab**](https://holmesgpt.dev/data-sources/builtin-toolsets/gitlab-mcp/) | Projects, merge requests, issues, and CI/CD pipelines (MCP) |

conftest.py

@@ -121,15 +121,21 @@ def _patched_openai_init(self, *args, **kwargs):
     if confluence_base and not os.environ.get("CONFLUENCE_SA_BASE_URL"):
         parsed = urllib.parse.urlparse(confluence_base)
         if parsed.scheme not in ("http", "https"):
-            logging.warning(f"CONFLUENCE_BASE_URL has unsupported scheme '{parsed.scheme}', skipping SA URL derivation")
+            logging.warning(
+                f"CONFLUENCE_BASE_URL has unsupported scheme '{parsed.scheme}', skipping SA URL derivation"
+            )
         else:
             try:
                 tenant_url = f"{confluence_base.rstrip('/')}/_edge/tenant_info"
                 with urllib.request.urlopen(tenant_url, timeout=10) as resp:
                     cloud_id = json.loads(resp.read())["cloudId"]
-                os.environ["CONFLUENCE_SA_BASE_URL"] = f"https://api.atlassian.com/ex/confluence/{cloud_id}"
+                os.environ["CONFLUENCE_SA_BASE_URL"] = (
+                    f"https://api.atlassian.com/ex/confluence/{cloud_id}"
+                )
                 os.environ["CONFLUENCE_CLOUD_ID"] = cloud_id
-                logging.info(f"Auto-derived CONFLUENCE_SA_BASE_URL and CONFLUENCE_CLOUD_ID from cloud ID {cloud_id}")
+                logging.info(
+                    f"Auto-derived CONFLUENCE_SA_BASE_URL and CONFLUENCE_CLOUD_ID from cloud ID {cloud_id}"
+                )
             except Exception as e:
                 logging.warning(f"Could not auto-derive CONFLUENCE_SA_BASE_URL: {e}")
 
@@ -287,6 +293,9 @@ def responses():
         rsps.add_passthru(re.compile(r"https://.*\.atlassian\.net"))
         rsps.add_passthru("https://api.atlassian.com")  # Atlassian Cloud API gateway
 
+        # Allow Freshservice (Freshworks) API calls
+        rsps.add_passthru(re.compile(r"https://.*\.freshservice\.com"))
+
         # Allow
         rsps.add_passthru("https://google.com")
         rsps.add_passthru("https://burgergooglenetworkspam.co.uk")

docs/data-sources/builtin-toolsets/.nav.yml

@@ -17,6 +17,7 @@ nav:
   - DataDog: datadog.md
   - Docker: docker.md
   - Elasticsearch / OpenSearch: elasticsearch.md
+  - Freshservice: freshservice.md
   - GCP (MCP): gcp.md
   - GitHub (MCP): github-mcp.md
   - GitLab (MCP): gitlab-mcp.md

docs/data-sources/builtin-toolsets/datadog.md

@@ -397,3 +397,72 @@ holmes ask "find recent incidents in Datadog"
 # Get synthetic test results
 holmes ask "show me the latest synthetic test results for our homepage"
 ```
+
+## Restricting Holmes to a Single Environment
+
+If your Datadog organization contains data from multiple environments (e.g. production and staging) and Holmes should only see one of them, restrict access in two layers. The first layer is the actual security boundary; the second is defence in depth inside Holmes.
+
+**Layer 1: Restrict the Datadog credential (the security boundary)**
+
+Datadog enforces data access at the role level, so the strongest guarantee is a credential that cannot read the other environments at all:
+
+1. In Datadog, create a role with a [restriction query](https://docs.datadoghq.com/account_management/rbac/) of `env:staging` (adjust the tag to your environment).
+2. Create a service account holding only that role, and issue an API key and Application key pair for it.
+3. Point the Holmes toolset config at those keys — Datadog then filters logs and traces server-side, regardless of what Holmes queries.
+
+Note that Datadog restriction queries do not cover the metrics query API, which is why the Holmes-side layer below matters for metrics.
+
+**Layer 2: Configure `scope` in Holmes (defence in depth)**
+
+All Datadog toolsets accept an optional `scope` block:
+
+```yaml-toolset-config
+toolsets:
+  datadog/logs:
+    enabled: true
+    config:
+      api_key: "{{ env.DATADOG_API_KEY }}"
+      app_key: "{{ env.DATADOG_APP_KEY }}"
+      api_url: https://api.datadoghq.eu
+      scope:
+        tags:
+          env: staging
+  datadog/metrics:
+    enabled: true
+    config:
+      api_key: "{{ env.DATADOG_API_KEY }}"
+      app_key: "{{ env.DATADOG_APP_KEY }}"
+      api_url: https://api.datadoghq.eu
+      scope:
+        tags:
+          env: staging
+  datadog/traces:
+    enabled: true
+    config:
+      api_key: "{{ env.DATADOG_API_KEY }}"
+      app_key: "{{ env.DATADOG_APP_KEY }}"
+      api_url: https://api.datadoghq.eu
+      scope:
+        tags:
+          env: staging
+  datadog/general:
+    enabled: false  # Required when a scope is configured — see below
+```
+
+With a scope configured:
+
+- **`datadog/logs`** and **`datadog/traces`**: every search query is wrapped and combined with the scope — `(your query) AND (env:staging)` — so no query, including ones containing `OR`, can reach data outside the scope. The Datadog deep links returned alongside results carry the same scoped query.
+- **`datadog/metrics`**: metric queries are validated, not rewritten. Every metric selector must include the scope tag as a plain `tag:value` term (e.g. `system.cpu.user{env:staging,host:web-1}`); queries with unscoped selectors such as `{*}`, boolean operators inside selectors, or anything unparseable are rejected before reaching Datadog, with an error telling the model how to fix the query. `list_active_datadog_metrics` is forced to filter by the scope tag. `get_datadog_metric_metadata` and `list_datadog_metric_tags` remain available: they return metric and tag names (no timeseries data), and the model needs them to construct correctly scoped queries.
+- **`datadog/general`** must be disabled. Most of its endpoints — dashboards, monitors, incidents, hosts, containers, org and user data — have no environment dimension, so there is nothing to scope them by. If a scope is configured while `datadog/general` is enabled, the toolset fails its prerequisites with an explanatory message rather than silently serving unscoped data. Setting both `scope` and `allow_custom_endpoints: true` is rejected at config validation.
+
+Scope tag values are matched exactly: `staging` does not match `staging-eu` or `stag*`. A tag may list multiple allowed values:
+
+```yaml
+scope:
+  tags:
+    env: [staging, dev]
+```
+
+When `scope` is not set, all toolsets behave exactly as before — the feature is fully backwards compatible.
+
+Empty results under a scope explicitly say the search was limited to the configured scope, so an out-of-scope service is reported as "not visible" rather than "healthy".

docs/data-sources/builtin-toolsets/freshservice.md

@@ -0,0 +1,162 @@
+# Freshservice
+
+Connect HolmesGPT to [Freshservice](https://www.freshworks.com/freshservice/) (Freshworks ITSM) to work with tickets, problems, changes, releases, assets, requesters, agents, the service catalog, the knowledge base and every other Freshservice object via the [Freshservice API v2](https://api.freshservice.com/).
+
+Access is read-only by default. Create/update/delete tools can be enabled with `enable_write_tools: true`, and each write requires human approval unless you disable that too (see [Write access](#write-access-optional)).
+
+## Prerequisites
+
+- A Freshservice instance (e.g. `https://your-domain.freshservice.com`)
+- A Freshservice API key. In the Freshservice UI, click your profile picture → **Profile settings** — the API key is shown below the change password section.
+
+The API key inherits the permissions of its user, so the tickets, changes and other objects HolmesGPT can read are determined by that user's role. Some object types (e.g. assets/CMDB) are only available on certain Freshservice plans; HolmesGPT reports the exact API error when an object type is not accessible.
+
+Verify your credentials:
+
+```bash
+curl -u <your-api-key>:X "https://<your-domain>.freshservice.com/api/v2/tickets?per_page=1"
+```
+
+## Configuration
+
+=== "Holmes CLI"
+
+    Add the following to **~/.holmes/config.yaml**. Create the file if it doesn't exist:
+
+    ```yaml
+    toolsets:
+      freshservice:
+        enabled: true
+        config:
+          api_url: <your Freshservice URL>  # e.g. https://your-domain.freshservice.com
+          api_key: <your Freshservice API key>
+
+          # Optional
+          default_page_size: 30  # Records per page when the LLM doesn't specify (max 100)
+          timeout_seconds: 30  # HTTP timeout for Freshservice API requests
+          health_check_object: tickets  # Object type listed on startup to verify connectivity
+    ```
+
+    --8<-- "snippets/toolset_refresh_warning.md"
+
+    To test, run:
+
+    ```bash
+    holmes ask "Show me all open urgent tickets in Freshservice"
+    ```
+
+=== "Holmes Helm Chart"
+
+    First, create a Kubernetes secret with your Freshservice API key:
+
+    ```bash
+    kubectl create secret generic freshservice-credentials \
+      --from-literal=api-key=your-freshservice-api-key \
+      -n holmes
+    ```
+
+    --8<-- "snippets/secret_namespace_note.md"
+
+    Then add to your Holmes Helm values:
+
+    ```yaml
+    additionalEnvVars:
+      - name: FRESHSERVICE_API_KEY
+        valueFrom:
+          secretKeyRef:
+            name: freshservice-credentials
+            key: api-key
+
+    toolsets:
+      freshservice:
+        enabled: true
+        config:
+          api_url: <your Freshservice URL>  # e.g. https://your-domain.freshservice.com
+          api_key: "{{ env.FRESHSERVICE_API_KEY }}"
+    ```
+
+=== "Robusta Helm Chart"
+
+    First, create a Kubernetes secret with your Freshservice API key:
+
+    ```bash
+    kubectl create secret generic freshservice-credentials \
+      --from-literal=api-key=your-freshservice-api-key \
+      -n default
+    ```
+
+    --8<-- "snippets/secret_namespace_note.md"
+
+    Then add to your Robusta Helm values:
+
+    ```yaml
+    holmes:
+      additionalEnvVars:
+        - name: FRESHSERVICE_API_KEY
+          valueFrom:
+            secretKeyRef:
+              name: freshservice-credentials
+              key: api-key
+      toolsets:
+        freshservice:
+          enabled: true
+          config:
+            api_url: <your Freshservice URL>  # e.g. https://your-domain.freshservice.com
+            api_key: "{{ env.FRESHSERVICE_API_KEY }}"
+    ```
+
+    --8<-- "snippets/helm_upgrade_command.md"
+
+### Optional Fields
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default_page_size` | `30` | Number of records returned per page when the LLM does not specify one (max 100). |
+| `timeout_seconds` | `30` | Timeout for Freshservice API requests. |
+| `health_check_object` | `tickets` | Object type listed on startup to verify connectivity and permissions. Change this if your API key cannot access tickets. |
+| `enable_write_tools` | `false` | Expose tools that create, update and delete Freshservice objects. When `false`, only read tools are available. |
+| `require_approval_for_writes` | `true` | When write tools are enabled, require human approval before each create/update/delete call. Set to `false` for fully autonomous writes. |
+
+## Write Access (optional)
+
+By default HolmesGPT can only read from Freshservice. To let it create, update and delete objects (tickets, problems, changes, notes, tasks, time entries, custom object records and more), enable write tools:
+
+```yaml
+toolsets:
+  freshservice:
+    enabled: true
+    config:
+      api_url: <your Freshservice URL>
+      api_key: <your Freshservice API key>
+      enable_write_tools: true
+      # require_approval_for_writes: false  # only for fully autonomous writes
+```
+
+With writes enabled, six additional tools become available: `freshservice_create_object`, `freshservice_update_object`, `freshservice_delete_object` and their `*_related_object` counterparts for notes, replies, tasks and time entries.
+
+!!! warning
+    Every write call requires interactive human approval by default. Only set `require_approval_for_writes: false` in automated flows where the API key's own Freshservice role is scoped to what Holmes should be allowed to touch — deletes move tickets to trash and deactivate requesters/agents. Some object types are read-only in the Freshservice API itself (roles, workspaces, form fields, SLA policies, business hours, service catalog) regardless of this setting.
+
+## Multiple Instances
+
+```multi-instance
+toolset: freshservice
+name: Freshservice
+config: |
+  api_url: <your Freshservice URL>
+  api_key: <your Freshservice API key>
+```
+
+## Common Use Cases
+
+```
+Which urgent Freshservice tickets are currently open, and what do their latest conversations say?
+```
+
+```
+Are there any Freshservice changes planned for this week that could affect the payment service?
+```
+
+```
+Find the Freshservice problem records related to database connectivity and summarize their root cause notes.
+```

docs/data-sources/builtin-toolsets/index.md

@@ -54,6 +54,7 @@ HolmesGPT includes pre-built integrations for popular monitoring and observabili
 
 <div class="grid cards" markdown>
 
+-   [:material-ticket-confirmation:{ .lg .middle } **Freshservice**](freshservice.md)
 -   [:material-ticket:{ .lg .middle } **ServiceNow**](servicenow.md)
 
 </div>

docs/why-holmesgpt.md

@@ -63,7 +63,7 @@ HolmesGPT ships with read-only integrations for every major observability vendor
 - **CI/CD**: Jenkins
 - **Cloud**: AWS RDS, Azure SQL, Azure AKS, GCP
 - **Databases**: PostgreSQL, MySQL, ClickHouse, MariaDB, SQL Server, MongoDB Atlas
-- **ITSM**: ServiceNow
+- **ITSM**: ServiceNow, Freshservice
 - **Messaging**: Kafka, RabbitMQ
 - **Knowledge**: Atlassian Rovo (Jira + Confluence), Confluence, Notion, Slab, Internet/web search
 

holmes/plugins/toolsets/__init__.py

@@ -25,7 +25,6 @@
 from holmes.plugins.toolsets.connectivity_check import ConnectivityCheckToolset
 from holmes.plugins.toolsets.coralogix.toolset_coralogix import CoralogixToolset
 from holmes.plugins.toolsets.database.database import DatabaseToolset
-from holmes.plugins.toolsets.mongodb.mongodb import MongoDBToolset
 from holmes.plugins.toolsets.datadog.toolset_datadog_general import (
     DatadogGeneralToolset,
 )
@@ -43,6 +42,7 @@
 from holmes.plugins.toolsets.elasticsearch.opensearch_query_assist import (
     OpenSearchQueryAssistToolset,
 )
+from holmes.plugins.toolsets.freshservice.freshservice import FreshserviceToolset
 from holmes.plugins.toolsets.grafana.loki.toolset_grafana_loki import GrafanaLokiToolset
 from holmes.plugins.toolsets.grafana.toolset_grafana import GrafanaToolset
 from holmes.plugins.toolsets.grafana.toolset_grafana_tempo import GrafanaTempoToolset
@@ -56,17 +56,18 @@
 from holmes.plugins.toolsets.kubectl_run.kubectl_run_toolset import KubectlRunToolset
 from holmes.plugins.toolsets.kubernetes_logs import KubernetesLogsToolset
 from holmes.plugins.toolsets.mcp.toolset_mcp import RemoteMCPToolset
+from holmes.plugins.toolsets.mongodb.mongodb import MongoDBToolset
 from holmes.plugins.toolsets.multi_instance import multi_instance
 from holmes.plugins.toolsets.newrelic.newrelic import NewRelicToolset
 from holmes.plugins.toolsets.rabbitmq.toolset_rabbitmq import RabbitMQToolset
 from holmes.plugins.toolsets.robusta.robusta import RobustaToolset
 from holmes.plugins.toolsets.robusta_platform_mcp.robusta_platform_mcp import (
     make_robusta_platform_mcp_toolset,
 )
-from holmes.plugins.toolsets.skills.skills_fetcher import SkillsToolset
 from holmes.plugins.toolsets.servicenow_tables.servicenow_tables import (
     ServiceNowTablesToolset,
 )
+from holmes.plugins.toolsets.skills.skills_fetcher import SkillsToolset
 from holmes.plugins.toolsets.victorialogs.victorialogs import VictoriaLogsToolset
 
 THIS_DIR = os.path.abspath(os.path.dirname(__file__))
@@ -125,6 +126,7 @@ def load_python_toolsets(
         multi_instance(MongoDBAtlasToolset),
         SkillsToolset(dal=dal, additional_search_paths=additional_search_paths),
         multi_instance(ServiceNowTablesToolset),
+        multi_instance(FreshserviceToolset),
         multi_instance(VictoriaLogsToolset),
         DatabaseToolset(),
         multi_instance(ElasticsearchDataToolset),
@@ -210,9 +212,7 @@ def _make_invalid_toolset_placeholder(
         description=description,
         tools=[],
         enabled=True,  # must be True so check_prerequisites runs and keeps it FAILED
-        prerequisites=[
-            StaticPrerequisite(enabled=False, disabled_reason=error)
-        ],
+        prerequisites=[StaticPrerequisite(enabled=False, disabled_reason=error)],
     )
     # Set FAILED status + error up front so the sync layer sees them even if
     # check_prerequisites is skipped (e.g. on cached startup paths).

holmes/plugins/toolsets/datadog/datadog_api.py

@@ -12,6 +12,7 @@
 from tenacity import retry, retry_if_exception, stop_after_attempt, wait_incrementing
 from tenacity.wait import wait_base
 
+from holmes.plugins.toolsets.datadog.datadog_scope import DatadogScopeConfig
 from holmes.utils.pydantic_utils import ToolsetConfig
 
 START_RETRY_DELAY = (
@@ -137,6 +138,18 @@ class DatadogBaseConfig(ToolsetConfig):
         title="Timeout",
         description="HTTP request timeout in seconds",
     )
+    scope: Optional[DatadogScopeConfig] = Field(
+        default=None,
+        title="Environment Scope",
+        description=(
+            "Restricts every Datadog toolset to data carrying the given tags, e.g. "
+            "{'tags': {'env': 'staging'}}. Left unset (the default) the toolsets "
+            "behave exactly as before. This is defence in depth: the actual security "
+            "boundary is a Datadog role restriction query on the credential Holmes "
+            "uses. See "
+            "https://holmesgpt.dev/data-sources/builtin-toolsets/datadog/#restricting-holmes-to-a-single-environment"
+        ),
+    )
 
 
 class DataDogRequestError(Exception):