|
| 1 | +# SSH MITM Driver |
| 2 | + |
| 3 | +`jumpstarter-driver-ssh-mitm` provides a secure SSH proxy layer where private keys |
| 4 | +are stored on the exporter and never transmitted to clients. It is designed to be |
| 5 | +used as a child of `SSHWrapper`. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +```{code-block} console |
| 10 | +:substitutions: |
| 11 | +$ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-ssh-mitm |
| 12 | +``` |
| 13 | + |
| 14 | +## Architecture |
| 15 | + |
| 16 | +``` |
| 17 | +SSHWrapper --> SSHMITM --> TcpNetwork --> DUT |
| 18 | +``` |
| 19 | + |
| 20 | +- **SSHWrapper**: Handles SSH CLI and command execution |
| 21 | +- **SSHMITM**: Provides authenticated proxy connection (stores the SSH key) |
| 22 | +- **TcpNetwork**: Raw TCP connection to the DUT |
| 23 | + |
| 24 | +## Configuration |
| 25 | + |
| 26 | +The command name is determined by the key in the `export` section. Use `ssh_mitm` to get the `j ssh_mitm` command: |
| 27 | + |
| 28 | +```yaml |
| 29 | +export: |
| 30 | + ssh_mitm: # ← This gives you "j ssh_mitm" command |
| 31 | + type: jumpstarter_driver_ssh.driver.SSHWrapper |
| 32 | + config: |
| 33 | + default_username: root |
| 34 | + children: |
| 35 | + tcp: |
| 36 | + type: jumpstarter_driver_ssh_mitm.driver.SSHMITM |
| 37 | + config: |
| 38 | + ssh_identity_file: /path/to/private/key |
| 39 | + default_username: root |
| 40 | + children: |
| 41 | + tcp: |
| 42 | + type: jumpstarter_driver_network.driver.TcpNetwork |
| 43 | + config: |
| 44 | + host: 192.168.1.100 |
| 45 | + port: 22 |
| 46 | +``` |
| 47 | +
|
| 48 | +Or with inline key: |
| 49 | +
|
| 50 | +```yaml |
| 51 | +export: |
| 52 | + ssh_mitm: # ← This gives you "j ssh_mitm" command |
| 53 | + type: jumpstarter_driver_ssh.driver.SSHWrapper |
| 54 | + config: |
| 55 | + default_username: root |
| 56 | + children: |
| 57 | + tcp: |
| 58 | + type: jumpstarter_driver_ssh_mitm.driver.SSHMITM |
| 59 | + config: |
| 60 | + default_username: root |
| 61 | + ssh_identity: | |
| 62 | + -----BEGIN OPENSSH PRIVATE KEY----- |
| 63 | + ... |
| 64 | + -----END OPENSSH PRIVATE KEY----- |
| 65 | + children: |
| 66 | + tcp: |
| 67 | + type: jumpstarter_driver_network.driver.TcpNetwork |
| 68 | + config: |
| 69 | + host: 192.168.1.100 |
| 70 | + port: 22 |
| 71 | +``` |
| 72 | +
|
| 73 | +### SSHMITM Config parameters |
| 74 | +
|
| 75 | +| Parameter | Description | Type | Required | Default | |
| 76 | +| ----------------- | ---------------------------------------- | ----- | -------- | ------- | |
| 77 | +| default_username | SSH username for DUT connection | str | no | "" | |
| 78 | +| ssh_identity | SSH private key content (inline) | str | no* | None | |
| 79 | +| ssh_identity_file | Path to SSH private key file | str | no* | None | |
| 80 | +
|
| 81 | +\* Either `ssh_identity` or `ssh_identity_file` must be provided. |
| 82 | + |
| 83 | +### Required children |
| 84 | + |
| 85 | +- `tcp`: A `TcpNetwork` driver providing target host and port |
| 86 | + |
| 87 | +## Usage |
| 88 | + |
| 89 | +Since SSHMITM is used as a child of SSHWrapper, you use the configured command name (e.g., `ssh_mitm`): |
| 90 | + |
| 91 | +```bash |
| 92 | +# Execute a command |
| 93 | +j ssh_mitm whoami |
| 94 | +
|
| 95 | +# Interactive shell |
| 96 | +j ssh_mitm |
| 97 | +
|
| 98 | +# With arguments |
| 99 | +j ssh_mitm ls -la /tmp |
| 100 | +
|
| 101 | +# With SSH flags |
| 102 | +j ssh_mitm -v hostname |
| 103 | +``` |
| 104 | + |
| 105 | +**Note**: The command name (`ssh_mitm`) is determined by the key in your exporter config's `export` section. You can use any name you prefer. |
| 106 | + |
| 107 | +## API Reference |
| 108 | + |
| 109 | +```{eval-rst} |
| 110 | +.. autoclass:: jumpstarter_driver_ssh_mitm.driver.SSHMITM() |
| 111 | +``` |
0 commit comments