@jupiterone/jupiterone-mcp 0.0.4 → 0.0.7

package/dist/descriptions/create-dashboard-widget.md

@@ -1,325 +0,0 @@
-# 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\n  RETURN\n    snapshot.tag.AccountName as name,\n    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|Service) AS a
-RETURN
-  a.tag.AccountName AS name,
-  count(ds) AS value
-```
-**Non-Trend 1:**
-```j1ql
-FIND DataStore AS ds
-  THAT RELATES TO (Account|Service) AS a
-RETURN
-  a.tag.AccountName AS name,
-  count(ds) AS value
-```
-**Non-Trend 2:**
-```j1ql
-FIND DataStore AS ds
-  THAT RELATES TO (Account|Service) AS a
-RETURN
-  count(ds) AS value
-```
-
----
-
-## Bar Chart
-The bar chart visualization allows you to view categorical data to analyze your queries with a specified x and y axis. You are able to run multiple queries and visualize the bar chart in stacked format. This chart is best suited for categorizing your results. In the trend version of the chart you are able to visualize the value change of each categorical result through a %Change indicator and a reference category bar of the result value from the previous time period selected.
-
-### Query Requirements
-Expects one or more `x` and `y` values.
-
-### Example Queries
-**Trend:**
-```j1ql
-FIND Person AS p
-  THAT IS User AS u
-  THAT opened PR
-  WITH state='OPEN' AS pr
-RETURN
-  p.displayName AS x,
-  count(pr) AS y
-ORDER BY y DESC
-```
-**Non-Trend:**
-```j1ql
-FIND Person AS p
-  THAT IS User AS u
-  THAT opened PR
-  WITH state='OPEN' AS pr
-RETURN
-  p.displayName AS x,
-  count(pr) AS y
-ORDER BY y DESC
-LIMIT 5
-```
-
----
-
-## Line Chart
-The line chart is created by plotting a series of several points and connecting them with a straight line. This is best suited for data that has historical trend data enabled.
-
-### Query Requirements
-Expects `line` and `y` values.
-
-### Example Queries
-**Trend:**
-```j1ql
-FIND Finding
-  WITH createdOn > date.now-7day AS f
-RETURN
-  count(f) AS y,
-  f.numericSeverity AS line
-```
-**Non-Trend:**
-```j1ql
-FIND Finding
-  WITH createdOn > date.now-7day AS f
-RETURN
-  f.createdOn AS x,
-  count(f) AS y,
-  f.numericSeverity AS line
-```
-
----
-
-## Matrix Chart
-The matrix chart is used for analyzing and displaying the relationship between data sets. The matrix diagram shows the relationship between two, three, or four groups of information.
-
-### Query Requirements
-Expects `x` and `y` row and column names. Optional `label` to be shown in each cell. Any additional properties returned will be shown as key: value.
-
-### Example Queries
-**Firewall matrix:**
-```j1ql
-FIND Firewall AS row
-  THAT allows AS rel
-  Network AS col
-RETURN
-  row.displayName AS x,
-  col.displayName AS y,
-  rel.egress AS egress,
-  rel.ingress AS ingress,
-  rel.fromPort as fromPort,
-  rel.toPort as toPort,
-  rel.ipProtocol AS label
-```
-
----
-
-## Table
-The tables chart present data in as close to raw form as possible. Tables are meant to be read, so they are ideal when you have data that cannot easily be presented visually, or when the data requires more specific attention.
-
-### Query Requirements
-Note: This chart is currently limited to displaying 250 rows, and it does not handle pagination. It is recommended to use LIMIT and ORDER BY to sort and limit the results.
-
-### Example Queries
-**Most recent people:**
-```j1ql
-FIND Person AS p
-  RETURN
-    p.name AS Name,
-    p.email AS Email,
-    p.manager AS Manager
-  ORDER BY p._createdOn DESC
-  LIMIT 5
-```
-
----
-
-## Graph Chart
-The graph chart displays a tree graph of query results. This chart is best used to visualize specific relationships between entities.
-
-### Example Queries
-**Most recent people:**
-```j1ql
-FIND Person RETURN TREE
-```
-
----
-
-## Status
-The status chart displays a visual summary of correlating queries. This chart is best used to show positive or negative results based on if relationships are present in query results. This chart is best suited by multiple queries.
-
-### Example Queries
-**Users passing security check:**
-```j1ql
-Find Person as p
-  Return
-    p.email as id,
-    p.name as displayName,
-    p.acceptedSecurityPolicyOn,
-    p.backgroundCheck,
-    p.iconWebLink as iconWebLink
-```
-```j1ql
-Find Person as p that owns Device as d
-  Return
-    p.email as id,
-    d.encrypted
-```
-```j1ql
-Find Person as p that is User as u
-  Return
-    p.email as id,
-    count(u)
-```
-
----
-
-## Area Chart
-The area chart is a graph that combines a line chart and a bar chart to show changes in quantities over time. This chart requires the assets in the query to have relevant dates in their properties. For the best results, these charts can be generated by J1 Questions that have trend collection enabled. (This will soon be available straight from Insights.)
-
-### Query Requirements
-Expects two or more `x` and `y` values.
-
-### Example Queries
-**Top 5 most open PRs by Person:**
-```j1ql
-FIND Person AS p
-  THAT IS User AS u
-  THAT opened PR
-  WITH state='OPEN' AS pr
-RETURN
-  p.displayName AS x,
-  count(pr) AS y
-ORDER BY y DESC
-LIMIT 5
-```
-
----
-
-## Markdown Chart
-The markdown chart/widget allows you to display custom Markdown content directly on your dashboard. This is useful for adding documentation, instructions, or contextual information alongside your visualizations.
-
-### Query Requirements
-- No queries are required for this widget type.
-- The widget's settings must include a `markdown.text` property containing the Markdown content to display.
-
-### Example Configuration
-**Simple Markdown widget:**
-```json
-{
-  "type": "markdown",
-  "config": {
-    "queries": [],
-    "settings": {
-      "markdown": {
-        "text": "# test markdown here\nsome more content"
-      }
-    }
-  }
-}
-```
-
----

package/dist/descriptions/create-dashboard.md

@@ -1,12 +0,0 @@
-# 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',
-}
-```

package/dist/descriptions/create-inline-question-rule.md

@@ -1,374 +0,0 @@
-# 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",
-  "specVersion": 1,
-  "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",
-  "targetValue": "CRITICAL"
-}
-```
-
-**Common Values for alertLevel**: `"LOW"`, `"MEDIUM"`, `"HIGH"`, `"CRITICAL"`, `"INFO"`
-
-### 2. CREATE_ALERT
-Creates a basic alert in JupiterOne.
-
-**Configuration**:
-```json
-{
-  "type": "CREATE_ALERT"
-}
-```
-
-**Note**: This is the most basic action and should almost always be included.
-
-### 3. SEND_EMAIL
-Sends email notifications to specified recipients.
-
-**Configuration**:
-```json
-{
-  "type": "SEND_EMAIL",
-  "recipients": ["user1@company.com", "user2@company.com"],
-  "body": "Affected Items: <br><br>* {{queries.query0.data|mapProperty('displayName')|join('<br>* ')}}"
-}
-```
-
-**Required Information to Ask User**:
-- Email addresses of recipients
-- Custom email body content (if desired)
-
-**Template Variables Available**:
-- `{{alertWebLink}}` - Link to the alert in JupiterOne
-- `{{queries.queryName.data|mapProperty('fieldName')|join('separator')}}` - Format query results
-
-### 4. TAG_ENTITIES
-Adds or removes tags from entities that triggered the rule.
-
-**Configuration**:
-```json
-{
-  "type": "TAG_ENTITIES",
-  "entities": "{{queries.query0.data}}",
-  "tags": [
-    {"name": "existing tag to remove", "value": null},
-    {"name": "new tag", "value": "tag value"}
-  ]
-}
-```
-
-**Required Information to Ask User**:
-- Tag names and values to add
-- Tag names to remove (set value to `null`)
-
-### 5. SEND_SLACK_MESSAGE
-Sends messages to Slack channels (requires Slack integration).
-
-**Configuration**:
-```json
-{
-  "integrationInstanceId": "d97d9127-c532-410a-bf0a-9ea93f66c3d2",
-  "type": "SEND_SLACK_MESSAGE",
-  "channels": ["#security-alerts", "#general"],
-  "body": "*Affected Items:* \n\n- {{queries.query0.data|mapProperty('displayName')|join('\n- ')}}"
-}
-```
-
-**Required Information to Ask User**:
-- Slack channel names (with # prefix)
-- Slack integration instance ID (may need to query available integrations)
-- Custom message content (if desired)
-
-### 6. SEND_TO_S3
-Sends alert data to an S3 bucket (requires AWS S3 integration).
-
-**Configuration**:
-```json
-{
-  "integrationInstanceId": "f89568b4-2a1b-4bd8-8abd-aee21270df75",
-  "type": "SEND_TO_S3",
-  "bucket": "security-alerts-bucket",
-  "region": "us-east-1",
-  "data": {
-    "description": "{{alertWebLink}}\n\n**Affected Items:**\n\n* {{queries.query0.data|mapProperty('displayName')|join('\n* ')}}"
-  }
-}
-```
-
-**Required Information to Ask User**:
-- S3 bucket name
-- AWS region
-- S3 integration instance ID
-- Data structure to send
-
-### 7. CREATE_JIRA_TICKET
-Creates a Jira ticket for the alert (requires Jira integration).
-
-**Configuration**:
-```json
-{
-  "integrationInstanceId": "53a99eaa-18a5-45ef-b748-2de39d642a91",
-  "type": "CREATE_JIRA_TICKET",
-  "entityClass": "Finding",
-  "summary": "Security Alert: Critical Unencrypted Data Found",
-  "issueType": "Bug",
-  "project": "SEC",
-  "updateContentOnChanges": false,
-  "additionalFields": {
-    "description": {
-      "type": "doc",
-      "version": 1,
-      "content": [
-        {
-          "type": "paragraph",
-          "content": [
-            {
-              "type": "text",
-              "text": "{{alertWebLink}}\n\n**Affected Items:**\n\n* {{queries.query0.data|mapProperty('displayName')|join('\n* ')}}"
-            }
-          ]
-        }
-      ]
-    }
-  }
-}
-```
-
-**Required Information to Ask User**:
-- Jira project key
-- Issue type (Bug, Task, Story, etc.)
-- Ticket summary/title
-- Jira integration instance ID
-- Additional fields as needed
-
-**Common Entity Classes**: `"Finding"`, `"Incident"`, `"Issue"`
-
-## Template Variables and Formatting
-
-### Available Variables
-- `{{alertWebLink}}` - Direct link to the alert in JupiterOne
-- `{{queries.queryName.data}}` - Array of entities from the specified query
-- `{{queries.queryName.total}}` - Count of entities from the query
-
-### Data Formatting
-- `|mapProperty('fieldName')` - Extract specific field from each entity
-- `|join('separator')` - Join array elements with specified separator
-- Example: `{{queries.users.data|mapProperty('displayName')|join(', ')}}` - Creates comma-separated list of user names
-
-### Common Formatting Patterns
-- **HTML list**: `{{queries.query0.data|mapProperty('displayName')|join('<br>* ')}}`
-- **Markdown list**: `{{queries.query0.data|mapProperty('displayName')|join('\n- ')}}`
-- **Simple list**: `{{queries.query0.data|mapProperty('displayName')|join('\n* ')}}`
-
-## Integration Dependencies
-
-For actions requiring integrations, you may need to:
-1. Query available integration instances using `get-integration-instances`
-2. Ask the user which integration to use
-3. Use the integration's `id` as the `integrationInstanceId`
-
-**Actions requiring integrations**:
-- `SEND_SLACK_MESSAGE` (Slack integration)
-- `SEND_TO_S3` (AWS S3 integration)
-- `CREATE_JIRA_TICKET` (Jira integration)
-
-## Working Example Template
-
-### Complete Working Rule Structure
-Based on confirmed working examples, use this template:
-
-```json
-{
-  "name": "Your Rule Name",
-  "description": "Your rule description",
-  "notifyOnFailure": true,
-  "triggerActionsOnNewEntitiesOnly": true,
-  "ignorePreviousResults": false,
-  "pollingInterval": "ONE_DAY",
-  "specVersion": 1,
-  "templates": {},
-  "outputs": ["alertLevel"],
-  "tags": [],
-  "labels": [
-    {"labelName": "severity", "labelValue": "high"},
-    {"labelName": "category", "labelValue": "security"}
-  ],
-  "queries": [
-    {
-      "query": "FIND Entity WITH condition",
-      "name": "query0",
-      "version": "v1",
-      "includeDeleted": false
-    }
-  ],
-  "operations": [
-    {
-      "when": {
-        "type": "FILTER",
-        "condition": ["AND", ["queries.query0.total", ">", 0]]
-      },
-      "actions": [
-        {
-          "type": "SET_PROPERTY",
-          "targetProperty": "alertLevel",
-          "targetValue": "CRITICAL"
-        },
-        {
-          "type": "CREATE_ALERT"
-        },
-        {
-          "type": "SEND_EMAIL",
-          "recipients": ["user@company.com"],
-          "body": "Affected Items: <br><br>* {{queries.query0.data|mapProperty('displayName')|join('<br>* ')}}"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## Common Patterns
-
-### New Entity Monitoring
-```json
-{
-  "condition": ["AND", ["queries.query0.total", ">", 0]],
-  "triggerActionsOnNewEntitiesOnly": true
-}
-```
-
-### Threshold-based Alerts
-```json
-{
-  "condition": ["AND", ["queries.query0.total", ">=", 5]]
-}
-```
-
-### Multi-action Rule Example
-```json
-"actions": [
-  {"type": "SET_PROPERTY", "targetProperty": "alertLevel", "targetValue": "HIGH"},
-  {"type": "CREATE_ALERT"},
-  {"type": "SEND_EMAIL", "recipients": ["security@company.com"], "body": "Security issue detected: {{alertWebLink}}"},
-  {"type": "TAG_ENTITIES", "entities": "{{queries.query0.data}}", "tags": [{"name": "needs-review", "value": "true"}]}
-]
-```
-
-## Debugging Tips
-- If you get "Invalid conjunction operator" errors, check the condition array format
-- If you get "additional properties" errors, remove extra fields from the `when` clause
-- If you get missing property errors, ensure all required schema fields are included
-- **Always include**: `ignorePreviousResults`, `templates`, `tags`, query `version` and `includeDeleted`
-- Always reference existing rules with `get-rule-details` to see working examples
-- Test with simple conditions first, then add complexity
-- Use `"query0"` as the standard query name for compatibility
-
-## Best Practices
-- Use descriptive query names that match their purpose (but prefer `"query0"` for main query)
-- Include relevant entity fields in `outputs` for alert context
-- Set appropriate polling intervals (default to `"ONE_DAY"` unless specified)
-- Use the `labels` field for rule organization and tagging (not the deprecated `tags` field)
-- Use `notifyOnFailure: true` to catch rule execution issues
-- Always include `CREATE_ALERT` action as a baseline
-- Always include all required schema fields from the working template
-- Ask users for specific details when configuring notification actions (emails, channels, etc.)
-- When users request tagging functionality, use the `labels` field with key-value pairs
-
-This format ensures reliable rule creation and helps avoid common pitfalls encountered during rule development.