diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..f23f339 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..16b8300 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..bd5da3d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -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 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..27d4847 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ +## What changed + + + +## Why + + + +## How it was tested + + + +## 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`). diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..50fcc0d --- /dev/null +++ b/.github/dependabot.yml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index d43a29a..14a7c4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8c61965 --- /dev/null +++ b/CONTRIBUTING.md @@ -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). diff --git a/README.md b/README.md index cf16c1c..ac954ef 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..e37a9f7 --- /dev/null +++ b/SECURITY.md @@ -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: + + + +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.