Update examples with argument parsing#298

Open

zeroSteiner wants to merge 19 commits intorapid7:masterfrom

zeroSteiner:feat/examples-with-args

Contributor

zeroSteiner commented Apr 28, 2026

This updates each of the examples scripts to use OptionParser and respond to -h / --help. This allows the operator to get the help output from the script and see the arguments without needing to review the source code.

Can validate the arguments for each by running for script in examples/*; do ruby "$script" -h; done.

The arguments that each take are standardized and were already used by the handful that originally used OptionParser such as read_file.rb.

zeroSteiner added 19 commits

April 28, 2026 16:04


          Update examples/authenticate.rb to use OptionParser

f565419

Replace raw ARGV access with OptionParser following the convention used
in examples/read_file.rb and examples/anonymous_auth.rb. Adds --[no-]smbv1/2/3,
--username (with domain\username splitting), and --password flags. Prints
the help banner when target is missing or when -h/--help is given. The
existing five-combination test cycle is preserved but filtered by the
user's selected SMB versions.


          Update examples/append_file.rb to use OptionParser

cf9d8e5

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/delete_file.rb to use OptionParser

e6868f8

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/dump_secrets_from_sid.rb to use OptionParser

c1bf166

Replace raw ARGV access with OptionParser following the existing convention.
Adds --username (with domain\username splitting) and --password flags;
keeps the AD lookup domain and SID as positional arguments. Prints the help
banner when a required positional is missing or when -h/--help is given.

Also requires 'ruby_smb' so the script loads independently — the previous
'ruby_smb/dcerpc/client' require alone was failing with an uninitialized
Net::NTLM constant.


          Update examples/enum_domain_users.rb to use OptionParser

fd9c2bf

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags; keeps the AD lookup domain as a positional argument.
Prints the help banner when a required positional is missing or when
-h/--help is given.


          Update examples/enum_registry_key.rb to use OptionParser

cae8892

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/enum_registry_values.rb to use OptionParser

94d0192

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/get_computer_info.rb to use OptionParser

58f8c96

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when target is missing or when
-h/--help is given.


          Update examples/list_directory.rb to use OptionParser

63f2254

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/negotiate.rb to use OptionParser

551d485

Replace raw ARGV access with OptionParser following the existing convention
used in examples/authenticate.rb. Adds --[no-]smbv1/2/3 flags that filter
the seven hardcoded SMB version combinations. Drops the unused hardcoded
msfadmin credentials (negotiate does not authenticate). Prints the help
banner when target is missing or when -h/--help is given.


          Update examples/negotiate_with_netbios_service.rb to use OptionParser

b9c913c

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3 flags that filter the five hardcoded SMB version
combinations and a --netbios-name flag (default *SMBSERVER) replacing the
optional second positional. Drops the unused hardcoded msfadmin credentials
(this script does not authenticate). Prints the help banner when target is
missing or when -h/--help is given.


          Update examples/net_share_enum_all.rb to use OptionParser

f3807f1

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when target is missing or when
-h/--help is given.


          Update examples/pipes.rb to use OptionParser

9308c5b

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/query_service_status.rb to use OptionParser

366b8a4

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/read_file_encryption.rb to use OptionParser

8141da3

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3 (defaults: SMB1/2 disabled, SMB3 enabled to force
encryption-capable negotiation), --username (with domain\username
splitting), and --password flags. Prints the help banner when a required
positional is missing or when -h/--help is given.

Also splat the client options hash so the call works on Ruby 3.x where
non-keyword hash positionals are no longer auto-converted.


          Update examples/read_registry_key_value.rb to use OptionParser

f6b3c2d

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/rename_file.rb to use OptionParser

6be1ee0

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Update examples/write_file.rb to use OptionParser

e96489d

Replace raw ARGV access with OptionParser following the existing convention.
Adds --[no-]smbv1/2/3, --username (with domain\username splitting), and
--password flags. Prints the help banner when a required positional is
missing or when -h/--help is given.


          Print help when -h/--help is the only argument to anonymous_auth.rb

5dc2515

Without this, the positional pop consumed -h/--help as the target and the
script then tried to open a TCP socket to that string. Now matches the
behavior added to authenticate.rb and the other examples.

zeroSteiner mentioned this pull request

Don't report anonymous as a success when relaying rapid7/metasploit-framework#21390

Open

4 tasks

smcintyre-r7 requested a review from Copilot

April 28, 2026 21:31

Copilot started reviewing on behalf of smcintyre-r7

April 28, 2026 21:32

Copilot AI reviewed

View reviewed changes

Copilot AI left a comment

Pull request overview

This PR standardizes argument parsing across the examples/ Ruby scripts by switching them to OptionParser and aligning common flags (SMB version toggles and credentials) so operators can discover usage via -h/--help.

Changes:

Adds OptionParser-based CLI parsing to many example scripts, including SMB dialect toggles and --username/--password (with optional DOMAIN\user parsing).
Updates example usage text and refactors scripts to consume named options plus positional arguments consistently.
Adjusts specific examples to support additional parameters (e.g., NetBIOS called name flag, SMBv3 encryption defaults).

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
examples/write_file.rb	Adds OptionParser + positional parsing for target/share/file/data and SMB dialect toggles.
examples/rename_file.rb	Adds OptionParser + positional parsing for target/share/file/new_name and SMB dialect toggles.
examples/read_registry_key_value.rb	Adds OptionParser + positional parsing for target/registry_key/value_name and SMB dialect toggles.
examples/read_file_encryption.rb	Adds OptionParser + positional parsing for target/share/file; defaults to SMBv3-only for encryption testing.
examples/query_service_status.rb	Adds OptionParser + positional parsing for target/service and SMB dialect toggles.
examples/pipes.rb	Adds OptionParser + positional parsing for target/pipename and SMB dialect toggles.
examples/net_share_enum_all.rb	Adds OptionParser + positional parsing for target and SMB dialect toggles.
examples/negotiate_with_netbios_service.rb	Adds OptionParser + SMB dialect toggles + `--netbios-name` for the NetBIOS called name.
examples/negotiate.rb	Adds OptionParser + SMB dialect toggles and iterates supported negotiation combinations.
examples/list_directory.rb	Adds OptionParser + positional parsing for target/share/directory and SMB dialect toggles.
examples/get_computer_info.rb	Adds OptionParser + positional parsing for target and SMB dialect toggles.
examples/enum_registry_values.rb	Adds OptionParser + positional parsing for target/registry_key and SMB dialect toggles.
examples/enum_registry_key.rb	Adds OptionParser + positional parsing for target/registry_key and SMB dialect toggles.
examples/enum_domain_users.rb	Adds OptionParser + positional parsing for target/domain and SMB dialect toggles.
examples/dump_secrets_from_sid.rb	Adds OptionParser + positional parsing for target/domain/sid and credentials flags.
examples/delete_file.rb	Adds OptionParser + positional parsing for target/share/file and SMB dialect toggles.
examples/authenticate.rb	Adds OptionParser + SMB dialect toggles + credentials/domain handling for auth testing.
examples/append_file.rb	Adds OptionParser + positional parsing for target/share/file/data and SMB dialect toggles.
examples/anonymous_auth.rb	Adds `-h/--help` handling around OptionParser for anonymous authentication example.

Impact Analysis: isolated change; no meaningful downstream impact identified from diff.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

examples/write_file.rb

Comment on lines +26 to +30

+              options[:data] = args.pop
+              options[:file] = args.pop
+              options[:share] = args.pop
+              options[:target] = args.pop
+              optparser = OptionParser.new do |opts|

examples/write_file.rb

		@@ -35,8 +78,8 @@
		puts "Failed to connect to #{path}: #{e.message}"

examples/negotiate_with_netbios_service.rb

Comment on lines +4 to 7

+              # Example usage: ruby negotiate_with_netbios_service.rb 192.168.172.138 NBNAME
+              # This will connect to 192.168.172.138 (139/TCP) and request a NetBIOS session with NBNAME as the called name.
               # If successful, a SMB negotiation is performed using this NetBIOS session.
               # The default *SMBSERVER name is used if the NetBIOS name is not provided.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet