PERSONALSOC 0.1.14 · Last updated: 2026-10-17

PersonalSOC User Manual

This explains how to use the app that gathers this device's logs and the state of its defenses, read-only and with one button, into a report you can grasp at a glance. The on-screen steps come first, and the command line is collected in a later chapter.

1. What PersonalSOC is

PersonalSOC is an app that gathers this device's logs and the state of its defenses and sums them up as findings and a report. It is built so that an individual with no dedicated security staff can see, with evidence, what is happening on their own device and decide what to do next.

It is read-only, so it never changes settings, deletes files or blocks traffic. Log analysis is done by fixed analyzers that use neither an LLM nor the network. LLM integration is optional and off at first.

What it does not do

It is a tool for the one device it runs on. There is no feature for viewing several devices together.
It never raises its privileges. A log that only root can read is shown as unreadable, and sudo is not used.
“No detections” is not proof of safety. The overall risk is also only a 0 to 100 estimate, not a probability.
It reads only a fixed set of sources. You cannot specify files or commands to read from the screen.

2. Installing and launching

PersonalSOC is a separate app from RoamSwitch. It has its own icon and ships bundled with RoamSwitch. There is no entry for it in RoamSwitch's menus; you open it as an app of its own.

Environment	How to install and open it
Mac	The RoamSwitch DMG contains PersonalSOC.app. Move it to the Applications folder and open “PersonalSOC”. It requires macOS 12 or later.
Linux (client edition)	It is bundled with RoamSwitch's deb, rpm, tarball and AUR packages. Open “PersonalSOC” from the app list, or run `personalsoc-app` in a terminal. The window needs WebKitGTK 4.1, which deb and rpm install automatically. On Arch (AUR), install `webkit2gtk-4.1` as an optional dependency.
Linux Server Edition	Only the command is included. Run `personalsoc` in a terminal (the window app `personalsoc-app` is not included). For running the server edition, see the Operations Manual (Linux Server).

It also works without RoamSwitch

PersonalSOC works on its own. On a device that has RoamSwitch, it also pulls in unresolved detections, configuration diagnostics and more from RoamSwitch's read-only MCP and puts them into one report together with the log findings. Without RoamSwitch, that source is simply not used.

3. Your first status check

It reads the fixed sources only when you press “Check status”. You can switch off any source you do not want it to read in Settings.

Steps

Open the app and press “Settings” at the top right.
Below it, the sources read on this OS are listed. Untick any you do not want read.
Press “Save”, then “← Back” to return to the home screen.
Press “Check status”. A progress bar appears, and the result tabs show up when it finishes.

When it finishes, the counts appear, for example “Check complete. 3 detection(s) / 2 IOC(s)”. The next chapter explains the tabs.

Environment	What is read
Mac	The macOS unified log (sudo and sshd for the last 24 hours) and MCP settings (Claude Code, Claude Desktop, opencode, Cursor). It also reads web server access logs (the stock macOS Apache and Homebrew's nginx and httpd). The record of what Gatekeeper refused takes about 10 seconds to read, so it is off at first.
Linux	The authentication log (sshd), auditd, web access logs (nginx / apache, including per-virtual-host logs), DNS query logs (dnsmasq / named) and MCP settings.
Both	If RoamSwitch is installed, its read-only MCP. You can turn it off with the “Get detection history and configuration diagnostics from RoamSwitch's MCP (read-only)” checkbox.

4. Reading the results

Tab	What you see
Dashboard	Charts show the overall risk (an estimate) gauge, counts by severity, occurrences by category, the trend over time and MITRE ATT&CK counts.
Report	A Markdown report covering the sources, the findings by category and the IOCs. “Copy Markdown” copies all of it, and “Show Markdown source” switches to the raw text.
Findings	You can go through the detections one by one, each with its severity, confidence, ATT&CK ID, count and the line numbers of the log lines that support it.
Sources	A list of what was checked. The state is one of “Read”, “Not present”, “Unreadable (permission)”, “Failed” or “Disabled”, and sources that are unreadable or failed have not been checked.
IOC	A list of the IPs, domains, URLs and hashes found in the logs. They are shown in a defanged form such as 198[.]51[.]100[.]7 so that nothing is opened by accident.
Summary input for an LLM	This tab appears only when LLM integration is off. It is a summary for handing to an LLM by hand, and it contains no raw log lines. Use “Copy”.

About the overall risk number

The overall risk is a 0 to 100 estimate, adding up each type of detection weighted by severity and confidence. It is not a probability, and it does not grow however often the same detection appears. Confidence has three levels, “Confirmed”, “Likely” and “Hypothesis”.

5. Settings and scheduled runs

“Settings” at the top right of the home screen is divided into tabs by function. After changing something, press “Save”, then “← Back” to return home.

Display language Besides “Automatic (follow the OS)”, you can choose Japanese, English, German, Spanish, French, Italian, Korean, Portuguese (Portugal), Simplified Chinese or Traditional Chinese, each listed under its own name.

Scheduled runs (optional)

Tick “Check automatically at regular intervals” and save, and it is registered as a launchd user agent on Mac and a systemd user timer on Linux. You pick the interval from 7 steps between 15 minutes and 24 hours, and it starts at 1 hour.

Only personalsoc scan --notify runs, and root is not used. It notifies only when there is a detection that was not there last time, and the message contains only counts (on Linux, notify-send is needed). You can also turn notifications off with “Notify only when there is a detection that was not there last time”.

Untick it and save, and the registration is removed.

6. LLM integration (optional)

LLM integration is optional and off at first. When enabled, after the status check the command of the LLM you chose carries out further investigation and writes a report as an auditor. The commands you can use are opencode, claude, codex and agy.

Steps

Tick “Enable LLM integration”.
Choose the “LLM to use”. One shown as “(not installed)” has no command on this device.
If needed, change the model and the timeout (seconds). If you leave the model empty, that LLM's default is used.
Press “Save”, go back home and press “Check status”. After the check, the LLM investigation runs right away.

What reaches the LLM

What is passed on is the content of the detections, the log lines that serve as evidence, the strings returned by MCP and the notes on the sources. They are passed so that the situation can be investigated accurately.
Before they are passed on, secrets such as keys, tokens and passwords are masked and invisible characters are removed.
PersonalSOC gives the LLM neither a shell nor files. The LLM only requests what it wants to look into, and PersonalSOC runs the read-only tools it allows and returns the results. There are at most 6 rounds of investigation.
The LLM's output is not trusted and is treated as a quotation in the report. An LLM can read a detection as more serious than it is, so always check the conclusion against the “Findings”.

About restricting tools

In the “Status” column of the table in Settings, opencode and claude show “Tools locked”. claude is started with its built-in tools, MCP servers and skills switched off and without loading your own settings. opencode is started with every permission denied.
codex and agy cannot be switched off this way, so they show “Tools cannot be locked”.

When you use an LLM whose tools cannot be locked

During the investigation the LLM may read files on its own judgment, and what it reads is sent to that LLM's service. To use one, tick the confirmation under “LLM to use”. The confirmation is per LLM, and without the tick you can neither save nor run the investigation.

Relation to Zero Telemetry

RoamSwitch's “Zero Telemetry” (no communication content or logs are sent out) describes RoamSwitch itself. Communication that happens when you enable PersonalSOC's LLM integration is not covered by it. Where the data goes and how it is handled follow the terms of the LLM you chose and its provider. While LLM integration stays off, PersonalSOC does not send the contents of your logs outside the device.

7. Using the command line

The command is personalsoc. On Linux it is at /usr/bin/personalsoc, and on Mac it is inside PersonalSOC.app/Contents/MacOS/.

Command	What it does
`personalsoc scan`	Automatically checks this device's logs and RoamSwitch (MCP) and prints the detections as a list. For the logs only root can read (authentication, web server, auditd), run it with `sudo`.
`personalsoc scan --report`	Prints the Markdown report (without an LLM).
`personalsoc scan --llm <name>`	Prints the report that the LLM wrote as an auditor after investigating with read-only tools. `name` is opencode, claude, codex, agy and so on.
`personalsoc scan --notify`	Notifies only when there is a detection that was not there last time. This is the form the scheduled run calls.
`personalsoc <type> <file>`	Analyzes a file you name. `type` is one of sshd, auditd, web, dns, unified, mcp, inject and ioc. If you give `-` as `file`, it reads standard input, and `--report`, `--brief` and `--llm` can be added.
`--lang <lang>`	Can be added to any command and sets the display language, taking priority over the setting. The codes are ja, en, de, es, fr, it, ko, pt-PT, zh-Hans and zh-Hant.

LLMs on the command line

On the command line, running with --llm is itself the explicit act of handing the content to the LLM, so it works even when “Enable LLM integration” is off in Settings. The confirmation for LLMs whose tools cannot be locked is not asked for either, so when you use codex or agy, do so knowing that files may be read and sent during the investigation.

8. Where data is stored, and updates

What is stored

Item	Location
Settings	`~/.config/personalsoc/settings.json` (saved with permissions that only you can read and write)
Record of the previous detections (for deciding on notifications)	`~/.local/state/personalsoc/last.json` (only hashes that act as fingerprints of the detections; no log text is kept)
Scheduled-run registration	On Mac, `~/Library/LaunchAgents/dev.personalsoc.scan.plist` (its output goes to `~/Library/Logs/personalsoc-scan.log`). On Linux, `personalsoc-scan.timer` and `personalsoc-scan.service` in `~/.config/systemd/user/`.

PersonalSOC does not save reports or collected logs to files. To keep one, use “Copy Markdown” on the screen or the command-line output. To add an LLM, edit profiles in the settings file by hand; it cannot be changed from the screen.

Updates

On Mac, you update from “Updates” in Settings. It connects to lafine.net only when you press “Check for updates”, and receives information about the latest version (a public JSON file). Nothing about this device or its logs is sent. If a newer version exists, press “Download and install”. The downloaded file has its signature verified with the public key embedded in the app, and nothing is installed if that fails. The app restarts when it finishes.

On Mac, updating RoamSwitch itself does not update PersonalSOC. Linux has no update feature, and PersonalSOC is included in the updates of the RoamSwitch packages.

9. When something goes wrong

Symptom	Cause and remedy
A source shows “Unreadable (permission)”	The authentication, web server and auditd logs cannot be read without administrator rights. PersonalSOC does not raise its own privileges, so run it with `sudo`. This is different from “no detections”: that log has not been checked.
Scheduled runs cannot be saved	If Mac says the app is running from a temporary quarantined location, move PersonalSOC.app to the Applications folder, reopen it and save again. If it says the personalsoc command was not found, `personalsoc` must be in the same place as the app itself.
The claude investigation fails with “Not logged in”	PersonalSOC starts claude without loading your own settings (such as env and apiKeyHelper in `~/.claude/settings.json`). Setups that authenticate through those settings, such as a proxy, Bedrock or Vertex, fail. If you add `"llm_user_settings": ["claude"]` to the settings file by hand, claude is started with your settings loaded. Its tools and MCP stay switched off.

← PersonalSOC product page To the User Manual for Mac →