Adds wiki guide for session searching

Also tweaks an error message add readme to directory
rapid7 · Oct 23, 2023 · 8331f4d · 8331f4d
1 parent 30e1930
commit 8331f4d
Show file tree

Hide file tree

Showing 4 changed files with 68 additions and 2 deletions.
diff --git a/docs/metasploit-framework.wiki/Managing-Sessions.md b/docs/metasploit-framework.wiki/Managing-Sessions.md
@@ -0,0 +1,62 @@
+## Sessions Command
+
+### Session Search
+
+When you have a number of sessions open, searching can be a useful tool to navigate them. This guide explains what capabilities are available for navigating open sessions with search.
+
+You can get a list of sessions matching a specific criteria within msfconsole:
+
+```msf
+msf6 payload(windows/meterpreter/reverse_http) > sessions --search "session_id:1 session_id:2"
+Active sessions
+===============
+
+  Id  Name  Type                     Information                                    Connection
+  --  ----  ----                     -----------                                    ----------
+  1         meterpreter x86/windows  WIN-ED9KFH65RDH\Zach Goldman @WIN-ED9KFH65RDH  192.168.2.1:4444 -> 192.168.2.132:52190 (192.168.2.132)                                         
+                                                      
+```
+
+Currently, the only supported keywords for search are `session_id`, `session_type`, and `last_checkin`. These keywords can be combined to further filter your results, and used with other flags. For example:
+
+```msf
+msf6 payload(windows/meterpreter/reverse_http) > sessions --search "session_id:1 session_type:meterpreter last_checkin:greater_than:10s last_checkin:less_than:10d5h2m30s" -v
+
+Active sessions
+===============
+
+  Session ID: 1
+        Name:
+        Type: meterpreter windows
+        Info: WIN-ED9KFH65RDH\Zach Goldman @ WIN-ED9KFH65RDH
+      Tunnel: 192.168.2.1:4444 -> 192.168.2.132:52190 (192.168.2.132)
+         Via: exploit/multi/handler
+   Encrypted: Yes (AES-256-CBC)
+        UUID: 958f7b976db67d60/x86=1/windows=1/2023-10-19T12:38:05Z
+     CheckIn: 21725s ago @ 2023-10-19 09:26:08 -0500
+  Registered: No
+
+```
+
+Of note in the above example, `last_checkin` requires an extra argument. The second argument must be either `greater_than` or `less_than`. The third argument can be a sequence of alternating amounts and units of time (d: days, h: hours, m: minutes, and s: seconds), i.e. `5m2s`, `10d`, or `1d5m`.
+
+### Killing stale sessions
+
+If `--search` is used in conjunction with `--kill-all`, it will restrict the latter function to only the search results. For example:
+
+```msf
+msf6 payload(windows/meterpreter/reverse_http) > sessions -K -S "session_type:meterpreter"
+[*] Killing matching sessions...
+
+Active sessions
+===============
+
+  Id  Name  Type                     Information                                     Connection
+  --  ----  ----                     -----------                                     ----------
+  1         meterpreter x86/windows  WIN-ED9KFH65RDH\Zach Goldman @ WIN-ED9KFH65RDH  192.168.2.1:4444 -> 192.168.2.132:52190 (192.168.2.132)
+  2         meterpreter x86/windows  WIN-ED9KFH65RDH\Zach Goldman @ WIN-ED9KFH65RDH  192.168.2.1:4444 -> 192.168.2.132:52192 (192.168.2.132)
+
+[*] 192.168.2.132 - Meterpreter session 1 closed.
+[*] 192.168.2.132 - Meterpreter session 2 closed.
+msf6 payload(windows/meterpreter/reverse_http) >
+```
diff --git a/docs/navigation.rb b/docs/navigation.rb
@@ -272,6 +272,10 @@ def without_prefix(prefix)
           {
             path: 'How-to-use-msfvenom.md',
             nav_order: 7
+          },
+          {
+            path: 'Managing-Sessions.md',
+            nav_order: 8
           }
         ]
       },

diff --git a/lib/msf/ui/console/command_dispatcher/core.rb b/lib/msf/ui/console/command_dispatcher/core.rb
@@ -1860,7 +1860,7 @@ def get_matching_sessions(search_term)
       when LAST_CHECKIN
         checkin_searches << term
       else
-        print_error("Please provide valid search term. Given: #{term.split(':').first}")
+        print_error("Please provide valid search term. Given: #{term.split(':').first}. Supported keywords are: #{VALID_SESSION_SEARCH_PARAMS.join(', ')}")
         return nil
       end
     end

diff --git a/spec/lib/msf/ui/console/command_dispatcher/core_spec.rb b/spec/lib/msf/ui/console/command_dispatcher/core_spec.rb
@@ -434,7 +434,7 @@ def set_tabs_test(option)
       it 'When the user searches for an invalid field' do
         core.cmd_sessions('--search', 'not_a_term:1')
         expect(@combined_output.join("\n")).to match_table <<~TABLE
-          Please provide valid search term. Given: not_a_term
+          Please provide valid search term. Given: not_a_term. Supported keywords are: last_checkin, session_id, session_type
         TABLE
       end
     end