Initial commit with readme.

Author: lukehunterdev

.dxtignore

@@ -0,0 +1,9 @@
+__pycache__/
+.claude/
+.ruff_cache/
+.venv/
+build/
+lib/
+scripts/
+docs/
+*.egg-info/

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -1,2 +1,144 @@
-# mcp-server-ntm
-The official MCP server for Threat Manager.
+# Netwrix Threat Manager MCP Server
+
+This [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server enables AI assistants to interface directly with Netwrix Threat Manager (NTM), enhancing your organization's threat management capabilities.
+
+## Use Cases
+- **Threat Monitoring:** View the most recent threats or those within a specified time frame.
+- **Filtering:** Filter threats by one or more perpetrators or by threat types.
+- **Details and Events:** Dive into the details and get the events that triggered a given threat.
+- **Searching:** Find objects and users, search by name or tag, and list tags.
+- **Links:** Usable links back to NTM (login required).
+- **Complex Queries:** Ask more complex questions that combine tools intelligently for a more targetted answer.
+
+## Example Usages
+Here are some example prompts, and which tools are invoked, and how the LLM may respond. See below for tool details.
+
+- "Show me the most recent threats."
+    - `get_recent_threats`, no threat IDs, no perp IDs, default `skip` and `take` values.
+    - _The LLM may ask if you want to see more threats once this is complete, which will set the `skip` and `take` params accordingly._
+
+- "Find any users with the surname Hunter."
+    - `find_users_by_name`: using the string "Hunter" as `name_search`.
+    - _The tool will find any user with Hunter in their name, so it would also find those with a first name of Hunter. The LLM in this case will probably differentiate between those with the surname "Hunter" and those with it as a first name._
+
+- "I want to know which objects are stale."
+    - `get_all_tags`: the LLM will consider using get_objects_with_tag but then realises it needs to call this tool first.
+    - `get_objects_with_tag`: set `tag_id` parameter using tag ID for "stale" as found in previous tool.
+
+- "Find me all threats for last Wednesday by users tagged as stale."
+    - `get_all_tags`: to fetch all tag IDs, then find the one for "stale".
+    - `get_users_with_tag`: to fetch all users tagged as stale.
+    - `get_threats_within_time_range`: using the user IDs found, will fetch the 20 most recent threats from "last Wednesday".
+    - _The LLM may repeat calls to the last tool to get all threats. For example if the first call returns 20, a safe assumption to make is that there is more, less than 20 means there is no point skipping and taking more._
+
+![MCP Server for NTM in Claude Desktop](docs/images/Threats%20Last%20Monday%20Privileged.gif)
+
+## Tools
+
+### Threat Discovery and Details
+
+- **get_threat_types** - View all types of threats, their level, and if they are enabled.
+
+- **get_recent_threats** - Gets the most recent threats, optionally filtered by threat type, and optionally filtered by perpetrator.
+    - `threat_type_ids`: Filter on threat types, obtained by get_threat_types tool. Empty list assumes all threats. (array, required)
+    - `perp_ids`: Filter on perpetrators, obtained by get_threat_types tool. Empty list assumes all perpetrators. (array, required)
+    - `skip`: Skip a number of records. Defaults to 0.
+    - `take`: Take a number of records. Defaults to 20, maximum of 20.
+
+- **get_threats_within_time_range** - Gets threats within the given date and time range, optionally filtered by threat type, and optionally filtered by perpetrator.
+    - `start_time` start date and time to search from. (datetime, required)
+    - `end_time` end date and time to search until. (datetime, required)
+    - `threat_type_ids`: Filter on threat types, obtained by get_threat_types tool. Empty list assumes all threats. (array, required)
+    - `perp_ids`: Filter on perpetrators, obtained by get_threat_types tool. Empty list assumes all perpetrators. (array, required)
+    - `skip`: Skip a number of records. Defaults to 0.
+    - `take`: Take a number of records. Defaults to 20, maximum of 20.
+
+- **get_details_for_threat** - Gets details for the given threat.
+    - `threat_id`: Threat ID, obtained by get_recent_threats and get_threats_within_time_range tools. (GUID, required)
+
+- **get_recent_events_for_threat** - Gets threats within the given date and time range, optionally filtered by threat type, and optionally filtered by perpetrator.
+    - `threat_id`: Threat ID, obtained by get_recent_threats and get_threats_within_time_range tools. (GUID, required)
+    - `skip`: Skip a number of records. Defaults to 0.
+    - `take`: Take a number of records. Defaults to 20, maximum of 20.
+
+### User and Object Searching
+
+- **find_users_by_name** - Finds all users by name. Partial matches will also be returned.
+    - `name_search`: Partial or full name of user to search for, case is ignored. (string, required)
+
+- **get_all_tags** - Get tags available in NTM.
+    - `skip`: Skip a number of records. Defaults to 0.
+    - `take`: Take a number of records. Defaults to 20, maximum of 20.
+
+- **get_objects_with_tag** - Get all objects with the given tag ID.
+    - `tag_id`: The tag ID to filter objects by. (integer, required)
+
+- **get_users_with_tag** - Get all users with the given tag ID.
+    - `tag_id`: The tag ID to filter objects by, from get_all_tags tool. (integer, required)
+
+### Version
+- **get_ntm_version** - Get the version of your Netwrix Threat Manager server.
+
+## Installation
+
+Prequisites:
+
+- Install [uv](https://docs.astral.sh/uv/getting-started/installation/), a Python project manager
+
+- Clone the repository (or download it as a zip)
+
+To clone the repository:
+```bash
+git clone https://github.com/netwrix/mcp-server-ntm.git
+```
+
+### Install in Claude Desktop via Desktop Extensions (Recommended)
+
+#### Option 1: One-click Installation
+
+- Download the latest `mcp_server_ntm.dxt` file from [releases](https://github.com/netwrix/mcp-server-ntm/releases)
+
+- Double-click to open with Claude Desktop (may have to find Claude Desktop to "Open with...")
+
+- Click "Install"
+
+#### Option 2: Upload Desktop Extension File Manually
+
+- Download the latest `mcp_server_ntm.dxt` file from [releases](https://github.com/netwrix/mcp-server-ntm/releases)
+- Navigate to `File -> Settings -> Extensions -> Advanced settings -> Install Extension...`
+- Fill out the required fields, select Install and Enable
+
+### Install in Claude Desktop via Configuration File
+
+- Navigate to `File -> Settings -> Developer -> Edit Config`
+
+Open the `claude_desktop_config.json` file and add the following:
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-ntm": {
+    "command": "uv",
+    "args": [
+        "run",
+        "path/to/src/mcp_server_ntm/server.py"
+    ],
+      "env": {
+        "NTM_URL": "https://example.com",
+        "NTM_USERNAME": "your_ntm_username",
+        "NTM_PASSWORD": "your_ntm_password"
+      }
+    }
+  }
+}
+```
+
+Then, restart Claude Desktop.
+
+## License
+
+This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE) for the full terms.
+
+## Connect with Us
+
+If you need help using this MCP server, want to better understand your results, or would like to share feedback, visit the [Netwrix Community](https://community.netwrix.com/) - we’re here to help and eager to hear about your experience!

docs/images/Threats Last Monday Privileged.gif

@@ -0,0 +1,112 @@
+{
+  "dxt_version": "0.1",
+  "name": "mcp-server-ntm",
+  "display_name": "Netwrix Threat Manager MCP Server",
+  "version": "0.0.1",
+  "description": "Monitor and assess threats.",
+  "author": {
+    "name": "Netwrix Corporation"
+  },
+  "keywords": [
+    "netwrix",
+    "security",
+    "threat",
+    "monitoring"
+  ],
+  "license": "MIT",
+  "icon": "assets/icon.png",
+  "server": {
+    "type": "python",
+    "entry_point": "server.py",
+    "mcp_config": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "${__dirname}",
+        "python",
+        "${__dirname}/server.py"
+      ],
+      "env": {
+        "PYTHONPATH": "${__dirname}/lib",
+        "NTM_URL": "${user_config.ntm_url}",
+        "NTM_USERNAME": "${user_config.ntm_username}",
+        "NTM_PASSWORD": "${user_config.ntm_password}",
+        "NTM_VERIFY_TRUST": "false",
+        "MCP_TRANSPORT": "stdio"
+      }
+    }
+  },
+  "tools": [
+    {
+      "name": "get_threat_types",
+      "description": "Get all threat types in NTM. This will return all enabled and disabled threats."
+    },
+    {
+      "name": "get_recent_threats",
+      "description": "Gets the most recent threats, optionally filtered by threat type, and optionally filtered by perpetrator."
+    },
+    {
+      "name": "get_threats_within_time_range",
+      "description": "Gets threats within the given date and time range, optionally filtered by threat type, and optionally filtered by perpetrator."
+    },
+    {
+      "name": "get_details_for_threat",
+      "description": "Gets details for the given threat. Only one threat at a time is supported."
+    },
+    {
+      "name": "get_recent_events_for_threat",
+      "description": "Gets most recent events for the given threat ID."
+    },
+    {
+      "name": "find_users_by_name",
+      "description": "Finds all users by name using a case-insensitive search. Partial matches will also be returned."
+    },
+    {
+      "name": "get_all_tags",
+      "description": "Get tags available in NTM."
+    },
+    {
+      "name": "get_objects_with_tag",
+      "description": "Get all objects with the given tag ID."
+    },
+    {
+      "name": "get_users_with_tag",
+      "description": "Get all users with the given tag ID."
+    },
+    {
+      "name": "get_ntm_version",
+      "description": "Get the version of NTM (Netwrix Threat Manager)."
+    }
+  ],
+  "user_config": {
+    "ntm_url": {
+      "type": "string",
+      "title": "NTM Server URL",
+      "description": "The URL for your Threat Manager server (e.g., https://ntm.example.com)",
+      "required": true
+    },
+    "ntm_username": {
+      "type": "string",
+      "title": "Username",
+      "description": "Your Threat Manager username",
+      "required": true
+    },
+    "ntm_password": {
+      "type": "string",
+      "title": "Password",
+      "description": "Your Threat Manager password",
+      "sensitive": true,
+      "required": true
+    }
+  },
+  "compatibility": {
+    "dxt_version": ">=0.1",
+    "platforms": [
+      "win32"
+    ],
+    "runtimes": {
+      "python": ">=3.12"
+    }
+  }
+}