All servers / Security / JupiterOne MCP server
JupiterOne MCP server
Model Context Protocol server for JupiterOne account rules and rule details
Tested by ConnectATDScore 81 out of 100. Tested 2026-11-19 on package version 2.9.5. Package: @jupiterone/jupiterone-mcp
Score breakdown
| Runs | 18 / 20 | |
|---|---|---|
| Tool descriptions | 19 / 20 | |
| Package safety | 16 / 20 | |
| Maintenance | 20 / 20 | |
| Adoption | 8 / 20 |
What we saw
- Starts and answers the MCP handshake: yes (4.7 seconds including download)
- Tools offered: 54
- Last published: 2026-11-18
- Weekly downloads (npm): 829
- License: MIT · Direct dependencies: 7
Want this server set up for your team?
ConnectATD builds AI automation and wires up MCP servers like this one. Tell us what you are trying to do.
Talk to ConnectATDTools and how they are described
Agents choose tools from these descriptions. Under each name you can see how many of its parameters are explained.
list-rules2 of 4 parameters describedList the account's alert rules, a page at a time, with each rule's polling interval, last evaluation times and latest alert. Rules are the configuration behind alerts; for the alerts themselves call `get-active-alerts`. Siblings: `get-rule-details` reads one rule in full, `list-rule-evaluations` lists a rule's runs. Vocabulary: rules, monitors, alert configuration. ## Paging Page with `cursor` set to `pageInfo.endCursor` while `pageInfo.hasNextPage` is true. ## Compliance rules `rules[].managedBy` is `'ccm'` for a rule named `CONTROL-TEST:<test name>`, otherwise `null`. JupiterOne Compliance (CCM) runs each control test as a rule, but this listing leaves CCM's rules out, so a page with no `'ccm'` row does not mean the account has no control tests. A control test's rule id is the `referencedRuleId` from `get-control`; `update-inline-question-rule` and `delete-rule` refuse such a rule. ## Why a rule fired `list-rules` → `list-rule-evaluations` (each run's `timestamp` and `rawDataDescriptors[].rawDataKey`) → `get-rule-evaluation-details` with the timestamp for the run's conditions and actions, or `get-rule-evaluation-query-results` with the `rawDataKey` for the entities it matched.
get-rule-details2 of 3 parameters describedRead one alert rule in full by its id: queries, condition, actions, schedule, labels, tags, version and remediation steps. Call it before `update-inline-question-rule`, which needs every field sent back. Siblings: `list-rules` finds the id, `list-rule-evaluations` lists the rule's runs. Vocabulary: rule configuration, the query behind an alert, version. ## Compliance rules `managedBy` is `'ccm'` for a rule named `CONTROL-TEST:<test name>`, otherwise `null`. JupiterOne Compliance (CCM) runs each control test as a rule, hidden from this tool and from `list-rules`, so a control test's `referencedRuleId` from `get-control` comes back as not found here. Read that rule's runs with `list-rule-evaluations`, and the control and its tests with `get-control`. A CCM rule is changed through its control, never with `update-inline-question-rule` or `delete-rule`, which refuse it.
preview-rule-actions7 of 10 parameters describedShow what a rule's actions would send, without sending anything: renders each action's templates (Slack message, Jira ticket, email, webhook body, tags) against a sample of the rule's current query results, and checks them. Pass `ruleId` for a saved rule, or `question`, `operations`, `templates`, `name` and `description` in the `create-inline-question-rule` shape for a draft. Call it before saving a rule that notifies anyone. Vocabulary: dry run, test rule, what would this alert send, render template, action impact. ## What runs Each query runs once; the first 10 rows are kept and `total` counts them all. `fixtures: { <query name>: [rows] }` renders against those rows instead and does not run that query: use it to reach a branch the data does not. Nothing is created, posted, filed or tagged, and the rule is not saved. Conditions (`when`) are not evaluated: every action renders as if its condition held, so compare each condition with the totals before saying an action will fire. ## Reading the result - `queries[]`: `status` `ok` or `empty`, `sampledRows` of `total`; `estimate: true` when `total` is the query engine's estimate, not a count. Lists such as `{{queries.query0.data|mapProperty('displayName')|join(', ')}}` show only the sampled rows; a run holds every row. `notes` says so. - `actions[]`, in rule order, each with its `path` (`operations[0].actions[2]`) and `status`: - `rendered`: `rendered` is the action as sent when its condition holds; `messages` are template errors; Slack actions carry `envelope`, the whole post (name, description, severity, timestamp, body as truncated). - `render_failed`: `error` says why. - `loop`: a `FOR_EACH_ITEM`; `iterations` counts its items when `items` is `{{queries.<name>.data}}`. Its nested actions follow, rendered for the first sampled row (`loopRows` up to 10 for more), each with `row` and `itemBound`. - `not_run` (loop with no items), `skipped` (`CREATE_ALERT` in a loop), `not_previewable` (`JUPITERONE_QUERY`, a loop in a loop). - Fix before saving: `warnings[]` (`{ code, field, message }`: Slack body over the 1,500-character cap or truncated, missing description, malformed recipient, unknown transform, a named template mapped inside a loop), `unresolvedPaths` (fields that rendered `undefined`) and `undefinedReads[]` (reads that found nothing, with the expression, including ones used as tests, which print nothing). - `{{alertWebLink}}` renders a sample link and `param.*` `[REDACTED PARAMETER]`. With `triggerActionsOnNewEntitiesOnly`, a run acts only on entities the last run did not see; the preview uses every match. ## Refusals `query_failed` (a query failed or was still running; repeating the call re-attaches to a running one), `render_failed` (no action rendered), `invalid_query` (a draft query does not parse), `not_found`, `read_failed` (the saved rule could not be read in time; call again), `no_queries` (pass the queries as a draft), `no_actions`, `invalid_input` (neither or both of `ruleId` and a draft, a draft without both `question` and `operations`, or a fixture naming no query). Needs permission to create or update rules. Full reference: get-reference topic rule-templates
evaluate-rule2 of 3 parameters describedRun an alert rule now rather than at its next polling interval. The response carries only the evaluation's `id`, not its results: read the outcome with `list-rule-evaluations` and `get-rule-evaluation-details`. Vocabulary: run the rule now, trigger an evaluation, re-check.
create-inline-question-rule6 of 15 parameters describedCreate an alert rule from an inline J1QL question: the query runs on a schedule and, when its condition holds, the actions fire (alert, email, Slack, Jira ticket, tag, webhook, S3). Test the query with `execute-j1ql-query` first; the rule stores it as written. Siblings: `update-inline-question-rule` replaces an existing rule, `get-rule-details` reads one, `list-rules` finds them, `evaluate-rule` runs one now, `preview-rule-actions` renders what its actions would send without saving. Vocabulary: rule, alert, monitor, notify, schedule, polling interval, condition, actions, labels. ## Payload - `question.queries[]`: each entry is `{name, query, version: "v1", includeDeleted: false}`. Name the primary query `query0`; the condition references it as `queries.query0.total`. - `specVersion`: `1`. - `operations[].when`: `{type: "FILTER", condition}`; condition `["AND", ["queries.query0.total", ">", 0]]`; `AND` or `OR`, operators `>`, `<`, `>=`, `<=`, `=`, `!=`. - `outputs`: `["alertLevel"]`. `templates`: `{}`. - `pollingInterval`: `ONE_DAY` unless the user asks for another. - `triggerActionsOnNewEntitiesOnly: true` for "new user" or "new resource" rules. `notifyOnFailure: true`. - Organise rules with `labels` (`{labelName, labelValue}`) and omit `tags`, a legacy string array the API still accepts. ## Actions Types: `SET_PROPERTY`, `CREATE_ALERT`, `SEND_EMAIL`, `TAG_ENTITIES`, `SEND_SLACK_MESSAGE`, `SEND_TO_S3`, `CREATE_JIRA_TICKET`, `WEBHOOK` and `FOR_EACH_ITEM`, which runs nested actions once per entity. Always include `CREATE_ALERT`. `SET_PROPERTY` on `alertLevel` takes `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` or `INFO`. Slack, S3 and Jira actions need an `integrationInstanceId`: find the definition with `get-integration-definitions`, list instances with `get-integration-instances`, and ask the user which. Ask for recipients, channels, project and wording before writing an action that notifies someone, and show the user what it will send with `preview-rule-actions` before creating the rule. ## Critical assets Scope a rule about critical assets by the account's asset criticality levels (`j1.criticality`, `j1.normalizedCriticality`; `get-graph-context` lists them), not by tags. A rename or reorder of the levels changes what the rule matches. ## Refusals and response A `name` starting `CONTROL-TEST:` is refused with `lintCode: 'ccm-managed-rule'` (the prefix marks compliance control tests). A query that fails to parse returns the parser's suggestion and creates nothing. The response carries `rule.url`; give it to the user. Full reference: get-reference topic rule-authoring
update-inline-question-rule8 of 19 parameters describedReplace an existing inline-question rule's whole definition: name, query, condition, actions, schedule. Read it with `get-rule-details` first, change what you need and send every field back; an omitted field is an error, not "unchanged". Test a changed query with `execute-j1ql-query` first; the rule stores it as written. To stop a rule, set `pollingInterval: "DISABLED"` instead of deleting it. Siblings: `create-inline-question-rule` makes a new rule, `delete-rule` removes one. Vocabulary: edit rule, change recipients, disable, re-enable, version. ## Full replacement - `id` and the current `version` from `get-rule-details`; JupiterOne increments the version. - `specVersion` as read, normally `1`. - `resourceGroupId` and `remediationSteps` may be `null` but must be present. - `tags` is required here: pass back what `get-rule-details` returned, `[]` when none, and keep organisation in `labels`. - `question.queries` and `operations` take the create shape; `when` is `{type: "FILTER", condition: ["AND", ["queries.query0.total", ">", 0]]}`. ## Compliance rules JupiterOne Compliance (CCM) runs each control test as a rule named `CONTROL-TEST:<test name>`, hidden from `list-rules` and `get-rule-details`. The tool asks the graph whether a control test references the id and refuses with `lintCode: 'ccm-managed-rule'`; a `name` with the prefix is refused too. The change belongs on the control, which `get-control` reads. The response carries `ownershipCheck`: `'graph'` when the check ran and found no control test, `'skipped'` when it could not run and the update went ahead. ## Before saving When the update changes an action, render it with `preview-rule-actions` (pass the new `question`, `operations` and `templates`) and show the user what it will send; nothing is saved or sent by the preview. ## Response `rule.url`; give it to the user. Full reference: get-reference topic rule-authoring
delete-rule3 of 3 parameters describedDelete an alert rule permanently: one built from an inline question or one that references a saved question. There is no undo and the configuration cannot be recovered, so confirm the `ruleId` against `list-rules` or `get-rule-details` and confirm with the user before calling. Alerts the rule already raised stay active. To stop a rule and keep its configuration and evaluation history, call `update-inline-question-rule` with `pollingInterval: "DISABLED"` instead. Vocabulary: delete, remove, retire a rule. ## Compliance rules JupiterOne Compliance (CCM) runs each control test as a rule named `CONTROL-TEST:<test name>`, owned by its control and hidden from `list-rules` and `get-rule-details`. Before deleting, the tool asks the graph whether a control test references the id and refuses if one does (`lintCode: 'ccm-managed-rule'`); `update-inline-question-rule` refuses to disable such a rule too. The change belongs on the control, which `get-control` reads. If the check cannot answer — the query failed, or `ruleId` is not a UUID — the delete is refused with `lintCode: 'ccm-ownership-unverified'` rather than risk breaking a control test; nothing was deleted, so retry or correct the id. ## Response `ruleId` as passed, `id` the backend confirmed deleted, and `ccmOwnership`: `'clear'` on a delete, `'managed'` or `'unverified'` on a refusal.
list-rule-evaluations2 of 7 parameters describedList a rule's evaluation runs, each with its `timestamp`, `outputs`, `tag` and `rawDataDescriptors[].rawDataKey`. `beginTimestamp` and `endTimestamp` are epoch milliseconds; `tag` filters the runs. Chain: `list-rules` → `list-rule-evaluations` → `get-rule-evaluation-details` with a run's `timestamp` for its conditions and actions, or `get-rule-evaluation-query-results` with its `rawDataKey` for the entities it matched. Vocabulary: evaluation history, when did the rule run, why did it fire.
get-rule-evaluation-details2 of 4 parameters describedRead one evaluation run of a rule: each query's status and duration, the condition verdict, and each action's status, logs and `externalOutputs` (what it produced outside JupiterOne: a Slack permalink in `webLink`, an email's recipients, a ticket). `timestamp` comes from `list-rule-evaluations`. For the entities the run matched, call `get-rule-evaluation-query-results` with that run's `rawDataKey` instead. Vocabulary: why did the rule fire, did the action run, evaluation log.
get-rule-evaluation-query-results4 of 5 parameters describedReturn the entities a rule evaluation matched, from the `rawDataKey` in a run's `rawDataDescriptors` (`list-rule-evaluations`), or a signed link to download the whole set. For a compliance control test's evidence, the key is the `latestEvaluation.rawDataKey` that `get-control` returns for that test: the assets the test scored on its latest run. Sibling: `get-rule-evaluation-details` for the run's conditions and actions. Vocabulary: matched entities, evidence, affected assets, download, export, raw results. ## Rows Rows are full entities, so a few dozen can be large; `limit` (1–250) cuts them, and a cut result carries `truncated: true` and `total`, the row count before the cut. A `table` result (a query with RETURN columns) carries each row's entity under `_meta.byAlias.<alias>.entity` (`_id`, `_key`, `_scope`, `_type`), which is what `create-exemptions` takes. ## Download `format: "downloadUrl"` returns `{ rawDataKey, downloadUrl }` instead of rows: a signed URL for the whole result set, to hand to the user for a large set. `limit` does not apply.
get-active-alerts2 of 3 parameters describedList the account's active alerts, each with its level, status, timestamps, the matched record count and the rule that raised it (`ruleId`, name, labels). Alerts are what rules produced; for the configuration behind one, call `get-rule-details` with its `ruleId`, or `list-rules`. `limit` caps the rows returned and `total` is the full active count. Vocabulary: alerts, open alerts, firing, severity, alert level.
get-dashboards2 of 2 parameters describedList every dashboard in the account, personal and account-level, with `id`, `name`, `category` and `isJ1ManagedBoard`. Use it to find a `dashboardId`; `get-dashboard-details` reads one board. No parameters.
create-dashboard2 of 4 parameters describedCreate an empty dashboard, the first step of a build: `create-dashboard` → `create-dashboard-widget` once per widget → `update-dashboard` with `autoLayout`; a board left at default sizes is not finished. Default to a personal `User` dashboard unless asked otherwise. An account-level API token (`test-connection` reports `credential.type: "account_token"`) has no user, so it can only create `Account` dashboards; a `User` request is refused. Siblings: `get-dashboards` lists existing boards. Vocabulary: dashboard, board, insights. ## Response `id` is the `dashboardId` every later call takes; `url` opens the board, give it to the user.
get-dashboard-details2 of 3 parameters describedRead one dashboard in full: its widgets with their queries and settings, and its `layouts` for all five breakpoints. Read it before `update-dashboard-widget` or a `layouts` merge, since both replace what they touch, and to confirm what `create-dashboard-widget` saved, since its response does not echo everything (`drilldownQuery`). `get-dashboards` finds the `dashboardId`.
create-dashboard-widget4 of 4 parameters describedAdd one widget to an existing dashboard: J1QL queries drawn as a chart. The render contract is enforced: a query whose RETURN aliases are not the ones the chart type reads is rejected before anything is written, with a corrected query where one can be derived. Run the query through `execute-j1ql-query` first; an empty result still creates a widget, which renders blank. Siblings: `update-dashboard-widget` replaces a widget, `update-dashboard` arranges them, `delete-dashboard-widget` removes one. Vocabulary: widget, chart, pie, bar, line, number, table, matrix, graph, status, markdown. ## Columns by chart type - `number` → **Enforced: required `value`.** Exactly one column, per query; percentage mode is the one legitimately multi-query number widget. - `pie` → **Enforced: required `value`, and `name` too on a single-query pie.** The renderer groups slices by `name`: one query without it draws one slice labelled `undefined` summing every row. A multi-query pie labels each slice by its query name, so `name` is optional there. - `bar` → **Enforced: required `x`, `y`.** Stacking is one query per series on a shared `x` with `settings.bar.view: 'stacked'`, never several `y` columns. - `line` → **Enforced: required `y`.** `x` (position) and `line` (series split) are recommended. - `matrix` → **Enforced: required `x`, `y`.** `label` is optional and shown in each cell. - `table` → any aliases; add `ORDER BY` and `LIMIT` (250-row cap, no paging). - `graph` → **Enforced: the query must `RETURN TREE`.** Columns give it nothing to draw. - `status` → **Enforced: required `id`, on every query.** The first query is the roster and supplies the display fields (`displayName`, `iconWebLink`); each later query is one pass/fail check, and `id` is what correlates them. - `markdown` → `config.queries: []`; the body goes in `settings.markdown.text`. - `area` → accepted by the schema, refused by the tool: it renders nothing. Use `bar` or `line`. ## Settings and queries Always set `noResultMessage`; it is what lets a reader tell "nothing matched" from "broken". Settings nest under the chart type (`settings.bar.decimalLimit`); a key the service does not know is dropped silently on save, the write still succeeds, and `droppedSettingsKeys` names what was discarded. Each query may carry a `drilldownQuery`, validated like the widget query. A proportion is a percentage number widget: a numerator query and a query counting the whole population, each returning `count(x) AS value`, with `settings.number.showAsPercentage: true`, `numeratorQueryName` (one comma-joined string; a name matching no query is rejected before writing) and `includeNumeratorInTotal: false`. Left out, JupiterOne divides by every query, numerator included, so the write is refused until it is set; `true` is for queries that split the population (`Patched` + `Unpatched`). `renderPreflight.percentage` reports the figure drawn. Thresholds, labels and trend keys: see `widget-settings`. ## Response `renderPreflight` is measured after the write and never blocks it. The widget `id` is what `update-dashboard` lays out; `dashboardUrl` opens the board, give it to the user. An empty widget backed by a correct query is a finding; never broaden a filter to fill it. Build order: `create-dashboard` → `create-dashboard-widget` per widget → `update-dashboard` with `autoLayout`. Full reference: get-reference topic widget-types or widget-settings
update-dashboard5 of 5 parameters describedArrange the widgets on a dashboard: which are wide, their reading order, their grid positions. Call it after `create-dashboard` and the widgets; a board left at default sizes is not finished. Send exactly one of `autoLayout` (ordered widget ids with sizes; the server computes every breakpoint) or `layouts` (a hand-placed grid). Siblings: `update-dashboard-widget` changes a widget's content, not its place. Vocabulary: layout, grid, breakpoint, resize, arrange, columns, full width. ## autoLayout The grid has 12 columns; `small`, `medium`, `large` and `full` are 4, 6, 8 and 12 columns wide, default `medium`. Small screens render it as a single column. ```json { "dashboardId": "abc-123", "autoLayout": [{ "id": "w-1", "size": "full" }, { "id": "w-2", "size": "small" }, "w-3"] } ``` ## layouts `layouts` replaces the whole layout set; it is not a patch. All five breakpoints (`xs`, `sm`, `md`, `lg`, `xl`) are required: a widget omitted from a breakpoint's array loses its place there, and an omitted breakpoint becomes `[]`, which leaves that width unarranged. To change one widget, read the current `layouts` with `get-dashboard-details`, merge the change into that full set and send everything back. Each item is `{ i, x, y, w, h }`: `i` is the widget id, `x` and `y` the grid position, `w` and `h` the size in grid units. ## Response Widgets left out of the layout are removed from the grid and named in `omittedWidgets`; cells that overlap are reported in `layoutOverlaps`; `note` names any breakpoint left unarranged. Full reference: get-reference topic dashboard-layout
update-dashboard-widget5 of 5 parameters describedReplace an existing widget's whole definition: its query, title, chart type or settings. The `input` is the widget's new full state, so read the current widget with `get-dashboard-details`, apply the change to that object and send everything back; an omitted field is dropped, not kept. Siblings: `create-dashboard-widget` adds a widget, `update-dashboard` moves one, `delete-dashboard-widget` removes one. Vocabulary: edit widget, fix query, rename, chart type. ## Render contract The same gate as `create-dashboard-widget`: a query whose RETURN aliases are not the ones the chart type reads is rejected before anything is written, with a corrected query where one can be derived. Run a changed query through `execute-j1ql-query` first; an empty result still updates the widget, which renders blank. ## Response `resultCode`, `widgetId`, `dashboardUrl` and `renderPreflight`, measured after the write. The update returns no widget to compare against, so there is no `droppedSettingsKeys`; read back with `get-dashboard-details` to confirm the settings stored. Full reference: get-reference topic widget-types or widget-settings
delete-dashboard-widget4 of 4 parameters describedDelete one widget from a dashboard: the recovery path for a widget created by mistake or no longer wanted. This is destructive and irreversible: confirm the `widgetId` with `get-dashboard-details`, and confirm with the user when the intent is ambiguous. To delete the whole board, use `delete-dashboard`. Vocabulary: remove widget, delete chart. ## Response `success`, `widgetId` and `dashboardUrl`. The widget also leaves the dashboard's layout; call `update-dashboard` with `autoLayout` to re-pack the remaining widgets.
delete-dashboard3 of 3 parameters describedDelete a dashboard and every widget on it. This is destructive and irreversible: confirm the `dashboardId` with `get-dashboards` or `get-dashboard-details`, and confirm with the user before calling. To remove one widget instead, use `delete-dashboard-widget`. Vocabulary: delete dashboard, remove board. The response is `success` with the `dashboardId` deleted.
get-integration-definitions4 of 4 parameters describedList the integration definitions available to the account: the kinds of integration that can be configured (AWS, Azure, GitHub, Slack, Jira) and, with `includeConfig`, their configuration fields. Start here when another task needs an integration instance id, such as a Slack, Jira or S3 rule action: find the definitions whose `name` or `title` match the product, then list that definition's instances with `get-integration-instances`. When several definitions could fit, say how they differ and let the user choose. Vocabulary: integration, connector, definition, provider, Slack, Jira, AWS. ## Paging When `pageInfo.hasNextPage` is true, call again with `cursor` set to `pageInfo.endCursor`, and page through the whole list before choosing a definition. `includeConfig` is usually left out; the schemas are large.
get-integration-instances5 of 5 parameters describedList the integration instances configured in the account: the actual connections to external services (an AWS account, a GitHub organization, a Slack workspace), with their configuration, status and recent job information. Filter by `definitionId` from `get-integration-definitions`; without one the list spans every integration type. When another task needs an instance id, such as a rule action, ask the user which of the matching instances to use rather than choosing one. Vocabulary: integration instance, connection, configured integration, sync status. ## Paging When `pageInfo.hasNextPage` is true, call again with `cursor` set to `pageInfo.endCursor`.
get-integration-jobs9 of 9 parameters describedList integration job runs with their status, timing and results, for one instance, several, a definition or a status, or read one run by its id. Use it to see whether an integration has synced lately or is failing; `get-integration-events` reads a run's logs. Vocabulary: integration job, sync, run history, failed sync, job status. ## One job `integrationJobId` with `integrationInstanceId` (both from a row of this tool) returns that run alone as a one-row list; the other filters are ignored. Without the instance id the call is an `invalid_input:` error and nothing is read. ## Paging When `pageInfo.hasNextPage` is true, call again with `cursor` set to `pageInfo.endCursor`.
get-integration-events6 of 6 parameters describedReturn the events and logs of one integration job run, for troubleshooting a failed or partial sync: what each step did, what it skipped and the errors it raised. Take the job id and its instance id from `get-integration-jobs`. When `pageInfo.hasNextPage` is true, call again with `cursor` set to `pageInfo.endCursor`. Vocabulary: integration logs, job events, sync errors, troubleshooting.
execute-j1ql-query8 of 8 parameters describedRun a J1QL query against the account's asset graph and return its rows. Use it for any question about real inventory, findings, identities or relationships, and to prove a query before it goes into a widget or rule. Discover, then verify: `get-graph-context`, sample a type with `FIND <type> AS e RETURN e.* LIMIT 5`, then run the finished query and confirm it returns rows. Relationship direction filters nothing; filter on the edge's own properties (`rel.ingress = true`). `get-query-results` collects a query still running. J1QL reads FIND, WITH, THAT, RETURN, count, LIMIT and cursor. ## Syntax rules - The alias follows the WITH filter: `FIND Device WITH name ~= 'x' AS dev`. - String literals use single quotes. Comparison is case-sensitive, `~=` included; `= /x/i` is the only case-insensitive match, and its regex takes no `|` or anchors. - WITH filters an entity's own properties (indexed); WHERE is for edge properties and cross-entity comparisons, and needs aliases. - Direction arrows follow the verb: `FIND User THAT HAS >> Device`. - `count` and other keywords cannot be aliases; write `AS total`. - `LIMIT` is at most 250; every query carries an aggregate or a `LIMIT`. Page with `cursor`, never `SKIP`. - SQL habits do not parse: `IN (...)` is `= ('a' OR 'b')` (`!=` excludes them all), `LIKE '%x%'` is `~= 'x'` (case-sensitive), and `DISTINCT`, `GROUP BY` and `JOIN` do not exist; non-aggregated RETURN columns are the grouping keys. `*` is the only wildcard target; `ANY`, `ANYTHING` and `entity` parse and match nothing. `count(rel)` counts edges, `count(tar)` distinct targets; say which one you report. ## Result `type` is `list` (entities), `table` (named RETURN columns) or `tree` (`RETURN TREE`); `data` is an array of rows, or `{ vertices, edges }` for a tree. A non-empty `cursor` (`hasMore: true`) means another page: repeat the call with the identical query and the cursor; a page can hold zero rows while a cursor is present, so stop only on `hasMore: false`. `url` opens the result in the app; give it to the user. An `emptyResultDiagnosis` with a `correctedQuery` explains an empty result, such as a literal stored under another casing; run it before reporting a zero. ## Still running The call waits 10 seconds. `status: IN_PROGRESS` with a `resultsUrl` is not a failure: the query keeps running server-side. Keep working and collect it with `get-query-results`; do not re-issue it. An identical re-run within 5 minutes re-attaches to the job; results stay for about an hour. ## Errors Queries are parsed locally before they are sent; a syntax error returns at once with a suggestion, so fix and retry. A timeout or an aborted request is the server's 55-second deadline: move simple filters from WHERE into indexed WITH, lower the LIMIT, traverse fewer hops. ## Unified entities `UnifiedDevice`, `UnifiedIdentity` and `UnifiedVulnerability` are the deduplicated devices, identities and vulnerabilities and usually what the user means, so answer in unified terms. They relate only to their source entities; traverse through those for context. ## Critical assets An asset's business criticality is `j1.criticality` (its level's value) and `j1.normalizedCriticality` (its rank, 0 most critical), set by the account's asset criticality levels; filter on these, not tags. A query that reads them returns the levels as `assetCriticality`. Full reference: get-reference topic j1ql-language or j1ql-discovery
get-query-results3 of 3 parameters describedCollect the result of a J1QL query that was still running when `execute-j1ql-query` returned `status: IN_PROGRESS` with a `resultsUrl`. A long-running query keeps executing server-side; this tool polls its handle, waits for completion and returns the same envelope `execute-j1ql-query` does. It redeems a handle, so it needs no account. A new or changed query goes through `execute-j1ql-query`. ## Outcomes - Finished: the standard query envelope. Continue any pagination through `execute-j1ql-query` with the `cursor`. - Still running: `status: IN_PROGRESS` with the same `resultsUrl`. Successful queries almost always finish within about 4 minutes; past about 13 minutes (the backend's full retry window) the query will not succeed, so abandon the handle and run a narrower query instead. - Failed server-side: the execution error. Narrow the query (indexed `WITH` filters, a smaller `LIMIT`, fewer traversals) and run it again with `execute-j1ql-query`. ## Handle lifetime The handle expires about an hour after the query started. If it expired or was lost, re-run the original query with `execute-j1ql-query`; an identical re-run within 5 minutes re-attaches to the same execution. Do not re-issue a query that is still running just to collect it.
get-graph-context2 of 2 parameters describedStart here before writing J1QL: the account's graph context. Returns the entity classes and types the account holds, each with a count (`classes`, `types`), and its asset criticality levels with the filters that select each (`assetCriticality`). Call it first so a query names a class or type that exists, and filters critical assets by the account's own levels. Classes are TitleCase (`User`, `Finding`), types snake_case (`aws_instance`). `execute-j1ql-query` runs queries; sampling a type's properties is a query. Vocabulary: entity types, classes, schema, critical assets, crown jewels. ## What the list proves The counts come from a stored index, not from the graph: on a live tenant it disagreed with direct queries on counts and omitted types that queries returned. A type listed here exists; a type missing from it may still exist. When a type matters, confirm it directly with `FIND <type> AS e RETURN count(e) AS value`. ## Asset criticality `assetCriticality.levels` lists the account's levels, most critical first: `name`, `slug` (the value runs write on each asset as `j1.criticality`, hourly and after each change), `rank` (`j1.normalizedCriticality`, 0 most critical), `appliedAs` (the two filters that select the level) and `assetsQuery`. `suggestedQueries` count assets by level, list the two most critical levels and the unclassified assets. For "critical assets" in a query, rule or widget, filter on these, not on tags or smart classes. `configured: false` means no levels exist, so nothing carries `j1.criticality`; `assetCriticality: "unavailable"` means the levels could not be read in time, not that there are none. The queries that fill each level are on `get-asset-criticality`. Full reference: get-reference topic j1ql-discovery
test-connection2 of 2 parameters describedTest the connection to JupiterOne and the caller's access to the target account, and report who the caller is: the credential type, the signed-in user's email and a summary of permissions. Call it at the start of a session, after an access error, or whenever it is unclear which sign-in or account is active. `list-accounts` lists every account a sign-in can reach; this tool checks one. ## Reading the result `credential.type` is `user`, `account_token` or `userless_token` (an API token with no user that could not be identified; `credential.lookup` says why, and none of its values means the token cannot act). Surface `user.email` to the user when there is any doubt about which sign-in is active. A `false` anywhere in `permissions` proves nothing: it summarises fine-grained RBAC rows, and callers with no rows at all write successfully every day. Use it to explain a denial after one happens, never to refuse an operation in advance. ## Failure A failed test returns an error whose text says why and what to do next. When the failure is an authorization rejection and account discovery is available, the text lists the accounts the sign-in can access. If tools take an `accountId`, retry with one of those; the connection itself needs no change. If the connection is pinned, the list carries each account's connector URL; relay it so the user 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.
get-reference2 of 2 parameters describedReturn one reference page; read it before writing a query, widget, rule or compliance answer beyond what a tool description gives. Topics: `j1ql-language` (grammar), `j1ql-discovery` (types, properties, values), `widget-types` (chart types, RETURN columns), `widget-settings` (per chart type), `dashboard-layout` (grid, autoLayout), `rule-authoring` (payloads, actions), `rule-templates` (templates, previews), `compliance-model` (control scoring), `compliance-fields` (field glossary), `framework-authoring` (controls, tests, exemptions), `asset-criticality` (levels). Read-only; needs no account.
get-threat5 of 5 parameters describedReturn JupiterOne's threat brief for one CVE: how dangerous it is, whether it is exploited in the wild or listed in a KEV catalog, whether the security ecosystem can detect it, and how fast CISA's directive says to remediate it. This is intelligence about the CVE itself; `check-threat-exposure` answers whether this account is affected, and `get-threat-trending` lists what is escalating now. Vocabulary: CVE, vulnerability, exploited, KEV, SSVC, EPSS, remediation, BOD 26-04, exposure, threat intelligence. ## Parameters - `assetExposure` resolves the remediation section to one branch; omitted, both branches come back when the directive's answer differs for public and internal assets, and one when it does not. - `detail: true` returns the full brief, a much larger payload; the raw reference URL lists (thousands of rows) are never included. The compact brief's `affectedProduct` (the join key for a product-presence search of the graph) is as complete as the full brief's, so do not spend the larger call looking for one. ## Reading the result `notes`, when present, carries the reading rules this brief needs (no product identity, or SSVC sources that disagree); pass them on with the answer. ## Outcomes `outcome` is one of four, and they are not interchangeable: - `found` — a brief was returned. This describes the lookup, not the CVE: it says nothing about whether the vulnerability is remediated anywhere. - `not_found` — a valid CVE id with no upstream record. - `invalid_input` — not a CVE identifier; no lookup was attempted. - `source_unavailable` — the upstream was unreachable, timed out or rate-limited. This is a retry state, never "no such CVE"; the id is preserved for the retry. ## Access Needs the account's VulnerabilityManagement entitlement and vulnerability read permission; without them the call returns an access-denied error. ## Example `{ "cveId": "CVE-2021-44228" }`
get-threat-trending3 of 3 parameters describedReturn the ranked list of trending threats: CVEs that have recently escalated (newly exploited in the wild, weaponized, added to a KEV catalog, or a public PoC appeared), each with its escalation reason, affected vendor and product, commercial-scanner coverage gap and KEV additions. It says what is hot now, not whether this account is affected: pair it with `check-threat-exposure` (scanner match) or, for product presence, a J1QL search on the row's `affectedProduct`; `get-threat` briefs one CVE. Vocabulary: trending, CVE, exploited, KEV, weaponized, PoC, exposure, threat intelligence. ## Reading the result - The list is cached for about 30 minutes; `generatedAt` is the cache fill time of the instance that answered, so consecutive calls can differ. - List order is the ranking; the upstream caps it (25 rows today), usually all `act_now`. - `rowsWithoutProduct` counts rows with no `affectedProduct`, and the `note` says how to treat them; pass it on with the answer. - A product-presence search matches on text, so it also matches your own tooling: searching the graph for `artifactory` returns the container images of JupiterOne's integration for Artifactory, not a running server. Confirm matched entities are instances of the product, not code, images, pipelines or alarms named after it, before counting them as exposure. ## Access Needs the account's VulnerabilityManagement entitlement and vulnerability read permission; without them the call returns an access-denied error.
check-threat-exposure3 of 3 parameters describedAnswer, from this account's own graph, whether it is exposed to up to 25 CVEs: how many devices a vulnerability scanner has confirmed carry each one, a handle to drill into the affected assets, and whether any matched device is internet-facing. This is the direct, strict match on the unified vulnerability's `cveId`, so it sees only what a scanner has already fingerprinted for that CVE; `get-threat` briefs the CVE itself and `get-threat-trending` lists what is escalating. Vocabulary: exposure, exposed, affected, CVE, scanner, findings, KEV, internet-facing. ## Reading the result Key results off each one's `subjectId`, not position. `status` is `checked`, `invalid_input` or `unavailable`. - `checked` means the lookup ran and the count is real; it says nothing about remediation. Read the count. - `scannerConfirmedAssetCount: 0` does not mean "not affected": no scanner reported it, and absence of a finding is not evidence of absence. Render it as "none found". There is no not-found outcome: a CVE that does not exist and a real CVE with no findings both return `0`; only `get-threat` answers existence. - `unavailable` is not a zero count: the graph lookup failed or timed out, a retry state. Never collapse it into "0 affected". - `assetExposure: null` means unknown, not "not internet-facing"; it is set only when a matched device carries an exposure classification. - A count is only as fresh as the scanner behind it; a feed that stopped months ago still reports its last findings. Drill in and check when they were last observed, with `unifiedVulnerabilityId` (the `_id` of this account's `unified_entity` for the CVE): `FIND * WITH _id = '<unifiedVulnerabilityId>' THAT RELATES TO Finding AS f THAT RELATES TO (Host|Device|Domain) AS a RETURN a.displayName, a._type, f._type, f._beginOn ORDER BY f._beginOn DESC LIMIT 50`. Keep the second hop restricted as shown, or control tests and alerts dominate it. - Ids are upper-cased before the lookup. - Which affected devices matter most: break them down by the account's asset criticality levels (`get-graph-context` lists them): `FIND UnifiedVulnerability WITH cveId = 'CVE-2021-44228' AS uv THAT IS Vulnerability WITH open = true THAT HAS (Host|Device) THAT IS UnifiedDevice AS ud RETURN ud.j1.criticality AS level, count(ud) AS devices`. Devices with no level are unclassified, not unimportant. ## Access Needs the account's VulnerabilityManagement entitlement and vulnerability read permission; without them the call returns an access-denied error. ## Example `{ "cveIds": ["CVE-2021-44228", "CVE-2023-4966"] }`
get-compliance-summary7 of 7 parameters describedReturn the account's compliance posture from JupiterOne Compliance (CCM): a scorecard per framework and, for one framework, its sections and failing requirements, plus attestations expiring soon or already lapsed. Answer posture questions from it rather than re-deriving pass/fail in J1QL. Siblings: `list-controls` for the controls behind a number, `get-control` for why one control passes or fails, `update-attestation` to renew an attestation. Vocabulary: compliance, framework, SOC 2, ISO 27001, requirements, controls, health, attestations, audit. ## Parameters `frameworkId` drills one framework and reads only its scorecard, faster on an account with many frameworks; `frameworkName` does the same by name; `frameworkIds` scores a chosen set (up to 25) with no drill. More than one of the three is an `invalid_input:` error. `includeRequirements` with a drill adds the framework's `requirementList` (id, identifier, title, section, priority), what `create-controls` and `link-controls` take requirement ids from; `requirementListTruncated` past 1,000, `requirementListSkipped` with the reason when not read. The expiry window bounds `expiringAttestations` only. ## Outcomes - `ok` — `frameworks: []` is a real answer: no CCM frameworks. - `ambiguous` — `frameworkName` matched several (`candidates`, up to 25); ask the user, or call again with that `id` as `frameworkId`. - `framework_not_found` — `frameworks` lists every framework without counts; take the id from there. - `frameworkResolution: "partial"` is a substring match: confirm the `name` with the user. `frameworksComplete: false` means the list stopped at its page limit. - `frameworkIdsNotFound` lists requested ids no framework has; the rest are scored. ## Reading the scorecard - `attested` counts every control with a valid attestation, failing ones too; it is not a subset of `passing`. - `null` counts mean not read, never zero (`statsIncomplete` names them). - `healthPct` is passing ÷ (passing + failing) requirements, `null` when none is evaluated. It ignores unevaluated requirements, so compare passing + failing with `requirements.total` before calling a framework healthy. `importStatus` other than `COMPLETE` means incomplete counts. - `controls.passingWithoutData`: CCM counts tests that saw no data as passing, so a high score can rest on tests that saw nothing. - `importJobs[]`: framework imports in flight or failed (`status`, `message`, `name`, `sourceId`), the ones `import-framework` queued; absent when none. - An empty `failingRequirements` is real only when `failingControlsTruncated` is `false` and `requirementLookupsSkipped` is `0`; otherwise answer from `failingControls`. ## Attestations - `expiringAttestations` and `expiredAttestations` (not revoked, at most 50). The string `'unavailable'` in place of a list means it could not be read with these permissions, never that nothing expires. - An expired, unrevoked attestation fails its control until renewed with `update-attestation` or revoked, so answer "what expires" from both lists. - `expiringAttestationsScope: "account"` means the lists are not limited to the drilled framework. ## Warnings and links Pass `warnings` on with the answer. Give a framework's or control's `url` when you name it. ## Access Needs the Compliance (CCM) entitlement and control read permission; account-wide attestation lists also need CCM read-admin, or only they are `'unavailable'`. An access-denied error names the missing one; re-authenticating will not help. Full reference: get-reference topic compliance-fields or compliance-model
list-controls17 of 17 parameters describedList JupiterOne Compliance (CCM) controls with the filters CCM's own controls view offers: status, state, framework, org unit, owner, attestation, catalog, MITRE technique and text search (test names too). Rows are compact (status, state, test counts, fail reason, framework names), no descriptions or queries. Use it to find a control by name, identifier or test name, and to list what fails in a framework or org unit. Siblings: `get-compliance-summary` for framework numbers, `get-control` for one control. Vocabulary: compliance, controls, failing, LIVE, org unit, owner, search, MITRE, audit. ## Filters - `status` on a non-LIVE control is left over from its last evaluation; add `states: ["LIVE"]` to list what fails now. Drafts count only once `transition-controls` promotes them. - `search` reads control name, description, identifier and id; controls whose test names contain it come back separately in `testNameMatches` (control and test, failing tests first, from the graph, first page only, honouring `states`, `status`, `frameworkId` and `source`). `testNameSearch` says `ran`, or why not: `first_page_only`, `unsupported_filters` (another filter was set), `time_budget`, `read_failed`. - `orgUnit` selects controls whose tests touch an asset in the unit; a row's `status` stays the control's overall status. An id (a value with a colon) is used unchecked; a name is searched in up to 10 enabled namespaces. - `sort` by `LAST_EVALUATED_ON` with `DESC` lists never-evaluated controls (`null`) first; add `status: ["PASS", "FAIL"]` to leave them out. - A cursor works only with the exact filters of the call that returned it; a refused one is an error starting `cursor_rejected:` with the API's reason. - For a count rather than rows, run `execute-j1ql-query` with `FIND ccm_control WITH state = 'LIVE' AND status = 'FAIL' AS c RETURN count(c) AS value`. ## Outcomes - `ok` — `controls` is this page, `returned` its size. An empty list is a real answer. With `orgUnit`, the response adds `orgUnit` and `ouResolution` (`id`, `name` or `id_unverified`); an empty page behind `id_unverified` carries a `note`. - `ambiguous` — the `orgUnit` name matched several units; `candidates` lists up to 25, incomplete when `namespacesFailed` is above 0. Ask the user, or call again with one's `id`. - `org_unit_not_found` — no unit matched. `namespaces` lists what was searched (`failed: true` where it failed), `namespacesNotSearched` counts the rest, and `units` offers up to 10 per namespace. It is not proof the unit does not exist, and never "no failing controls"; when every search fails, the call is an error. ## Rows `status` is `PASS`, `FAIL` or `null` (never evaluated); `effectiveStatus` is `EFFECTIVE`, `NO_TESTS` or `NO_DATAPOINTS`; `failingTests` counts non-deleted failing tests; `failReason` on a FAIL row is `failing_test`, `no_failing_test` (LIVE with no failing test: an expired attestation, or a status not re-scored since the tests changed; `get-control` says which), `not_live` (a stale status) or `tests_unread`; `frameworkNames` follows `frameworkIds`, `null` where unresolved. ## Access Needs the Compliance (CCM) entitlement and control read permission. CCM silently leaves out controls in resource groups the caller cannot read, and no read permission returns an empty list; a missing entitlement is an access-denied error that names it. ## Example `{ "frameworkId": "<frameworkId>", "status": ["FAIL"], "states": ["LIVE"] }` Full reference: get-reference topic compliance-fields
get-control6 of 6 parameters describedReturn one JupiterOne Compliance (CCM) control with what explains its status: its tests and their latest evaluation, attestations, requirements, frameworks and `statusExplanation`. Look it up by `controlId`, `identifier` (such as `CC6.1`) or `controlName`. Use it for why a control fails, how to fix it (`control.remediation`) and how to get an exception (`control.exceptionProcess`); `list-controls` finds controls. Vocabulary: compliance, control, test, evidence, failing, attested, remediation, exception, audit. ## Parameters Exactly one of `controlId`, `identifier` or `controlName`; none or several is an `invalid_input:` error. `includeDeleted` adds deleted tests, never a deleted control. ## Outcomes - `found` — one match, or several with exactly one LIVE (`otherCandidates` lists the rest). - `not_found` — nothing matched, deleted included; the `note` says how to search. - `ambiguous` — several matched, not exactly one LIVE; `candidates` lists up to 25, incomplete when `searchComplete` is `false` (the search stops at 200 controls). Call again with one's `controlId`, or narrow with `list-controls`. ## Status - A failing test fails the control; an attestation never masks it. - An attestation passes a control only when no test has a status. - An expired, unrevoked attestation fails the control, whatever the tests say. - Only LIVE controls are evaluated; a test that saw no data still passes. A DRAFT or REVIEW control reports `not_live` with `testsRan`, `testsPassing` and `testsFailing` from the runs `evaluate-controls` queued; the tests have statuses, the control does not. `statusExplanation` is one of `not_live`, `failing_test`, `failing_expired_attestation`, `undetermined`, `passing_by_tests`, `passing_by_attestation`, `no_tests`, `no_datapoints`; `statusMeaning` explains it. `blockers` lists every cause; clear them all. `storedStatusStale: true`: CCM has not re-scored yet, so report `expectedStatus`. ## Tests - `resultsAre: "BAD"`: any row is a violation and fails the test. `"GOOD"`: rows are compliant and the test never fails, so zero rows is a pass on no data. `effective` is not a verdict. - What CCM scored: `get-rule-evaluation-query-results` with `latestEvaluation.rawDataKey`. What is true now: the test's own `query` through `execute-j1ql-query`, narrowed in its `WITH`, never a new query. - `failedEvaluationTests`: tests whose latest run failed (`latestEvaluation.tag` `EVALUATION_FAILURE`). They stored no result, and CCM leaves a test with no status out of the control's score, so fix their query. - `exemptions[]`: the assets exempted from the test (`create-exemptions`), each with the `groupId` that `revoke-exemptions` takes, its `reason`, `status` and `expiresOnIso`; `exemptionsTruncated` past 50. ## Attestations and requirements `attestations: 'unavailable'` means not readable, never none; revoked ones never affect the status. Empty `requirements` or `frameworks` beside a skip reason means not read; `notes` says so. ## Access Needs the Compliance (CCM) entitlement and control read permission; a missing one returns an access-denied error that names it. Full reference: get-reference topic compliance-model or compliance-fields
create-attestation8 of 8 parameters describedAttest a JupiterOne Compliance (CCM) control: record that it is met by evidence no test can query (a policy, a review, a document) until a stated expiry. Attestations apply to LIVE controls only; one passes a control only when no test has a status, and never masks a failing test. Resolve the control id with `get-control` first. Siblings: `update-attestation` changes or renews one (an expired one too), `revoke-attestation` withdraws one. Vocabulary: compliance, attest, attestation, evidence, exception, compensating control, expiry, policy, audit. ## Parameters - `subject` is the duplicate key: an ACTIVE attestation on the control with the same subject (trimmed, ignoring case) is returned instead of a second one. - `expiresOn` must be in the future; a date alone is the end of that day, UTC. A date-time without `Z` or an offset, and a number below 1e12 (epoch seconds), are rejected. - A non-email `owner`, a non-http(s) `documentLink` or a quote in `controlId` is rejected before the tool runs. ## Outcomes - `created`, or `already_exists` when an ACTIVE attestation with this subject exists: it is returned, nothing was written, and a retry is safe; `requestedExpiresOnApplied: false` means its expiry stands. Both carry `attestation`, `control`, `blockers`, a `note` and `statusImpact`: - `blocked` — a failing test or an expired, unrevoked attestation keeps the control failing whatever is attested (`blockers` lists each). Do not call the control covered: fix the test, or renew or revoke the expired attestation. - `passes_by_attestation` — no test has a status and nothing blocks; the control passes once CCM re-scores it. - `already_passing` — a passing test already passes the control; the attestation changes nothing. - Refusals are errors starting with the outcome, `structuredContent.controlId` names the control, and nothing was created: `not_found`; `not_live` (promote the control with `transition-controls`, then attest); `invalid_input` (`expiresOn` fails the rules above); `interrupted` (the write was cut off at the 55-second limit and may have landed; the error says how to confirm before creating again). ## Read-back CCM reads lag its writes by up to a minute, so `get-control` can show no new attestation right after `created`; re-read after a pause, since a second create inside that window makes a duplicate. ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; a missing one returns an access-denied error that names it. ## Example `{ "controlId": "<id>", "subject": "Log Management Policy v3", "expiresOn": "2027-06-30" }` Full reference: get-reference topic compliance-model
update-attestation8 of 8 parameters describedChange an existing attestation on a JupiterOne Compliance (CCM) control, most often to renew it with a later `expiresOn`; an expired attestation given a future expiry is active again, so renewing works before and after it lapses. Find the attestation `id` in `get-control` (`attestations`) or `get-compliance-summary` (`expiringAttestations`, `expiredAttestations`). Siblings: `create-attestation` records a new one, `revoke-attestation` withdraws one for good. Vocabulary: compliance, renew, extend, expiry, attestation, evidence, exception, audit. ## Parameters - At least one field to change; an omitted field is left as it is, and `null` clears `description`, `owner` or `documentLink`. - `expiresOn` must be in the future; a date alone is the end of that day, UTC. A date-time without `Z` or an offset, and a number below 1e12 (epoch seconds), are rejected. - `subject`: CCM accepts a subject another ACTIVE attestation on the control already has, but `create-attestation` finds an attestation by its subject, so keep each control's subjects distinct. ## Outcomes - `updated` — `attestation` as saved, `control` (`id`, `name`, `state`, `url`), `blockers`, a `note` naming each blocker, and `statusImpact` read after the write: `blocked` (a failing test, another expired attestation, this one still expired, or a control that is not LIVE, as `{ "type": "not_live" }`), `passes_by_attestation`, `already_passing`, or `unknown` (the control could not be read back in time; the update went through and does not need repeating, and `control` carries `id` and `url` only). `subjectCollision` names another ACTIVE attestation left with the same subject; rename one of them. - `not_found` — no attestation has this id and nothing changed; a normal result, not an error. A revoked attestation is gone for good and is `not_found` too: attest again with `create-attestation`. - Errors: `invalid_input:` (no field to change, or `expiresOn` fails the rules above; nothing was called) and `interrupted:` (the write was cut off at the 55-second limit and may have landed; read the attestation with `get-control` before repeating it). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; a missing one returns an access-denied error that names it. ## Example `{ "attestationId": "<id from get-control>", "expiresOn": "2028-06-30" }` Full reference: get-reference topic compliance-model
revoke-attestation3 of 3 parameters describedWithdraw an attestation on a JupiterOne Compliance (CCM) control. Revocation is permanent: a revoked attestation cannot be updated or reinstated, so confirm it with the user before calling, and use `update-attestation` to extend or correct one instead. Afterwards the control's status follows its tests and any other valid attestation. Find the `id` in `get-control` (`attestations`) or `get-compliance-summary` (`expiredAttestations`); `create-attestation` attests again later. Vocabulary: compliance, revoke, withdraw, attestation, exception, evidence, audit. ## Outcomes - `revoked` — `attestation`, `control` (`id`, `name`, `state`, `url`), `blockers`, a `note` saying what now decides the status, and `statusImpact` read after the revoke: - `no_longer_passing` — no passing test and no other valid attestation remain; once CCM re-scores the control, it is not evaluated. - `still_passing` — a passing test or another valid attestation keeps it passing. - `still_failing` — a failing test or another expired attestation keeps it failing; `blockers` lists them. - `now_passing` — the revoked attestation had expired, so a failure is cleared, and a passing test or another valid attestation passes the control once CCM re-scores it. - `no_longer_failing` — the revoked attestation had expired and nothing else passes the control; once re-scored, it is not evaluated. - `unknown` — the control could not be read back in time; the revoke went through and does not need repeating. - `not_found` — no attestation has this id and nothing changed; a normal result, not an error. An already revoked attestation is `not_found` too, so revoking the same id twice is harmless. - `interrupted:` (an error) — the write was cut off at the 55-second limit and may have landed; call again, and `not_found` confirms it. ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; a missing one returns an access-denied error that names it. ## Example `{ "attestationId": "<id from get-control>" }` Full reference: get-reference topic compliance-model
check-compliance-coverage4 of 4 parameters describedCheck whether a standard, framework or control topic is already covered in JupiterOne Compliance (CCM) before assessing it by hand or creating anything: is the framework loaded, importable from JupiterOne's library, or absent, and which existing controls already address a topic and can be reused. Call it when a question names a standard, benchmark or named control (SOC 2, ISO 27001, CIS, PCI DSS, NIST, HIPAA, "our MFA control"). Siblings: `get-compliance-summary` for posture, `list-controls` for the full list. Vocabulary: coverage, covered, framework, standard, benchmark, library, reuse, gap. ## Parameters At least one of `framework` (a standard's name or a fragment: "CIS AWS", "SOC 2", "PCI DSS 4") and `topic` (a control subject: "MFA for console users", "S3 encryption"). Both together answer both questions in one call. ## Outcomes - `verdict`: `covered` (LIVE controls with tests exist for it), `partial` (controls exist but are DRAFT, REVIEW or without tests; `draftCount` says how many are drafts, which is why a framework can read "0 passing, 0 failing"), `importable` (not loaded, but JupiterOne's library has it: `importable[]` carries `source` and `sourceId` for `import-framework`), `not_covered`. - `frameworks[]`: the loaded frameworks that matched, with `id`, `name`, `source`, `url`. - `controls[]`: up to 25 existing controls matching the topic, with `id`, `name`, `identifier`, `state`, `status`, `testCount`, `frameworkNames`, `url`. These are reuse candidates for `link-controls`; a control can serve several requirements and frameworks. - `nextStep`: the call that acts on the verdict, ready to run. - Error `read_failed:` the loaded framework list could not be read in time, so there is no verdict. Call again. An empty `controls[]` with `not_covered` means nothing matched the words given, not that no related control exists; try another phrasing before creating. The legacy Compliance app is never consulted. ## Access Needs the Compliance (CCM) entitlement and control read permission; an access-denied error names the missing one. The library search needs no permission beyond the entitlement. ## Example `{ "framework": "CIS AWS Foundations", "topic": "root account MFA" }` Full reference: get-reference topic framework-authoring
import-framework5 of 5 parameters describedImport one of JupiterOne's prebuilt compliance frameworks (CIS benchmarks, SOC 2, ISO 27001, NIST, PCI DSS, DORA) into JupiterOne Compliance (CCM) by its library `source` and `sourceId`, as `check-compliance-coverage` reports them. The backend creates the framework, requirements, controls and tests as a job; imported controls arrive DRAFT, so nothing counts until `transition-controls` promotes them. A customer's own program is built with `create-framework` and the tools after it. Vocabulary: import, library, prebuilt, template, load framework, CIS, SOC 2, ISO, NIST, PCI. ## Parameters `source` is `J1` (JupiterOne-authored) or `UCF`; `sourceId` is the library identifier from `check-compliance-coverage` (`importable[].sourceId`). `resourceGroupId` is optional. The framework's name comes from the library entry. ## Outcomes - `queued`: the import job was accepted. `job` carries `status`, `initiatedOn`, `name` and `sourceId`; the framework may not be listed for a short while. Read progress with `get-compliance-summary` (`importJobs[]` while it runs, then the framework's `importStatus`). A job that ends `FAILED` carries the backend's `message`; the live-controls limit, if the library content sets controls LIVE, surfaces there and not at this call. - `already_exists`: a framework with this `sourceId` is already loaded; `framework` carries its `id`, `name` and `url`, and nothing was started. A normal result, safe on replay. - `import_in_progress`: an import for this `sourceId` is already running; `job` says since when. - Error `not_importable:` no library entry has this `sourceId`; `structuredContent.nearest` lists the closest library names and ids. Nothing was started. - Error `read_failed:` the framework list, the library or the import jobs could not be read in time, or the list was cut short; nothing was started. Call again. - Error `interrupted:` the call was cut off at the 55-second limit and the job may have started; call `get-compliance-summary` and read `importJobs[]` before importing again. ## Access Needs the Compliance (CCM) entitlement and framework create permission; an access-denied error names the missing one. ## Example `{ "source": "J1", "sourceId": "cis-aws-foundations-v5" }` Full reference: get-reference topic framework-authoring
create-framework6 of 6 parameters describedCreate an empty JupiterOne Compliance (CCM) framework for a customer's own compliance program, the first step of incremental authoring: framework, then `create-requirements`, then `create-controls` or `link-controls`, then `create-control-test`. Everything authored lands DRAFT for the user to review; `transition-controls` promotes it later. For a standard JupiterOne already ships, `import-framework` loads the prebuilt version instead. Vocabulary: new framework, custom framework, internal policy, control register, compliance program, build, author. ## Parameters `title` (the program's name as the customer calls it) and `description` are required; `owner` (an email) and `resourceGroupId` are optional and omitted when absent. ## Outcomes - `created`: `framework` with `id`, `name`, `url`. `nextStep` names `create-requirements` and says to show the proposed sections and requirements to the user first. - `already_exists`: a non-deleted framework with this title (ignoring case) exists; `framework` carries it and nothing was created. A normal result, safe on replay; continue with its id, or choose another name if the user wants a second program. - Error `invalid_input:` an empty name or a malformed owner email; nothing was called. - Error `read_failed:` the framework list could not be read in time or was cut short, so a framework with this title cannot be ruled out; nothing was created. Call again. - Error `interrupted:` the call was cut off at the 55-second limit and may have landed. The framework list lags a create by up to a minute: wait a minute, then read `get-compliance-summary` (the `frameworks` list) before creating again. ## Access Needs the Compliance (CCM) entitlement and framework create permission; an access-denied error names the missing one. ## Example `{ "title": "ACME Security Policy", "description": "Internal controls for ACME, mapped to SOC 2." }` Full reference: get-reference topic framework-authoring
create-requirements4 of 4 parameters describedAdd requirements to a JupiterOne Compliance (CCM) framework in one batch: the obligations a standard or an internal program states, each with the standard's own identifier and wording, grouped by `section`. One call per section is the natural unit, and the user reviews the list before controls go under it. Framework ids come from `create-framework` or `get-compliance-summary`. Siblings: `create-controls` and `link-controls` fill a requirement. Vocabulary: requirements, criteria, obligations, sections, control objectives, CC6.1, A.9.1.1, add requirements. ## Parameters `frameworkId` and `requirements[]` (1 to 50). Each item: `title` (required; the obligation in the standard's words), `description`, `identifier` (the standard's id, such as `CC6.1`), `section` (the grouping shown in the app), `priority` (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`). Optional strings are omitted when absent, never sent empty. ## Outcomes Always `ok` with one `items[]` entry per input, in order: `outcome` `created` (with `id`, `title`, `identifier`, `section`), `already_exists` (a non-deleted requirement in this framework with the same `identifier`, or the same `title` when no identifier was given, ignoring case; its `id` is returned and nothing was created) or `refused` (the backend rejected this item; `reason` carries its text). `createdCount`, `existingCount`, `refusedCount` summarise; one refused item never stops the others. `framework.url` opens the framework. `nextStep` names `create-controls` and `link-controls` per requirement and says to confirm the structure with the user first. Errors: `framework_not_found:` no framework has this id; `invalid_input:` an empty batch, an item without a title, or an unknown priority; nothing was called. `read_failed:` the framework's existing requirements could not be read, so nothing was created (a create without that read could duplicate); call again. A call cut off at the 55-second limit comes back with items `interrupted`, or with no response at all, and some items may have landed. The duplicate check reads the API, so calling again with the same input is safe: landed items come back `already_exists`. ## Access Needs the Compliance (CCM) entitlement and framework edit permission; an access-denied error names the missing one. ## Example `{ "frameworkId": "<id>", "requirements": [{ "title": "Logical access security over protected assets", "identifier": "CC6.1", "section": "Logical and Physical Access" }] }` Full reference: get-reference topic framework-authoring
create-controls4 of 4 parameters describedCreate JupiterOne Compliance (CCM) controls under one requirement in a batch, in the customer's own words and identifiers. Controls land DRAFT for the user to review; promotion is a separate `transition-controls` call. Before creating, look for a control the account already holds (`check-compliance-coverage` with a `topic`, or `list-controls` with `search`) and attach it with `link-controls`: one control can serve many requirements. Tests come afterwards with `create-control-test`. Vocabulary: create control, new control, add controls, custom control, control register, author. ## Parameters `requirementId` (from `create-requirements` or `get-compliance-summary` with `includeRequirements`) and `controls[]` (1 to 25). Each item: `name` (required), `description` (what the organisation does, naming the tool or process; specific enough to write a test from), `identifier` (the customer's id, kept verbatim), `catalog`, `owner` (an email), `remediation` and `exceptionProcess` (markdown), `mitreTechnique` (`T1078` or `T1059.001`), `state` (`DRAFT`, the default, or `LIVE`, which counts against the live-controls limit at once). Optional strings are omitted when absent. ## Outcomes Always `ok` with one `items[]` entry per input, in order: `created` (with `id`, `name`, `identifier`, `state`, `url`), `already_exists` (a non-deleted control with this name, ignoring case, exists anywhere in the account; `control` carries its `id`, `state` and `frameworkNames`, nothing was created, and the way to use it for this requirement is `link-controls`), or `refused` (`reason` carries the backend's text). `createdCount`, `existingCount`, `refusedCount` summarise. A `live_limit` refusal on a LIVE item carries the backend's numbers verbatim and stops the rest of the batch; items after it are `not_attempted`. `nextStep` names `create-control-test` for the automated controls and says to confirm the list with the user; attestation-only controls need no test and are attested once LIVE. **Unfinished batches.** `remaining` counts items `not_attempted` (the call's budget ran out) and `interrupted` (cut off mid-create; it may have landed). `nextInputs` holds only the not-attempted items: call again with it, never with the whole batch. The duplicate check reads the graph, which lags a create by up to a minute, so resending items created moments ago makes second copies. Look `interrupted` items up with `list-controls` `search` after a minute before creating them again, and do the same after a call that returned no response at all. A single create took 41 s on a slow backend, so keep batches small when calls run long. Errors: `requirement_not_found:`; `invalid_input:` (empty batch, item without a name, malformed owner or MITRE id); `read_failed:` (the requirement or the account's existing controls could not be read, or more existing controls match the names than one call reads; use more distinctive names). Nothing was created. ## Access Needs the Compliance (CCM) entitlement and control create permission in the resource group; an access-denied error names the missing one. ## Example `{ "requirementId": "<id>", "controls": [{ "name": "MFA enforced for all Okta users", "identifier": "6.1.2", "description": "MFA is enforced through Okta sign-on policies for every active user." }] }` Full reference: get-reference topic framework-authoring
link-controls4 of 4 parameters describedAttach existing JupiterOne Compliance (CCM) controls to a requirement so they count toward it, instead of creating duplicates: a control can serve several requirements and frameworks, and a JupiterOne-managed control from a prebuilt framework or the customer's own often already satisfies a new requirement. Find candidates with `check-compliance-coverage` (a `topic`) or `list-controls` (`search`); `create-controls` is for controls that do not exist yet. Vocabulary: link, map, attach, reuse, existing control, assign control to requirement, shared control. ## Parameters `requirementId` and `controlIds[]` (1 to 25 exact control ids, `ccm_c_…`). Detaching is `update-control` with `requirementIds.remove`. ## Outcomes Always `ok` with one `items[]` entry per input id: `linked` (with the control's `name`, `state` and `url`), `already_linked` (it already served this requirement; nothing changed), `not_found` (no non-deleted control has this id; one the graph does not list yet is checked with the API first), `refused` (`reason`; that check failed) or `not_attempted` (the call's budget ran out first). `linkedCount`, `alreadyLinkedCount`, `notFoundCount` summarise; one unknown id never stops the others. A linked control that is DRAFT or REVIEW does not count until promoted, and one with no tests passes only by attestation: `notes[]` says which. Safe to repeat: a replay reports `already_linked` for everything it linked before. Errors: `requirement_not_found:`; `not_ready:` (the requirement exists but CCM cannot link to it yet, as happens just after `create-requirements`; nothing was written; call again in a minute with the same input); `invalid_input:` (empty list, or an id containing a quote); a call cut off at the 55-second limit comes back with items `interrupted`, or with no response; calling again with the same input is safe, and linked ones come back `already_linked`. ## Access Needs the Compliance (CCM) entitlement and edit permission on each control's resource group; an access-denied error names the missing one. ## Example `{ "requirementId": "<id>", "controlIds": ["ccm_c_J1_…", "ccm_c_JSON_…"] }` Full reference: get-reference topic framework-authoring
update-control12 of 13 parameters describedChange a JupiterOne Compliance (CCM) control's fields: name, description, identifier, catalog, owner, remediation, exception process, MITRE technique, resource group, and the requirements it serves. Use it to enrich a template control with the customer's own wording and ids, to fix a mistake, or to detach a control from a requirement. It never changes the lifecycle state (`transition-controls`) or the tests (`create-`, `update-`, `delete-control-test`). Vocabulary: edit control, rename, update description, remediation, owner, map to requirement, unlink, requirementIds. ## Parameters `controlId` plus at least one field to change. Strings: `controlName`, `description`, `identifier`, `catalog`, `owner` (an email), `remediation`, `exceptionProcess` (markdown), `mitreTechnique` (`T1078` or `T1059.001`), `resourceGroupId`; `null` clears `identifier`, `catalog`, `owner`, `remediation`, `exceptionProcess` or `mitreTechnique`; `description` and `resourceGroupId` cannot be cleared, only replaced. `requirementIds` is an object with one of `set` (replace the whole list; never empty), `add` or `remove`; an omitted field is left as it is. ## Outcomes - `updated`: `control` as saved, with `state`, `frameworkIds`, `url`. Safe to repeat: the same input a second time changes nothing. A `requirementIds` change is the slow path (over a minute on a slow backend, answered `interrupted:`); finish it, read the control back, and only then transition it, since a late-landing update restores the state it read. The reverse holds too: after `transition-controls` moves a control, read it with `get-control` until it shows the new state before updating it. - `not_found`: no non-deleted control has this id; nothing changed. - Errors: `invalid_input:` (no field to change, a malformed owner or MITRE id, `requirementIds` with several of `set`, `add`, `remove`, or `set: []`); `requirement_not_found:` (an id to add does not exist); `not_ready:` (an id to add was created moments ago and CCM cannot link to it yet; nothing changed; call again in a minute); `interrupted:` (cut off at the 55-second limit and may have landed; read back with `get-control` before repeating). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlId": "ccm_c_…", "identifier": "6.1.2", "remediation": "Enable the Okta MFA sign-on policy for the affected group.", "requirementIds": { "add": ["<requirementId>"] } }` Full reference: get-reference topic framework-authoring
delete-control3 of 3 parameters describedDelete a JupiterOne Compliance (CCM) control that was created by mistake while authoring. This is a hard delete: the control and its tests are removed and any attestations on it are purged, so it is accepted only for a DRAFT control that was never scored and never attested (revoked attestations count). A LIVE control leaves the program with `transition-controls` to RETIRED, which keeps its history. A control under the wrong requirement is moved with `update-control` (`requirementIds`), not deleted. Vocabulary: delete control, remove control, undo create, discard draft, mistake. ## Outcomes - `deleted`: the control's `id` and `name`, `testsRemoved`, and the `requirements[]` it was linked to (`id`, `title`), so a replacement can be created under them. - `not_deletable`: nothing changed; `reason` is `state` (not DRAFT), `was_live` (it has been scored as a LIVE control) or `has_attestations` (revoked ones included). `nextStep` fits the state: LIVE → RETIRED with `transition-controls`; REVIEW → back to DRAFT, then delete; a DRAFT with history stays a DRAFT (never scored) or is detached with `update-control`. - `not_found`: no control has this id, which is also what a repeated delete sees; nothing changed. - Error `read_failed:` the control or its attestations could not be read in time, so nothing was deleted; call again. - Error `interrupted:` the call was cut off at the 55-second limit and may have landed; calling again is safe, and `not_found` confirms it. ## Access Needs the Compliance (CCM) entitlement and delete permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlId": "ccm_c_JSON_…" }` Full reference: get-reference topic framework-authoring
create-control-test6 of 7 parameters describedAdd one test to a JupiterOne Compliance (CCM) control: a J1QL query plus whether its rows are `GOOD` (compliant assets; the test never fails, and zero rows is a pass on no data) or `BAD` (violations; any row fails the test). The query is parsed and run before it is saved and its rows are reported, so prove the query with `execute-j1ql-query` first and create the test once the rows are the evidence an auditor would accept. One query per test. On a DRAFT control the test runs only when `evaluate-controls` asks. Vocabulary: control test, add test, evidence query, automated check, GOOD, BAD, J1QL. ## Parameters `controlId` (exact id), `testName` (what the auditor would call the check), `query` (one J1QL query; a control that needs two checks gets two tests), `resultsAre` (`GOOD` or `BAD`), `description` (optional). ## Preflight The query is parsed locally: a syntax error, or an alias returned from a negated (`THAT !`) step, returns `invalid_input:` with a hint, nothing is saved, and `structuredContent.suggestion` carries the fix, a ready-to-run query when one is known. A query that parses is then run once (up to 10 seconds, within the call's budget): `rows` is what it returned now, `noDatapoints` is true when it returned nothing, `queryRun` is `ran`, `skipped_deadline` or `error` (with the hint). A run the engine rejects outright is refused the same way. Nothing else blocks the create: a query that failed for another reason is saved, checks nothing until it runs, and `nextStep` says how to fix it; a GOOD test with zero rows proves nothing, and a BAD test with rows will fail the control once it is LIVE. Report all three to the user. ## Outcomes - `created`: `test` with `id`, `name`, `referencedRuleId`, `effective` and `url`, the control's `state`, and `nextStep`. `effective: false` means the query names an entity type this account does not hold (`unknownEntityType: true`): the test will pass on no data until the data exists. - `already_exists`: a non-deleted test on this control with this name (ignoring case); `test` carries it and nothing was created. Safe on replay; use `update-control-test` to change it. - Errors: `control_not_found:`; `invalid_input:` (see Preflight; also an empty testName); `read_failed:` (the control could not be read in time; nothing was created; call again); `interrupted:` (cut off at the 55-second limit and may have landed: read the control's tests with `get-control` before creating again). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlId": "ccm_c_…", "testName": "Okta users without MFA", "query": "FIND okta_user WITH status = 'ACTIVE' AND mfaEnabled != true AS u RETURN u.displayName, u.email", "resultsAre": "BAD" }` Full reference: get-reference topic framework-authoring
update-control-test7 of 7 parameters describedChange an existing test on a JupiterOne Compliance (CCM) control: its query, whether rows are `GOOD` or `BAD`, its name or description. The usual reason is a query that measured the wrong thing (an unconnected tool, a value stored in another casing, too broad a scope); prove the new query with `execute-j1ql-query` first. A changed query is parsed and run before it is saved, like `create-control-test`. Test ids come from `get-control` (`tests[].id`). `delete-control-test` removes a test; `create-control-test` adds one. Vocabulary: fix test, edit query, change resultsAre, rename test, tune. ## Parameters `controlTestId` plus at least one of `testName`, `query`, `resultsAre` (`GOOD` or `BAD`), `description`. One query per test. ## Preflight When `query` changes it is parsed locally and run once within the call's budget, as in `create-control-test`. A syntax error, or a run the engine rejects outright, returns `invalid_input:` with `structuredContent.suggestion`; nothing is saved. Otherwise `rows`, `noDatapoints` and `queryRun` (`ran`, `skipped_deadline`, `error`) are advisory, and an `error` comes with a `nextStep`. ## Outcomes - `updated`: `test` as saved (`id`, `name`, `resultsAre`, `effective`, `referencedRuleId`), the control's `id`, `state`, `url`. The stored evaluation and the control's status are from the previous query until the next run: `evaluate-controls` on a draft, or the daily run on a LIVE control. Exemptions apply to evaluations of the query they were filed against, so a changed query may need a new evaluation before `create-exemptions` is eligible. Safe to repeat. - `not_found`: no non-deleted test has this id; nothing changed. - Errors: `invalid_input:` (no field to change, or a query that cannot run); `read_failed:` (the test could not be read in time; nothing changed; call again); `interrupted:` (cut off at the 55-second limit and may have landed; read back with `get-control` before repeating). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlTestId": "<id from get-control>", "query": "FIND wiz_finding WITH severity = 'critical' AND status = 'OPEN' AS f RETURN f.displayName" }` Full reference: get-reference topic framework-authoring
delete-control-test3 of 3 parameters describedRemove a test from a JupiterOne Compliance (CCM) control, for a test created by mistake or made obsolete by another. The test is soft-deleted (its rule stops running) and the control's status then follows its remaining tests and attestations; to change what a test checks, use `update-control-test` instead. Test ids come from `get-control` (`tests[].id`). Vocabulary: delete test, remove test, drop test, undo test, wrong control. ## Outcomes - `deleted`: `test` (`id`, `name`), `deletedTestStatus` (its last result), the control's `id`, `name`, `state`, `url`, and `note` saying what now decides the control's status (remaining tests, attestations, or nothing until a test or attestation exists). - `not_deletable`: nothing changed; the control is LIVE and this is a failing test (`reason` `failing_test_on_live`: the control would pass on its next run) or its last test (`last_test_on_live`: its status would clear). Fix the query with `update-control-test`, exempt assets with `create-exemptions`, or move the control to REVIEW with `transition-controls` first. - `not_found`: no non-deleted test has this id, which is also what a repeated delete sees; nothing changed. A normal result. - Error `read_failed:` the test could not be read in time, so nothing was deleted; call again. - Error `interrupted:` the call was cut off at the 55-second limit and may have landed; calling again is safe, and `not_found` confirms it. ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlTestId": "<id from get-control>" }` Full reference: get-reference topic framework-authoring
transition-controls7 of 7 parameters describedMove JupiterOne Compliance (CCM) controls between lifecycle states in a batch, by id or for a whole framework: promote drafts to REVIEW or LIVE, send a control back, or retire one. Authored and imported controls land DRAFT and are excluded from every scorecard until they are LIVE, so this is the call that makes a framework count; which state to go to is the user's decision. Siblings: `evaluate-controls` proves drafts first, `list-controls` with `states` shows what is waiting. Vocabulary: promote, go live, make live, activate, bulk, publish controls, review, retire, draft to live, state. ## States - `DRAFT`: authoring; excluded from counts; tests run only on request. - `REVIEW`: sign-off; still excluded. - `LIVE`: evaluated daily, counted everywhere, counts against the live-controls limit, attestable. Newly LIVE controls read "0 passing, 0 failing" until their first run. - `RETIRED`: excluded; the stored status is cleared on leaving LIVE and re-scored on return. Valid moves: DRAFT→REVIEW, REVIEW→DRAFT, REVIEW→LIVE, LIVE→REVIEW, LIVE→RETIRED, RETIRED→LIVE. A request for a state two moves away (DRAFT to LIVE) walks both, landing the first move across the whole batch before the second so a cut-off call leaves every control in a consistent state. A path through LIVE toward another state (DRAFT or REVIEW to RETIRED, RETIRED to REVIEW or DRAFT) is not taken: promote to LIVE first if that is what the user wants. ## Parameters Exactly one of `controlIds[]` (1 to 25 exact ids) or `frameworkId` (every control of the framework in one of `fromStates`, default `["DRAFT", "REVIEW"]`); `targetState`; optional `note` recorded on each transition. With `controlIds`, a control moves from whatever state it is in unless `fromStates` is given. `RETIRED` is accepted only with `controlIds`. Every move is decided on the state the API holds now, never on the graph's. ## Outcomes Always `ok`: `transitioned[]`, one entry per move (`id`, `name`, `from`, `to`, `url`; DRAFT to LIVE is two), `skipped[]` (`already_in_state`, `not_in_from_states`, `passes_through_live`, `not_found`, or `invalid_transition`, each with the control's current state), `refused[]` (`reason` with the backend's text, including a control whose read was denied; a `live_limit` refusal carries its numbers verbatim and stops the rest), `interrupted[]` (moves cut off mid-flight that may still land; each comes back in `nextInputs` from either state unless the live-controls limit stopped the call, and `nextStep` says to wait for the state to settle first), and `remaining`: the controls not reached or not finished within the call's budget, listed in `remainingControlIds`. `nextInputs` holds the calls that finish the job: make each, then repeat with each result's `nextInputs` until there are none. A control this call moved comes back by id with only the state it was left in, so a follow-up that reads it stale moves nothing; a framework pass comes back as the framework, re-checked control by control. `selectionComplete: false` means the framework had more controls than one call selects. `nextStep` says so, and names `get-compliance-summary` once everything is LIVE. Errors: `invalid_input:` (both or neither selector, an unknown state, RETIRED without ids); `framework_not_found:`; a call cut off at the 55-second limit can return no response at all: read the controls back with `get-control` or `list-controls` `states`, then call again; every move is decided on the state the API reads at that moment. After a move, read a control back with `get-control` before `update-control` or `link-controls` on it: CCM writes a control back whole from a read that can lag (`note` says so). ## Access Needs the Compliance (CCM) entitlement and edit permission on each control's resource group; an access-denied error names the missing one. ## Example `{ "frameworkId": "<id>", "targetState": "LIVE" }` Full reference: get-reference topic framework-authoring
evaluate-controls3 of 3 parameters describedRun the tests of JupiterOne Compliance (CCM) controls now, in a batch, instead of waiting for the daily run: the way a DRAFT or REVIEW control proves its tests before promotion, and the way to re-check a LIVE control after a fix. Results take minutes and are read with `get-control`. A non-LIVE control's tests gain a status; the control itself stays unscored until it is LIVE. Siblings: `get-control` reads the result, `update-control-test` fixes a query, `transition-controls` promotes. Vocabulary: evaluate, run tests now, re-check, prove draft, trigger evaluation, refresh status. ## Parameters `controlIds[]`: 1 to 25 exact control ids. ## Outcomes Always `ok` with one `items[]` entry per id: `queued` (with the control's `name`, `state`, `testCount`), `no_tests` (nothing to run; the control passes only by attestation once LIVE), or `not_found`. `queuedCount` summarises. `nextStep` says to wait a few minutes, then `get-control` on each: on a LIVE control `status` and `statusExplanation` follow the tests; on a DRAFT or REVIEW control `statusExplanation` stays `not_live` and `testsRan`, `testsPassing`, `testsFailing` carry the proof, with each test's `status` and `lastEvaluatedOn` under `tests[]`. Each call queues a fresh run, so repeat it only when a query changed or data moved; the daily run covers LIVE controls on its own. Errors: `invalid_input:` (empty list, or an id containing a quote); a call cut off at the 55-second limit comes back with items `interrupted`, or with no response; runs already queued complete on their own, so read back with `get-control` before queueing again. Items the budget did not reach are not queued; `nextStep` names them. ## Access Needs the Compliance (CCM) entitlement and edit permission on each control's resource group; an access-denied error names the missing one. ## Example `{ "controlIds": ["ccm_c_JSON_…", "ccm_c_JSON_…"] }` Full reference: get-reference topic framework-authoring
create-exemptions7 of 7 parameters describedExempt specific assets from a JupiterOne Compliance (CCM) control test so they stop failing it: a risk the organisation accepts, an asset the test does not apply to, a false positive, or one covered by a compensating control, with a justification and an optional expiry. One call records one decision for many entities, taken from the test's latest evaluation rows. An attestation covers a whole control; an exemption covers assets within one test. Vocabulary: exempt, exception, risk accepted, not applicable, false positive, compensating control, exclude asset, waiver. ## Parameters `controlTestId`; `entities[]` (1 to 50) of `entityId` (the graph `_id`) with optional `entityKey`, `entityScope`, `entityType`, `entityDisplayName` as the evaluation rows carry them (`get-control` gives the test's `latestEvaluation.rawDataKey`; `get-rule-evaluation-query-results` gives the rows: a `list` row is the entity, and a `table` row carries it under `_meta.byAlias.<alias>.entity` with `_id`, `_key`, `_scope`, `_type`); `exemptionReason` (`RISK_ACCEPTED`, `NOT_APPLICABLE`, `FALSE_POSITIVE`, `COMPENSATING_CONTROL`); `justification` (required; what an auditor should read); `expiresOn` (optional; a date, the end of that day UTC, or a date-time; omitted means the exemption never expires). ## Outcomes - `created`: `groupId` (shared by every entity in this decision; `revoke-exemptions` takes it), `count`, the test's `name` and the control's `id`, `name`, `url`, and `replaced[]`: earlier active exemptions on the same assets that this filing overwrote (one per asset is kept, whoever filed it; `replacedComplete: false` when they could not all be read), and `note` that the control's status changes on the test's next evaluation (`evaluate-controls` to run it now). Re-exempting an entity replaces its earlier exemption and files it under the new call's `groupId`, so after a repeat the earlier `groupId` holds none of those entities. - `not_eligible`: nothing written; `message` is the backend's own reason (the test has no stored evaluation, its query changed since that evaluation, or its shape cannot take exemptions). Evaluate the test again and re-read the rows before retrying. - Errors: `test_not_found:`; `invalid_input:` (empty entities, an empty justification, an expiry in the past, an unknown reason); `read_failed:` (the test or its latest evaluation could not be read in time; nothing was filed; call again); `interrupted:` (cut off at the 55-second limit and may have landed; read the test's `exemptions` on `get-control` before repeating, since a repeat re-groups the entities). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlTestId": "<id>", "entities": [{ "entityId": "<graph _id>", "entityKey": "arn:aws:s3:::logs-archive-bucket", "entityScope": "<_scope>", "entityType": "aws_s3_bucket", "entityDisplayName": "logs-archive-bucket" }], "exemptionReason": "NOT_APPLICABLE", "justification": "Public by design: it serves the status page.", "expiresOn": "2027-12-31" }` Full reference: get-reference topic framework-authoring
revoke-exemptions5 of 5 parameters describedWithdraw exemptions on a JupiterOne Compliance (CCM) control test, by decision (`groupId` from `create-exemptions`), by entity, or both (the intersection), so the assets fail the test again on its next run. A revoke is a hard delete, and by `entityIds` alone it removes whoever's exemption those assets carry; prefer `groupId`. The test's whole set cannot be revoked in one call; name the decision or the entities. Exemptions and their groups are listed on `get-control` (`tests[].exemptions`). Vocabulary: revoke exemption, remove exception, un-exempt, expire waiver, reinstate. ## Parameters `controlTestId` and at least one of `groupId` and `entityIds[]` (graph `_id`s, 1 to 50). ## Outcomes - `revoked`: `count` of exemptions withdrawn, the test's `name`, the control's `id`, `name`, `url`, and `note` that the status changes on the next evaluation. A `count` of 0 means nothing matched the selector and nothing changed. It is not proof the assets are unexempted: a re-file moves them to a new `groupId`, so confirm on the test's `exemptions` in `get-control`. - Errors: `test_not_found:`; `invalid_input:` (neither selector); `read_failed:` (the test could not be read in time; nothing was revoked); `interrupted:` (cut off at the 55-second limit and may have landed; read the test's `exemptions` on `get-control` to see what is still active before calling again). ## Access Needs the Compliance (CCM) entitlement and edit permission on the control's resource group; an access-denied error names the missing one. ## Example `{ "controlTestId": "<id>", "groupId": "<groupId from create-exemptions>" }` Full reference: get-reference topic framework-authoring
get-asset-criticality2 of 2 parameters describedRead the account's asset criticality config: its ordered levels (most critical first), the J1QL queries that place assets in each level, how many assets each level holds, and the latest runs that applied it. Use it before changing the config with `update-asset-criticality`, and to answer which assets are critical and why. The levels alone, without their queries, also come back on `get-graph-context`. Vocabulary: asset criticality, crown jewels, business impact, tiers, levels, critical assets. ## How criticality works Each level is filled by J1QL queries; an asset matching several levels gets the most critical. JupiterOne applies the config every hour and after every save, writing `j1.criticality` (the level's value, made from its name) and `j1.normalizedCriticality` (its rank, 0 most critical) onto each matched asset, any class, and removing them from assets no query matches. Levels feed the vulnerability risk score. ## Outcomes - `configured`: `levels[]` carries each level's `name`, `slug` (the value on assets), `rank`, `multiplier` (risk-score weight, null when unset), `assetCount`, `appliedAs` (the two filters that select it), `assetsQuery` (its assets, ready to run) and `queries` (`id`, `name`, `j1ql`, `enabled`). `taggingNothing: true` means no level has an enabled query, so the next run clears every asset's level. `unplacedQueries` holds queries whose level no longer exists; every save is refused until they are moved or removed. `suggestedQueries` counts assets by level, lists the two most critical levels and the unclassified assets. - `not_configured`: no levels yet, so no asset carries `j1.criticality`; a query on it returns nothing, which means "not classified", never "no critical assets". - `read_failed`: the config could not be read in time; it says nothing about the config. Call again. `assetCountsStatus` is `complete`, `pending` (the count query was still running; run `suggestedQueries.countByLevel`) or `unavailable`. `assetCount` counts the value on assets, which only a run writes, so it trails a save until a run started after it completes. `runPending: true` means a run is requested, running or still applying, or the latest ended `PARTIAL` or `FAILED`, hourly runs included (null when the runs could not be read); `valuesOutsideLevels` counts assets still carrying a value no level has, such as a renamed level's old one. Then report the counts as the last applied state, without waiting: a save is applied once `runs.latest` holds a `COMPLETE` run started after it. `runsStatus` is `unavailable` when the caller may read the config but not its run history, and `failed` when the history read failed or ran late; the config beside it is complete either way. `runs.latest` lists each run's `status` (`APPLYING`, `COMPLETE`, `PARTIAL`, `SUPERSEDED`, `FAILED`), `trigger` (`SETUP` after a save, `SCHEDULED` hourly, `MANUAL`), who started it and the per-level changes, as the levels stood at that run (not the current ladder). `inProgressSince` is when the run executing now started; a save made after that waits for the next run. `applyPendingUntil` is set while a finished run's changes are still being written onto assets. `PARTIAL` means capped, continuing on the next run; `SUPERSEDED`, capped and then overtaken by a save. `pendingRequest` is a run queued to apply a config that is already saved, often the caller's own save (`performedBy`), never an unsaved change: the levels and queries read here are current, and saving again is safe. ## Access Needs Assets: Admin, Vulnerabilities: Admin or full admin. Full reference: get-reference topic asset-criticality
update-asset-criticality5 of 5 parameters describedSet up or change the account's asset criticality: create the levels, rename, reorder or remove them, and add, change, move or remove the J1QL queries that place assets in each level. Works on an account with no config (send the levels and their queries in one call) and on an existing one (send only the change). The config is saved at once; assets carry the change only once runs apply it, which can take a while on a large account. Read the current config with `get-asset-criticality` first. Vocabulary: asset criticality, crown jewels, tiers, set up, create, classify assets. ## Input - `levels`: the whole ladder, most critical first, 2-6 levels, sent only when levels change. Keep an existing level by sending its `slug` from the read with its name; a changed name renames it. A level missing from the list is removed. An entry without `slug` is a new level, and one whose name matches an existing level is refused unless the call changes nothing (a repeat answers `unchanged`). Swapping two levels' names, or giving a new level the name a renamed one gives up, is refused too: make it two calls. - `upsertQueries`: without `id` creates a query (`level`, `name`, `j1ql` required); with `id` changes only the fields given, and a new `level` moves it. One entry per query id. `level` is a level's name or slug in the ladder this call produces. - `removeQueryIds`: queries to delete. A query selects the complete set of its level's assets, any class: no `LIMIT` or `SKIP`, at most 1,024 characters. Write a plain filter (`FIND DataStore WITH tag.PCI = true`) and `RETURN e._id AS entityId` is added, or return one entity's `_id AS entityId` yourself. Prove the query with `execute-j1ql-query` first. ## Outcomes - `saved`: `changes` lists what changed; `queries` echoes each created or changed query as saved, with `returnAdded` (true when the tool appended the `RETURN` to a plain filter) and its `matchCount`, what the query returns now and the next run applies, not what assets carry yet (null while still counting: run its `countQuery`); `levels` carries each level's `slug`, `rank` and `appliedAs` as saved; `effects` says what a change to the levels does to assets on the next run: a rename, reorder or removal, or a level or the ladder left without an enabled query. It is empty for a call that adds, changes or removes queries and leaves every level an enabled one; their reach is each query's `matchCount`. - `unchanged`: the config already says this (a repeated call is safe): nothing was saved. - Refusals, nothing saved: `invalid_query` (`invalidQueries`: each failing query's index and why), `invalid_input`, `level_has_queries` (move or remove the `queryIds` in the same call), `queries_without_level`, `query_not_found`, `conflict` (re-read and resend), `read_failed` (call again), `interrupted` (the save may have landed; sending the same call again is safe). ## Effects to tell the user A renamed level changes its value on every asset (`retag`); a reorder or removal renumbers ranks (`renumber`); a removed level un-levels its assets and drops its risk-score multiplier; a level or ladder left without an enabled query un-levels its assets. A rule or widget on a changed value or rank selects other assets, or none, once a run applies the change, and one on the new value or rank does until then (`filters_stale` names, per level, the filter that holds across the run). ## Access Needs Assets: Admin (with Shared: Graph Data: Read) or full admin. Full reference: get-reference topic asset-criticality
Tested in a sandbox with an empty environment: no API keys, a throwaway folder, nothing from a real account. A passing test shows the server runs and responds. It is not a security audit.