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 
    
      connect: Connect to a service. One of --service or --port must be specified.Usage: connect [--service 
     
      [.
      
       ]] [--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 
       
         --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 [
         
          ] [--values] [--types] * lsv: Shorthand for ls --values. Usage: lsv [
          
           ] [--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 
           
             Commands marked with (*) are currently unavailable. Type `help 
            ` to learn more.
           
          
         
        
       
      
     
    

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

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.

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.

Change Node

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 »

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.

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.

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.