JupiterOne MCP Server

# List Rules Tool List rules in your JupiterOne account using cursor pagination. This tool returns a page of rule instances, including their IDs, names, descriptions, versions, polling intervals, and other metadata. Use the cursor parameter to navigate through pages of results. This does not get alerts, but rather the configuration behind what may generate an alert, or other workflow action. ## Parameters - `limit` (optional): Maximum number of rules to return per page (between 1 and 1000). Defaults to 100 if not specified. - `cursor` (optional): Pagination cursor to get the next page of results. Use the `endCursor` from a previous response's `pageInfo`. Omit this parameter to get the first page. ## Example Usage Get the first page of rules (default page size): ```json {} ``` Get the first page with specific limit: ```json { "limit": 50 } ``` Get the next page using a cursor: ```json { "limit": 50, "cursor": "cursor_value_from_previous_response" } ``` ## Response Format All responses include pagination information: ```json { "returned": 50, "rules": [...], "pageInfo": { "hasNextPage": true, "endCursor": "cursor_for_next_page" } } ``` - `returned`: Number of rules in this page - `rules`: Array of rule objects - `pageInfo.hasNextPage`: Whether there are more pages available - `pageInfo.endCursor`: Cursor to use for the next page (if `hasNextPage` is true) ## Pagination Pattern To get all rules across multiple pages: 1. Call with no cursor to get the first page 2. Check if `pageInfo.hasNextPage` is true 3. If true, call again with `cursor` set to `pageInfo.endCursor` 4. Repeat until `hasNextPage` is false

# Get Rule Details Tool Get detailed information about a specific JupiterOne alert rule by its ID. This tool returns comprehensive rule configuration including queries, conditions, actions, and metadata. ## Parameters - `ruleId` (required): The unique identifier of the rule to retrieve ## Example Usage Request the details of a specific rule: ```json { "ruleId": "12345678-1234-1234-1234-123456789abc" } ```

# Evaluate Rule Tool Manually trigger the evaluation of a JupiterOne alert rule. This tool forces an immediate evaluation of the rule's conditions and returns the results. ## Parameters - `ruleId` (required): The unique identifier of the rule to evaluate ## Example Usage Evaluate a specific rule: ```json { "ruleId": "12345678-1234-1234-1234-123456789abc" } ```

# JupiterOne Rule Creation Tool - Complete Guide **Purpose**: Creates inline question-based alert rules in JupiterOne to monitor entities and trigger alerts based on specified conditions. The first step in creating a rule is to identify the query you want to use in order to get the data you want to take action with. Use the `execute-j1ql-query` tool to find the correct query. ## Key Requirements for Success ### 1. Condition Format (Critical) The `condition` parameter must use JupiterOne's specific array format: - **Structure**: `["LOGICAL_OPERATOR", [left_value, operator, right_value]]` - **Example**: `["AND", ["queries.queryName.total", ">", 0]]` - **Supported operators**: `>`, `<`, `>=`, `<=`, `=`, `!=` - **Logical operators**: `"AND"`, `"OR"` ### 2. Operations Structure The `when` clause should only contain: - `type`: Always `"FILTER"` - `condition`: The array format described above - **Do NOT include**: `version`, `specVersion` (these belong at the rule level, not in the when clause) ### 3. Query Naming Convention - Query names in the `queries` array must match the references in conditions - Example: If query name is `"users"`, reference it as `"queries.users.total"` - **IMPORTANT**: Use `"query0"` as the standard query name for compatibility with existing patterns ### 4. New Entity Detection - Use `triggerActionsOnNewEntitiesOnly: true` to only alert on genuinely new entities - This prevents re-alerting on existing entities every polling cycle - Essential for "new user" or "new resource" type alerts ### 5. Polling Intervals - **Default**: Use `"ONE_DAY"` unless the user specifically requests a different interval - **Available options**: `"DISABLED"`, `"THIRTY_MINUTES"`, `"ONE_HOUR"`, `"FOUR_HOURS"`, `"EIGHT_HOURS"`, `"TWELVE_HOURS"`, `"ONE_DAY"`, `"ONE_WEEK"` - Only use more frequent intervals (like `"THIRTY_MINUTES"`) when explicitly requested or for time-sensitive security alerts ### 6. Tags vs Labels (Important) - **DEPRECATED**: The `tags` array field is deprecated and should always be set to an empty array `[]` - **USE INSTEAD**: For tagging functionality, use the `labels` field with key-value pairs - **Format**: `labels: [{"labelName": "key", "labelValue": "value"}]` - **When users ask for tagging**: Always use the `labels` field to meet their needs - **Note**: The `tags` field is still required in the schema for compatibility but should remain empty ## Required Schema Fields ### Complete Required Parameters for create-inline-question-rule **CRITICAL**: All of these fields must be included for successful rule creation: ```json { "name": "Rule Name", "description": "Rule description", "notifyOnFailure": true, "triggerActionsOnNewEntitiesOnly": true, "ignorePreviousResults": false, "pollingInterval": "ONE_DAY", "templates": {}, "outputs": ["alertLevel"], "tags": [], "labels": [ {"labelName": "environment", "labelValue": "production"}, {"labelName": "team", "labelValue": "security"} ], "queries": [ { "query": "FIND Entity...", "name": "query0", "version": "v1", "includeDeleted": false } ], "operations": [ { "when": { "type": "FILTER", "condition": ["AND", ["queries.query0.total", ">", 0]] }, "actions": [...] } ] } ``` **Key Schema Requirements**: - `ignorePreviousResults`: Must be included (typically `false`) - `templates`: Must be included (use `{}` if empty) - `tags`: Must be included but should always be empty `[]` (deprecated field) - `labels`: Use this for actual tagging functionality with key-value pairs - Query `name`: Use `"query0"` for primary query - Query `version`: Include `"v1"` for compatibility - Query `includeDeleted`: Must be explicitly set to `false` ## Available Action Types ### 1. SET_PROPERTY Sets a property value on the alert (commonly used for alert severity levels). **Configuration**: ```json { "type": "SET_PROPERTY", "targetProperty": "alertLevel", "t…

# JupiterOne Rule Update Tool - Complete Guide **Purpose**: Updates existing inline question-based alert rules in JupiterOne. This tool modifies the configuration of an existing rule while preserving its identity and version history. **Important**: Before updating a rule, use the `get-rule-details` tool to retrieve the current configuration. This ensures you have all required fields and can see what needs to be changed. ## Key Requirements for Updates ### 1. Required Fields for Updates When updating a rule, you must provide **ALL** fields, not just the ones you want to change. The update operation replaces the entire rule configuration, so missing fields will result in errors. **Critical Required Fields**: - `id`: The existing rule ID (from `get-rule-details`) - `version`: The current version number (from `get-rule-details`) - `specVersion`: Usually 1 - `ignorePreviousResults`: Must be included - `templates`: Must be included (use `{}` if empty) - `tags`: Must be included but should always be empty `[]` (deprecated) - `labels`: Use this for actual tagging functionality - `resourceGroupId`: Must be included (can be null) - `remediationSteps`: Must be included (can be null) ### 2. Condition Format (Critical) The `condition` parameter must use JupiterOne's specific array format: - **Structure**: `["LOGICAL_OPERATOR", [left_value, operator, right_value]]` - **Example**: `["AND", ["queries.queryName.total", ">", 0]]` - **Supported operators**: `>`, `<`, `>=`, `<=`, `=`, `!=` - **Logical operators**: `"AND"`, `"OR"` ### 3. Operations Structure The `when` clause should only contain: - `type`: Always `"FILTER"` - `condition`: The array format described above - **Do NOT include**: `version`, `specVersion` (these belong at the rule level, not in the when clause) ### 4. Query Naming Convention - Query names in the `queries` array must match the references in conditions - Example: If query name is `"users"`, reference it as `"queries.users.total"` - **IMPORTANT**: Use `"query0"` as the standard query name for compatibility with existing patterns ### 5. Version Management - The `version` field will be automatically incremented by JupiterOne - You must provide the current version number in your update request - Get the current version using `get-rule-details` before updating ### 6. Tags vs Labels (Important) - **DEPRECATED**: The `tags` array field is deprecated and should always be set to an empty array `[]` - **USE INSTEAD**: For tagging functionality, use the `labels` field with key-value pairs - **Format**: `labels: [{"labelName": "key", "labelValue": "value"}]` - **When users ask for tagging**: Always use the `labels` field to meet their needs - **Note**: The `tags` field is still required in the schema for compatibility but should remain empty ## Update Workflow ### Step 1: Get Current Rule Configuration ``` Use get-rule-details with the rule ID to get the current configuration ``` ### Step 2: Modify Required Fields Update only the fields you need to change while preserving all other required fields. ### Step 3: Submit Update Use this tool with the complete configuration including your changes. ## Required Schema Fields for Updates ### Complete Required Parameters for update-inline-question-rule **CRITICAL**: All of these fields must be included for successful rule updates: ```json { "id": "existing-rule-id", "name": "Updated Rule Name", "description": "Updated rule description", "notifyOnFailure": true, "triggerActionsOnNewEntitiesOnly": true, "ignorePreviousResults": false, "pollingInterval": "ONE_DAY", "specVersion": 1, "version": 2, "templates": {}, "outputs": ["alertLevel"], "tags": [], "labels": [ {"labelName": "environment", "labelValue": "production"}, {"labelName": "team", "labelValue": "security"} ], "resourceGroupId": null, "remediationSteps": null, "question": { "queries": [ { "query": "FIND Entity...", "name": "query0", "version":…

# Delete Rule Tool Deletes an alert rule. Works for any rule instance — one built from an inline question or one that references a saved question. **This is a destructive, irreversible action.** Confirm the `ruleId` against `list-rules` or `get-rule-details` and confirm with the user before calling. There is no undo and no way to recover the rule's configuration afterwards. Deleting a rule does **not** dismiss alerts it has already raised — those stay active. If the intent is to stop a rule from firing while keeping its configuration and evaluation history, call `update-inline-question-rule` with `pollingInterval: "DISABLED"` instead of deleting it. ## Parameters - `ruleId` (required): The unique identifier of the rule to delete. ## Example Usage ```json { "ruleId": "12345678-1234-1234-1234-123456789abc" } ``` The response echoes the `ruleId` you passed and the `id` the backend confirmed deleted.

# List Rule Evaluations Tool List the evaluation history for a specific rule. This tool shows when a rule was evaluated and the results of each evaluation. ## Parameters - `ruleId` (required): The ID of the rule to get evaluations for - `beginTimestamp` (optional): Start time for the evaluation period (Unix timestamp) - `endTimestamp` (optional): End time for the evaluation period (Unix timestamp) - `limit` (optional): Maximum number of evaluations to return (1-1000) - `tag` (optional): Filter evaluations by tag ## Example Usage Get recent evaluations for a rule: ```json { "ruleId": "rule-123", "limit": 10 } ```

# Get Rule Evaluation Details Tool Get detailed information about a specific rule evaluation including query results and any generated alerts. ## Parameters - `ruleId` (required): The ID of the rule - `timestamp` (required): The timestamp of the evaluation to retrieve (Unix timestamp) ## Example Usage Get details of a specific rule evaluation: ```json { "ruleId": "rule-123", "timestamp": 1641024000000 } ```

# Get Raw Data Download URL Tool Generate a signed URL for downloading raw data from JupiterOne. This is typically used to download large result sets from rule evaluations. ## Parameters - `rawDataKey` (required): The key identifying the raw data to download ## Example Usage Get download URL for raw data: ```json { "rawDataKey": "data-key-123" } ```

# Get Rule Evaluation Query Results Tool Retrieve the actual query results from a rule evaluation. This tool fetches the entities that matched the rule's query conditions. ## Parameters - `rawDataKey` (required): The key identifying the query results to retrieve ## Example Usage Get query results from a rule evaluation: ```json { "rawDataKey": "results-key-123" } ```

# List Alerts Tool List all currently active alerts in your JupiterOne account. This tool returns a list of active alert instances, including their IDs, names, descriptions, levels, statuses, timestamps, and related rule information. You can optionally specify a limit to restrict the number of alerts returned. If a user is looking for configuration behind an alert, then list out the rules or get the details of the rule associated with an alert. If they are looking for alert data or then use this tool rather than listing rules. ## Parameters - `limit` (optional): Maximum number of alerts to return (between 1 and 1000). ## Example Usage Request the first 5 active alerts: ```json { "limit": 5 } ```

# Get Dashboards Tool List all dashboards available in your JupiterOne account. This tool returns both personal and account-level dashboards with their metadata. ## Parameters None required. ## Example Usage Get all dashboards: ```json {} ```

# Create Dashboard Tool Creates a new dashboard in JupiterOne. This tool is simple and self-descriptive: provide a name and a type to create a dashboard. Unless specified otherwise, default to creating personal dashboards. After creating a dashboard and all its widgets, you will typically want to call `update-dashboard` tool to set a layout favorable for the user, widgets should never be left at their default size. ## Valid Dashboard Types ```typescript export enum DashboardType { USER = 'User', ACCOUNT = 'Account', } ``` After creating a dashboard, you should include the dashboard's url in your response to the user.

# Get Dashboard Details Tool Get detailed information about a specific JupiterOne dashboard including its widgets, layout, and configuration. ## Parameters - `dashboardId` (required): The unique identifier of the dashboard to retrieve ## Example Usage Get details of a specific dashboard: ```json { "dashboardId": "95936c1a-468a-494f-b11d-b134ac9b9577" } ```

# JupiterOne Create Dashboard Widget Tool **Purpose**: Adds a new widget to a specified JupiterOne dashboard. This tool allows you to programmatically create visual widgets (such as pie charts, bar charts, tables, etc.) on any dashboard, using custom queries and configuration. This tool should be used when: - You want to add a new visualization to an existing dashboard - You need to automate dashboard widget creation for reporting or monitoring - You want to programmatically manage dashboard content ## Required Parameters - `dashboardId`: The ID of the dashboard to add the widget to - `input`: The widget configuration object (CreateInsightsWidgetInput), including: - `title`: Widget title - `description`: Widget description (optional) - `type`: Widget type (e.g., 'pie', 'bar', 'table', etc.) - `noResultMessage`: Message to display when there are no results - `config`: Widget configuration, including queries and settings ## Supported Chart Types The following values are supported for the `type` property when creating a widget: ```typescript export enum ChartType { Area = 'area', Bar = 'bar', Graph = 'graph', Line = 'line', Matrix = 'matrix', Number = 'number', Pie = 'pie', Table = 'table', Status = 'status', Markdown = 'markdown', } ``` ## Example Usage ```json { "dashboardId": "95936c1a-468a-494f-b11d-b134ac9b9577", "input": { "title": "Example title", "type": "pie", "noResultMessage": "Message that shows when no results", "config": { "queries": [ { "query": "FIND (aws_db_cluster_snapshot|aws_db_snapshot) as snapshot RETURN snapshot.tag.AccountName as name, sum(snapshot.allocatedStorage) * 0.02 as value", "name": "Query 1" } ], "settings": { "pie": { "customColors": { "0": "#26A69A", "1": "#3F51B5", "2": "#D81B60", "3": "#FF8F00", "4": "#9575CD", "5": "#8BC34A", "6": "#039BE5" }, "upwardTrendIsGood": true } } } } } ``` # Widget Options When creating a dashboard, there are several options for widgets to choose from. This allows you to utilize the most impactful visual representation for your data. Below are the supported dashboard widgets, each with their own requirements and examples. --- # Chart Types and Example Queries > **Note:** > To enable trend functionality for a chart, set `trendDataIsEnabled: true` in the relevant chart type's settings (e.g., `settings.pie.trendDataIsEnabled`). You can also use keys like `trendQueryResultsCount` to control the number of trend data points, and `upwardTrendIsGood` to indicate if an upward trend is positive. ## Number The number chart visualization shows one large stat value. In the trend version of this chart you are able to track the value through a spark line to see if the result is getting larger or smaller over time. ### Query Requirements Expects only a single `value` in the returned query response. ### Example Queries **Trend:** ```j1ql FIND User AS u RETURN count(u) AS value ``` **Non-Trend:** ```j1ql FIND User AS u RETURN count(u) AS value ``` --- ## Pie Chart The pie chart displays values from one or more queries, as they relate to each other, in the form of slices of a pie. The arc length, area and central angle of a slice are all proportional to the slice's value, as it relates to the sum of all values. This type of chart is best used when you want a quick comparison of a small set of values in an aesthetically pleasing form. In the trend version of this chart you are able to track the value change of each slice value as well as the total value through a spark line to see if the data set is getting larger or smaller over time. ### Query Requirements Expects 2 or more pairs of `name` and numeric `value` properties. ### Example Queries **Trend:** ```j1ql FIND DataStore AS ds THAT RELATES TO (Account|Se…

Patch an existing dashboard's layout configuration. This tool is primarily used for modifying the layout of widgets on a dashboard after they have been created. You will always want to call this after creating a dashboard and all its widgets so you can give a favorable layout to the user. Provide **exactly one** of `autoLayout` or `layouts`. ## `autoLayout` — RECOMMENDED for initial layout Hand-packing the grid is error-prone. For the first layout of a dashboard, pass `autoLayout`: an **ordered** array of widget IDs and let the server compute `x`/`y`/`w`/`h` for all five breakpoints. Each element is either: - a bare widget ID string, or - an object `{ "id": "<widgetId>", "size": "small" | "medium" | "large" | "full" }` (size defaults to `medium`). Widgets are placed left-to-right, top-to-bottom on a 12-column grid (single column on small screens). Sizes map to widths of 4 / 6 / 8 / 12 columns. ```json { "dashboardId": "abc-123", "autoLayout": [ { "id": "widget-header", "size": "full" }, { "id": "widget-count-1", "size": "small" }, { "id": "widget-count-2", "size": "small" }, "widget-table" ] } ``` ## `layouts` — manual, for fine control Use `layouts` only when you need precise placement (for example, adjusting one widget after an auto-layout). **All five breakpoints (`xs`, `sm`, `md`, `lg`, `xl`) are required by the API.** Send an empty array `[]` for any breakpoint you are not laying out (the tool defaults missing breakpoints to `[]`, but include them explicitly when you can). **This tool REPLACES the entire layout set — it is not a partial patch.** Any widget you omit from a breakpoint's array loses its placement in that breakpoint. To change one widget without disturbing the others, first call `get-dashboard-details` to read the current `layouts`, merge your change into that full set, and send the merged result back. The layout configuration is organized by screen breakpoint sizes (xs, sm, md, lg, xl) and includes positioning information for each widget. Each layout item contains: - `i`: Widget ID - `x`: X coordinate (horizontal position) - `y`: Y coordinate (vertical position) - `w`: Width in grid units - `h`: Height in grid units - `moved`: Whether the widget has been moved (should always be false) - `static`: Whether the widget position is fixed (should always be false) Example layout configuration: ```json { "xs": [], "sm": [], "md": [ { "w": 5, "h": 2, "x": 0, "y": 0, "i": "widget-id-1", "moved": false, "static": false } ], "lg": [], "xl": [] } ``` Here's an example layout that should be used for inspiration: ```json "layouts": { "xs": [], "sm": [ { "w": 1, "h": 1, "x": 0, "y": 0, "i": "cc1bb92b-736b-4b76-bb2a-4ffb3fb6db04", "moved": false, "static": false }, { "w": 1, "h": 1, "x": 0, "y": 1, "i": "750ea929-fb31-46ef-b1d4-68c53b06e5a3", "moved": false, "static": false }, { "w": 1, "h": 1, "x": 0, "y": 2, "i": "92507e3e-2c99-4089-b75a-ce97ad4743d5", "moved": false, "static": false }, { "w": 2, "h": 2, "x": 0, "y": 3, "i": "f1535f10-a7ba-4c74-8ae6-d5be8c5655ee", "moved": false, "static": false }, { "w": 1, "h": 1, "x": 0, "y": 7, "i": "29df3495-eea3-45a2-b779-788d92c8baa4", "moved": false, "static": false }, { "w": 1, "h": 1, "x": 0, "y": 8, "i": "814000f8-9ffd-4ac3-90f8-26d321e9eba6", "moved": false, "static": false }, { "w": 1, "h": 1, "x": 0, "y": 9, "i": "293fc7fd-eb34-4383-82b8-068b62ffdd61", "moved": false, "static": false }, { "…

# Update Dashboard Widget Tool Updates an existing widget on a dashboard — for example, to fix its query, rename it, or change its chart type. **This replaces the entire widget definition.** The `input` you send is the widget's new full state, so include every field (title, type, and the complete `config.queries`), not just the ones you are changing. To avoid dropping fields, first call `get-dashboard-details` to read the current widget, apply your change to that object, and send the merged result. Parameters: - `dashboardId`: ID of the dashboard the widget belongs to. - `widgetId`: ID of the widget to update. - `input`: the full replacement widget definition, in the same shape as `create-dashboard-widget` (title, description, type, noResultMessage, config with queries and settings). As with creating widgets, test any J1QL with `execute-j1ql-query` before sending it. The response includes `resultCode` and the dashboard `url`.

# Delete Dashboard Widget Tool Deletes a single widget from a dashboard. Use this to remove a widget you created by mistake or that is no longer wanted — it is the recovery path for a bad widget (previously the only option was to add more). **This is a destructive, irreversible action.** Confirm the `widgetId` (from `get-dashboard-details`) before calling, and confirm with the user when the intent is ambiguous. Provide the `dashboardId` and the `widgetId`. After deleting, the widget also disappears from the dashboard's layout; call `update-dashboard` if you want to re-pack the remaining widgets. The response includes `success` and the dashboard `url`.

# Delete Dashboard Tool Deletes an entire dashboard, including all of its widgets. **This is a destructive, irreversible action.** Confirm the `dashboardId` (from `get-dashboards` or `get-dashboard-details`) and confirm with the user before calling — deleting a dashboard removes every widget on it. To remove a single widget instead, use `delete-dashboard-widget`. Provide the `dashboardId`. The response includes `success`.

# Get Integration Definitions Tool Get all available integration definitions in your JupiterOne account. This tool returns a list of integration definitions that can be used to create integration instances. Integration definitions define the types of integrations available (like AWS, Azure, GitHub, etc.) and their configuration requirements. If a user is needing a specific integration instance id for something such as a rule action, you will want to start here and then use the `get-integration-instances` tool. Each integration definition will have a Name and a Title field, you should use this to identify which definition is correct for what the user is looking for. As an example, if the user wants to send a slack notification as a part of a rule action, you would want to pull all of the integration definitions and find any that have Slack in the name and/or title. If there are multiple, then clarify the differences to the user and allow them to guide you on which one is correct. ## Parameters - `cursor` (optional): Pagination cursor to get the next page of results. The response includes a `pageInfo`; when `pageInfo.hasNextPage` is true, call again with `cursor` set to `pageInfo.endCursor`, and stop once it is false. When you need a specific type of integration, page through the full list so you can select from all definitions. - `includeConfig` (optional): Whether to include configuration fields in the response. When true, returns detailed configuration schemas for each integration type. Typically this should be false or omitted entirely. ## Example Usage Get all integration definitions without configuration details: ```json {} ``` Get all integration definitions with configuration fields: ```json { "includeConfig": true } ``` Get the next page of integration definitions using a cursor: ```json { "cursor": "cursor_here" } ```

# Get Integration Instances Tool Get all integration instances in your JupiterOne account. This tool returns a list of configured integration instances, including their configuration, status, and recent job information. Integration instances are the actual configured connections to external services like AWS accounts, GitHub repositories, etc. Unless you have an integration definition id, you typically will not want to query this yet. To get an integration definition id, use the `get-integration-definitions` tool. If you need an integration instance id for another task (such as creating a rule action), ask the user which of the possible integrations they want you to use. ## Parameters - `definitionId` (optional): Filter instances by a specific integration definition ID. Use this to get only instances of a particular integration type. - `limit` (optional): Maximum number of instances to return (between 1 and 1000). - `cursor` (optional): Pagination cursor. The response includes a `pageInfo` object; when `pageInfo.hasNextPage` is true, call this tool again with `cursor` set to `pageInfo.endCursor` to fetch the next page. ## Example Usage Get all integration instances: ```json {} ``` Get the first 10 integration instances: ```json { "limit": 10 } ``` Get all instances of a specific integration type: ```json { "definitionId": "integration-definition-id-here" } ``` Get the first 5 instances of a specific integration type: ```json { "definitionId": "integration-definition-id-here", "limit": 5 } ```

# Get Integration Jobs Tool List integration job execution history. This tool returns information about integration runs including their status, timing, and results. ## Parameters - `integrationDefinitionId` (optional): Filter jobs by definition ID - `integrationInstanceId` (optional): Filter jobs by instance ID - `integrationInstanceIds` (optional): Array of instance IDs to filter jobs - `status` (optional): Filter by job status (PENDING, RUNNING, COMPLETED, FAILED, CANCELLED) - `size` (optional): Maximum number of jobs to return (1-1000) - `cursor` (optional): Pagination cursor. The response includes a `pageInfo` object; when `pageInfo.hasNextPage` is true, call this tool again with `cursor` set to `pageInfo.endCursor` to fetch the next page. ## Example Usage Get all integration jobs: ```json {} ``` Get jobs for a specific integration instance: ```json { "integrationInstanceId": "abc123", "status": "FAILED", "size": 10 } ```

# Get Integration Job Tool Get detailed information about a specific integration job execution. ## Parameters - `integrationJobId` (required): The ID of the job to retrieve - `integrationInstanceId` (required): The ID of the instance the job belongs to ## Example Usage Get details of a specific integration job: ```json { "integrationJobId": "job-123", "integrationInstanceId": "instance-456" } ```

# Get Integration Events Tool Get events and logs from a specific integration job execution. This tool provides detailed execution logs for troubleshooting integration issues. ## Parameters - `jobId` (required): The ID of the job to get events for - `integrationInstanceId` (required): The ID of the instance the job belongs to - `size` (optional): Maximum number of events to return (1-1000) - `cursor` (optional): Pagination cursor for fetching additional events ## Example Usage Get events for a specific job: ```json { "jobId": "job-123", "integrationInstanceId": "instance-456", "size": 50 } ```

# JupiterOne J1QL Query Executor **Purpose**: Executes JupiterOne Query Language (J1QL) queries against your JupiterOne data and returns the results. This tool is used to directly run J1QL queries. ## Recommended Query Development Workflow **CRITICAL**: Follow this workflow for best results when writing J1QL queries: 1. **Use `list-entity-types`** - Discover what entity classes and types are available in the account 2. **Evaluate relevant entity types** - Based on the user's request, identify which entity types you need to query 3. **Run exploratory queries** - Execute simple queries to discover each type's properties and sample values: ``` FIND <entity_type> AS e RETURN e.* LIMIT 5 ``` 4. **Construct final query** - Build your complete query using the discovered types, properties, and values This systematic approach ensures your queries will return meaningful results and use the correct property names and filters. This tool should be used when: - You need to validate the data of a query - You need to get results from a previously generated query - You want to test a query before using it in a rule or widget - You need to analyze data directly using J1QL The tool supports various query parameters including: - Including/excluding deleted entities - Returning row metadata - Returning computed properties - Applying scope filters - Pagination using cursors ### JupiterOne Query Language (J1QL) Quick Reference > **IMPORTANT:** Always validate queries using this tool before creating rules or widgets. Start with discovery queries if unsure about data structure. #### Core Concepts **Entity and Relationship Structure** - **Entities**: Assets in your environment with specific classes and types - **Entity Class**: Always `TitleCase` (e.g., `User`, `Host`, `Application`) - **Entity Type**: Always `snake_case` (e.g., `aws_iam_user`, `github_user`) - **Relationships**: Connections between entities - **Relationship Class**: Always `ALLCAPS` (e.g., `HAS`, `USES`, `PROTECTS`) - **Default Returns**: Queries return the first entity after FIND unless explicitly modified with RETURN - **Unified Entities**: Deduplicated repersentation of assets seen in JupiterOne have a `_type: unified_entity` #### Unified Entities Unified entities are the deduplicated "real-world" repersentation of data seen by JupiterOne. All Unified entities have a `_type = unified_entity`, and this is often the entity the user wants referenced. Unified Entities currently supported: - **UnifiedDevice**: Deduplicated representation of devices in the inventory - **UnifiedIdentity**: Deduplicated representation of identities in the inventory - **UnifiedVulnerability**: Deduplicated representation of vulnerabilities in the inventory Unified entities typically also have additional enrichment making them valuable assets to search off of or reference back to. Unified entities only have relationships to the entities that they deduplicate, and you need to query off of their source components to get more context - for example a list of all devices related to users would look like: ``` FIND UnifiedIdentity AS identity THAT IS << User THAT RELATES TO AS rel (Device|Host) THAT IS >> UnifiedDevice AS device RETURN identity.displayName, rel._class, device.displayName ``` **IMPORTANT**: Whenever answering questions about entities that have a unified entity representation, answer the question in terms of unified entities. #### MANDATORY Query Structure ``` FIND <entity> [WITH <property_filter>] [AS <alias>] [THAT <relationship> [<direction>] <entity> [WITH <property_filter>] [AS <alias>]] [WHERE <condition>] [RETURN <field_selection>] [ORDER BY <field>] [SKIP <number>] [LIMIT <number>] ``` #### ⚠️ CRITICAL SYNTAX RULES ⚠️ ALL QUERIES MUST ADHERE TO THESE RULES 1. **Alias Placement**: Aliases MUST follow the WITH statement when filtering ✅ `FIND Device WITH name~='TEST' AS dev` ❌ `FIND Device AS dev WITH name~='TEST'` 2. **String V…

# Get Query Results **Purpose**: Retrieves the results of a J1QL query that was still running when `execute-j1ql-query` returned. Use this whenever `execute-j1ql-query` responds with `status: "IN_PROGRESS"` and a `resultsUrl`. A query that outlives the tool-call window keeps executing server-side (heavy traversals can take up to ~4 minutes) and its results stay retrievable for about an hour. This tool waits for completion and returns the results in the same format as `execute-j1ql-query`. ## Parameters | Parameter | Required | Description | |-----------|----------|-------------| | `resultsUrl` | Yes | The exact `resultsUrl` returned by `execute-j1ql-query`. Do not construct or modify this URL. | | `waitSeconds` | No | How long to wait for completion before returning the `IN_PROGRESS` handle again (1–45, default 40). | ## Behavior - **Query finished** → returns the standard query envelope (`data`, `cursor`, `hasMore`, `totalCount`, `status: "COMPLETED"`). Continue pagination, if any, through `execute-j1ql-query` with the returned `cursor`. - **Query still running** → returns `status: "IN_PROGRESS"` with the same `resultsUrl`, plus `startedAt`/`elapsedSeconds` when recoverable. Successful queries almost always finish within ~4 minutes of execution; past ~13 minutes (the backend's full retry window) a query will not succeed — abandon the handle and run a narrower query instead. - **Query failed server-side** → returns the execution error. At that point, narrow the query (indexed `WITH` filters, smaller `LIMIT`, fewer traversals) and run it again with `execute-j1ql-query`. ## Tips - **You do not need to babysit a running query.** Do other work between checks — each call here already waits up to 40 seconds, so a handful of calls spread over a few minutes is plenty. Long queries usually finish within ~4 minutes. - Use `waitSeconds: 1` when you only want a quick status check before moving on. - Do **not** re-issue `execute-j1ql-query` just to get these results — that starts from scratch. Only re-issue if the query FAILED (narrowed) or the handle expired. - The `resultsUrl` handle expires roughly an hour after the query started. If it has expired or was lost, re-run the original query with `execute-j1ql-query` (an identical re-run within ~5 minutes of the original re-attaches to the same execution server-side).

# JupiterOne Entity Types Discoverer **Purpose**: Discovers all entity classes and types in your JupiterOne account. This tool helps you find relevant entity types when building queries or exploring your data model. **CRITICAL**: This tool should ALWAYS be run FIRST before writing any J1QL queries. Without knowing what entity classes and types exist in your JupiterOne account, you cannot write valid queries that will return results and are more likely to hallucinate. This is the essential first step for any query-writing task. This tool provides a comprehensive count of all entity classes and types in your account using an efficient GraphQL query. ## Features - Returns all entity classes and types in your account - Shows counts for each class and type - Provides results as key-value pairs for easy lookup - Fast and efficient - no pagination required ## Example Usage ``` list-entity-types ``` ## Response Format Returns an object with two properties: - `classes`: Object mapping class names to their counts (e.g., `{"User": 150, "Device": 200}`) - `types`: Object mapping type names to their counts (e.g., `{"aws_instance": 50, "github_user": 25}`) Example response: ```json { "classes": { "User": 150, "Device": 200, "Finding": 1234, "DataStore": 45 }, "types": { "aws_instance": 50, "aws_s3_bucket": 30, "github_user": 25, "crowdstrike_device": 100 } } ``` ## Use Cases - **REQUIRED FIRST STEP**: Run this before writing any J1QL queries to know what entities exist - Discovering available entity types before writing J1QL queries - Finding integration-specific entities (e.g., all Snyk entities) - Understanding your data model and available entity types - Exploring what data is available from specific integrations ## Why This Is Essential When writing J1QL queries, you need to specify entity classes (like `User`, `Device`, `Finding`) or entity types (like `aws_instance`, `github_user`). Without running this tool first, you're essentially guessing what entities exist in your account. This tool provides the complete list of valid entity classes and types that you can query, ensuring your J1QL queries will actually find and return data.

# Test Connection Tool Test the connection to JupiterOne and verify the caller's access to the target account. On success it also reports who you are and a summary of what you're allowed to do, so you can plan tool usage before making calls. ## Parameters None required. ## Example Usage ```json {} ``` ## Returns - `connected`: whether the account could be reached and authorized. - `account`: account details (id, name, subdomain) when connected. - `user.email`: the identity your token resolves to — surface this to the user if there is any doubt about which sign-in is active. - `permissions.resourceAreas`: per-area `{create, read, update, delete}` summary (e.g. `dashboard`, `rule`, `integration`). A `true` means at least one fine-grained grant exists. **Check this before calling write tools** — e.g. if `dashboard.create` is false and `hasBroadAccess` is also false, tell the user they lack dashboard-create permission instead of attempting it. - `permissions.hasBroadAccess`: true when the caller is a full account admin. When this is true, `resourceAreas` may show `false` for areas the caller can actually use (admins often have no per-area rows) — so attempt the operation rather than refusing on an empty `resourceAreas`. ## Failure A failed test returns an error result whose text explains why and what to do next. When the failure is an authorization rejection and account discovery is available, the text includes the accounts your sign-in CAN access (with connector URLs) — relay these to the user so they can fix the connector's account binding. Do not loop on re-authentication: if the text says the pinned account is inaccessible, re-authenticating will not fix it.