First Hour After an Incident

A guide to which RoamSwitch features to use, and in what order, during the first hour after RoamSwitch detects a serious threat and contains it.

1. About this page

When RoamSwitch detects a serious threat, it contains it automatically, for example by isolating the network (Air-Gap) or freezing a process. This page sets out, for each environment, what to check, what to preserve, and when to release the containment. For details of each screen and operation, see the individual manuals.

This page explains how to use RoamSwitch's features. It does not cover your organization's communications, legal response, or recovery planning.

2. The same order in every environment

A containment is triggered for a reason. Before you rush to release it, work through these steps in order.

1. Check. See what was detected, when, and in what order, on a timeline.
2. Preserve. Export records and evidence before you release anything or restart. Information about the running state can be lost afterwards.
3. Decide. Decide whether it was an operation you recognize or genuinely suspicious activity.
4. Release. Release the containment only after you have confirmed it is safe.
5. Watch. After releasing, keep watching for a while to see whether the same detection appears again.

To investigate from the logs, you can also use PersonalSOC and AccessScope in section 6.

If you were isolated by ARP spoofing, also read 8.

If ransomware is the cause on the Linux desktop edition, also read 9.

While a Mac or PC is isolated, it cannot open this page. On a Mac, the “Why you're isolated & how to release…” window shows a QR code for this page. On the Linux desktop edition, the release confirmation window shows it. Scan it with a phone on its own connection to read this page. The QR code holds only this page's public address.

3. Mac

1. Open the menu bar 🛡️ icon and check whether it shows “🔒 Isolated (full)” or “🔒 Isolated (degraded)”.
2. Open “ℹ️ Why you're isolated & how to release…” and read the reason it was triggered.
3. Open 🛡️ → Mac Security Comprehensive Diagnostic → “📈 Security Activity Log…”. Narrow the period, then filter by severity and category to see, on a timeline, what was detected just before. Clicking a bar in the chart narrows the list to that time slot.
4. With Pro, you can export the filtered results to CSV and keep them.
5. If you turned on “🧾 Process Execution Recording…” (Pro) beforehand, the history of launched processes is available for investigation. It is off by default.
6. When ransomware or XProtect detection triggers an isolation, evidence is saved automatically just before the network is cut. It holds the list of running processes, the network connections and the list of recently modified files, with a SHA-256 for each file. It is saved in ~/Library/Application Support/RoamSwitch/incident-evidence/. Packet capture is not available on a Mac.
7. Look back over whether you did anything that could explain it, such as launching a suspicious app.
8. From the same menu, choose “🔓 Release Air-Gap isolation” and choose “Release” in the confirmation dialog. Communication comes back immediately.

If the incident involved ransomware, open 🛡️ → Malware Protection (XProtect & ClamAV) → “🗂 Ransomware Recovery…” (Pro). From the APFS local snapshots that RoamSwitch takes on a schedule, you can take files out to another place (~/RoamSwitch-Recovered/<ID>/). Your current files are not overwritten. Taking files out needs Full Disk Access.

4. Linux desktop edition

1. Open the system tray 🛡️ icon. If the network has been isolated because of a serious threat, “🚨 Release Air-Gap & Restore Network” is shown. Do not press it yet.
2. In the main window, open “Notifications” to see the history of notifications from the last 7 days and confirm what was reported.
3. In “Incident Timeline” (an experimental feature), follow the flow from detection through response to release on a timeline.
4. In “Security Activity Log”, combine period, category, severity and keyword filters to investigate what happened just before. The contents of Incident Timeline and Notifications are combined in one view.
5. Look back over whether you did anything that could explain it. Once you have confirmed it is safe, press “🚨 Release Air-Gap & Restore Network” in the tray.

5. Linux Server Edition

Server Edition is operated from the command line. The commands described here also work on the Linux desktop edition (only sudo roamswitch server ack is specific to the Server Edition). A high-confidence isolation (canary tampering, ransomware-like mass rewriting, eBPF Critical / Emergency / Alert, and so on) moves to degraded (DEGRADED) mode by default after 3600 seconds (one hour) if there has been neither an acknowledgement (ack) nor confirmation that the cause is gone. In degraded mode, new connections other than the maintenance SSH ports and the management paths of whitelisted IPs stay blocked, and they never reopen on their own as time passes.

5.1 Check the notifications

If you configured Telegram, LINE or a webhook, the notification has already arrived there. Even if you did not, notifications from the last week are kept locally.

roamswitch notifications

5.2 Look at the isolation state

Shows the eBPF runtime guard's current isolation state and the history of detected incidents.

roamswitch server ebpf

5.3 Check the frozen processes

Lists the processes the guard has frozen with SIGSTOP. Do not resume them until you have preserved the evidence.

roamswitch frozen list

5.4 Preserve the evidence

When the eBPF runtime guard contains a single process, an evidence bundle is created automatically. It holds about 30 seconds of packet capture and, when the PID is known, a snapshot of /proc/<pid> (where tshark is not installed, only the packet capture is skipped). It is saved to /var/lib/roamswitch/incident-evidence/<timestamp>-<ID>/.

When the whole host is isolated, a bundle is not created automatically at present. In that case, or when you want to keep the state from before the containment, take one manually.

sudo roamswitch-incident-capture snapshot --pid <PID> --reason "first-response"

5.5 Export the timeline and the execution record

Export the integrated incident timeline (experimental) as JSON Lines. The execution recorder can be searched by time range or process.

roamswitch timeline --export incident.jsonl
sudo roamswitch events search --since 2h

5.6 Decide, then release

Resume a process that was frozen by a false positive with the command below (resume all resumes all of them).

roamswitch frozen resume <PID>

To allow the same false positive permanently, add it to the allowlist. With --exe, the entry is bound to the path of the executable, so renaming a process does not bypass it.

sudo roamswitch server allowlist add <rule> <process> --exe <path>

Acknowledge the isolation. During FULL isolation, the acknowledgement keeps the strict isolation in place (the operator is treated as having taken over, which stops the move to degraded mode and any automatic release). During degraded mode, the acknowledgement means release.

sudo roamswitch server ack

5.7 If you are locked out

Log in through the cloud provider's web management console (VNC or serial console) and release the emergency isolation. By default, the maintenance SSH ports and the management sessions of the administrator IP stay open during isolation.

sudo roamswitch emergency-restore

5.8 Tidy up afterwards

Evidence bundles are not deleted automatically. Delete bundles older than the retention period (30 days by default) with the command below.

sudo roamswitch-incident-capture prune --keep-days 30

6. Investigating from the logs (PersonalSOC and AccessScope)

RoamSwitch bundles two separate tools for reading logs: PersonalSOC and AccessScope. Both are read-only: they change no settings and block no traffic. The analysis does not use the network and runs entirely on this machine, so it works while the machine is isolated.

6.1 PersonalSOC: put this machine's logs and detections in one report

It reads this machine's authentication logs (sudo and sshd on a Mac; auth.log, auditd, nginx, apache and others on Linux) and RoamSwitch's unresolved detections, and puts a risk estimate, a timeline and IOCs (IPs, domains, URLs, hashes) in one report.

sudo personalsoc scan --report

6.2 AccessScope: find attacks in the access logs

From web server, SSH and other access logs it shows brute-force attempts, web shells, chains of attack steps and successful logins from an unfamiliar source, each with evidence line numbers and a confidence level (confirmed, likely, hypothesis). It never declares a compromise on its own.

sudo accessscope scan --auto --since 24h --report report.md

6.3 Where to use them in the order

• Confirm and decide: use the two tools above to see, with evidence, what happened before and after the detection. Whether the attack is continuing and whether it may have succeeded are the grounds for deciding if it is safe to release.
• Watch: after releasing, run AccessScope repeatedly with the command below; it shows only the findings that were not in the previous run.

sudo accessscope scan --auto --since 24h --since-last --new-only

7. Afterwards

After releasing, keep checking the timeline (on the Mac, the Security Activity Log) for a while to see whether the same detection returns. Keep the exported records and evidence bundles; do not delete them.

Steps outside RoamSwitch, such as changing passwords or keys and contacting the parties concerned, are out of scope for this page.

8. When you are isolated by ARP spoofing

On public Wi-Fi and similar networks, an attacker on the same network can pretend to be the router and try to read your traffic. This is ARP spoofing. RoamSwitch detects it, for example, from a sudden change in the gateway (router) MAC address. Mac and the Linux desktop edition work the same way.

1. When it isolates. On a network you have not registered (protection level: lockdown), it isolates automatically when it detects an anomaly involving the gateway. On a place you registered (home, work and so on), it does not isolate automatically. It shows a warning, and isolates only if you choose “Contain now”.
2. What to check before releasing. The app's confirmation window gives similar advice. Is another device on the same network spoofing ARP? Does the gateway's MAC address match the trusted one (the Linux confirmation window shows the current and the trusted values)? On public Wi-Fi, it is safer to move to another connection, such as tethering, before releasing.
3. Automatic release. A timer alone does not release it. When the gateway's MAC address matches the trusted value on 3 checks in a row, spread over at least 60 seconds, it releases automatically and notifies you. If this cannot be confirmed for 1 hour (the default), it moves to a heavily restricted state (degraded). The degraded state does not open on a timer; you release it by hand.
4. Releasing by hand. On Mac, use “Release Air-Gap isolation” in the menu. On the Linux desktop edition, use “Release Air-Gap and restore the network” in the tray, or sudo roamswitch emergency-restore. If the cause is still there when you release, traffic resumes and you are exposed to it again, so check first.
5. After releasing. Watch for a while to see whether the same detection appears again. If it does, stop using that network and move to another connection.

9. When you are isolated by ransomware (Linux desktop edition)

When many files are rewritten in a short time, RoamSwitch treats it as possible ransomware: it freezes the process doing the rewriting (SIGSTOP) and cuts the network (Air-Gap). The Air-Gap confirmation window opens and shows the reason, the process and how many files were rewritten. This section is for the Linux desktop edition. On Mac, read 3.

1. Check. In the confirmation window and the notification history, see which process rewrote which files. You can also see frozen processes with roamswitch frozen list (5.3).
2. Record. Before releasing or restarting, save the evidence and the timeline as in 5.4 and 5.5.
3. Decide. If the frozen process was an operation you recognize (a backup or compression, for example), it is a false positive. Resume it with sudo roamswitch frozen resume <PID>. If it is a real attack, do not resume it: record the evidence, then end the process.
4. Get the files back. You can take rewritten files out of a snapshot. On screen, in the "Ransomware Recovery" tab in the sidebar (Linux 1.11.21 and later), select the recommended pre-damage (★) snapshot and press "Restore Files" or "Restore a Folder". With commands, run sudo roamswitch-ransomware-rollback list and then sudo roamswitch-ransomware-rollback restore-files <ID> <PATH>. The target is a btrfs subvolume or an LVM logical volume (a home on ext4 cannot use this). A pre-damage snapshot is taken automatically every 6 hours by default. A snapshot at the moment of detection is also taken automatically, but it contains the encrypted files, so it cannot be used to go back to before the encryption. Your current files are not overwritten. The restored files go to <target>/RoamSwitch-Recovered/<ID>/ by default. restore, which rolls everything back, overwrites the current state, so it is a last resort (command only).
5. Release. A timer alone does not release it. It is released only when the cause is confirmed gone, or when you release it with “Release Air-Gap and restore the network” in the tray or sudo roamswitch emergency-restore.
6. Watch. After releasing, check whether the same detection appears again. Check the contents of the restored files before you put them back in their original place.