Research
Recent Trends in Malicious Packages Targeting Discord
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.
promise-sftp
Advanced tools
Readme
promise-sftp is an SFTP client module for node.js that provides an asynchronous interface for communicating with an SFTP server.
This module is a wrapper the SFTP client functionality from ssh2, and provides some additional features as well as a convenient promise-based API. The API is semi-interchangeable with the promise-ftp module, an idea that was inspired by sftpjs.
This library is written primarily in CoffeeScript, but may be used just as easily in a Node app using Javascript or CoffeeScript. Promises in this module are provided by Bluebird.
PromiseSftp.ERROR_CODES
npm install promise-sftp
TODO: examples
For the most part, this module's API mirrors ssh2's SFTPStream API, except that it returns promises which resolve or reject, rather than emitting events or calling callbacks. However, there are some minor differences and some additional features, including attempts to make this API as interchangeable as possible with promise-ftp's.
Most errors generated by this module will be instances of one of the following:
FtpConnectionError: Indicates the connection status was not appropriate for the method called; e.g. connect() or reconnect() was called when the connection was not in a disconnected state, end() was called when the connection has already closed, etc.
FtpReconnectError: Only possible when the autoReconnect
option is set true, this indicates a reconnect was
attempted and failed. It includes information about both the original disconnect error (if any) as well as the error
while attempting to reconnect.
In addition, errors from the underlying node-ftp library may be rejected unchanged through method calls. These errors
may contain a code
property that references the SFTP error code. This code may be translated into a (generic)
human-readable text explanation by referencing the map PromiseSftp.ERROR_CODES
.
TODO: investigate and document ssh-level errors and the level
property of errors.
connect(config <object>): Connects to an SFTP server; returned promise resolves to the server's greeting
message. If multiple authentication methods are available based on the passed config, they are attempted in the
following order: Password > Private Key > Agent > keyboard-interactive (if tryKeyboard
is set) >
Host-based > None. NOTE: many of the config properties below are NOT relevant for
promise-ftp. However, all
promise-ftp connect options will work here, except for secure,
secureOptions, and preserveCwd. Valid config properties are:
host <string>: The hostname or IP address of the SFTP server. Default: 'localhost'
port <integer>: The port of the SFTP server. Default: 22
username <string>: Username for authentication.
password <string>: Password for password-based user authentication. Default: (none)
changePassword <function>: When using password-based user authentication, set this option to handle password change requests. If this option isn't set, and the server requests a password change, I haven't tested what will happen. The function should behave as described below. Default: (none)
autoReconnect <boolean>: Whether to attempt to automatically reconnect using the existing config if the connection is unexpectedly closed. Auto-reconnection is lazy, and so will wait until a command needs to be issued before attempting to reconnect.
forceIPv4 <boolean>: Only connect via resolved IPv4 address for host
. Default: false
forceIPv6 <boolean>: Only connect via resolved IPv6 address for host
. Default: false
hostHash <string>: 'md5' or 'sha1'. The host's key is hashed using this method and passed to the
hostVerifier
function. Default: (none)
hostVerifier <function>: Function that is passed a string hex hash of the host's key for verification purposes.
Return true
to continue with the handshake or false
to reject and disconnect. Default: (auto-accept)
agent <string>: Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket." Default: (none)
privateKey <mixed>: Buffer or string that contains a private key for either key-based or host-based user authentication (OpenSSH format). Default: (none)
privateKeyFile <string>: Path and name of a file containing a private key as would be passed to the privateKey
option. If privateKey
is also set, priority is given to the privateKey
option. Default: (none)
passphrase <string>: For an encrypted private key, this is the passphrase used to decrypt it. Default: (none)
localHostname <string>: Along with localUsername
and privateKey
, set this to a non-empty string for
host-based user authentication. Default: (none)
localUsername <string>: Along with localHostname
and privateKey
, set this to a non-empty string for
host-based user authentication. Default: (none)
tryKeyboard <function>: Set this option to a function to try keyboard-interactive user authentication if primary user authentication method fails. The function should behave as described below. Default: (none)
tryKeyboard(name <string>, instructions <string>, instructionsLang <string>, prompts <array>): The
goal of this function is to acquire responses to the given prompts
.
name
is generally what you'd use as a header or GUI window title to describe the purpose of the prompts
.
prompts
is an array of objects containing the fields prompt
(the query to <string> pose to the user)
and echo
(a indicating <boolean> whether the user's input should be displayed on-screen).
The function's return value should be one of the following: an array of response strings, a promise to an array of response strings, or an array of promises to response strings.
NOTE: This function may be called more than once, with the same or different prompts.
keepaliveInterval <integer>: How often (in milliseconds) to send SSH-level keepalive packets to the server (in
a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
keepaliveCountMax <integer>: How many consecutive, unanswered SSH-level keepalive packets that can be sent to
the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3
readyTimeout <integer>: How long (in milliseconds) to wait for the SSH handshake to complete.
Default: 20000
strictVendor <boolean>: Performs a strict server vendor check before sending vendor-specific requests, etc.
(e.g. check for OpenSSH server when using openssh_noMoreSessions()
) Default: true
sock <ReadableStream>: A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
agentForward <boolean>: Set to true
to use OpenSSH agent forwarding (auth-agent@openssh.com
) for the life
of the connection. agent
must also be set to use this feature. Default: false
debug <function>: Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
the additional promise-ftp-style option aliases below are used for compatibility purposes. The aliases are only used if the actual option is not set:
user <string>: alias for username
connTimeout <integer>: alias for readyTimeout
pasvTimeout <integer>: alias for readyTimeout
; if both this and connTimeout
are given truthy values,
connTimeout
will be given priority.
keepalive <integer>: alias for keepaliveInterval
reconnect(): Connects to an SFTP server using the config from the most recent call to connect(). Returned promise resolves to the server's greeting message.
end(): Closes the connection to the server after any/all enqueued commands have been executed; returned promise resolves to a boolean indicating whether there was an error associated with closing the connection.
destroy(): Closes the connection to the server immediately. Returns a boolean indicating whether the connection was connected prior to the call to destroy().
getConnectionStatus(): Returns a string describing the current connection state. Possible strings are
enumerated in PromiseSftp.STATUSES
, as well as below:
not yet connected
connecting
connected
logging out
disconnecting
disconnected
reconnecting
list([path <string>]): Retrieves the directory listing of path
. path
defaults to '.'. Returned promise
resolves to an array of objects with these properties:
* type <_string_>: A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for
symlink on **\*NIX only**).
* name <_string_>: The name of the entry.
* size <_string_>: The size of the entry in bytes.
* date <_Date_>: The last modified date of the entry.
* rights <_object_>: The various permissions for this entry **(*NIX only)**.
* user <_string_>: An empty string or any combination of 'r', 'w', 'x'.
* group <_string_>: An empty string or any combination of 'r', 'w', 'x'.
* other <_string_>: An empty string or any combination of 'r', 'w', 'x'.
* owner <_string_>: The user name or ID that this entry belongs to **(*NIX only)**.
* group <_string_>: The group name or ID that this entry belongs to **(*NIX only)**.
* target <_string_>: _null_ **TODO**: For symlink entries, this is the symlink's target **(*NIX only)**.
* sticky <_boolean_>: _null_ **TODO**: True if the sticky bit is set for this entry **(*NIX only)**.
get(path <string>): Retrieves a file at path
from the server. Returned promise resolves to a ReadableStream
.
put(input <mixed>, destPath <string>): Sends data to the server to be stored as destPath
. input
can be a
ReadableStream, a Buffer, or a path to a local file. Returned promise resolves to undefined.
append(input <mixed>, destPath <string>): Same as put(), except if destPath
already exists, it will be
appended to instead of overwritten.
logout(): Alias to end().
delete(path <string>): Alias for unlink()
rename(oldPath <string>, newPath <string>): Renames/moves oldPath
to newPath
on the server. Returned
promise resolves to undefined.
mkdir(path <string>[, recursive <boolean>][, attributes <ATTRS>]): Creates a new directory on
the server at path
. recursive
is for enabling a 'mkdir -p' algorithm and defaults to false. attributes
sets the
ATTRS used when creating directories. Returned promise resolves to undefined.
TODO: The recursive
option here may not work as desired currently -- fix it.
rmdir(path <string>): Removes the directory on the server at path
. Returned promise resolves to undefined.
TODO: Test whether this deletes directory contents recursively, and document and/or add recursive
option to
behave like promise-ftp
listSafe([path <string>]): Alias to list().
size(path <string>): Retrieves the size of path
. Returned promise resolves to number of bytes.
lastMod(path <string>): Retrieves the last modified date and time for path
. Returned promise resolves an
instance of Date
.
restart(byteOffset <integer>): Sets the file byte offset for the next file transfer action initiated via
get() or put() to byteOffset
. Returned promise resolves to undefined.
fastGet(remotePath <string>, localPath <string>[, options <object>]): Downloads a file at remotePath
to
localPath
using parallel reads for faster throughput. Returned promise resolves to undefined. options
can have
the following properties:
concurrency <integer>: Number of concurrent reads Default: 25
chunkSize <integer>: Size of each read in bytes Default: 32768
step - <function(total_transferred <integer>, chunk <integer>, total <integer>)>: Called every time a part of a file was transferred
fastPut(localPath <string>, remotePath <string>[, options <object>]): Uploads a file from localPath
to
remotePath
using parallel reads for faster throughput. Returned promise resolves to undefined. options
can have
the following properties:
concurrency <integer>: Number of concurrent reads Default: 25
chunkSize <integer>: Size of each read in bytes Default: 32768
step - <function(total_transferred <integer>, chunk <integer>, total <integer>)>: Called every time a part of a file was transferred
createReadStream(path <string>[, options <object>]): Returned promise resolves to a new readable stream for
path
. options
has the following defaults:
{
flags: 'r',
encoding: null,
handle: null,
mode: 0666,
autoClose: true
}
options
can include start
and end
values to read a range of bytes from the file instead of the entire file.
Both start
and end
are inclusive and 0-indexed. The encoding
can be 'utf8'
, 'ascii'
, or 'base64'
.
If autoClose
is false, then the file handle won't be closed, even if there's an error. It is your responsibility
to close it and make sure there's no file handle leak. If autoClose
is set to true (default behavior), on error
or end
the file handle will be closed automatically.
An example to read the last 10 bytes of a file which is 100 bytes long:
sftp.createReadStream('sample.txt', {start: 90, end: 99});
createWriteStream(path <string>[, options <object>]): Returned promise resolves to a new readable stream
for path
. options
has the following defaults:
{
flags: 'w',
encoding: null,
mode: 0666
}
options
may also include a start
option to allow writing data at some position past the beginning of the file.
Modifying a file rather than replacing it may require a flags mode of 'r+'
rather than the default mode 'w'
.
If 'autoClose' is set to false and you pipe to this stream, this stream will not automatically close after there is no more data upstream -- allowing future pipes and/or manual writes.
open(filename <string>, mode <string>[, attributes <ATTRS>]): Opens a file filename
for mode
with
optional attributes
(in case open() creates a file). mode
is any of the modes supported by fs.open
(except
sync mode). Returned promise resolves to a Buffer containing a handle to the file.
close(handle <Buffer>): Closes the resource associated with handle
given by open() or opendir().
Returned promise resolves to undefined.
read(handle <Buffer>, buffer <Buffer>, offset <integer>, length <integer>, position <integer>):
Reads length
bytes from the resource associated with handle
starting at position
and stores the bytes in buffer
starting at offset
. Returned promise resolves to an object with the following properties:
bytesRead <integer>: bytes successfully read
buffer <_Buffer>: the buffer passed to read(), but offset
-adjusted
position <integer>: the position
passed to read()
write(handle <Buffer>, buffer <Buffer>, offset <integer>, length <integer>, position <integer>):
Writes length
bytes from buffer
starting at offset
to the resource associated with handle
starting at
position
. Returned promise resolves to undefined.
fstat(handle <Buffer>): Retrieves attributes for the resource associated with handle
. Returned promise
resolves to a Stats object.
fsetstat(handle <Buffer>, attributes <ATTRS>): Sets the attributes
for the resource associated with
handle
. Returned promise resolves to undefined.
futimes(handle <Buffer>, atime <mixed>, mtime <mixed>): Sets the access time and modified time for the
resource associated with handle
. atime
and mtime
can be Date instances or UNIX timestamp integers. Returned
promise resolves to undefined.
fchown(handle <Buffer>, uid <integer>, gid <integer>): Sets the owner for the resource associated with
handle
. Returned promise resolves to undefined.
fchmod(handle <Buffer>, mode <mixed>): Sets the mode for the resource associated with handle
. mode
can be
an integer or a string containing an octal number. Returned promise resolves to undefined.
opendir(path <string>): Opens a directory path
. Returned promise resolves to a Buffer containing a
directory handle.
readdir(location <mixed>): Retrieves a directory listing. location
can either be a Buffer containing a
valid directory handle from opendir() or a string containing the path to a directory. Returned promise resolves
to an Array of { filename: <_string_>, longname: <_string_>, attrs: [ATTRS](#attrs) }
style objects. NOTE: If
location
is a directory handle, this function may need to be called multiple times until it resolves to boolean false,
which indicates that no more directory entries are available for that directory handle.
unlink(path <string>): Removes the file/symlink at path
. Returned promise resolves to undefined.
stat(path <string>): Retrieves attributes for path
. Returned promise resolves to a Stats
object.
lstat(path <string>): Retrieves attributes for path
. If path
is a symlink, the link itself is stat'ed
instead of the resource it refers to. Returned promise resolves to a Stats object.
setstat(path <string>, attributes <ATTRS>): Sets the attributes defined in attributes
for path
.
Returned promise resolves to undefined.
utimes(path <string>, atime <mixed>, mtime <mixed>): Sets the access time and modified time for path
.
atime
and mtime
can be Date instances or UNIX timestamp integers. Returned promise resolves to undefined.
chown(path <string>, uid <integer>, gid <integer>): Sets the owner and group for path
. Returned promise
resolves to undefined.
chmod(path <string>, mode <mixed>): Sets the mode for path
. mode
can be an integer or a string containing
an octal number. Returned promise resolves to undefined.
readlink(path <string>): Returned promise resolves to the target for a symlink at path
.
symlink(targetPath <string>, linkPath <string>): Creates a symlink at linkPath
to targetPath
. Returned
promise resolves to undefined.
realpath(path <string>): Returned promise resolves to the absolute path corresponding to path
.
ext_openssh_rename(srcPath <string>, destPath <string>): OpenSSH extension Performs POSIX rename(3)
from srcPath
to destPath
. Returned promise resolves to undefined.
ext_openssh_statvfs(path <string>): OpenSSH extension Performs POSIX statvfs(2) on path
. Returned
promise resolves to an object containing the same fields as found in the
statvfs struct.
ext_openssh_fstatvfs(handle <Buffer>): OpenSSH extension Performs POSIX fstatvfs(2) on open handle
handle
. Returned promise resolves to an object containing the same fields as found in the
statvfs struct.
ext_openssh_hardlink(targetPath <string>, linkPath <string>): OpenSSH extension Performs POSIX link(2)
to create a hard link to targetPath
at linkPath
. Returned promise resolves to undefined.
ext_openssh_fsync(handle <Buffer>): OpenSSH extension Performs POSIX fsync(3) on the open handle
handle
. Returned promise resolves to undefined.
wait(): Waits for any previously-issued commands to complete.
TODO: document
TODO: document
level
property of underlying errors workscode
property of underlying errors works, especially re:
ssh errors vs sftp errors vs socket errors (?)target
and sticky
attributes on the list() commandrecursive
optionrecursive
option to rmdirFAQs
a promise-based sftp client for node.js
We found that promise-sftp demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
The Socket research team breaks down a sampling of malicious packages that download and execute files, among other suspicious behaviors, targeting the popular Discord platform.
Security News
Socket CEO Feross Aboukhadijeh joins a16z partners to discuss how modern, sophisticated supply chain attacks require AI-driven defenses and explore the challenges and solutions in leveraging AI for threat detection early in the development life cycle.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.