shell

Shell

This guide describes the shell utility nw-shell that can be used to troubleshoot the operations of NetWitness management services like security-server, investigate-server, and correlation-server. It is the equivalent of the NwConsole utility used to interact with NetWitness capture services like Decoders and Concentrators. The shell utility is independent of the business logic of the service, and works the same with most NetWitness services.

Features

The nw-shell utility implements the following features:

Supports secure connections to the local NetWitness service instances.
Supports navigation of the service tree to explore its operational state (for more information, see Tree View).
Provides an intuitive display of configuration, metrics, and health-check information to help with troubleshooting.
Supports scripting to automate simple administration tasks in field deployments.
Supports Linux, OSX and Windows terminals.

Installation

The nw-shell utility can be installed with the rsa-nw-shell RPM as shown here:

   $ sudo yum install rsa-nw-shell
$ /usr/local/bin/nw-shell
████████ ██████ ██
██ ██ ██ ████
██ ██ ██ ██ ██
██ ████ ██████ ██ ██
██ ██ ██ ██ ██
██ ██ ██ ██ ██
██ ██ ███████ ██ ██
RSA NetWitness Shell. Version: 4.0.0
See "help" to list available commands, "help connect" to get started.
offline »
  

Usage

The primary goal of nw-shell is to help a human operator explore the runtime state of a NetWitness service. It is, essentially, an interactive program that invokes APIs on running NetWitness services. Each NetWitness service includes a system API that exposes its runtime state as a logical tree. The shell leverages the Tree API structure to present a hierarchical view of a service that is similar to a file system view. Users can navigate the tree by using the cd command to access directories, and can view or modify the corresponding configuration at the location, or invoke API methods and view the current state of components in the node.

The set of commands available to users at a given time depend on the current shell context, for example, their placement inside the logical tree. Certain commands, however, are always available, and we begin with a description of those commands.

System Commands

Shell system commands operate on the shell itself, instead of the nodes of a connected service. These commands are always available.

Use the help to explore the available commands. It is always available.
nw-shell supports tab completion of a command, and the applicable parameter names wherever possible. For example, pressing the Tab key after typing e completes the command to exit.
nw-shell also supports a non-interactive mode where it executes scripts from a provided file, used by specifying the absolute filepath prefixed by the @ argument. See Shell for details.

Available Commands

    Built-In Commands
    
 clear: Clear the shell screen.
    
 exit, quit: Exit the shell.
    
 help: Display help about available commands.
    
 history: Display or save the history of previously run commands
    
 script: Read and execute commands from a file.
    
 stacktrace: Display the full stacktrace of the last error.
    
Context Commands
    
 * cd: Change the current node. Usage: cd <path> 
    
 connect: Connect to a service. One of --service or --port must be specified.Usage: connect [--service <service>[.<id>]] [--broker amqp://localhost/rsa/system] [--host localhost] [--port] [--insecure false]
    
 * where: Which service shell is connected to?
    
Token Commands
    
 login: Authenticate to a service. Usage: login [connect-parameters]
    
 login-insecure: Authenticate to a service providing user and password on the command prompt. The password is recorded in the shell history so this command must be used with care.Usage: login-insecure --user <user> --password <password> [connect-parameters]
    
 * logout: Clear the authentication context: logout
    
 * whoami: Who am I?
    
Tree Node Commands
    
 * json: Print the current node as a JSON string
    
 * show: Pretty print the current node
    
Tree Node List Commands
    
 * config: Summarize configuration of the current subtree
    
 * health: Summarize health of the current subtree
    
 * ls: List the children of the current node. Usage: ls [<filter>] [--values] [--types]
    
 * lsv: Shorthand for ls --values. Usage: lsv [<filter>] [--types]
    
 * method: Summarize methods of the current subtree
    
 * metrics: Summarize metrics of the current subtree
    
 * snapshot: Snapshot the current subtree
    
Tree Node Method Commands
    
 * invoke: Invokes the method that exists on the current method type node. Usage: invoke [argument] [--file jsonfile]
    
Tree Node Value Commands
    
 * get: Get the value of the current node
    
 * set: Set the value of the current node. Usage: set <new-value>
    
Commands marked with (*) are currently unavailable.
    
Type `help <command>` to learn more.

Help, History Command Usage

     offline » help connect
     
 connect - Connect to a service. One of --service or --port must be specified. Usage: connect [--service <service>[.<id>]] [--broker amqp://localhost/rsa/system] [--host localhost] [--port] [--insecure false]
     
 ...
     
 ...
     
offline » history
     
help
     
help connect
     
history
     
offline »

You can navigate previously-typed commands in nw-shell by using the Up and Down arrow keys, which can help minimize typing by recalling previously-executed commands.

Authentication Commands

As an administration and monitoring tool, it is important that nw-shell authenticates users before handing them control over a running service. The following commands manage the shell authentication context:

The login command can be used to authenticate the user and establish an identity. Service operators can log in once (against the NetWitness Security Server) and then use the token to connect to multiple services and perform administration based on the roles assigned. This single-sign-on workflow is simplified by separating the login and connect commands to allow the operator to authenticate once (using login) and then switch services seamlessly using connect.

In general, the login command takes the same parameters as connect (described below) to specify the service that performs the credential validation. For example:

    offline » login
user: admin
password: ********
admin@offline » connect --service respond-server
INFO: Connected to respond-server (23e1dab7-0658-41a5-bb1e-d716a37d5ea5)
admin@respond-server:Folder:/rsa »
admin@respond-server:Folder:/rsa » connect --service investigate-server
INFO: Connected to investigate-server 2f21db20-4b50-48cf-8f7f-c0be0d1d1d12)
admin@investigate-server:Folder:/rsa »
   

The current logged-in identity can be confirmed at any point using the whoami command. For example:

admin@offline » whoami

The shell security context can be cleared by using the logout command.

    security-server:Folder:/rsa » logout
security-server:Folder:/rsa » whoami
You are not logged in.
   

Some operations, such as setting certain configuration properties or invoking a method, require a certain RBAC. To perform such privileged operations, you need to authenticate with an identity that has the necessary permissions. For example:

    security-server:Configuration » /rsa/logging/operations/max-file-count » get
    
10
    
security-server:Configuration:/rsa/logging/operations/max-file-count » set 15
    
ERROR: Failed to set the node value: Access is denied
    
security-server:Configuration:/rsa/logging/operations/max-file-count » login
    
user: admin
    
password: **********
    
admin@security-server:Configuration:/rsa/logging/operations/max-file-count » set 15
    
security-server:Configuration:/rsa/logging/operations/max-file-count » get
    
15

Context-Changing Commands

The following commands change the current shell context.

Connecting to a Service

The shell can connect to services over AMQP or HTTP(S), however, AMQP is the preferred and default option.

To connect to a specific instance of a service, name and serviceId needs to be supplied in the format:
connect --service {service-name}.{serivceId}
For example, foo-server.d6a55b48-6103-46bd-9ead-3b4d589b302b.

If the service identifier is skipped, it is assumed to be any, for example, connect --service foo-server will connect with any service named foo-server that is connected to the AMQP broker.

Change Node

The cd command can be used to change the current node. Just like cd on a file system shell, it takes relative or absolute paths as input and changes the current context to the node at that path.

    offline » cd
Command 'cd' was found but is not currently available because you are not connected to any service.

offline » connect
security-server:Folder:/rsa » cd log
security-server:Folder:/rsa/logging » cd ../security
security-server:Component:/rsa/security » cd /rsa/security/fips-mode
security-server:Configuration:/rsa/security/fips-mode » cd
security-server:Folder:/rsa »
   

The shell prompt summarizes and presents the user’s current context. It starts off with offline, and once the shell is connected to a service, it displays the service name it is connected to, and the type and the path of the current node. Once the user is authenticated, the userId is included in the prompt.

Invoking cd before connecting to a service reminds the user that some commands work only in certain contexts.

Note: Some commands are available only in certain contexts. For example, cd works only when the shell is online. The Help command lists all the commands, but commands marked with (*) are unavailable in the given context.

Certain node-specific commands are enabled only when the current node is of a certain type. For example, method nodes support a command invoke, which is not enabled for any other node type.

Node Display Commands

The following commands are available with all node types. They do not take any arguments, and display the node details for the user to review.

For example:

security-server:Configuration:/rsa/security/authentication/token-lifetime » show

   
security-server:Configuration » /rsa/security/authentication/token-lifetime » json
{ 
 "path" : "/rsa/security/authentication/token-lifetime",
 "type" : "Configuration",
 "value" : "10 HOURS",
 "parent" : {
 "path" : "/rsa/security/authentication",
 "type" : "Component" 
 },
 "attributes" : {
 "defaultValue" : 10,
 "valueType" : "com.rsa.asoc.launch.api.helpers.Seconds",
 "description" : "The time-to-live on a token."
 }
}
  

The output of json dumps the API payload and may contain more details than those shown by show.

Node Value Commands

Configuration, Metric and Health nodes have values. Their current values can be obtained using the get command.

For example:

   security-server:Gauge:/rsa/process/hostname » get
"hostxyz.corp.emc.com" 
security-server:Gauge:/rsa/process/hostname » cd /rsa/transport/http/secure
security-server:Configuration:/rsa/transport/http/secure » get
true
  

The value of a Configuration node can be changed by invoking the set command. For example:

admin@security-server:Configuration:/rsa/security/pki/tls-protocols » show

   admin@security-server:Configuration:/rsa/security/pki/tls-protocols » set '["SSLv3"]' 
admin@security-server:Configuration:/rsa/security/pki/tls-protocols » value
[ 
 "SSLv3" 
]
  

Node List Commands

Folder, Component and Method nodes can contain other nodes as their children. You can use the ls command to list the children nodes, their types, and where available, their current values.