Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
name: Bug report
description: Report a problem with ssh2shell
title: "[Bug]: "
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for the report. Search the existing issues first, and remove
secrets, private keys, and real host names from anything you paste.

- type: input
id: version
attributes:
label: ssh2shell version
description: The version in your `package.json` or from `npm ls ssh2shell`.
placeholder: 4.0.0
validations:
required: true

- type: input
id: node
attributes:
label: Node.js version
description: The output of `node --version`.
placeholder: v20.11.0
validations:
required: true

- type: input
id: os
attributes:
label: Operating system
placeholder: Ubuntu 24.04, Windows 11, macOS 15
validations:
required: true

- type: textarea
id: description
attributes:
label: What happened?
description: What did you expect, and what happened instead?
validations:
required: true

- type: textarea
id: reproduction
attributes:
label: Minimal reproduction
description: The smallest host object and command list that shows the problem.
render: javascript
validations:
required: true

- type: textarea
id: debug
attributes:
label: Debug output
description: |
Set `debug: true` and `verbose: true` on the host and paste the relevant
output. Remove credentials, keys, and real host names first.
render: shell
validations:
required: false

- type: checkboxes
id: checks
attributes:
label: Checklist
options:
- label: I am using ssh2shell 4.x.
required: true
- label: I searched the existing issues and the README.
required: true
- label: This is not a security report (those go through SECURITY.md).
required: true
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: true
contact_links:
- name: Documentation
url: https://github.com/cmp-202/ssh2shell#readme
about: Usage, host configuration, events, and tunnelling
- name: Report a security vulnerability
url: https://github.com/cmp-202/ssh2shell/security/advisories/new
about: Report vulnerabilities privately instead of opening a public issue
44 changes: 44 additions & 0 deletions .github/ISSUE_TEMPLATE/feature_request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Feature request
description: Suggest a new capability or a change in behaviour
title: "[Feature]: "
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Describe the problem first, then the change you have in mind. Changes
that fit the existing host and command model are easier to add than new
configuration surfaces.

- type: textarea
id: problem
attributes:
label: What problem are you trying to solve?
validations:
required: true

- type: textarea
id: proposal
attributes:
label: Proposed change
description: What should ssh2shell do differently? Include a small example if it helps.
validations:
required: true

- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Workarounds you have tried, or other designs you rejected.
validations:
required: false

- type: checkboxes
id: checks
attributes:
label: Checklist
options:
- label: I am using ssh2shell 4.x.
required: true
- label: I searched the existing issues and the README.
required: true
22 changes: 22 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
## What changed

<!-- One or two sentences. Link the issue if there is one. -->

## Why

<!-- The problem this solves or the behaviour it changes. -->

## How it was tested

<!-- Commands you ran and the result, for example `npm test` or
`npm run test:live`. Say which tests you did not run. -->

## Checklist

- [ ] `npm test` passes (build check, unit, and baseline).
- [ ] Live tests run when the change touches connections, command flow, or
hops (`npm run test:live` or `npm run test:live:all`).
- [ ] `README.md` and `docs/` are updated for user-visible changes.
- [ ] `CHANGELOG.md` has an entry under `Unreleased`.
- [ ] No removed 3.x API is used (`server.ssh`, `exitCommands`,
`sshToNextHost`).
13 changes: 13 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
version: 2
updates:
- package-ecosystem: npm
directory: "/"
schedule:
interval: weekly
open-pull-requests-limit: 5

- package-ecosystem: github-actions
directory: "/"
schedule:
interval: weekly
open-pull-requests-limit: 5
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ Releases before `4.0.0` are recorded as git tags and GitHub Releases.
in `docs/PUBLISHING.md` now go through a pull request.
- Pointed the `package.json` `homepage` at the repository README instead of the
outdated wiki.
- Added `SECURITY.md`, `CONTRIBUTING.md`, Dependabot configuration, and issue
and pull request templates.

## [4.0.0] - 2026-11-15

Expand Down
29 changes: 29 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Contributing

## Before you start

- Use Node.js 18 or newer.
- For a bug, open an issue with the version, Node version, and a minimal
reproduction. For a security problem, follow [SECURITY.md](./SECURITY.md)
instead of opening a public issue.

## Set up

```bash
npm ci
npm test
```

`npm test` runs the build check, the unit suite, and the frozen baseline. The
live suite needs reachable SSH hosts; [test/README.md](./test/README.md)
documents the environment and the curated batch.

## Pull requests

- Branch from `master`. `master` requires a pull request, the CI matrix, and the
live suite, so direct pushes are rejected.
- Keep the change focused, and update `README.md`, `docs/`, and `CHANGELOG.md`
when behaviour changes.
- Use `npm run test:live` for connection, command-flow, and hop changes. Run
`npm run test:live:all` before a release.
- The release process is in [docs/PUBLISHING.md](./docs/PUBLISHING.md).
9 changes: 6 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1295,6 +1295,9 @@ parameters and the `host`/`userName`/`port` fields in releases before the
`ssh2` hop transport. It is fixed in `2.0.13`, `2.0.14`, and `3.0.0`. Users of
`2.0.12` and earlier should upgrade.

Report a vulnerability privately through [SECURITY.md](./SECURITY.md); do not
open a public issue.

## Development

```bash
Expand All @@ -1307,9 +1310,9 @@ npm test
`npm test` checks that `lib/` matches `src/`, runs the offline unit tests, and
runs the level-aware baseline tests. The live tests need SSH hosts; CI starts
three throwaway `sshd` instances on the runner, and the same suite can run
against the provisioning VMs locally. See [`test/README.md`](./test/README.md)
for the test layout, live runner, environment variables, keys, CI hosts, and VM
provisioning.
against the provisioning VMs locally. See [CONTRIBUTING.md](./CONTRIBUTING.md)
for the workflow and [`test/README.md`](./test/README.md) for the test layout,
live runner, environment variables, keys, CI hosts, and VM provisioning.

## Changelog

Expand Down
49 changes: 49 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Security policy

## Supported versions

| Version | Supported |
| --- | --- |
| 4.x | Yes |
| 3.x and earlier | No |

3.x and earlier are deprecated on npm and do not receive fixes. If you are
still on 3.x, upgrade to 4.x; see the [4.0.0 changelog entry](./CHANGELOG.md)
for the host-hop and `server.ssh` changes.

## Reporting a vulnerability

Do not open a public issue for a security problem. Use GitHub's private
vulnerability reporting:

<https://github.com/cmp-202/ssh2shell/security/advisories/new>

Please include:

- the ssh2shell version, Node.js version, and operating system;
- what an attacker could do with the issue;
- a minimal reproduction, with secrets and real host names removed;
- any mitigation you have already identified.

I will acknowledge the report, confirm the impact, and prepare a fix and
release. I will credit you in the advisory unless you ask me not to.

## Scope

In scope:

- escaping the command flow to run unintended commands on a host;
- bypassing `hostHash` / `hostVerifier` when a host key is pinned;
- leaking credentials, private keys, or passphrases through events,
`sessionText`, logs, or errors;
- a hop reaching a host it should not reach, or a failure that leaves a
session open.

Out of scope:

- the security of the remote host, the commands you choose to run, or the
privileges you grant them;
- vulnerabilities in [`ssh2`](https://github.com/mscdex/ssh2) itself, which
should be reported upstream;
- host-key acceptance when `hostHash` / `hostVerifier` is not set, which is
`ssh2`'s documented default and is described in the README.
Loading