net-scp 4.1.2 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1413e9916cf7c4d82160a87e9da29044528f7c32dc746d12a873ea4d902a940
-  data.tar.gz: b0e33d71c6a78b8d263fd95408e23188c3c7e0bb274d52c1df6745bbc6793cc6
+  metadata.gz: b666f903f4a48fb442f7ddea7efbdf5a222a44b7e2c9f7ae0cba5b6b8a126e10
+  data.tar.gz: 39032bdfeb545761cd2229af060ca0a79855e051ecab1123e2c68100deb03e19
 SHA512:
-  metadata.gz: 46648015028eb41a2d7f269f4fe6baa430289da17f82c2945c5ef49ff4fa43085a966734d7e361a98b08cd91f7abf99f219eeebd954607bc74969f398e861ceb
-  data.tar.gz: e307dc9bb8e181c76acb226ffc8b35f5c2002adbef0f027f8954b9e695cc8436b780a7f4316dba7b685a48048184676c20dacceb2db81d235dcf51a83045ddf5
+  metadata.gz: 8608726350662b31607e5beaa21d0276fa93942b045ac29a5762236b99b5a57925f9fde59a9fb59ebdd6ada2d6ccb1f52aa17f90e7ee196d2c7a714d66afce2d
+  data.tar.gz: 3c4112b0662c5401f6bc4e50aec2797a583faa5d67947ee3e46c2dd7f1d48ed074f49df9893910d08ea09f0625b14071d1d66d8f7390bff66dee60e1e7d19095

data/.github/workflows/ci.yml

@@ -23,3 +23,18 @@ jobs:
         run: bundle exec rake test
         env:
           RUBYOPT: "--enable=frozen_string_literal"
+  test-legacy:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['2.3', '2.4', '2.5']
+    steps:
+      - uses: actions/checkout@v3
+      # Plain docker run rather than container: the ruby:2.3/2.4 images' glibc is too old for the actions' Node.
+      # Not rake test: the Rakefile loads changelogd, which these Rubies can't install.
+      # No frozen_string_literal: net-ssh 6 mutates string literals.
+      - name: Run Tests
+        run: >-
+          docker run --rm -v "$PWD:/w" -w /w -e BUNDLE_GEMFILE=gemfiles/legacy.gemfile ruby:${{ matrix.ruby-version }}
+          sh -c 'bundle install --jobs 4 && bundle exec ruby -Ilib -Itest -e "Dir.glob(\"./test/test_*.rb\").each { |f| require f }"'

data/.gitignore

@@ -11,3 +11,4 @@ doc
 Gemfile.lock
 
 lib/net/ssh/version.rb.old
+/gemfiles/*.lock

data/CHANGES.txt

@@ -1,3 +1,9 @@
+=== 4.1.3
+
+* Load again on Ruby 2.3-2.5 (4.1.2 needed 2.5), and declare `required_ruby_version >= 2.3` [#112, #110]
+* Add a `quote:` option to `upload`/`download` for the remote path: `:posix` (default), `:windows` for Win32-OpenSSH under cmd.exe or PowerShell (double-quoted, `\` sent as `/`, paths containing `"`, `$`, `` ` ``, `%`, `!`, curly quotes, CR, LF or NUL rejected), `:none` to send the path unchanged to servers without a shell, or a callable. By default a leading `~` or `~/` is now left for the remote shell to expand to the home directory; such paths previously referred to a literal `~` entry in the login directory and usually failed. Thanks @ArtsiomMusin for the Windows patch in #34 [#109, #34, #9]
+* Recursive uploads no longer abort on a broken symlink: it is skipped with a warning, the rest is uploaded, and a Net::SCP::Error listing the skipped paths is raised at the end, like OpenSSH scp. Based on #23 by @maage. [#108, #23]
+
 === 4.1.2
 
 * Security: Downloads no longer apply setuid, setgid or sticky bits sent by the server, check that a server-chosen local name matches the requested remote basename (as OpenSSH does since CVE-2019-6111), and refuse to follow an existing local symlink at a server-named path instead of writing through it. The local path passed by the caller may still be a symlink. O_NOFOLLOW suggested in net-sftp#162 by srosenhamer [#104]

data/README.md

@@ -69,6 +69,24 @@ require 'uri/open-scp'
 data = open("scp://user@host/path/to/file.txt").read
 ```
 
+The remote path is escaped for a POSIX shell, except that a leading `~` or
+`~/` is left for the remote shell to expand to the home directory (`~user/` is
+not expanded). Use the `quote:` option of `upload`/`download` for other
+servers:
+
+```ruby
+# Win32-OpenSSH (cmd.exe or PowerShell): the path is double-quoted and "\" becomes "/".
+# Paths containing ", $, `, %, !, curly quotes, CR, LF or NUL raise ArgumentError.
+scp.upload! "/local/path", "C:\\Program Files\\App\\file.txt", quote: :windows
+
+# Servers that don't run a shell (MikroTik and other appliances): the path is
+# sent unchanged. Never use this with untrusted paths.
+scp.download! "flash/backup.rsc", "/local/backup.rsc", quote: :none
+
+# Or quote it yourself
+scp.upload! "/local/path", remote, quote: ->(path) { "'#{path}'" }
+```
+
 For more information, see Net::SCP.
 
 ## REQUIREMENTS:

data/gemfiles/legacy.gemfile

@@ -0,0 +1,7 @@
+# Ruby 2.3-2.5: the last net-ssh and mocha releases that still install there.
+source 'https://rubygems.org'
+
+gemspec path: ".."
+
+gem "net-ssh", "< 7"
+gem "mocha", "< 2"

data/lib/net/scp/upload.rb

@@ -49,7 +49,8 @@ module Net; class SCP
         directive = "D%04o %d %s\n" % [mode, 0, File.basename(channel[:current])]
         channel.send_data(directive)
         channel[:cwd] = channel[:current]
-        channel[:stack] << Dir.entries(channel[:current]).reject { |i| i == "." || i == ".." }
+        entries = Dir.entries(channel[:current]).reject { |i| i == "." || i == ".." }
+        channel[:stack] << entries.reject { |i| skip_broken_symlink(channel, File.join(channel[:current], i)) }
         await_response(channel, :next_item)
       end
     end
@@ -124,6 +125,29 @@ module Net; class SCP
       end
     end
 
+    # Returns true if +path+ is a symlink whose target doesn't exist, after
+    # logging a warning and recording it for #raise_if_entries_skipped.
+    def skip_broken_symlink(channel, path)
+      return false unless File.symlink?(path) && !File.exist?(path)
+
+      lwarn { "#{path}: broken symlink, skipping" }
+      (channel[:skipped] ||= []) << path
+      true
+    end
+
+    # Once the remote has closed the channel, raises a Net::SCP::Error listing
+    # the entries skipped by #skip_broken_symlink, if any.
+    def raise_if_entries_skipped(channel)
+      return unless channel.closing? && channel[:skipped]
+
+      # Cleared so it raises once, as on_process keeps calling this until the close is flushed.
+      skipped, channel[:skipped] = channel[:skipped], nil
+      # A failed remote scp is reported by start_command's exit-status check instead.
+      return unless channel[:exit].to_i.zero?
+
+      raise Net::SCP::Error, "upload incomplete, skipped broken symlinks: #{skipped.map(&:inspect).join(', ')}"
+    end
+
     # If the :preserve option is set, send a 'T' directive and wait for the
     # server to respond before proceeding to either #upload_file_state or
     # #upload_directory_state, depending on what is being uploaded.

data/lib/net/scp/version.rb

@@ -52,7 +52,7 @@ module Net
       MINOR = 1
 
       # The tiny component of this version of the Net::SSH library
-      TINY  = 2
+      TINY  = 3
 
       # The prerelease component of this version of the Net::SSH library
       # nil allowed

data/lib/net/scp.rb

@@ -259,13 +259,24 @@ module Net
     #
     # * :recursive - the +local+ parameter refers to a local directory, which
     #   should be uploaded to a new directory named +remote+ on the remote
-    #   server.
+    #   server. Broken symlinks in it are skipped with a warning, and once
+    #   everything else is uploaded a Net::SCP::Error listing them is raised.
     # * :preserve - the atime and mtime of the file should be preserved.
     # * :verbose - the process should result in verbose output on the server
     #   end (useful for debugging).
     # * :chunk_size - the size of each "chunk" that should be sent. Defaults
     #   to 2048. Changing this value may improve throughput at the expense
     #   of decreasing interactivity.
+    # * :quote - how +remote+ is quoted in the scp command run by the remote
+    #   shell. :posix (the default) escapes it for a POSIX shell, leaving a
+    #   leading "~" or "~/" unescaped so it expands to the remote home
+    #   directory ("~user/" is not expanded). :windows is for Win32-OpenSSH,
+    #   whose shell may be cmd.exe or PowerShell: backslashes become "/", the
+    #   path is wrapped in double quotes, and paths containing a double or curly
+    #   quote, $, `, %, !, CR, LF or NUL raise ArgumentError. :none sends the
+    #   path unchanged, for servers that don't run a shell (some routers and
+    #   appliances); never use it with untrusted input. A callable is given
+    #   +remote+ and returns the string to send.
     #
     # This method will return immediately, returning the Net::SSH::Connection::Channel
     # object that will support the upload. To wait for the upload to finish,
@@ -298,6 +309,7 @@ module Net
     # * :preserve - the atime and mtime of the file should be preserved.
     # * :verbose - the process should result in verbose output on the server
     #   end (useful for debugging).
+    # * :quote - how +remote+ is quoted for the remote shell (see #upload).
     #
     # This method will return immediately, returning the Net::SSH::Connection::Channel
     # object that will support the download. To wait for the download to finish,
@@ -348,15 +360,14 @@ module Net
       # (See Net::SCP::Upload and Net::SCP::Download).
       def start_command(mode, local, remote, options={}, &callback)
         local = local.to_path if local.is_a?(Pathname)
-        session.open_channel do |channel|
-
-          if options[:shell]
-            escaped_file = shellescape(remote).gsub(/'/) { |m| "'\\''" }
-            command = "#{options[:shell]} -c '#{scp_command(mode, options)} #{escaped_file}'"
-          else
-            command = "#{scp_command(mode, options)} #{shellescape remote}"
-          end
+        # Kept in channel[:remote] too, so a download's basename check sees "C:/a/b.txt" as b.txt.
+        remote = remote.to_s.tr("\\", "/") if options[:quote] == :windows
+        command = "#{scp_command(mode, options)} #{quote_remote(remote, options[:quote] || :posix)}"
+        if options[:shell]
+          command = "#{options[:shell]} -c '#{command.gsub("'") { "'\\''" }}'"
+        end
 
+        session.open_channel do |channel|
           channel.exec(command) do |ch, success|
             if success
               channel[:local   ] = local
@@ -369,22 +380,24 @@ module Net
               channel[:error_string] = +''
 
               channel.on_close do
-                # The close can be dispatched before on_process has consumed data that arrived with it.
-                send("#{channel[:state]}_state", channel)
-                # If we got an exit-status and it is not 0, something went wrong
-                if !channel[:exit].nil? && channel[:exit] != 0
-                  raise Net::SCP::Error, 'SCP did not finish successfully ' \
-                                         "(#{channel[:exit]}): #{channel[:error_string]}"
-                end
-                # A zero or missing exit-status does not prove the transfer completed.
-                if channel[:state] != :finish
-                  message = +'SCP did not finish successfully (channel closed before end of transmission)'
-                  message << ": #{channel[:error_string]}" unless channel[:error_string].empty?
-                  raise Net::SCP::Error, message
+                begin
+                  # The close can be dispatched before on_process has consumed data that arrived with it.
+                  send("#{channel[:state]}_state", channel)
+                  # If we got an exit-status and it is not 0, something went wrong
+                  if !channel[:exit].nil? && channel[:exit] != 0
+                    raise Net::SCP::Error, 'SCP did not finish successfully ' \
+                                           "(#{channel[:exit]}): #{channel[:error_string]}"
+                  end
+                  # A zero or missing exit-status does not prove the transfer completed.
+                  if channel[:state] != :finish
+                    message = +'SCP did not finish successfully (channel closed before end of transmission)'
+                    message << ": #{channel[:error_string]}" unless channel[:error_string].empty?
+                    raise Net::SCP::Error, message
+                  end
+                ensure
+                  io = channel[:io]
+                  io.close if io && io != channel[:local] && !io.closed?
                 end
-              ensure
-                io = channel[:io]
-                io.close if io && io != channel[:local] && !io.closed?
               end
               channel.on_data                   { |ch2, data| channel[:buffer].append(data) }
               channel.on_extended_data          { |ch2, type, data| debug { data.chomp } }
@@ -428,6 +441,7 @@ module Net
       # of the pipe, and allows the pipe to drain until the server closes it.
       def finish_state(channel)
         channel.eof!
+        raise_if_entries_skipped(channel)
       end
 
       # Invoked to report progress back to the client. If a callback was not
@@ -436,6 +450,29 @@ module Net
         channel[:callback].call(channel, name, sent, total) if channel[:callback]
       end
 
+      # Inside double quotes cmd.exe still expands % and !, PowerShell expands $ and `, and PowerShell also ends a string at U+2018..U+201E.
+      WINDOWS_UNSAFE = /["$`%!\r\n\0\u2018-\u201E]/
+
+      def quote_remote(remote, quote)
+        case quote
+        when :posix
+          remote = remote.to_s
+          return remote if remote == "~" || remote == "~/"
+          return "~/#{shellescape(remote[2..-1])}" if remote.start_with?("~/")
+          shellescape(remote)
+        when :windows
+          if remote.dup.force_encoding(Encoding::UTF_8) =~ WINDOWS_UNSAFE
+            raise ArgumentError, "remote path #{remote.inspect} contains a character that can't be quoted safely for a Windows shell"
+          end
+          "\"#{remote}\""
+        when :none
+          remote.to_s
+        else
+          raise ArgumentError, ":quote must be :posix, :windows, :none or a callable, got #{quote.inspect}" unless quote.respond_to?(:call)
+          quote.call(remote).to_s
+        end
+      end
+
       # Imported from ruby 1.9.2 shellwords.rb
       def shellescape(path)
         # Convert path to a string if it isn't already one.

data/net-scp.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/net-ssh/net-scp"
   spec.license       = "MIT"
   spec.required_rubygems_version = Gem::Requirement.new(">= 0") if spec.respond_to? :required_rubygems_version=
+  spec.required_ruby_version = ">= 2.3"
   spec.metadata      = {
     "changelog_uri" => "https://github.com/net-ssh/net-scp/blob/master/CHANGES.txt"
   }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: net-scp
 version: !ruby/object:Gem::Version
-  version: 4.1.2
+  version: 4.1.3
 platform: ruby
 authors:
 - Jamis Buck
@@ -32,7 +32,7 @@ cert_chain:
   vNiMFH5yLu/tlav4xh+HlYscWVdFQIvd7f/Uxa+Vip1Pi16wmhnrE15z/vDX921v
   hukBRIoCEAuUgNVBh+L/C8aETzbf/77WU3Si/w==
   -----END CERTIFICATE-----
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -104,6 +104,7 @@ files:
 - Rakefile
 - SECURITY.md
 - changelog.d/README.md
+- gemfiles/legacy.gemfile
 - lib/net/scp.rb
 - lib/net/scp/download.rb
 - lib/net/scp/errors.rb
@@ -127,7 +128,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="