CLI/헤드리스 운영 가이드

1. 구성품

A 헤드리스 배포는 데몬 + roamswitch CLI(원하는 경우 roamswitch-mcp 추가)에서 실행됩니다. 모든 자율 방어 메커니즘은 GUI 없이 작동합니다.

2. 데몬(시스템 서비스)

클라이언트 에디션

sudo systemctl status  roamswitch.service      # 가동 상태
sudo systemctl enable  roamswitch.service      # 부팅 시 자동 시작(설치 시 활성화)
sudo systemctl restart roamswitch.service      # 재시작
journalctl -u roamswitch.service -f            # 로그 추적
journalctl -u roamswitch.service --since "1h ago"

클라이언트 데몬이 시작 시 및 매 주기(3초)마다 자율적으로 수행하는 작업은 다음과 같습니다.

• 연결된 게이트웨이 MAC을 식별하고 trusted_networks에 대해 nftables 프로필(open / balanced / lockdown)을 적용합니다.
• 행동 기반 랜섬웨어 탐지(fanotify + Shannon 엔트로피 + 카나리아)
• 온액세스 악성 코드 검사(fanotify, 선택적으로 ClamAV)
• ARP 스푸핑 모니터링 및 신뢰할 수 없는 네트워크에 대한 예방 게이트웨이 ARP/NDP 고정
• 프로필당 커널 강화(sysctl / Yama / 코어 덤프 / /tmp noexec)
• 위협 방지 DNS 적용(dns_enabled + dns_scope)
• 피싱 차단을 위한 링크 가드(NFQUEUE)
• /run/roamswitch/state.json에 대한 런타임 상태 출력

서버 에디션

sudo systemctl status  roamswitch-server.service      # 가동 상태
sudo systemctl restart roamswitch-server.service      # 재시작
journalctl -u roamswitch-server.service -f            # 로그 추적

3. CLI 명령 참조

기본 구문: roamswitch <command> [options]. 인수 없이 실행하면 기본값은 status입니다. 출력 언어는 자동으로 OS 로케일(LC_ALL / LC_MESSAGES / LANG)을 따릅니다.

격리(Air-Gap) 정책

고정 타이머만으로 해제하면 기다리기만 하는 공격자에게 돌파당하므로, 격리의 트리거는 신뢰도로 분류됩니다(클라이언트판·서버판 공통).

• 저신뢰도(수동 Air-Gap, 범용 이상, eBPF의 Error / Warning 이하 등): 짧은 타이머 후에 전체 복구합니다(클라이언트: airgap_low_confidence_secs, 기본값 600초. 서버: guard.yaml의 safety_timer_secs, 기본값 300초. 0으로 타이머 비활성).
• 고신뢰도(카나리아 변조, 랜섬웨어성 대량 덮어쓰기, lockdown 중의 ARP 스푸핑, eBPF의 Critical / Emergency / Alert, 동일 규칙의 반복 등): 조용히 복구하지 않습니다. 타이머 이후에는 원인(동결한 PID·카나리아·ARP·규칙의 재발화)을 재확인하고, 원인이 사라진 것을 확인했을 때만 알림과 함께 해제합니다. 확인하지 못한 채 ack도 없이 상한(클라이언트: airgap_hard_cap_secs, 서버: server.conf의 isolation_hard_cap_secs. 기본값은 둘 다 3600초, 0 = 상한 없음)에 도달하면 축소(DEGRADED) 모드로 전환됩니다.
• 축소 모드는 시간 경과만으로는 절대 자동으로 열리지 않습니다(클라이언트는 루프백만 허용, 서버는 유지보수 SSH와 화이트리스트 IP의 관리 경로만 허용). 해제는 원인 소멸의 재확인, 명시적인 확인 응답(서버: roamswitch server ack), 또는 수동 해제(GUI의 해제 버튼 / roamswitch emergency-restore)뿐입니다. 클라이언트의 축소 모드에서는 airgap_degraded_lift_rfkill을 true로 하지 않는 한 Wi-Fi의 rfkill도 해제되지 않습니다.
• 관리 경로 이외의 확립된 연결은 끊깁니다(서버: 유지보수 SSH 포트와 화이트리스트 IP 이외. 공격자가 이미 맺어 둔 C2나 리버스 셸도 차단). 수동 Air-Gap은 경고 없는 메뉴 / GUI / roamswitch airgap enable이라면 저신뢰도이지만, ARP 스푸핑 경고의 「지금 바로 차단」에서 발동한 경우에는 그 경고의 신뢰도(높음)를 이어받으며, 게이트웨이의 MAC이 신뢰된 MAC과 연속으로 일치하는지를 네트워크 송신 없이 재확인합니다(arp_recheck_consecutive회·arp_recheck_min_secs초 이상). 각 전환은 인시던트 타임라인에 기록됩니다.

랜섬웨어 복구(스냅샷 및 파일 단위 복원)

다음 명령은 roamswitch-ransomware-rollback의 것입니다(roamswitch의 하위 명령이 아닙니다). 상태는 /var/lib/roamswitch에 저장됩니다.

예

sudo roamswitch status                 # 클라이언트 종합 진단(27개 항목)
sudo roamswitch status --server        # 서버판 종합 진단(34개 항목)
sudo roamswitch ports -a               # 전체 리스닝 포트
roamswitch guards                      # 가드 가동 상태
roamswitch audit-url https://examp1e-login.com
roamswitch audit-secrets ./deploy.env
roamswitch audit-secrets .                          # 현재 디렉터리 재귀 스캔
roamswitch audit-logs 72               # 최근 72시간 로그 분석
sudo roamswitch sharing on             # 미신뢰 네트워크에서 SSH/Samba/RDP 자동 중지
sudo roamswitch fim verify             # FIM 파일 무결성 검증
sudo roamswitch fim update             # FIM 기준선 업데이트
sudo roamswitch emergency-restore      # 긴급 차단 전체 해제 및 복구
sudo roamswitch airgap enable          # 긴급 차단
sudo roamswitch airgap disable         # 해제
sudo roamswitch server ack             # 긴급 격리를 확인 응답(FULL 격리 중에는 엄격한 격리를 유지, 축소 모드 중에는 해제)
roamswitch canary                      # 카나리아 인시던트 기록
roamswitch vuln-status                 # 최근 스캔 결과와 경과 일수(pass_age)를 표시
roamswitch port-anomaly                # 미확인 포트 노출 가드 인시던트 기록
roamswitch server ebpf                 # eBPF 가드의 격리 상태와 인시던트 기록
roamswitch server bans                 # SSH 무차별 대입 가드의 상태와 차단 중인 접속 출처 목록
sudo roamswitch server unban 203.0.113.9   # SSH 무차별 대입 가드의 차단 해제(root 필요)
roamswitch notifications               # 최근 1주일간의 알림 기록
roamswitch frozen                      # 동결 중인 프로세스 목록
sudo roamswitch frozen resume 12345    # 오탐 프로세스를 해제
sudo roamswitch sensor pair --addr 192.168.1.50 --code AB3DFGH2 --fingerprint 3F:45:89:E1:...:36:10  # 페어링 코드로 Sensor와 페어링
sudo roamswitch sensor key             # 자신의 공개 키/주소를 표시
roamswitch port-scan                   # 포트 스캔 탐지 이력
roamswitch timeline --json             # all incident-timeline records as JSON
roamswitch notifications --export n.jsonl   # JSON Lines
sudo roamswitch events search --since 2h --exe curl
sudo roamswitch forward status
sudo roamswitch server allowlist add "<rule>" mytool --exe /usr/local/bin/mytool
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT>
sudo roamswitch server tui

서버 에디션 데몬은 root 권한으로 실행되므로, nftables 규칙 세트를 읽거나 프로세스 소유자를 확인해야 하는 명령(status / status --server / ports -a)은 sudo 없이 실행하면 부정확한 결과(잘못된 '비활성' 판정이나 프로세스 정보 누락)를 반환합니다. 설정을 변경하는 명령(sharing / fim update / airgap / emergency-restore 등)도 마찬가지로 sudo가 필요합니다. 그 외의 읽기 전용 명령은 sudo 없이도 정확하게 동작합니다.

4. 구성 파일

클라이언트 에디션(~/.config/roamswitch/config.json)

데몬은 루트로 실행되며 찾은 첫 번째 유효한 파일(또는 루트 전용 환경에서는 /root/.config/roamswitch/config.json)을 사용하여 /home/*/.config/roamswitch/config.json을 검색합니다.

서버 에디션(/etc/roamswitch/server.conf)

서버판은 INI 형식의 설정 파일을 사용하며, 퍼미션 0600(root 전용)으로 보호됩니다. 모든 키의 형식·가능한 값·기본값·재시작 필요 여부는 서버판 운영 매뉴얼 §18에 있습니다. roamswitch server config show|get|set로 변경할 수 있으며, roamswitch server tui의 설정 편집기(server.conf와 guard.yaml의 전체 146개 키)에서도 편집할 수 있습니다. 서버판은 설정 리로드를 지원하지 않으므로, 변경 후에는 sudo roamswitch server restart로 반영합니다.

공유 기기용: 관리자 전용 모드

여러 사람이 함께 쓰는 기기에서는 sudo touch /etc/roamswitch/admin-only로 '관리자 전용' 모드를 켤 수 있습니다. 방화벽, DNS, VPN, USB, 커널과 마운트 강화, 무선, Sensor 신뢰처럼 기기 전체에 영향을 주는 변경이 root 또는 sudo / wheel / roamswitch 그룹의 사용자로 제한됩니다. 자신의 파일이나 프로세스에 묶인 작업(격리, kill, freeze, 스캔)은 이전과 같습니다. /etc/roamswitch/admin-only는 root 소유이고 다른 사용자가 쓸 수 없을 때만 유효합니다(사용자가 직접 만들어 전환할 수 없습니다). 기본값은 꺼짐(파일 없음)입니다.

5. 로그 및 런타임 상태 파일

IPC 직접 호출(고급)

데몬은 /run/roamswitch/roamswitch.sock에서 줄 바꿈으로 구분된 JSON을 허용합니다.

# 프로파일 강제 전환(클라이언트판)
printf '{"id":1,"method":"set_security_level","params":{"level":"lockdown"}}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

# 게이트웨이 ARP 고정 즉시 재확인
printf '{"id":1,"method":"reconcile_gateway_lock","params":null}\n' \
  | sudo socat - UNIX-CONNECT:/run/roamswitch/roamswitch.sock

6. 프로그래밍 상태(MCP)

roamswitch-mcp은 stdio(get_security_report / verify_security_findings / get_exposed_ports / get_guard_status / audit_url_safety / audit_secrets / audit_security_logs / audit_mcp_configs / audit_agent_setup / get_app_help / get_quarantine_status / get_file_scan_guard_status / verify_fim / get_port_anomaly_incidents / get_ebpf_incidents / get_resource_guard_incidents / get_port_scan_incidents / get_ssh_guard_incidents / get_canary_status / get_vulnerability_scan_history / get_notification_history / search_exec_events / get_process_tree / get_incident_timeline / get_fleet_status / get_vpn_status / get_link_guard_status / get_air_gap_status / get_sharing_services_status / get_bluetooth_guard_status / get_usb_guard_status / run_active_vuln_scan / run_package_cve_scan / run_package_cve_scan_languages / run_package_lifecycle_script_scan / run_typosquat_scan / run_npm_audit_signatures / get_sensor_audit_results)에서 JSON-RPC를 통해 읽기 전용 도구를 노출합니다.

외부 호스트에는 연결하지 않고 로컬로 데몬 소켓에 연결하거나 roamswitch-core를 직접 호출합니다. get_security_report와 verify_security_findings는 LAN에도 아무것도 보내지 않습니다(게이트웨이 확인은 ARP 캐시 등을 참조할 뿐입니다). MCP 설정 가이드를 참조하세요.

• Linux용 RoamSwitch 제품 페이지
• 클라이언트 보안 백서
• 서버 보안 백서
• 서버 운영 매뉴얼
• AI 도우미 및 MCP 통합 가이드
• FAQ