Add guide for creating an isolated instance#47
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a new documentation guide describing multiple ways to isolate an OpenStack instance for malware analysis/safe testing, and surfaces it in site navigation and the docs landing page.
Changes:
- Adds a new “How to Isolate an Instance” guide with three isolation approaches (detach NICs, ingress-only SSH/RDP via security groups, isolated multi-instance network).
- Updates MkDocs navigation and the docs homepage to link the new guide.
- Adds/updates screenshots used by the new guide.
Reviewed changes
Copilot reviewed 3 out of 12 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds the new guide to the MkDocs nav under “User Guides”. |
| docs/index.md | Adds a homepage link to the new isolation guide. |
| docs/guides/How to Isolate an Instance.md | New guide content describing three isolation options and workflow steps. |
| docs/img/isolate-instance/setGroups.png | Screenshot used in Option 2 security group selection step. |
| docs/img/isolate-instance/passwordChange.png | Screenshot used in Option 1 password setup step. |
| docs/img/isolate-instance/detach-2.png | Screenshot used in Option 1 detaching external network step. |
| docs/img/isolate-instance/detach-3.png | Screenshot used in Option 1 “confirm isolation” step. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Before following this guide, you should know how to | ||
|
|
||
| - Set up an instance: [OpenStack Setup Guide](../OpenStack Setup Guide) | ||
| - Set up a virtual network and attach an instance: [How to use Virtual Networks](../How to use Virtual Networks) | ||
| - Configure security groups: [Security Groups](../Security Groups) |
There was a problem hiding this comment.
The prerequisite links point to paths that don’t exist from docs/guides/ (e.g., ../OpenStack Setup Guide). These should link to the actual guide files in the same directory (e.g., ./OpenStack Setup Guide.md, ./How to use Virtual Networks.md, ./Security Groups.md) so they work in both MkDocs and GitHub rendering.
| 2. Click **`Manage Rules`** on the new security group and **delete the existing rules** | ||
|  | ||
|
|
||
| 3. Add a new rule to allow ingress SSH (Port 3389 for RDP) |
There was a problem hiding this comment.
This step is ambiguous about which port corresponds to which protocol (SSH is port 22; RDP is port 3389). Consider explicitly stating the port/protocol pair (or instructing to choose the built-in “SSH” or “RDP” rule type) to prevent misconfiguration.
| 3. Add a new rule to allow ingress SSH (Port 3389 for RDP) | |
| 3. Add a new ingress rule for the protocol you need: | |
| - For Linux, allow **SSH** on **port 22** (or choose the built-in **SSH** rule type) | |
| - For Windows, allow **RDP** on **port 3389** (or choose the built-in **RDP** rule type) |
| - **Remove the default security group!** | ||
| - Add the security group you just made | ||
|  | ||
|
|
||
| 5. Launch the instance and log in with SSH | ||
| 6. Confirm that the machine cannot access the internet or other computers | ||
|
|
||
| !!! note "Additional Traffic" |
There was a problem hiding this comment.
Deleting all existing security group rules (including default egress) and then attaching the instance to an external network can prevent the VM from obtaining network configuration (e.g., DHCP) and/or from being reachable over SSH/RDP. If the goal is “no outbound internet” but still manageable access, consider keeping the minimum required egress for bootstrapping (or applying the restrictive security group after the instance has an IP / after converting to static addressing).
| - **Remove the default security group!** | |
| - Add the security group you just made | |
|  | |
| 5. Launch the instance and log in with SSH | |
| 6. Confirm that the machine cannot access the internet or other computers | |
| !!! note "Additional Traffic" | |
| - Keep the default security group during the initial boot so the instance can obtain network configuration | |
| - Add the security group you just made | |
|  | |
| 5. Launch the instance and log in with SSH/RDP | |
| 6. After confirming the instance has an IP address and you can connect, remove the default security group so only the restrictive group remains | |
| 7. Confirm that the machine cannot access the internet or other computers | |
| !!! note "Additional Traffic" | |
| If removing all egress breaks DHCP or other first-boot networking in your environment, keep the minimum bootstrapping traffic allowed until the instance has finished configuring its network, then apply the more restrictive security group. | |
| !!! note "Additional Traffic" |
| - Add a security group to allow all traffic between instances on the isolated network | ||
|  | ||
|
|
||
| 3. Create as many instances as you like on the new network: | ||
| - **Do not attach any of them to the external network** | ||
| - **Add all of them to the security group you made in step 2** |
There was a problem hiding this comment.
Step 2 mentions allowing “all traffic between instances on the isolated network” but doesn’t specify how to scope the rule so it’s only between those instances. It would be clearer/safer to call out using a Remote Security Group (self-referential) or a specific isolated subnet CIDR, rather than 0.0.0.0/0.
| - Add a security group to allow all traffic between instances on the isolated network | |
|  | |
| 3. Create as many instances as you like on the new network: | |
| - **Do not attach any of them to the external network** | |
| - **Add all of them to the security group you made in step 2** | |
| - Add a security group that allows all traffic **only between instances on the isolated network** | |
| - When creating the rule, scope the remote source to either: | |
| - the same security group (Remote Security Group / self-referential rule), or | |
| - the isolated subnet CIDR | |
| - **Do not use `0.0.0.0/0` for this rule**, because that would allow traffic from anywhere rather than only from the isolated instances | |
|  | |
| 3. Create as many instances as you like on the new network: | |
| - **Do not attach any of them to the external network** | |
| - **Add all of them to the security group you made in step 2** so they can communicate only with the other isolated instances covered by that rule |
A guide for creating an isolated instance for malware analysis or other reasons. Contains 3 main subguides: