# p0 ssh

### 1. Quick health checklist <a href="#id-1-quick-health-checklist" id="id-1-quick-health-checklist"></a>

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

***

### 2. Common CLI start‑up errors <a href="#id-2-common-cli-start-up-errors" id="id-2-common-cli-start-up-errors"></a>

| 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) <a href="#id-3-errors-before-cloud-access-is-granted" id="id-3-errors-before-cloud-access-is-granted"></a>

| 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) <a href="#id-4-errors-during-access-propagation" id="id-4-errors-during-access-propagation"></a>

| 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 <a href="#id-5-openssh-network-level-failures-after-access-granted" id="id-5-openssh-network-level-failures-after-access-granted"></a>

| 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 <a href="#id-6-sudo-and-privilege-issues" id="id-6-sudo-and-privilege-issues"></a>

| 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 <a href="#id-7-file-transfer-scp-issues" id="id-7-file-transfer-scp-issues"></a>

| 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 <a href="#id-8-collecting-diagnostics" id="id-8-collecting-diagnostics"></a>

Run with maximum verbosity and pipe logs:

```plaintext
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 <a href="#id-9-escalate-to-support" id="id-9-escalate-to-support"></a>

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 <support@p0.dev> or post in **#p0-community** Slack.

***

### 10 Self‑service updates & docs <a href="#id-10-self-service-updates-and-docs" id="id-10-self-service-updates-and-docs"></a>

* **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) <a href="#id-11-appendix-decision-tree" id="id-11-appendix-decision-tree"></a>

```plaintext
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!**