p0cli: SSH: Troubleshooting

Last updated: April 29, 2025

P0 CLI – SSH Troubleshooting Guide

Covers AWS EC2, Google Cloud VMs, macOS, Windows, and generic OpenSSH problems

0 How to use this guide

Find the error message (or symptom) in the table of contents.
Follow the step‑by‑step fix. Each step explains why it matters, so you learn the underlying mechanism.
If the error is not listed, run the diagnostics script (§8) and collect the logs before contacting support.

1 Quick health checklist

		CheckCommandWhy it matters
Node ≥ 20	`node -v`	Older Node versions break npm‑installed CLI binaries.
P0 CLI in PATH	`p0 --version`	Verifies global install succeeded.
AWS CLI v2	`aws --version`	`ssm start-session` lives here.
Session Manager plugin	`session-manager-plugin --version`	Required for SSM tunnel on AWS.
gcloud SDK	`gcloud --version`	Provides `start-iap-tunnel`.
gcloud login	`gcloud auth list`	IAP tunnel fails without a valid OAuth token.
P0 identity file	`cat ~/.p0/identity.json` (mac)`type %USERPROFILE%\.p0\identity.json` (Win)	Confirms `p0 login` completed & org slug recorded.

2 Common CLI start‑up errors

		Symptom / MessageLikely causeFix & rationale
`node: bad option: --require ts-node/register`	Node < 20.	Upgrade Node: the CLI is compiled for ESM features included in v20+.
`Cannot find module '@p0security/cli'`	CLI not in PATH or NPM global root not in PATH.	Re‑install with `npm i -g @p0security/cli` andrestart terminal so PATH reloads.
`The 'org' argument is required` during `p0 login`	Forgot org slug env var.	Run `p0 login <ORG_ID>` or export `P0_ORG`.

3 Errors before cloud access is granted (P0 layer)

		MessageCauseFix
`This organization is not configured for SSH access via the P0 CLI`	Admins haven’t installed the SSH integration.	Ask platform team to complete P0 onboarding for SSH providers.
`Server did not return a request id`	Backend 503 or mis‑shaped request.	Retry. If persistent, grab CLI logs (`--debug`) and open support ticket.
`--approved-only` exits immediately	Access not pre‑approved.	Remove the flag or get an approver to pre‑approve via Slack.

4 Errors during access propagation (AWS & GCP)

			CloudError snippetRoot reasonResolution
AWS	`AccessDeniedException` OR `is not authorized to perform ssm:StartSession`	IAM policy not yet visible to SSM agent.	Wait – CLI retries 8 min by default. Use `--debug` to watch attempts.
AWS	`Unable to locate credentials…` inside ProxyCommand	Local AWS CLI lacks auth (SSO or keys).	`aws sso login --profile <name>`or set `AWS_PROFILE`.
GCP	`Please log in to the gcloud CLI to SSH`	OAuth token expired.	`gcloud auth login` again (token TTL 12 h).
GCP	Tunnel hangs at 127.0.0.1:0	Firewall denies egress websockets.	Check corporate proxy, allow `iap.googleapis.com:443`.

5 OpenSSH / Network level failures after access granted

		Error / SymptomCauseFix
`ssh: connect to host … port 22: Connection refused` (GCP)	SSH daemon disabled or moved.	Start `sshd` on VM or revert to port 22. (Azure note: port override unsupported.)
`Too many authentication failures`	Agent offered multiple keys before the P0 temp key.	CLI already adds `IdentitiesOnly=yes`; override your local `ssh_config` or kill `ssh-agent` keys.
Port forward fails with `bind: Address already in use`	Local port occupied.	Change local part of `-L` or `-R` binding.
Windows PowerShell: arguments split incorrectly	Quotes not escaped.	Wrap the entire SSH tail in double quotes and escape inner quotes (see examples).

6 Sudo & privilege issues

		ScenarioExplanationMitigation
`sudo: no tty present`	Your remote command used `sudo` inside non‑interactive mode.	Transpose with `sudo -n <cmd>` or request interactive shell.
No sudo despite `--sudo`	Approver rejected elevated scope.	Check Slack thread, re‑submit with business justification.

7 File‑transfer (SCP) issues

		ErrorRoot causeFix
`scp: protocol error: : Broken pipe`	ProxyCommand died (SSM/IAP restarted).	Large transfers: add `-- -o ServerAliveInterval=60` flag to keep tunnel alive.
`-r` flag ignored	Forgot to add `--recursive` to P0 flags when using `p0 scp`.	Use `p0 scp --recursive …` or rely on auto‑`-r` for dirs.

8 Collecting diagnostics

Run with maximum verbosity and pipe logs:

P0_LOG_LEVEL=debug p0 ssh <dest> --provider <cloud> --debug -- -vvv 2>&1 | tee p0-debug.log

Upload p0-debug.log in your support ticket. It includes:

CLI version, Node version, OS.
Full child commands (AWS, gcloud, ssh).
SSH handshake at -vvv level.

Privacy note: the log contains temporary instance IDs and IPs but never the private key material.

9 When to escalate to support

Please gather:

Command you ran (with flags).
Terminal output (use §8).
Approximate UTC timestamp.
Org slug and request ID (shown in Slack).

Send to support@p0.dev or post in #p0-community Slack.

10 Self‑service updates & docs

Release notes: https://github.com/p0-security/cli/releases
Full docs: https://docs.p0.dev
Upgrade CLI: npm -g update @p0security/cli

11 Appendix – Decision tree (plain text)

Start
 ├─ Does `p0` command run at all? ── No → Check Node + npm global install.
 │
 ├─ Does CLI create Permission Request? ── No → Check org slug, login, or network.
 │
 ├─ Waiting >8 min at "propagate"? ── Yes → Cloud IAM/OS Login stuck; contact admin.
 │
 ├─ Does SSH handshake start? ── No → ProxyCommand dependency (AWS CLI, gcloud) fails.
 │
 ├─ Shell opens but command fails? ── Yes → Remote OS issue (sshd, sudo), fix on VM.
 │
 └─ Success 🎉

Now you have a one‑stop shop for resolving P0 SSH headaches – happy debugging!