|
| 1 | + |
| 2 | +# Oracle Cloud Infrastructure (OCI) Bastion Service |
| 3 | + |
| 4 | +This reusable asset consist of a Python script that creates a bastion session with the Oracle OCI Bastion Service. The main purposes of this asset are: |
| 5 | + |
| 6 | +- Demonstrate the usage of OCI Python SDK |
| 7 | +- Create a simple OS independent command-line interface for creating bastion sessions |
| 8 | +- Create a simple way to make reusable configuration |
| 9 | +- Create a `ssh` command that works with Linux, Mac OS and Windows by providing the flexibility to configure either `ssh` command or `putty` commands. |
| 10 | + |
| 11 | +The script creates bastion session over SSH, and creates an example command to set up the tunnel for the target application. Other protocols like RDP can then be tunneled over the SSH session through the OCI Bastion Service. |
| 12 | + |
| 13 | +Some documentation for inspiraton: |
| 14 | + |
| 15 | +[https://www.ateam-oracle.com/post/openssh-proxyjump-with-oci-bastion-service](https://www.ateam-oracle.com/post/openssh-proxyjump-with-oci-bastion-service) |
| 16 | +[https://fluffyclouds.blog/2022/06/02/create-oci-bastion-sessions-with-python-sdk/](https://fluffyclouds.blog/2022/06/02/create-oci-bastion-sessions-with-python-sdk/) |
| 17 | + |
| 18 | +## Why use the OCI Bastion Service |
| 19 | + |
| 20 | +Oracle Cloud Infrastructure (OCI) Bastion Service, is a fully managed service providing secure and ephemeral Secure Shell (ssh) access to the private resources in OCI. OCI Bastion Service, like the bastion fortress of medieval times, improves security posture by providing an additional layer of defense against external threats. |
| 21 | + |
| 22 | +Accessing virtual services directly from the internet is a clear no-go. Best practices is to never expose compute resources directly, neither for SSH or RDP traffic. RDP is known to be one of the most common Initial Access Vectors for ransomware types of attacks. |
| 23 | + |
| 24 | +Common practice is to place a compute node with a minimum OS in a DMZ as jump host, and always use this as the entrypoint. |
| 25 | +The main weakness with this model is: |
| 26 | +- A extra computer-node that needs to be managed, monitored and patched |
| 27 | +- Extra set of required resources with risk of misconfiguration |
| 28 | +- The jump server will require an additional layer of user governance. |
| 29 | + |
| 30 | +The OCI Bastion Service removes the public and private virtual cloud networking (VCN) hassle for access to a jump host. No public IP is needed, resulting in no surface attack area or zero-day vulnerabilities with a dedicated jump host. Customers also eliminate shared credentials, broad access limits, and other bad habits of using jump hosts. OCI Bastion Service integrates with OCI Identity and Access Management (IAM) and allows the organization to control who can access a bastion or a session and what they can do with those resources. |
| 31 | + |
| 32 | +The OCI Bastion Service exists in two flavors: |
| 33 | +- Managed Session |
| 34 | +With managed sessions an agent is running on the compute node, and the bastion session connects to the agent and tunnels SSH through the agent. The managed session makes it possible to connect to a compute node from other networks without configure routing between the network where the compute node resides, and the network the bastion connection is initiated from. |
| 35 | +- Port Forwarding |
| 36 | +In this mode the OCI Bastion Service does not tunnel though the agent, but the OCI Bastion Service must have access to the subnet where the compute node resides, and the subnet security list |
| 37 | +For additional description of the OCI Bastion Service please review: |
| 38 | + |
| 39 | +## Requirements |
| 40 | + |
| 41 | +The following components needs to be installed in your environment: |
| 42 | +- Python 3.8 or above (latest patch version) |
| 43 | +- Latest version of the OCI CLI |
| 44 | +- Requirements, as defined in requirements.txt |
| 45 | + |
| 46 | +If you need to run older Python versions (below 3.8), note the changes for asyncio in the exec_command procedure. |
| 47 | + |
| 48 | +[OCI CLI Install guide](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) |
| 49 | + |
| 50 | +The file requirements.txt lists the Python modules required. |
| 51 | +Install the required modules with |
| 52 | + |
| 53 | +```pip install -r requirements.txt``` |
| 54 | + |
| 55 | + |
| 56 | +## Script Usage |
| 57 | + |
| 58 | +In addition, the script require a JSON configuration file. |
| 59 | + |
| 60 | +The basic structure of the config file looks like: |
| 61 | +``` |
| 62 | +{ "sessions":[ |
| 63 | + { <session one points to ociconfigurations>}, |
| 64 | + { <session two points to ociconfigurations>}], |
| 65 | + "ociconfigurations": [ |
| 66 | + { <ociconfiguration one>}, |
| 67 | + { <ociconfiguration one>}] |
| 68 | +} |
| 69 | +``` |
| 70 | +For example, review [config_example.json](files/config_example.json) |
| 71 | + |
| 72 | +The following elements exists in the configuration file. |
| 73 | + |
| 74 | +- "sessions": JSON array with one JSON config entry pr. Session |
| 75 | +- "ociconfigurations": JSON Array with one JSON element pr. OCI SDK configuration profile. |
| 76 | + |
| 77 | +Each “session” element has the following elements: |
| 78 | +- "sessionType":"PORT_FORWARDING" or MANAGED |
| 79 | +- "OCIConfig"-: name of profile, it looked up in the ociconfigurations array |
| 80 | +- "bastionOCID": OCID to the configured OCI Bastion service |
| 81 | +- "bastionPublicKeyFile":file with public key to the Bastion SSH session |
| 82 | +- "bastionPrivateKeyFile":Private key of bastion session key pair, |
| 83 | +- "targetPrivateKeyFile":Used for reference in the target `ssh` command, |
| 84 | +- "targetPort": Portnumber for the target SSH tunnel though the bastions Service. Use standard port for RDP if target is RDP, |
| 85 | +- "localPort":"2222", |
| 86 | +- "sessionDisplayName": Display name of the session in the OCI Console |
| 87 | +- "sshCommand": For linux, normally, for windows, normally putty teh command that will be generated into the tunnel command |
| 88 | +- "sshCommandOptions": applied to the tunnel comamndline, like ssh timeout options |
| 89 | +- "targetOCIDID":OCID of the target service, |
| 90 | +- "targetPrivateIP":IP Address of the target |
| 91 | +- "osUserName": Used for the generated `ssh` command , |
| 92 | +- "ociRegion": Region where the target resource runs, |
| 93 | +- "timetolive":Time the Bastion tunnel lives. Maximum value is 3600 sec., |
| 94 | +- "maxWaitCount":If the script creates the tunnel after creation of the session, maximum number of retries |
| 95 | +- "waitRefresh": time in sec, between each retry to establish the tunnel |
| 96 | +- "ociconfigurations": Array of OCI configurations |
| 97 | + |
| 98 | +Each array entry got the following JSON elements |
| 99 | +- "configName": Name of entry. Referenced from a session element above |
| 100 | +- "configFileName": Path to the OCI CLI configuration file |
| 101 | +- "profileName": Name of profile in the OCI CLI configuration file |
| 102 | + |
| 103 | + |
| 104 | +```Script commandline options. |
| 105 | + --configfile name of JSON configfile with named session and OCI CLI config info |
| 106 | + --session named session, section in config file |
| 107 | + --exec executes the `ssh` command and establishes the SSH connection |
| 108 | + --loglevel logging level, info or debug. default info |
| 109 | + --log logging output file or stdout, defaul stdout |
| 110 | +``` |
| 111 | +Example command: |
| 112 | + |
| 113 | +Example commandline: |
| 114 | +```python bastionsession.py --session port-example --configfile config_examlpe.json --loglevel debug``` |
| 115 | + |
| 116 | +Sample output |
| 117 | + |
| 118 | +``` |
| 119 | +Bastion session manager 1.0 26.02.25 |
| 120 | +
|
| 121 | +INFO:root:Open logfile |
| 122 | +Open logfile: stderr |
| 123 | +Successfully loaded session and OCI Config parameters |
| 124 | +Waiting for session state to be active. Current State ..CREATING |
| 125 | +Session has been created and is ACTIVE |
| 126 | +Bastion session created |
| 127 | +Port managed start cmd |
| 128 | +Port forwarding start cmd |
| 129 | +ssh -i <privateKey> -N -L <localPort>:10.10.1.229:22 -p 22 ocid1.bastionsession.oc1.eu-frankfurt-1.ama...ama@host.bastion.eu-frankfurt-1.oci.oraclecloud.com |
| 130 | +ssh tunnel command: |
| 131 | +putty -i c:\\usr\\ssh_keys\\mykey.ppk -N -ssh -L 2222:10.10.1.229:22 ocid1.bastionsession.oc1.eu-frankfurt-1.ama...ama@host.bastion.eu-frankfurt-1.oci.oraclecloud.com |
| 132 | +Client Connect: |
| 133 | +putty -i c:\\usr\\ssh_keys\\myprivatetkey.ppk -P 2222 ios@localhost |
| 134 | +Successfully completed bastion session(s) |
| 135 | +``` |
| 136 | + |
| 137 | +# License |
| 138 | + |
| 139 | +Copyright (c) 2025 Oracle and/or its affiliates. |
| 140 | + |
| 141 | +Licensed under the Universal Permissive License (UPL), Version 1.0. |
0 commit comments