p0 ssh

1. Quick health checklist

Check	Command	Why 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	macOS & Linux: cat ~/.p0/identity.json Windows: %USERPROFILE%.p0\identity.json	Confirms p0 login completed & org slug recorded.

---

2. Common CLI start‑up errors

Symptom / Message	Likely cause	Fix & 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 and restart 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)

Message	Cause	Fix
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 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)

Cloud	Error	Root reason	Resolution
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 / Symptom	Cause	Fix
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

Scenario	Explanation	Mitigation
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

Error	Root cause	Fix
scp: protocol error: : Broken pipe	ProxyCommand died (SSM/IAP restarted).	Large transfers: add -- -o ServerAliveInterval=60 flag to keep tunnel alive.

---

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 Escalate to support

Please gather:

1. Command you ran (with flags).

2. Terminal output (use §8).

3. Approximate UTC timestamp.

4. Org slug and request ID (shown in Slack).

Send to [email protected] or post in #p0-community Slack.

---

10 Self‑service updates & docs

• Release notes: https://github.com/p0-security/p0cli/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!