PERSONALSOC 0.1.14 · 최종 업데이트: 2026-10-17

PersonalSOC 사용 설명서

이 단말의 로그와 방어 상태를 버튼 하나로 읽기 전용으로 모아 한눈에 알 수 있는 보고서로 만들어 주는 앱의 사용법입니다. 화면 조작을 순서대로 설명하고, 명령줄은 뒤쪽 장에 모아 두었습니다.

1. PersonalSOC란

PersonalSOC는 이 단말의 로그와 방어 상태를 모아 검출 사항과 보고서로 정리하는 앱입니다. 전담 담당자가 없는 개인이 자신의 단말에서 무슨 일이 일어나고 있는지를 근거와 함께 알고 다음에 할 일을 정할 수 있도록 만들어졌습니다.

읽기 전용이므로 설정을 바꾸거나 파일을 지우거나 통신을 차단하지 않습니다. 로그 분석은 LLM도 네트워크도 사용하지 않는 정해진 절차의 분석기가 수행합니다. LLM 연동은 선택 사항이며 처음에는 꺼져 있습니다.

할 수 없는 것

실행 중인 단말 1대를 위한 도구입니다. 여러 단말을 한꺼번에 보는 기능은 없습니다.
권한을 높이지 않습니다. root가 아니면 읽을 수 없는 로그는 “읽을 수 없음”으로 표시하며 sudo는 사용하지 않습니다.
“검출 없음”은 안전의 증명이 아닙니다. 종합 위험도 0에서 100까지의 기준값일 뿐 확률이 아닙니다.
읽는 대상은 정해진 수집원뿐입니다. 화면에서 읽을 파일이나 명령을 지정할 수는 없습니다.

2. 설치와 실행 방법

PersonalSOC는 RoamSwitch와는 별도의 앱입니다. 고유한 아이콘을 가지며 RoamSwitch 배포물에 동봉되어 있습니다. RoamSwitch의 메뉴에는 진입점이 없고 독립된 앱으로 직접 엽니다.

환경	설치와 여는 방법
Mac	RoamSwitch의 DMG에 PersonalSOC.app이 들어 있습니다. 응용 프로그램 폴더로 옮긴 뒤 “PersonalSOC”를 엽니다. macOS 12 이상이 필요합니다.
Linux (클라이언트 에디션)	RoamSwitch의 deb, rpm, tarball, AUR 패키지에 동봉되어 있습니다. 앱 목록에서 “PersonalSOC”를 열거나 터미널에서 `personalsoc-app`을 실행합니다. 화면에는 WebKitGTK 4.1이 필요하며 deb와 rpm에서는 자동으로 설치됩니다. AUR에서는 `webkit2gtk-4.1`을 선택적 의존성으로 설치하세요.
Linux Server Edition	명령만 포함되어 있습니다. 터미널에서 `personalsoc`를 실행합니다(화면 앱 `personalsoc-app`은 포함되지 않습니다). 서버 에디션 운영은 운영 매뉴얼 (Linux Server)을 참조하세요.

RoamSwitch가 없어도 사용할 수 있습니다

PersonalSOC는 단독으로도 사용할 수 있습니다. RoamSwitch가 설치된 단말에서는 RoamSwitch의 읽기 전용 MCP에서 미해결 탐지와 설정 진단 결과 등도 가져와 로그의 검출 사항과 함께 하나의 보고서로 정리합니다. 설치되어 있지 않으면 그 수집원은 사용되지 않습니다.

3. 첫 상황 확인

'상태 확인'을 눌렀을 때만 고정된 수집원을 읽습니다. 읽게 하고 싶지 않은 수집원은 설정에서 끌 수 있습니다.

순서

앱을 열고 오른쪽 위의 “설정”을 누릅니다.
그 아래에 이 OS에서 읽는 수집원이 나열됩니다. 읽게 하고 싶지 않은 것이 있으면 체크를 해제합니다.
“저장”을 누른 뒤 “← 뒤로”로 홈 화면에 돌아갑니다.
“상황 확인”을 누릅니다. 진행 상황 막대가 나타나고, 끝나면 결과 탭이 나열됩니다.

끝나면 “확인이 끝났습니다. 탐지 3건 / IOC 2건”처럼 건수가 표시됩니다. 탭 보는 법은 다음 장에서 설명합니다.

환경	읽는 대상
Mac	macOS 통합 로그(최근 24시간의 sudo와 sshd)와 MCP 설정(Claude Code, Claude Desktop, opencode, Cursor). 웹 서버 액세스 로그(macOS 기본 Apache, Homebrew의 nginx와 httpd)도 읽습니다. Gatekeeper가 거부한 기록은 읽는 데 약 10초가 걸리므로 처음에는 꺼져 있습니다.
Linux	인증 로그(sshd), auditd, 웹 액세스 로그(nginx / apache. 가상 호스트별 로그 포함), DNS 쿼리 로그(dnsmasq / named), MCP 설정.
공통	RoamSwitch가 설치되어 있으면 그 MCP(읽기 전용). “RoamSwitch의 MCP(읽기 전용)에서 탐지 이력과 설정 진단을 가져옵니다” 체크로 끌 수 있습니다.

4. 결과 보는 법

탭	보이는 내용
대시보드	종합 위험(기준값) 게이지, 심각도별 건수, 분류별 발생 건수, 발생 추이, MITRE ATT&CK 건수를 그래프로 볼 수 있습니다.
보고서	수집원, 분류별 검출 사항, IOC를 정리한 Markdown 보고서입니다. “Markdown 복사”로 통째로 복사할 수 있고, “Markdown 소스 표시”로 원본 문자열로 전환할 수도 있습니다.
발견 사항	검출을 한 건씩 볼 수 있습니다. 심각도, 확도, ATT&CK 번호, 건수, 근거가 된 로그의 행 번호가 붙습니다.
수집원	무엇을 확인했는지의 목록입니다. 상태는 “읽음”, “해당 없음”, “읽을 수 없음(권한)”, “실패”, “비활성” 중 하나이며, “읽을 수 없음”과 “실패”인 수집원은 확인하지 못한 것입니다.
IOC	로그에서 발견된 IP, 도메인, URL, 해시의 목록입니다. 실수로 열지 않도록 198[.]51[.]100[.]7처럼 무해화한 표기로 나옵니다.
LLM용 요약 입력	LLM 연동이 꺼져 있을 때만 나타나는 탭입니다. 직접 LLM에 전달하기 위한 요약이며 로그의 원문 행은 들어 있지 않습니다. “복사”로 사용합니다.

종합 위험 수치에 대하여

종합 위험은 탐지 종류별로 심각도와 확도에 가중치를 두어 더한 0에서 100까지의 기준값입니다. 확률이 아니며, 같은 탐지가 몇 번 나와도 늘어나지 않습니다. 확도는 “확정”, “유력”, “가설”의 3단계입니다.

5. 설정과 정기 실행

홈 화면 오른쪽 위의 “설정”을 열면 기능별 탭으로 나뉘어 있습니다. 바꾼 뒤에는 “저장”을 누르고 “← 뒤로”로 홈에 돌아갑니다.

표시 언어 “자동(OS 설정에 따름)” 외에 日本語, English, Deutsch, Español, Français, Italiano, 한국어, Português (Portugal), 简体中文, 繁體中文 중에서 고를 수 있습니다.

정기 실행(선택)

“정기적으로 자동 확인”에 체크하고 저장하면 Mac에서는 launchd 사용자 에이전트, Linux에서는 systemd 사용자 타이머에 등록됩니다. 간격은 15분에서 24시간까지 7단계 중에서 고르며, 처음에는 1시간입니다.

실행되는 것은 personalsoc scan --notify뿐이며 root는 사용하지 않습니다. 지난번에 없던 탐지가 있을 때만 알리고, 본문은 건수뿐입니다(Linux에서는 notify-send가 필요합니다). “지난번에 없던 탐지가 있을 때만 알림”으로 알림을 끌 수도 있습니다.

체크를 해제하고 저장하면 등록이 해제됩니다.

6. LLM 연동(선택)

LLM 연동은 선택 사항이며 처음에는 꺼져 있습니다. 활성화하면 상황 확인 후에 선택한 LLM의 명령이 추가 조사를 하고 감사관으로서 보고서를 작성합니다. 사용할 수 있는 것은 opencode, claude, codex, agy 명령입니다.

순서

“LLM 연동 사용”에 체크합니다.
“사용할 LLM”을 선택합니다. “(미설치)”로 표시되는 것은 이 단말에 명령이 없는 것입니다.
필요하면 모델과 타임아웃(초)을 바꿉니다. 모델을 비워 두면 그 LLM의 기본값이 사용됩니다.
“저장”을 누르고 홈으로 돌아가 “상황 확인”을 누릅니다. 확인 후 이어서 LLM 조사가 실행됩니다.

LLM에 전달되는 것

전달되는 것은 검출 내용, 근거가 되는 로그의 행, MCP 반환값의 문자열, 수집원의 비고입니다. 상황을 정확하게 조사하기 위해 이것들을 전달합니다.
전달하기 전에 키, 토큰, 비밀번호 같은 비밀을 마스킹하고 보이지 않는 문자를 제거합니다.
PersonalSOC는 LLM에 셸도 파일도 주지 않습니다. LLM은 “조사하고 싶은 것”을 요청할 뿐이며, PersonalSOC가 허용한 읽기 전용 도구를 실행해 결과를 돌려줍니다. 조사 횟수는 최대 6회입니다.
LLM의 출력은 신뢰하지 않으며 보고서에서는 인용으로 취급합니다. LLM은 탐지를 과도하게 심각하게 해석하기도 하므로 결론은 반드시 “검출 사항”에서 확인하세요.

도구 제한에 대하여

설정 표의 “상태” 열에서 opencode와 claude는 “도구를 제한하고 실행”으로 표시됩니다. claude는 내장 도구, MCP 서버, 스킬을 끄고 사용자 설정도 읽어 들이지 않은 채 실행합니다. opencode는 모든 권한을 거부로 한 채 실행합니다.
codex와 agy는 이 방법으로는 멈출 수 없으므로 “도구를 제한할 수 없음”으로 표시됩니다.

도구를 제한할 수 없는 LLM을 사용할 때

조사 중에 LLM이 스스로 판단해 파일을 읽을 수 있으며, 읽은 내용은 그 LLM의 서비스로 전송됩니다. 사용하려면 “사용할 LLM” 아래의 확인란에 체크합니다. 확인은 LLM별로 하며, 체크가 없으면 저장도 조사도 할 수 없습니다.

Zero Telemetry와의 관계

RoamSwitch의 “Zero Telemetry”(통신 내용과 로그를 외부로 전송하지 않음)는 RoamSwitch 본체에 대한 설명입니다. PersonalSOC의 LLM 연동을 활성화했을 때의 통신은 여기에 포함되지 않습니다. 전송처와 취급은 선택한 LLM과 그 제공자의 약관을 따릅니다. LLM 연동을 꺼 둔 상태라면 PersonalSOC가 로그 내용을 단말 밖으로 보내는 일은 없습니다.

7. 명령줄에서 사용하기

명령은 personalsoc입니다. Linux에서는 /usr/bin/personalsoc에, Mac에서는 PersonalSOC.app/Contents/MacOS/ 안에 있습니다.

명령	할 수 있는 일
`personalsoc scan`	이 기기의 로그와 RoamSwitch(MCP)를 자동으로 확인하고 탐지 결과를 목록으로 표시합니다. root만 읽을 수 있는 로그(인증, 웹 서버, auditd)는 `sudo`를 붙여 실행합니다.
`personalsoc scan --report`	Markdown 보고서를 표시합니다(LLM 없음).
`personalsoc scan --llm <name>`	LLM이 읽기 전용 도구로 조사하여 감사관으로서 작성한 보고서를 표시합니다. `name`은 opencode, claude, codex, agy 등입니다.
`personalsoc scan --notify`	지난번에 없던 탐지가 있을 때만 알립니다. 정기 실행이 호출하는 형태입니다.
`personalsoc <type> <file>`	지정한 파일을 분석합니다. `type`은 sshd, auditd, web, dns, unified, mcp, inject, ioc 중 하나입니다. `file`에 `-`를 지정하면 표준 입력을 읽으며, `--report`, `--brief`, `--llm`도 붙일 수 있습니다.
`--lang <lang>`	어떤 명령에도 붙일 수 있으며, 표시 언어를 설정보다 우선하여 지정합니다. 코드는 ja, en, de, es, fr, it, ko, pt-PT, zh-Hans, zh-Hant입니다.

명령줄에서의 LLM

명령줄에서는 --llm을 붙여 실행하는 것 자체가 LLM에 넘기는 명시적인 조작이므로, 설정의 “LLM 연동 사용”이 꺼져 있어도 동작합니다. 도구를 제한할 수 없는 LLM의 확인도 요구되지 않으므로, codex나 agy를 사용할 때는 조사 중에 파일이 읽혀 전송될 수 있음을 이해한 뒤에 사용하세요.

8. 저장 위치와 업데이트

저장되는 것

항목	위치
설정	`~/.config/personalsoc/settings.json`(본인만 읽고 쓸 수 있는 권한으로 저장됩니다)
지난번 검출의 기록(알림 판정용)	`~/.local/state/personalsoc/last.json`(검출의 지문에 해당하는 해시뿐이며 로그 문자열은 남기지 않습니다)
정기 실행의 등록	Mac은 `~/Library/LaunchAgents/dev.personalsoc.scan.plist`(출력은 `~/Library/Logs/personalsoc-scan.log`). Linux는 `~/.config/systemd/user/`의 `personalsoc-scan.timer`와 `personalsoc-scan.service`입니다.

PersonalSOC는 보고서나 수집한 로그를 파일로 저장하지 않습니다. 남기고 싶을 때는 화면의 “Markdown 복사”나 명령줄 출력을 이용하세요. LLM을 늘리고 싶을 때는 설정 파일의 profiles를 직접 편집합니다. 화면에서는 바꿀 수 없습니다.

업데이트

Mac은 설정의 “업데이트”에서 갱신합니다. “업데이트 확인”을 눌렀을 때만 lafine.net에 접속하여 최신 버전 정보(공개 JSON)를 받습니다. 이 단말이나 로그의 정보는 보내지 않습니다. 새 버전이 있으면 “다운로드하고 설치”를 누릅니다. 내려받은 파일은 앱에 내장된 공개 키로 서명을 검증하며, 실패하면 아무것도 설치하지 않습니다. 끝나면 앱이 다시 시작됩니다.

Mac에서는 RoamSwitch 본체의 업데이트로는 PersonalSOC가 갱신되지 않습니다. Linux에는 업데이트 기능이 없으며 RoamSwitch 패키지의 업데이트에 포함됩니다.

9. 문제가 생겼을 때

증상	원인과 대처
수집원이 “읽을 수 없음(권한)”으로 표시된다	인증, 웹 서버, auditd 로그는 관리자 권한이 없으면 읽을 수 없습니다. PersonalSOC는 스스로 권한을 높이지 않으므로 `sudo`를 붙여 실행하세요. '탐지 없음'과는 다른 상태이며, 그 로그는 확인되지 않았습니다.
정기 실행을 저장할 수 없다	Mac에서 “격리된 임시 위치에서 실행 중”이라고 표시되면 PersonalSOC.app을 응용 프로그램 폴더로 옮겨 다시 열고 한 번 더 저장합니다. “personalsoc 명령을 찾을 수 없음”이 표시되면 앱 본체와 같은 위치에 `personalsoc`이 있어야 합니다.
claude의 조사가 “Not logged in”으로 실패한다	PersonalSOC는 claude를 사용자 설정(`~/.claude/settings.json`의 env나 apiKeyHelper 등)을 읽어 들이지 않은 채 실행합니다. 프록시, Bedrock, Vertex처럼 그 설정으로 인증하는 구성에서는 실패합니다. 설정 파일에 `"llm_user_settings": ["claude"]`를 직접 추가하면 사용자 설정을 읽어 들여 실행합니다. 도구와 MCP는 계속 꺼진 상태입니다.

← PersonalSOC 제품 페이지 Mac용 사용 설명서로 →