JupiterOne Parameter Service

Previously, some use cases of JupiterOne required referencing a literal value that is better suited to reference as a variable or a parameter. Some common values that are better stored and retrieved at runtime instead of saved literally include:

• Long or unwieldy values (such as a long URL)
• Sensitive values (such as a private key or API token)
• Common values (such as dates, keys) that you may want to change in many places at one time

A better alternative exists in the form of parameters that can be stored and referenced in rules and queries with a special syntax.

Examples

In the use case of a very long URL, which may not be easily human-readable and may be referenced in many rules, queries, or questions, use:

Example: Parameters in J1QL

FIND Application WITH loginUrl = ${ param.longURL }

Example: Parameters in Rules

  "headers": {
    "Authorization": "Bearer {{param.secretApiKey}}"
  }

The service hydrates the value of longUrl or secretApiKey and evaluates it against the remote contents instead of the parameter expression. You can leverage this same pattern for different types of parameter types and comparisons, explained below. As shown above, the syntax between rules and queries differs slightly, but is consistent with variables (in the case of queries) and expressions (in the case of rules).

Usage: Schema

Parameters can be managed from Settings > Account Parameters in the app, or through the public-facing GraphQL endpoints described below. The settings page is where you choose a parameter's type (String, Number, Boolean, or a list of strings or numbers); the stored type is what queries then compare and compute with.

A parameter is an object stored in the parameter-service, which uses the following schema:

Property	Type	Description
name	string	The parameter key or "name"
value	string | number | boolean | list*	The parameter value to be stored/retrieved
secret	boolean	Flag to treat value as sensitive data
lastUpdatedOn	date	Date which indicates last update

List Types

Lists are considered to be arrays of string, number, or boolean types.

Usage: API Operations and Queries

Queriable fields:
parameter	Individual QUERY for one parameter
parameterList	Bulk QUERY for parameters

Mutations:
setParameter	Create/update a remote parameter
deleteParameter	Remove a parameter from the remote store

GraphQL API

Query: parameter

Argument	Type	Required?
name	string	Yes

Returns: Parameter

Example:

query Query($name: String!) {
  parameter(name: $name) {
    name
    value
    secret
    lastUpdatedOn
  }
}

Query: parameterList

Argument	Type	Required?	Default
limit	number	No	100
cursor	string	No (unless paginating)	n/a

Returns: Paginated

Example:

query Query($limit: Int, $cursor: String) {
  parameterList(limit: $limit, cursor: $cursor) {
    items {
      name
      value
      secret
      lastUpdatedOn
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

Mutation: setParameter

Argument	Type	Required?	Default
name	string	Yes	n/a
value	string | number | boolean | list	Yes	n/a
secret	boolean	No	false

Returns

{
  success: boolean;
}

Example

mutation Mutation($name: String!, $value: ParameterValue!) {
  setParameter(name: $name, value: $value) {
    success
  }
}

List Parameters Variables Example

{
  "name": "items",
  "value": ["jupiterone.com", 2] // multi-type arrays are allowed
}

Non-List Parameters Variables Example

{
  "name": "j1domain",
  "value": "jupiterone.com"
}

Mutation: deleteParameter

Argument	Type	Required?
name	Array<string>	Yes

Returns

{
  success: boolean;
}

Example

mutation Mutation($name: String!) {
  deleteParameter(name: $name) {
    success
  }
}

Parameter References

You can reference parameters in rules' configurations or any query expression, although the syntax is slightly different between the two. param is a special keyword that, when invoked, fetches values from the parameter-storing service.

Note: In the case of both rules and queries, referencing a nonexistent parameter causes an error and abandon execution.

Where parameters can be used in J1QL

A parameter can stand in for a literal value in these positions.

As a comparison value in a WITH, WHERE or HAVING clause:

FIND Application WITH loginUrl = ${ param.longURL }

FIND Finding AS f WHERE f.score > ${ param.riskThreshold }

FIND Finding AS f RETURN f.severity AS severity, COUNT(f) AS total
HAVING total > ${ param.minimumCount }

As a returned value, with or without an alias. An unaliased parameter is returned in a column named param.<name>, so the column name stays the same when you change the parameter's value:

FIND Finding AS f RETURN f.displayName AS finding, ${ param.riskThreshold } AS threshold

In arithmetic, function arguments and aggregation arguments, in both RETURN and WHERE, and as a function argument in HAVING:

FIND unified_vulnerability AS uv
RETURN ${ param.cvssWeight } * COALESCE(uv.cvssImpactScore / 6.05, 0.0)
     + ${ param.epssWeight } * COALESCE(uv.epssScore, 0.0) AS riskScore

FIND Finding AS f WHERE f.numericSeverity * ${ param.weight } > ${ param.threshold }

This is what makes a query reusable: the thresholds and weightings live in parameters, so the query text does not change when you retune them.

A parameter's stored type is preserved — a parameter saved as a number is compared and computed as a number. A parameter saved as text or as a boolean cannot be used in arithmetic, and the error names the parameter so you can correct its type.

A parameter holding a list can be used as a comparison value in WITH or WHERE, where it expands into a comparison against each element:

FIND Application WITH _type = ${ param.approvedTypes }

A list is not supported in HAVING, as a returned value, or inside arithmetic, and an empty list is rejected wherever it appears.

Parameters are not accepted in ORDER BY, LIMIT or SKIP, or as the address range in CIDR(). A parameter cannot supply a regular expression: its value is compared as a value, never as a pattern. HAVING does not accept arithmetic, with or without a parameter — HAVING total * 2 > 10 is rejected too.

A secret parameter can only be used as a comparison value in WITH or WHERE.

Auditing and Security

All changes (including creation and deletion) of parameters is captured by an audit trail providing visibility into the historic usage and access of these values. In addition, all parameters are encrypted-at-rest and in-transit, subject to log redaction, and are subject to either ABAC or IAM-based fine-grained permissions.

Secret Parameters

Any parameters set with secret to be true have write-only values and are not readable from the API. Only evaluations of the query can access these parameter values. This usage enables the storage of sensitive parameters such as API keys that JupiterOne users should not be able to see. All read access to these secret parameters contains redacted values, but metadata is able to be read.

In a query, a secret parameter can only be used as a comparison value in WITH or WHERE:

FIND Application WITH clientId = ${ param.secretClientId }

Anywhere else (as a returned value, in arithmetic or a function argument, or in HAVING), the query is rejected with an error that names the parameter, so a query cannot return a secret's value.

Note: By design, you cannot update a parameter that has had secret set to true to secret: false without also changing the value in the same request.