RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide Contact Information RSA Link at https://community.rsa.com contains a knowledge base that answers common questions and provides solutions to known problems, product documentation, community discussions, and case management. Trademarks RSA Conference Logo, RSA, and other trademarks, are trademarks of RSA Security LLC or its affiliates ("RSA"). For a list of RSA trademarks, go to https://www.rsa.com/en-us/company/rsa-trademarks. Other trademarks are trademarks of their respective owners. License Agreement This software and the associated documentation are proprietary and confidential to RSA Security LLC or its affiliates are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice below. This software and the documentation, and any copies thereof, may not be provided or otherwise made available to any other person. No title to or ownership of the software or documentation or any intellectual property rights thereto is hereby transferred. Any unauthorized use or reproduction of this software and the documentation may be subject to civil and/or criminal liability. RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide This software is subject to change without notice and should not be construed as a commitment by RSA. Third-Party Licenses This product may include software developed by parties other than RSA. The text of the license agreements applicable to third-party software in this product may be viewed on the product documentation page on RSA Link. By using this product, a user of this product agrees to be fully bound by terms of the license agreements. Note on Encryption Technologies This product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when using, importing or exporting this product. Distribution Use, copying, and distribution of any RSA Security LLC or its affiliates ("RSA") software described in this publication requires an applicable software license. RSA believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide THE INFORMATION IN THIS PUBLICATION IS PROVIDED "AS IS." RSA MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. © 2020 RSA Security LLC or its affiliates. All Rights Reserved. June 2021 RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide Contents Shell 7 Features 7 Installation 7 Usage 8 System Commands 8 Available Commands 8 Help, History Command Usage 10 Authentication Commands 10 Context-Changing Commands 12 Connecting to a Service 12 Change Node 12 RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide Node Display Commands 13 Node Value Commands 14 Node List Commands 15 Method Node Commands 17 Run State of a Service 18 Health 18 Respond Server APIs 18 Retrieve Incidents 19 Retrieve Incident Details 19 Retrieve Alerts 20 Add Alerts to an Incident 21 Delete Alerts from an Incident 22 Metrics 22 Config 23 Snapshot 23 RSA® NetWitness Platform Version 11.6 NetWitness Shell User Guide Scripting 24 Troubleshooting Commands 25 fix-keystore 25 print-keystore 26 reconstruct-keystore 26 Advanced Customization 26 Tree View 28 Features 28 Implementation 28 Node Types 28 Node Structure 29 NetWitness Shell User Guide Shell This guide describes the shell utility nw-shell that can be used to troubleshoot the operations of NetWitness Platform management services like security-server, investigate-server, and correlation-server. It is the equivalent of the NwConsole utility used to interact with NetWitness Platform 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 Platform services. Features The nw-shell utility implements the following features: l Supports secure connections to the local NetWitness Platform service instances. l Supports navigation of the service tree to explore its operational state (for more information, see Tree View). l Provides an intuitive display of configuration, metrics, and health-check information to help with troubleshooting. l Supports scripting to automate simple administration tasks in field deployments. l 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 » 7 Shell NetWitness Shell User Guide Usage The primary goal of nw-shell is to help a human operator explore the runtime state of a NetWitness Platform service. It is, essentially, an interactive program that invokes APIs on running NetWitness Platform services. Each NetWitness Platform 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. Command Function Example help [<command>] Provides help on available commands or a help or help connect particular command. clear Clears the screen (shortcut Ctrl-l). clear exit or quit Exits the shell. quit history Displays the history of previously-run history commands. l Use the help <command> to explore the available commands. It is always available. l 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. l 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 Shell 8 NetWitness Shell User Guide 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 9 Shell NetWitness Shell User Guide 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