Skip to main content

NVIDIA OpenShell

This Integration is part of the NVIDIA OpenShell Pack.#

Supported versions

Available on Cortex XSOAR (versions 6.10.0 and later) and Cortex XSIAM.

Respond to AI agent threats in NVIDIA OpenShell sandboxes: stop or suspend a sandbox, block its egress to a host, and detach its credentials. This integration was integrated and tested with version 0.1.6 of NVIDIA OpenShell.

Configure NVIDIA OpenShell in Cortex#

ParameterDescriptionRequired
Gateway endpoint (host:port)The OpenShell gateway gRPC endpoint, for example openshell-gateway.example.com:17670. The gateway is usually private, so run this integration on an engine that can reach it.True
Gateway CA certificateThe PEM CA certificate that signed the gateway certificate (ca.crt). Leave empty to use the system trust store.False
Client certificateThe PEM client certificate for mutual TLS (tls.crt).False
Client private keyThe PEM private key of the client certificate (tls.key).False
OIDC bearer tokenAn OIDC access token, only for gateways configured for OIDC authentication. The token is not refreshed, so use a long-lived token and update this field before it expires.False
WorkspaceThe default OpenShell workspace for commands that do not specify one.False
Plaintext gateway (no TLS)Whether to connect without TLS. Not secure. Use only for test gateways that do not use TLS.False
Timeout (seconds)The number of seconds to wait for each gateway call.False

Safety#

  • openshell-sandbox-delete and openshell-provider-detach cannot be undone and require confirm=yes.
  • Policy changes are recorded as new policy revisions on the gateway. Use openshell-policy-history to review them.
  • openshell-egress-block-host applies all removals in one policy update, so it either fully succeeds or changes nothing. It does not remove wildcard entries (for example *.example.com), because that would block other hosts too; it lists them so you can remove them with openshell-policy-endpoint-remove or stop the sandbox.

Commands#

You can execute these commands from the CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

openshell-gateway-info-get#


Returns the OpenShell gateway version and information.

Base Command#

openshell-gateway-info-get

Input#

There are no input arguments for this command.

Context Output#

PathTypeDescription
OpenShell.Gateway.EndpointStringThe gateway endpoint.
OpenShell.Gateway.VersionStringThe gateway version.
OpenShell.Gateway.InfoUnknownThe gateway information returned by the gateway.

openshell-sandbox-list#


Lists sandboxes and their phase.

Base Command#

openshell-sandbox-list

Input#

Argument NameDescriptionRequired
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
all_workspacesWhether to list sandboxes across all workspaces. Possible values are: true, false. Default is false.Optional
label_selectorThe Kubernetes-style label selector to filter sandboxes by, for example team=ml.Optional
limitThe maximum number of sandboxes to return. Default is 50.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.

openshell-sandbox-get#


Returns a single sandbox.

Base Command#

openshell-sandbox-get

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.

openshell-sandbox-stop#


Stops a sandbox. The agent stops running. Its identity and workspace are kept, so it can be started again after the investigation.

Base Command#

openshell-sandbox-stop

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
waitWhether to wait until the sandbox reports STOPPED. Possible values are: true, false. Default is true.Optional
timeout_secondsThe number of seconds to wait for the sandbox to stop. Default is 120.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.
OpenShell.Sandbox.ActionStringThe action that was requested.

openshell-sandbox-start#


Starts a stopped sandbox.

Base Command#

openshell-sandbox-start

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.
OpenShell.Sandbox.ActionStringThe action that was requested.

openshell-sandbox-suspend#


Suspends a sandbox and keeps its state. Requires a sandbox driver that supports suspend.

Base Command#

openshell-sandbox-suspend

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.
OpenShell.Sandbox.ActionStringThe action that was requested.

openshell-sandbox-resume#


Resumes a suspended sandbox.

Base Command#

openshell-sandbox-resume

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.WorkspaceStringThe sandbox workspace.
OpenShell.Sandbox.PhaseStringThe sandbox phase, for example READY, STOPPED or SUSPENDED.
OpenShell.Sandbox.PolicyVersionNumberThe active policy version.
OpenShell.Sandbox.LabelsUnknownThe sandbox labels.
OpenShell.Sandbox.ActionStringThe action that was requested.

openshell-sandbox-delete#


Deletes a sandbox. This action cannot be undone.

Base Command#

openshell-sandbox-delete

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
confirmWhether to confirm the action, which cannot be undone. Set to yes to run it. Possible values are: yes, no.Required
allow_missingWhether to succeed if the sandbox does not exist. Possible values are: true, false. Default is false.Optional

Context Output#

PathTypeDescription
OpenShell.Sandbox.NameStringThe sandbox name.
OpenShell.Sandbox.IDStringThe sandbox ID.
OpenShell.Sandbox.OutcomeStringThe deletion outcome.
OpenShell.Sandbox.ActionStringThe action that was requested.

openshell-sandbox-logs#


Returns recent sandbox log lines, such as network decisions, process and policy events.

Base Command#

openshell-sandbox-logs

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
linesThe number of log lines to return. Default is 200.Optional
min_levelThe minimum log level to return, for example WARN.Optional
sourcesThe comma-separated list of log sources to include.Optional

Context Output#

PathTypeDescription
OpenShell.Log.SandboxStringThe sandbox name.
OpenShell.Log.TimeDateThe event time in ISO 8601 format (e.g., 2024-01-15T12:34:56Z).
OpenShell.Log.LevelStringThe log level.
OpenShell.Log.SourceStringThe log source.
OpenShell.Log.TargetStringThe log target.
OpenShell.Log.MessageStringThe log message.

openshell-policy-get#


Returns the current network policy of a sandbox: rules, hosts, ports and allowed binaries.

Base Command#

openshell-policy-get

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Policy.SandboxStringThe sandbox name.
OpenShell.Policy.VersionNumberThe policy version.
OpenShell.Policy.PolicyHashStringThe policy hash.
OpenShell.Policy.NetworkRules.RuleStringThe network rule name.
OpenShell.Policy.NetworkRules.HostStringThe allowed host.
OpenShell.Policy.NetworkRules.PortsNumberThe allowed ports.
OpenShell.Policy.NetworkRules.ProtocolStringThe protocol.
OpenShell.Policy.NetworkRules.PathStringThe allowed path.
OpenShell.Policy.NetworkRules.BinariesStringThe binaries allowed to use the rule.

openshell-policy-history#


Returns the policy revisions of a sandbox, newest first.

Base Command#

openshell-policy-history

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
limitThe maximum number of revisions to return. Default is 20.Optional

Context Output#

PathTypeDescription
OpenShell.PolicyRevision.SandboxStringThe sandbox name.
OpenShell.PolicyRevision.VersionNumberThe policy version.
OpenShell.PolicyRevision.StatusStringThe revision status.
OpenShell.PolicyRevision.HashStringThe policy hash.
OpenShell.PolicyRevision.LoadErrorStringThe load error, if the revision failed to load.
OpenShell.PolicyRevision.CreatedDateThe time the revision was created in ISO 8601 format (e.g., 2024-01-15T12:34:56Z).

openshell-egress-block-host#


Removes every exact allow entry for a host, on all ports and across all network rules, in one atomic policy update, so the agent can no longer reach that host. The sandbox keeps running. Wildcard entries that also cover the host (for example *.example.com) are not removed but are listed in the output.

Base Command#

openshell-egress-block-host

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
hostThe destination host, for example files.example.com.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
reasonThe reason for the change, recorded on the new policy revision. Default is Cortex response.Optional

Context Output#

PathTypeDescription
OpenShell.PolicyChange.SandboxStringThe sandbox name.
OpenShell.PolicyChange.NewVersionNumberThe new policy version.
OpenShell.PolicyChange.PolicyHashStringThe hash of the new policy.
OpenShell.PolicyChange.ChangeStringThe summary of the change.
OpenShell.PolicyChange.HostStringThe blocked host.
OpenShell.PolicyChange.RemovedFromRulesStringThe network rules the host was removed from.
OpenShell.PolicyChange.WildcardMatches.RuleStringThe network rule of a wildcard entry that still allows the host.
OpenShell.PolicyChange.WildcardMatches.HostStringThe wildcard entry that still allows the host.

openshell-policy-rule-remove#


Removes a network rule from the sandbox policy. All destinations of the rule are denied.

Base Command#

openshell-policy-rule-remove

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
rule_nameThe network rule name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
reasonThe reason for the change, recorded on the new policy revision. Default is Cortex response.Optional

Context Output#

PathTypeDescription
OpenShell.PolicyChange.SandboxStringThe sandbox name.
OpenShell.PolicyChange.NewVersionNumberThe new policy version.
OpenShell.PolicyChange.PolicyHashStringThe hash of the new policy.
OpenShell.PolicyChange.ChangeStringThe summary of the change.

openshell-policy-endpoint-remove#


Removes a single host and port from a network rule.

Base Command#

openshell-policy-endpoint-remove

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
rule_nameThe network rule name.Required
hostThe host to remove.Required
portThe port to remove. 0 removes the host on any port. Default is 0.Optional
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
reasonThe reason for the change, recorded on the new policy revision. Default is Cortex response.Optional

Context Output#

PathTypeDescription
OpenShell.PolicyChange.SandboxStringThe sandbox name.
OpenShell.PolicyChange.NewVersionNumberThe new policy version.
OpenShell.PolicyChange.PolicyHashStringThe hash of the new policy.
OpenShell.PolicyChange.ChangeStringThe summary of the change.

openshell-policy-binary-remove#


Removes a binary, for example /usr/bin/curl, from a network rule so it can no longer use that rule.

Base Command#

openshell-policy-binary-remove

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
rule_nameThe network rule name.Required
binary_pathThe binary path.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
reasonThe reason for the change, recorded on the new policy revision. Default is Cortex response.Optional

Context Output#

PathTypeDescription
OpenShell.PolicyChange.SandboxStringThe sandbox name.
OpenShell.PolicyChange.NewVersionNumberThe new policy version.
OpenShell.PolicyChange.PolicyHashStringThe hash of the new policy.
OpenShell.PolicyChange.ChangeStringThe summary of the change.

openshell-provider-list#


Lists the credential providers attached to a sandbox.

Base Command#

openshell-provider-list

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional

Context Output#

PathTypeDescription
OpenShell.Provider.SandboxStringThe sandbox name.
OpenShell.Provider.NameStringThe provider name.
OpenShell.Provider.TypeStringThe provider type.
OpenShell.Provider.WorkspaceStringThe provider profile workspace.

openshell-provider-detach#


Detaches a credential provider from a sandbox, so the agent no longer receives those credentials. This action cannot be undone.

Base Command#

openshell-provider-detach

Input#

Argument NameDescriptionRequired
nameThe sandbox name.Required
providerThe provider name.Required
workspaceThe OpenShell workspace. Defaults to the instance workspace.Optional
confirmWhether to confirm the action, which cannot be undone. Set to yes to run it. Possible values are: yes, no.Required

Context Output#

PathTypeDescription
OpenShell.Provider.SandboxStringThe sandbox name.
OpenShell.Provider.NameStringThe provider name.
OpenShell.Provider.ActionStringThe action that was performed.