From 8331f4d2adc2ecc3996f637e55ff9facd7fcbbcb Mon Sep 17 00:00:00 2001 From: Zach Goldman Date: Thu, 19 Oct 2023 15:36:37 -0500 Subject: [PATCH] Adds wiki guide for session searching Also tweaks an error message add readme to directory --- .../Managing-Sessions.md | 62 +++++++++++++++++++ docs/navigation.rb | 4 ++ lib/msf/ui/console/command_dispatcher/core.rb | 2 +- .../console/command_dispatcher/core_spec.rb | 2 +- 4 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 docs/metasploit-framework.wiki/Managing-Sessions.md diff --git a/docs/metasploit-framework.wiki/Managing-Sessions.md b/docs/metasploit-framework.wiki/Managing-Sessions.md new file mode 100644 index 000000000000..d0dd774c7938 --- /dev/null +++ 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 index 7dda31aede68..00b5eb1d5fa0 100644 --- 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 index 53c55804fc79..ce08f3cb5d48 100644 --- 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 index 6dea03e61bd1..ec2f21bd53eb 100644 --- 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