Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
JupiterOne Parameter Service - AskJ1 Community
<main> <article class="userContent"> <p>Previously, some use cases of JupiterOne required referencing a <em>literal</em> value that is better suited to reference as a <em>variable</em> or a <strong>parameter</strong>. Some common values that are better stored and retrieved at runtime instead of saved literally include:</p> <ul><li>Long or unwieldy values (such as a long URL)</li> <li>Sensitive values (such as a private key or API token)</li> <li><p>Common values (such as dates, keys) that you may want to change in many places at one time</p> <p>A better alternative exists in the form of parameters that can be stored and referenced in rules and queries with a special syntax.</p></li> </ul><h2 data-id="examples">Examples</h2> <p>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:</p> <h3 data-id="example-parameters-in-j1ql">Example: Parameters in J1QL</h3> <pre class="code codeBlock" spellcheck="false" tabindex="0">FIND Application WITH loginUrl = ${ param.longURL } </pre> <h3 data-id="example-parameters-in-rules">Example: Parameters in Rules</h3> <pre class="code codeBlock" spellcheck="false" tabindex="0"> "headers": { "Authorization": "Bearer {{param.secretApiKey}}" } </pre> <p>The service hydrates the value of <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">longUrl</code> or <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">secretApiKey</code> 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).</p> <h2 data-id="usage-schema">Usage: Schema</h2> <p>Currently, the storage of parameters is only accessible from public-facing GraphQL endpoints. In the future, a user interface will be available to account users but, currently, only the API exists.</p> <p>A parameter is an object stored in the parameter-service, which uses the following schema:</p> <table><thead><tr><th>Property</th> <th>Type</th> <th>Description</th> </tr></thead><tbody><tr><td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">name</code></td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code></td> <td>The parameter <strong>key</strong> or "name"</td> </tr><tr><td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">value</code></td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">number</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">boolean</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">list</code><a rel="nofollow" href="####list-types">*</a></td> <td>The parameter <strong>value</strong> to be stored/retrieved</td> </tr><tr><td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">secret</code><a rel="nofollow" href="##secretparameters">*</a></td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">boolean</code></td> <td><strong>Flag</strong> to treat value as sensitive data</td> </tr><tr><td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">lastUpdatedOn</code></td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">date</code></td> <td><strong>Date</strong> which indicates last update</td> </tr></tbody></table><h4 data-id="list-types">List Types</h4> <p>Lists are considered to be arrays of <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code>, <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">number</code>, or <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">boolean</code> types.</p> <h2 data-id="usage-api-operations-and-queries">Usage: API Operations and Queries</h2> <table><thead><tr><th>Queriable fields:</th> <th></th> </tr></thead><tbody><tr><td>parameter</td> <td>Individual <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">QUERY</code> for one parameter</td> </tr><tr><td>parameterList</td> <td>Bulk <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">QUERY</code> for parameters</td> </tr></tbody></table><table><thead><tr><th>Mutations:</th> <th></th> </tr></thead><tbody><tr><td>setParameter</td> <td>Create/update a remote parameter</td> </tr><tr><td>deleteParameter</td> <td>Remove a parameter from the remote store</td> </tr></tbody></table><h3 data-id="graphql-api">GraphQL API</h3> <h3 data-id="query-parameter">Query: <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">parameter</code></h3> <table><thead><tr><th><em>Argument</em></th> <th><em>Type</em></th> <th><em>Required?</em></th> </tr></thead><tbody><tr><td>name</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code></td> <td>Yes</td> </tr></tbody></table><p><strong><em>Returns</em></strong>: Parameter</p> <p><strong><em>Example</em></strong>:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">query Query($name: String!) { parameter(name: $name) { name value secret lastUpdatedOn } } </pre> <h3 data-id="query-parameterlist">Query: <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">parameterList</code></h3> <table><thead><tr><th><em>Argument</em></th> <th><em>Type</em></th> <th><em>Required?</em></th> <th><em>Default</em></th> </tr></thead><tbody><tr><td>limit</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">number</code></td> <td>No</td> <td>100</td> </tr><tr><td>cursor</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code></td> <td>No (unless paginating)</td> <td>n/a</td> </tr></tbody></table><p><strong><em>Returns</em></strong>: Paginated</p> <p><strong><em>Example</em></strong>:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">query Query($limit: Int, $cursor: String) { parameterList(limit: $limit, cursor: $cursor) { items { name value secret lastUpdatedOn } pageInfo { endCursor hasNextPage } } } </pre> <h3 data-id="mutation-setparameter">Mutation: <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">setParameter</code></h3> <table><thead><tr><th><em>Argument</em></th> <th><em>Type</em></th> <th><em>Required?</em></th> <th><em>Default</em></th> </tr></thead><tbody><tr><td>name</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code></td> <td>Yes</td> <td>n/a</td> </tr><tr><td>value</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">string</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">number</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">boolean</code> | <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">list</code></td> <td>Yes</td> <td>n/a</td> </tr><tr><td>secret</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">boolean</code></td> <td>No</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">false</code></td> </tr></tbody></table><h3 data-id="returns"><strong><em>Returns</em></strong></h3> <pre class="code codeBlock" spellcheck="false" tabindex="0">{ success: boolean } </pre> <p><strong><em>Example</em></strong></p> <pre class="code codeBlock" spellcheck="false" tabindex="0">mutation Mutation($name: String!, $value: ParameterValue!) { setParameter(name: $name, value: $value) { success } } </pre> <p><strong><em>List Parameters Variables Example</em></strong></p> <pre class="code codeBlock" spellcheck="false" tabindex="0">{ "name": "items", "value": ["jupiterone.com", 2] // multi-type arrays are allowed } </pre> <p><strong><em>Non-List Parameters Variables Example</em></strong></p> <pre class="code codeBlock" spellcheck="false" tabindex="0">{ "name": "j1domain", "value": "jupiterone.com" } </pre> <h4 data-id="mutation-deleteparameter">Mutation: <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">deleteParameter</code></h4> <table><thead><tr><th><em>Argument</em></th> <th><em>Type</em></th> <th><em>Required?</em></th> </tr></thead><tbody><tr><td>name</td> <td><code class="code codeInline code codeInline" spellcheck="false" tabindex="0">Array<string></code></td> <td>Yes</td> </tr></tbody></table><h4 data-id="returns-1"><strong><em>Returns</em></strong></h4> <pre class="code codeBlock" spellcheck="false" tabindex="0">{ success: boolean } </pre> <p><strong><em>Example</em></strong></p> <pre class="code codeBlock" spellcheck="false" tabindex="0">mutation Mutation($name: String!) { deleteParameter(name: $name) { success } } </pre> <h2 data-id="parameter-references">Parameter References</h2> <p>You can reference parameters in <a rel="nofollow" href="https://jupiterone.vanillacommunities.com/kb/articles/784-jupiterone-alert-rule-schema">rules' configurations</a> or any <a rel="nofollow" href="https://jupiterone.vanillacommunities.com/kb/articles/980-introduction-to-jupiterone-query-language-j1ql">query expression</a>, although the syntax is slightly different between the two. <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">param</code> is a special keyword that, when invoked, fetches values from the parameter-storing service.</p> <p><strong>Note:</strong> In the case of both rules and queries, referencing a nonexistent parameter causes an error and abandon execution.</p> <h2 data-id="auditing-and-security">Auditing and Security</h2> <p>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.</p> <h2 data-id="secret-parameters">Secret Parameters</h2> <p>Any parameters set with <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">secret</code> to be <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">true</code> 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.</p> <p><strong>Note:</strong> By design, you cannot update a parameter that has had <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">secret</code> set to true to <code class="code codeInline code codeInline" spellcheck="false" tabindex="0">secret: false</code> without also changing the value in the same request.</p> </article> </main>
.png)