RoamSwitch Sensor 운영 매뉴얼
LAN에 설치하기만 하면 같은 세그먼트 안의 새 기기 출현과 스푸핑을 탐지하는 네트워크 센서의 도입·운영 가이드입니다. RoamSwitch가 도입된 단말(Mac / Linux Client / Server Edition)에 대해서는 능동적인 취약점 감사도 수행합니다. apt / dnf 패키지로 배포 중입니다.
1. 개요 & 포지셔닝
RoamSwitch(Mac / Linux Client / Server Edition)는 모두 호스트에 상주하는 에이전트 형태입니다. 여기에는 구조적인 사각지대가 두 가지 있습니다.
- 단일 호스트의 자가 진단에는 원리적인 사각지대가 있습니다: "외부에서는 닫혀 있지만 같은 LAN 상의 다른 단말에서는 훤히 보이는" 횡적 이동(lateral movement) 위험은, 호스트 스스로가 자신만을 보고 있어서는 탐지할 수 없습니다.
- RoamSwitch를 설치할 수 없는 기기가 있습니다: IoT 기기(네트워크 카메라, 스마트 플러그, 복합기), 방문자·BYOD 단말, 네트워크 장비 자체, 임베디드 기기 등.
RoamSwitch Sensor는 LAN에 두는 전용 노드로, 이 두 가지 빈틈을 메웁니다. 구현된 것은 도입된 단말에 대한 능동적 취약점 감사, ARP를 이용한 기기 대장화와 스푸핑 탐지, 옵트인 수동 캡처에 의한 의심스러운 동작의 참고 정보입니다(§6). 탐지와 보고만 하며, 통신은 차단하지 않습니다.
updates.fetch_cve_map, 기본값 true. false면 오프라인). 기기·감사 데이터는 포함하지 않습니다. (2) 운영자가 설정한 대상으로의 알림·집계: 설정했을 때만 보냅니다.자기 방어 기능은 구현하지 않습니다(의도적인 설계 결정). Sensor 자체에 대한 공격 대책이 필요한 경우, 동일 머신에 RoamSwitch for Linux의 Server Edition을 별도로 설치할 것을 권장합니다. 두 프로세스는 완전히 독립적으로 공존할 수 있습니다.
2. 현재 동작 확인 환경
- 지원 OS: Debian 12 (bookworm) 이상 / Ubuntu 22.04 이상(apt), Fedora / RHEL 계열(dnf).
x86_64(amd64)와arm64(aarch64. Raspberry Pi 등)를 지원합니다. - 예상 하드웨어(향후 계획): 실제 운용 시에는 팬리스 N100/N150 계열 미니PC 등, 상시 가동에 적합한 저전력 기기를 상정하고 있지만, 현시점에서는 이를 전제로 한 전용 빌드·제공은 하지 않습니다.
- 네트워크 배치: 감시할 LAN 세그먼트에 연결합니다(ARP를 직접 보므로 호스트 네트워크에서 동작합니다). 요청을 받아야 하므로 고정 IP 주소가 필수입니다. TCP
50543번에서 대기하며, TLS 1.3도 같은 포트에서 받습니다(§4.4). - 리소스 소비: 상주 메모리는 수십 MB 정도이며, 유휴 시 CPU 부하는 매우 적습니다.
- 권장:
nmap(ARP 스윕·NSE 보완 진단·정기 감사의 MAC 확인에 사용됩니다. 설치하지 않아도 다른 기능은 동작하지만, ARP 스윕은 수행되지 않으며 Sensor가 통신한 기기만 보는 수동 동작이 됩니다).
nmap은 권장 패키지입니다. 없어도 Sensor는 설치할 수 있지만, 정기 감사, 미도입 기기의 정기 감사, 기기 대장의 능동 스캔(조용한 기기 탐지)은 동작하지 않습니다. roamswitch-sensor status에 “nmap: 미설치”로 표시됩니다.
3. 설치 & 시작
공식 서명된 패키지 저장소에서 roamswitch-sensor 패키지를 설치합니다. 설치 후 roamswitch-sensor.service(systemd)가 자동으로 활성화·시작됩니다.
3.1 APT(Ubuntu / Debian)
# 1. 저장소 서명 키 등록
curl -fsSL https://lafine.net/apt/roamswitch-archive-keyring.asc \
| sudo gpg --dearmor -o /usr/share/keyrings/roamswitch-archive-keyring.gpg
# 2. 저장소 추가
echo "deb [signed-by=/usr/share/keyrings/roamswitch-archive-keyring.gpg] https://lafine.net/apt stable main" \
| sudo tee /etc/apt/sources.list.d/roamswitch.list
# 3. 설치
sudo apt update && sudo apt install roamswitch-sensor
3.2 DNF / RPM(Fedora / RHEL)
# 1. GPG 키 가져오기
sudo rpm --import https://lafine.net/rpm/RPM-GPG-KEY-roamswitch
# 2. 저장소 설정 파일 추가
sudo curl -fsSL -o /etc/yum.repos.d/roamswitch.repo https://lafine.net/rpm/fedora/roamswitch.repo
# 3. 설치
sudo dnf install roamswitch-sensor
3.3 시작 확인
systemctl status roamswitch-sensor.service
sudo roamswitch-sensor status
3.4 CLI / TUI 실행
CLI(roamswitch-sensor)와 대화형 TUI(roamswitch-sensor-tui)는 설치 후 바로 실행할 수 있습니다.
sudo roamswitch-sensor status
sudo roamswitch-sensor-tui
ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE 환경 변수(systemctl edit roamswitch-sensor.service로 설정)에 대상 인터페이스 이름을 지정하면, 해당 인터페이스상의 Ethernet/IPv4/IPv6 헤더를 관측하여 신규 기기 출현이나 알려진 악성 IP와의 통신을 탐지합니다(§6.1 참조). 기본값은 비활성화입니다.4. 페어링(페어링 코드 방식)
Sensor는 초기 상태에서 아무것도 신뢰하지 않습니다. 페어링은 Sensor 운영자가 발급하는 1회용 페어링 코드를 사용해 이루어집니다. 「Sensor가 이 단말에 대해 능동적인 취약점 감사를 실행해도 된다」는 신뢰 관계는, 단 한 번의 페어링 조작으로 양방향에 동시에 성립합니다(한쪽 방향만의 신뢰라는 상태는 존재하지 않습니다).
전제 조건: Sensor는 고정 IP 주소(정적 할당 또는 DHCP 서버 측 주소 예약)로 운용해 주십시오. 단말은 페어링 시점에 확인한 Sensor의 IP 주소로 이후에도 직접 접속하므로(mDNS 등을 통한 자동 탐색은 수행하지 않습니다), Sensor 측 IP가 바뀌면 재페어링이 필요합니다. 엔드포인트 측은 동적 IP를 유지해도 무방합니다.
4.1 페어링 코드 발급(Sensor 측)
# Sensor 측에서 실행(TUI에서는 c 키)
sudo roamswitch-sensor issue-code
8자리 1회용 코드가 표시됩니다(0/O/1/I/L은 제외). 발급 후 10분이 지나면 만료됩니다. 단말에서 핀으로 고정할 TLS 인증서 핑거프린트(SHA-256)와 함께, 단말 측 운영자에게 바로 전달하십시오.
4.2 코드를 사용한 페어링(엔드포인트 측)
# 엔드포인트 측 (roamswitch-linux)
sudo roamswitch sensor pair --addr <SENSOR_IP> --code <CODE> --fingerprint <SHA256_FINGERPRINT>
Mac판에서는 메뉴 바의 「🔍 RoamSwitch Sensor 페어링…」에서 Sensor의 IP 주소·페어링 코드·인증서 핑거프린트를 입력해 GUI로 동일한 작업을 수행할 수 있습니다.
페어링이 성립하면 이후의 능동적 취약점 감사와 감사 결과 취득은 모두 Ed25519 서명으로 인증됩니다. Linux판 단말은 입력한 핑거프린트와 일치하는 인증서를 가진 Sensor와만 TLS 1.3으로 통신하며, 평문으로 자동 폴백하지 않습니다(§4.4). Sensor가 발급한 코드를 알고 있는 단말 측과 그 코드를 받은 Sensor 측 양쪽이 이 시점에서 서로를 신뢰 완료 상태로 취급합니다.
issue-code로 새 코드를 발급받으십시오.4.3 수동 페어링(공개 키를 직접 파악하고 있는 경우)
Sensor 운영자가 단말의 공개 키와 주소를 이미 파악하고 있는 경우, 페어링 코드 교환 없이 Sensor 측에서 직접 등록할 수도 있습니다(일반적으로는 4.2의 코드 방식을 사용해 단말 측에서 페어링하도록 하는 편이 간편합니다). 자신의 공개 키와 주소는 다음 명령으로 확인할 수 있습니다.
# 엔드포인트 측에서 자신의 공개 키/주소 확인
sudo roamswitch sensor key
# Sensor 측에서 자신의 공개 키/주소/MAC 주소 확인
sudo roamswitch-sensor status
# Sensor 측
sudo roamswitch-sensor pair <전체 공개 키> --addr <IP 주소> --confirm
4.4 제어 API(TCP 50543)의 보안(TLS·핑거프린트·잠금)
페어링·감사 요청·결과 취득은 Sensor의 제어 API(TCP 50543)에서 이루어집니다. 다음과 같은 방어 기능이 내장되어 있습니다.
- TLS 1.3과 인증서 핀:
control.tls는off/optional(기본값. 평문도 받고 경고) /required(TLS 1.3만)입니다. 인증서는 자체 서명(ECDSA P-256)이며, 신뢰는 SHA-256 핑거프린트 핀으로 결정됩니다. - 페어링 요청의 핑거프린트 바인딩: 단말은 핀 고정한 인증서의 핑거프린트를 자신의 비밀 키로 서명하여 페어링 요청에 포함합니다. 다른 인증서를 가진 중간자를 경유한 요청은
fingerprint_mismatch로 실패하며, 페어링 코드는 소비되지 않습니다. - 리플레이 내성이 있는 서명(v2): 감사 요청과 결과 취득의 서명은 시각(±300초)과 nonce를 포함하는 v2 형식이며 재전송을 거부합니다. 시각·nonce가 없는 구 v1 서명은 리플레이가 가능하므로, 수락 여부를
control.allow_legacy_signatures(기본값true=이행 기간용. 수락할 때마다 지원 중단 예정 경고)로 설정할 수 있습니다. 모든 단말이 v2가 되면false로 설정하십시오. - 잠금: 페어링 코드 무차별 대입은 같은 출발지 IP에서 10분 동안 5회 실패하면 60초 잠기고(반복하면 최대 1시간까지 지수적으로 연장), 모든 출발지 합계로 20회 실패하면 전체가 잠깁니다. 서명 실패는 조금 느슨하게(출발지 IP별 10회, 전체 100회) 처리합니다. 잠금은 알림
control_api_lockout으로 알립니다. - 수신 대기 IP:
control.bind_addr(기본값0.0.0.0, 재시작 시 반영)를 Sensor의 LAN 측 주소로 좁히면 노출을 줄일 수 있습니다. 와일드카드인 동안에는 데몬이 경고를 출력합니다. - 인증서 재생성(로테이션):
roamswitch-sensor tls rotate(TUI에서는T화면에서R)는 인증서를 재생성합니다. 이전 핑거프린트의 핀은 모두 무효가 되므로, 단말 측에서 새 값을 다시 입력(sudo roamswitch sensor repin <공개키> --fingerprint <값>)해야 합니다. 페어링 자체는 유지됩니다.
sudo roamswitch-sensor pairing show # mode, fingerprint, warnings
sudo roamswitch-sensor tls rotate # regenerate the certificate
sudo roamswitch sensor repin <PUBLIC_KEY> --fingerprint <NEW_FINGERPRINT> # on each endpoint
control.tls를 required로 설정하는 절차roamswitch-sensor status에 평문 연결 경고가 더 이상 나타나지 않는 것을 확인합니다 → (3) sudo roamswitch-sensor config set control.tls required → 데몬을 재시작합니다. off는 TLS가 필수인 Linux판 단말이 연결할 수 없게 되므로 보통은 사용하지 않습니다.5. 능동적 취약점 감사
페어링된 엔드포인트에 대해, Sensor가 비파괴적인 실증형 취약점 진단을 실행합니다. 파괴적인 작업(데이터 쓰기·삭제, 서비스 중지)은 일절 수행하지 않습니다.
sudo roamswitch-sensor scan <공개 키 또는 그 앞부분>
감사는 4단계로 구성되어 있습니다.
- 전체 포트 스캔: 대상 호스트에서 열려 있는 TCP 포트를 남김없이 탐지합니다.
- 기존 시그니처 진단: Redis / dockerd / Memcached / MongoDB / Elasticsearch / CouchDB / Jenkins / VNC의 인증 없는 노출 확인, SMTP 오픈 릴레이 진단(
MAIL FROM/RCPT TO만 전송하고DATA는 전송하지 않는 안전한 방식), 개발 서버의 CORS 설정 오류·경로 순회·오픈 리다이렉트 진단 등, 알려진 취약점 패턴에 대한 비파괴적인 실증 확인을 수행합니다. - 범용 배너 취득: 위 시그니처로 커버되지 않는 열린 포트에 대해, 연결만으로 배너 문자열을 취득합니다(데이터는 보내지 않습니다). 아무것도 표시하지 않는 열린 포트에는 서비스를 구별하기 위해
GET / HTTP/1.0을 한 번만 보냅니다(한 번의 감사에서 최대 32포트). - nmap NSE 보완 진단:
nmap --script safe를 통한 광범위한 프로토콜 대응 보완 진단입니다. 호스트에nmap이 설치되어 있으면 자동으로 실행됩니다(설치되어 있지 않으면 아무 동작도 하지 않습니다).
표준 외 포트의 서비스도 조사합니다. 6380번의 Redis나 2222번의 SSH 등에도 같은 읽기 전용 확인을 적용합니다. 구분하는 것은 처음 표시와 GET / HTTP/1.0 1회에 대한 응답입니다. 단말의 자기 신고(1회에 64건까지)는 서명 대상이 아니므로 범위를 넓히지 않고, 확인 항목을 고르는 용도로만 씁니다.
감사 결과는 매번 /var/lib/roamswitch-sensor/scan_history.json에 기록되며(탐지 여부와 관계없이, 그 시점에 문제가 없었다는 것도 기록의 가치가 있기 때문입니다), CLI 또는 TUI에서 열람할 수 있습니다.
roamswitch-sensor history
sudo roamswitch-sensor report <공개 키 또는 그 앞부분> --out /tmp/report.md
“열린 포트: 없음”이면서 ARP 응답도 없을 때는 “기기에 닿지 않았을 가능성이 있습니다”라고 표시됩니다. 이는 “문제 없음”이라는 뜻이 아닙니다. “nmap NSE: 실행하지 않음(nmap 미설치)”과 “해당 없음”은 서로 다른 의미입니다.
5.1 클라이언트 측에서의 감사 요청(pull 방식)
페어링된 단말 쪽에서 Sensor에 능동적 취약점 감사를 요청할 수도 있습니다. Mac 버전은 메뉴 막대의 「Sensor에 감사 요청」, Linux 버전은 다음 명령입니다.
sudo roamswitch sensor request-audit
Sensor가 감사를 실행한 후, 단말 측은 요청 5분 후부터 5분 간격으로 최대 5회까지 결과를 가지러 갑니다(최종 확인은 최대 25분 후). 취득한 결과는 단말 측에도 로컬로 저장됩니다.
roamswitch sensor results
Mac판에서는 설정 화면의 「감사 결과」 목록, 또는 MCP 도구 get_sensor_audit_results를 통해 AI 에이전트가 대응 계획을 세울 때의 입력으로도 사용할 수 있습니다. Sensor 측에서 페어링이 해제된 경우 등, 결과 제공이 명시적으로 거부되는 경우도 있습니다(§10 Q6 참조).
5.2 사양서와의 차이, 경계값 확인, AI의 추측(선택)
사양서와의 차이 및 경계값 확인(design_flaw.enabled. 기본 꺼짐, 옵트인) 페어링된 동의 단말만 대상입니다. OpenAPI / Swagger 문서를 찾아 선언과 실제 응답의 차이를 보고합니다. 쿼리 인수에는 정해진 안전한 값을 넣고 5xx 등의 이상을 보고합니다. 보내는 것은 GET뿐이며 기기 1대당 최대 20회 요청입니다. 순서는 고정이며 AI가 고르지 않습니다(요약은 비밀을 가리며, 1건당 240자까지).
AI에게 추측 작성시키기(선택) roamswitch-sensor design-hypotheses는 기록의 요약만을 선택한 AI 도구에 넘겨 미확인 추측을 작성하게 합니다. 실행한 사용자의 권한으로 동작하며, 제공업체에 요약이 전송될 수 있습니다. 기기에는 아무것도 보내지 않습니다.
6. 수동적 ARP 모니터링 & LAN 가시화
Sensor는 두 가지 방법으로 LAN의 기기를 파악합니다. (1) ARP 테이블 감시: 약 10초마다 읽어 새로운 IP/MAC과, 알려진 IP의 MAC 변화(스푸핑의 징후)를 탐지합니다. (2) 능동 ARP 스윕: nmap -sn -PR로 직접 연결된 서브넷(최대 /22)을 1시간마다 조사해 대장에 저장합니다. nmap이 없으면 (1)만 동작합니다.
roamswitch-sensor arp-events
탐지한 이벤트는 roamswitch-sensor arp-events나 TUI의 「ARP 이벤트」 탭(Enter로 상세)에서 확인할 수 있습니다. 각 이벤트에는 발생 시각·심각도(치명적~정보. 게이트웨이 IP의 MAC 변경은 「치명적」)·판단 근거·관련 기기의 정체·구체적인 다음 절차가 함께 표시됩니다.
6.1 수동적 LAN 가시화 확장(옵트인)
위의 ARP 모니터링은 「Sensor 자신이 과거에 통신한 기기」만을 대상으로 하지만, ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE 환경 변수로 대상 인터페이스를 지정하면, 해당 인터페이스상의 Ethernet/IPv4/IPv6 헤더와 기기가 스스로 알리는 내용만 관측하여(DNS·DHCP·mDNS·SSDP·WS-Discovery·LLDP 외의 데이터 내용은 보지 않음) 다음을 수행합니다.
- 신규 기기의 수동 관측: ARP 모니터링으로는 커버할 수 없는, Sensor 자신이 직접 통신하지 않은 기기의 출현. 브로드캐스트·멀티캐스트 트래픽으로부터 학습합니다.
- 알려진 악성 IP와의 통신 탐지: 목적지 IP가 로컬 위협 피드(RoamSwitch 본체의 Egress Guard와 동일한 형식)에 일치하는 통신을 탐지합니다(탐지만 하며 차단은 하지 않습니다).
- VLAN 태그(802.1Q/802.1ad): 미러 포트가 트렁크일 때 태그가 붙은 프레임도 읽습니다(이중 태그까지). 확인한 VLAN ID는 기기 대장에 남으며, 기기 1대당 최대 8개입니다. 이미 대장에 있는 기기에만 붙고, VLAN ID만으로 기기를 새로 만들지는 않습니다.
- IPv6 통신: IPv4와 마찬가지로 송신원·목적지·포트를 읽습니다. '신규 기기'와 '알려진 악성 IP' 판정은 IPv4만 대상입니다(IPv6는 프라이버시 주소가 계속 바뀌기 때문). 기기별 동작 학습, 대량 송신, IoT 기기의 관리용 포트 접속 탐지에는 IPv6도 사용합니다.
- 기기가 스스로 알리는 내용: LLDP(스위치·AP·IP 전화 등의 이름과 설명), mDNS의 TXT(
model=md=ty=), WS-Discovery(UDP 3702. ONVIF 카메라의 이름과 모델 번호)를 읽어 기기 대장의 '기종 힌트'로 삼습니다. 알린 문자열은 제어 문자를 제거하고 96자까지 잘라 저장합니다.
sudo systemctl edit roamswitch-sensor.service
# [Service]
# Environment=ROAMSWITCH_SENSOR_PASSIVE_CAPTURE_IFACE=eth0
sudo systemctl restart roamswitch-sensor.service
roamswitch-sensor passive-events
환경 변수를 추가했으면 sudo systemctl restart roamswitch-sensor로 재시작합니다. systemctl edit만으로는 실행 중인 데몬에 반영되지 않습니다. 반영되었는지는 roamswitch-sensor status의 「수동 캡처: eth0에서 수신 중」으로 확인합니다. 「수동 캡처는 비활성입니다」 그대로라면 재시작하지 않은 것입니다.
수신 버퍼는 capture.rcvbuf_mb(MiB. 기본 4, 0이면 시스템 기본값)로 바꿉니다. 권한이 CAP_NET_RAW뿐이므로, net.core.rmem_max를 넘는 부분은 잘립니다. kernel_drops가 나오면 rmem_max를 올리고(예: sudo sysctl -w net.core.rmem_max=8388608, 영구 적용은 /etc/sysctl.d/), capture.rcvbuf_mb도 올립니다.
6.2 기기 대장과 기기 메모
대장은 roamswitch-sensor device-inventory로 볼 수 있습니다. device-note로 메모를 등록한 기기는 '파악됨', 미등록은 '확인 필요'입니다. 보인 VLAN ID는 내보내기의 vlans 열 등에도 나옵니다.
sudo roamswitch-sensor refresh
roamswitch-sensor device-inventory
sudo roamswitch-sensor device-note aa:bb:cc:dd:ee:ff "3F copier"
6.3 의심스러운 동작의 참고 정보(모두 탐지 전용)
수동 캡처(§6.1, 옵트인)를 활성화하면 다음 참고 정보를 제시합니다. 모두 탐지와 표시만 하며, Sensor가 통신을 차단하는 일은 없습니다.
- IoT 기기의 동작(
iot-events): 분류된 기기에서 알려진 악성 IP나 관리용 포트(SSH/RDP/SMB 등)로의 연결. mDNS/SSDP/DHCP/LLDP/WS-Discovery의 자기 신고에 의한 기종 특정도 병용합니다. - 의심스러운 통신(
network-threats): 30초 창에서 다수의 대상으로의 연결(스캔·경유지 의심)이나 동일 대상으로의 대량 연결(DDoS 참여의 징후), DNS 터널링/C2의 징후(쿼리 이름의 구조적 특징만 판정에 사용하며 도메인 이름은 저장하지 않습니다). - 취약점 정보(
iot-advisories): 알려진 IoT 벤더 제품에 관한 공개 CVE의 참고 정보(정적으로 기본 제공. 네트워크를 통한 업데이트는 없습니다).
6.4 보이지 않는 범위(커버리지) 표시
수동 감시는 아무것도 들리지 않는 상태와 조용한 네트워크를 그대로는 구별하지 못합니다. Sensor는 스스로 관측할 수 있었던 것만 세어, 보이지 않는 범위를 '이벤트 없음'으로 착각하지 않도록 합니다. 새로운 통신도 새로운 소켓도 만들지 않습니다. 기본으로 켜져 있습니다.
roamswitch-sensor status와 TUI 상태 화면(i)에 '보이는 범위' 항목이 나옵니다. 수동 캡처의 상태(수신 중·인터페이스 이름·지금까지의 프레임 수·마지막 프레임 이후 경과 초, 또는 비활성)와, 보이지 않는 원인이 한 줄씩 표시됩니다.- 알림(Webhook·syslog)은 운영자가 이미 설정한 대상에만 나갑니다. 보이지 않는 범위가 생겼을 때
coverage_gap(심각도 medium)을 1회, 돌아왔을 때coverage_restored(info)를 1회 보냅니다. 단지 조용한 것일 수도 있는 항목(info)은 화면에만 표시하고 알리지 않습니다. - 컬렉터로의 전송을 켜 두었을 때는 기존 전송에
summary.capture와summary.coverage_notes가 더해지고, 대시보드의 Sensor 목록에 '보이지 않는 범위' 배지와 건수 카드가 표시됩니다.
세는 원인의 예는 수동 캡처를 열 수 없음, 30초 이상 멈춤, 수신이 5회 연속 실패, 5분간 프레임이 없고 링크도 끊김, 커널의 폐기(최근 10분), 2048바이트를 넘는 프레임, 헤더를 읽을 수 없는 프레임 등입니다. ARP 테이블을 읽을 수 없는 회차는 기준을 지우지 않고 셉니다.
할 수 없는 것 셀 수 있는 것은 Sensor가 스스로 관측할 수 있는 것뿐입니다. 미러 포트 설정 실수처럼 수신은 정상이지만 도착하는 프레임이 치우쳐 있을 뿐인 경우는 구별하지 못합니다. 5분간 프레임이 없고 링크는 살아 있는 경우(capture_silent, info)에는 '조용함'과 '들리지 않음'을 구별할 수 없다고 그대로 표시합니다.
7. CLI 명령어 빠른 참조
| 명령어 | 기능 개요 |
|---|---|
roamswitch-sensor status |
Sensor 자신의 공개 키·IP 주소·MAC 주소, 페어링 수·ARP 이벤트 수·대기 중인 감사 요청 수, 제어 API의 TLS 상태를 표시 |
roamswitch-sensor issue-code |
1회용 페어링 코드를 발급(10분간 유효). Sensor의 인증서 핑거프린트도 표시 |
roamswitch-sensor list |
페어링된 단말의 목록을 표시 |
roamswitch-sensor pair <public-key> [--addr <IP>] [--name <name>] --confirm |
공개 키와 주소를 직접 지정해 단말을 수동으로 페어링(일반적으로는 issue-code를 사용해 단말 측에서 자동으로 페어링하게 하는 편이 간편합니다) |
roamswitch-sensor unpair <public-key> |
페어링 해제 |
roamswitch-sensor scan <public-key> |
페어링된 단말에 능동적 취약점 감사를 실행 |
roamswitch-sensor history [public-key] |
감사 이력을 표시(공개 키를 생략하면 전체 단말) |
roamswitch-sensor report <public-key> [--out <file>] |
가장 최근 감사 결과를 Markdown 리포트로 출력 |
roamswitch-sensor arp-events |
탐지된 ARP 이벤트(신규 기기·스푸핑 의심)를 표시 |
roamswitch-sensor pairing show / tls show |
제어 API의 TLS 상태(모드·핑거프린트·평문 연결 경고·수신 대기 IP·구 v1 서명 허용 여부)를 표시(pairing show와 tls show는 동일한 내용) |
roamswitch-sensor tls rotate |
TLS 인증서를 재생성(이전 핑거프린트의 핀은 모두 무효가 되며 단말 측에서 재핀 고정이 필요) |
roamswitch-sensor refresh |
LAN 상의 기기를 지금 즉시 재스캔(ARP 스윕)하여 기기 대장을 갱신 |
roamswitch-sensor device-inventory |
기기 대장(LAN 상에서 관측한 모든 기기·온라인 상태·메모)을 표시 |
roamswitch-sensor device-note <MAC> [note] |
기기에 메모를 등록(메모를 생략하면 삭제) |
roamswitch-sensor passive-events / iot-events / network-threats / iot-advisories |
수동 캡처에서 유래한 각 이벤트(신규 기기·악성 IP로의 연결 / IoT 기기의 동작 / 의심스러운 통신 / IoT 취약점 정보)를 표시 |
roamswitch-sensor lan-overview [--json]roamswitch-sensor network-threats --json [--limit N] [--min-severity …] |
LAN 전체의 상태(기기 수·VLAN·위협 건수 등)와 위협 목록을 표시합니다. --json으로 JSON을 출력합니다(--limit은 최대 500). 둘 다 읽기 전용이며 root가 아니어도 실행할 수 있습니다. PersonalSOC와 Linux 버전 MCP가 읽습니다. |
roamswitch-sensor config [show | set <키> <값>] |
설정의 표시·변경(정기 감사·알림·보존 기간·컬렉터·제어 API·탐지 데이터 취득·언어). control.bind_addr와 control.tls는 데몬 재시작 시 반영되며, 그 외에는 재시작이 필요 없음(§11.8) |
roamswitch-sensor diff [공개 키] |
이전 감사와의 차이 표시(신규 발견·해소·새로 열린 포트·도달 불가 의심) |
roamswitch-sensor export <scans|inventory|audit-log|unmanaged|all> … |
감사 증적을 CSV / JSON / 인쇄용 HTML로 내보내기 |
roamswitch-sensor audit-log [verify] |
작업·승인 로그 표시. verify로 해시 체인 변조 감지 |
roamswitch-sensor notify-test |
설정한 알림 대상(Webhook / syslog)에 테스트 알림을 보내 연결 확인 |
roamswitch-sensor audit-unmanaged <IP|MAC> --confirmroamswitch-sensor unmanaged-audits |
RoamSwitch 미도입 기기의 경량 감사(연결 확인만). audit-unmanaged <IP 또는 MAC> --confirm으로 수동 실행, unmanaged-audits [--detail]로 결과 목록(§13) |
roamswitch-sensor design-hypotheses [鍵] --llm 名前 |
최신 design_flaw 결과로 선택한 AI 도구가 확인되지 않은 추측을 쓰게 합니다(§5.2). --llm·--model·--timeout·--show-prompt |
roamswitch-sensor lockdown [status | on | off] |
중지 상태 표시(status), 중지(on --reason 사유), 해제(off). 페어링·감사·전송·알림을 모두 멈춥니다(§14) |
roamswitch-sensor decommission --confirm |
이 Sensor의 키와 저장된 데이터를 삭제하고 중지합니다(되돌릴 수 없음). 감사 로그만 남기고, 페어링했던 단말 목록과 해제 방법을 표시합니다(§14) |
CLI는 일본어 / 영어에만 대응합니다(LANG 환경 변수를 따릅니다).
8. TUI 조작 가이드
대화형 TUI(roamswitch-sensor-tui)는 10개 언어를 지원하며 CLI와 설정의 모든 것을 조작할 수 있습니다(m으로 기능 목록). 주요 6개 탭(페어링 완료·네트워크 구성·ARP 이벤트·감사 이력·차이·작업 로그)은 Tab으로 전환합니다. 차이는 신규를 빨강, 해소를 초록, 도달 불능 의심을 노랑으로 표시합니다.
| 키 | 동작 |
|---|---|
Tab | 탭 전환 |
↑↓ / j k | 항목 선택 |
c | 페어링 코드를 발급(10분간 유효). 화면에는 단말 측에서 실행할 명령 sudo roamswitch sensor pair --addr <이 Sensor의 IP> --code <코드> --fingerprint <핑거프린트>가 실제 값이 채워진 상태로 표시됩니다 |
u | 페어링 해제 |
s | 선택 중인 단말에 능동적 취약점 감사를 실행 |
a | (네트워크 구성 탭) 선택한 기기를 경량 감사(확인 화면 있음, §13). 결과는 메뉴의 '미도입 기기 감사' 탭 |
K | 이 Sensor의 중지/해제(확인 화면 있음, 중지 중에는 화면 하단에 빨간 표시). 폐기는 메뉴에서(§14) |
n | (네트워크 구성 탭) 선택한 기기에 이름·용도·위치 등의 메모를 등록(메모가 있는 기기는 '파악됨'으로 취급) |
r | 지금 LAN 기기를 다시 스캔(ARP 스윕, 기본적으로 1시간마다 자동 실행) |
e | 감사 증적을 내보내기(감사 결과·기기 대장·작업 로그의 CSV, HTML 보고서, JSON). 양식에서 내용·형식·단말·시작일·저장 위치를 지정할 수 있으며 표시 언어(10개 언어)로 생성됩니다. 기본 저장 위치는 ~/.local/state/roamswitch-sensor/이고, 소유자만 읽을 수 있는 새 파일(기존 파일은 덮어쓰지 않습니다)로 생성되며, 내보냈다는 사실 자체도 작업 로그에 기록됩니다 |
p | 수동 페어링(공개 키와 주소를 입력 → 확인 화면 → 실행). 양식에 단말 측에서 핀 고정할 Sensor의 TLS 핑거프린트가 표시됩니다 |
T | TLS·페어링 상태(모드·핑거프린트·평문 연결 경고·수신 대기 IP·구 v1 서명 허용 여부). R로 인증서를 재생성(영향을 설명하는 확인 화면 포함) |
C | 설정 편집기(모든 설정 키를 표시·변경. 웹훅 URL은 항상 가려서 표시. 재시작이 필요한 키는 명시) |
N | 알림 테스트(전송 대상별 성공 여부를 표시. URL은 가려서 표시) |
m | 기능 목록 메뉴(수동 모니터링·IoT 동작·의심스러운 통신·IoT 취약점 정보·상태 i·컬렉터 관리 등) |
O | 컬렉터 관리(컬렉터의 데이터 디렉터리가 있는 호스트에서만). Sensor의 등록·폐기·목록·읽기 토큰·감사 로그 이상의 해제. 컬렉터 자체의 알림 전송처 설정은 n |
f / l / v | (감사 이력 탭) 단말별 필터링. (작업 로그 탭) l로 표시 건수를 변경, v로 해시 체인을 재검증 |
Enter | 선택한 행의 상세 표시(감사 이력·변경·ARP 이벤트·기기·작업 로그) |
w | (상세 표시 중) 보고서를 저장 위치를 지정하여 파일로 내보내기(표시 언어로 생성) |
L | 표시 언어를 선택(language 설정에 저장되며, 데몬이 출력하는 알림·로그의 언어에도 반영됩니다) |
q | 종료 |
9. 신뢰 모델 & 보안 설계
- 아웃오브밴드 확인(TOFU가 아님): Sensor 화면에 표시되는 인증서 핑거프린트와 페어링 코드를 운영자가 구두·채팅 등으로 단말 측에 전달합니다. 단말은 네트워크를 통해 핀을 가져오지 않으며(첫 연결을 무조건 신뢰하는 TOFU가 아닙니다), 입력한 값과 일치하는 인증서를 가진 Sensor와만 통신·페어링합니다. 페어링 성립 시에 교환된 공개 키로 이후의 프로브·요청의 정당성을 검증합니다.
- 파괴적인 조작 없이도, 파괴적인 조작을 허용하는 구멍은 발견할 수 있는 설계: 능동적 취약점 감사는 모두 비파괴적입니다(데이터 쓰기·삭제, 서비스 중지를 일절 수행하지 않습니다). 다만 「인증 없이 쓰기 가능」「오픈 릴레이로 동작」과 같이, 악용될 경우 파괴적인 조작을 허용해 버리는 설정 결함 자체는 탐지합니다.
- 오탐 대책(자기 감사 제외): Sensor의 전체 포트 감사를 수신 포트 스캔 탐지 가드가 오인하지 않도록, 출발지 IP로 제외합니다(IP는 신뢰 판정에는 쓰지 않습니다). 단말이 감사를 요청한 뒤 리포트가 나올 때까지(최대 약 25분간)는 차분하게 알립니다. 그 밖의 시간에는 기존과 같이 강한 경고를 냅니다.
- 외부 전송은 한정적이며 기기 정보는 기본값에서 전송하지 않음: 발견한 기기 정보, 감사 결과, ARP 이벤트는 기본값에서는 Sensor 자신의 로컬 스토리지에만 저장되며 Lafine이나 제3자의 서버로는 전송되지 않습니다. 외부와의 통신은 탐지용 데이터(CVE 맵·nmap NSE 데이터베이스)의 취득(
updates.fetch_cve_map으로 중지 가능. 기기·감사 데이터는 포함되지 않음)과, §11의 알림(웹훅·syslog) 및 중앙 컬렉터로의 전송(운영자가 전송 대상을 설정한 경우에만 자사 조직의 대상으로)뿐입니다.
10. 문제 해결 & FAQ
Q1. 페어링 코드를 입력해도 거부됩니다.
원인은 네 가지를 생각할 수 있습니다. (1) 발급 후 10분이 지났다(issue-code로 재발급). (2) 입력 오류. (3) --addr의 IP가 Sensor의 고정 IP와 다르다. (4) --fingerprint가 인증서와 다르다(roamswitch-sensor pairing show로 확인). 오류가 계속되면 rate_limited로 잠깁니다.
Q2. NSE 보완 진단 결과가 비어 있습니다.
원인은 다음 둘 중 하나입니다. (1) 컨테이너에 nmap이 설치되어 있지 않다. (2) 실행은 되었지만 대상 포트에 해당하는 안전한 스크립트의 출력이 실제로 없었다. nmap NSE 보완 진단은 호스트에 nmap이 설치되어 있으면 자동으로 실행됩니다.
Q3. 감사가 완료될 때까지 얼마나 걸립니까?
전체 포트 스캔만이라면 수십 초 정도입니다. 호스트에 nmap이 설치되어 있으면 NSE 보완 진단이 자동으로 더해져, 대상의 열린 포트 수에 따라 최대 2분 정도 걸릴 수 있습니다. TUI에는 실행 중 경과 초가 계속 표시되므로 진행 상황을 확인할 수 있습니다.
Q4. 페어링했는데도 감사를 실행할 수 없습니다.
원인은 다음 네 가지를 생각할 수 있습니다. (1) 단말 쪽에서 sensor_pairing_enabled: true로 하지 않았다(기본 OFF). (2) Sensor의 고정 IP가 바뀌었다(재페어링 필요). (3) Sensor 쪽에서 unpair되었다. (4) 인증서를 다시 만들어 단말의 핀이 오래되었다(roamswitch sensor repin). 양쪽 목록에서 서로의 등록을 확인하십시오.
Q5. Sensor 자체는 RoamSwitch 본체(Client/Server Edition)와 함께 사용할 수 있습니까?
네. Sensor는 자기 방어 기능이 없는 설계이므로, 동일 머신에 RoamSwitch for Linux Server Edition을 함께 설치할 것을 권장합니다. 두 프로세스는 완전히 독립된 프로세스·데이터 저장소로 동작하며 충돌하지 않습니다.
Q6. roamswitch sensor results가 「페어링이 해제되었습니다」라고 표시됩니다.
Sensor 측에서 이 단말의 페어링이 unpair로 해제되었습니다. Sensor 운영자에게 새 페어링 코드를 발급받아, roamswitch sensor pair --addr <IP> --code <코드> --fingerprint <SHA-256>로 다시 페어링해 주십시오.
11. 조직 규모 감사 운영 기능 (옵트인)
대규모 조직의 보안 담당자가 감사 증적과 변화 파악을 위해 사용하는 기능 모음입니다. 모두 초기 상태에서는 꺼져 있으며, Lafine이나 제3자에게는 아무것도 전송되지 않습니다. 알림·집계 대상은 모두 운영자가 설정한 자사 조직의 것입니다. 설정은 sudo roamswitch-sensor config set <키> <값>으로 하며(데몬 재시작 불필요, 변경 내용은 작업 로그에 기록됨) config show로 현재 값을 확인할 수 있습니다.
11.1 정기 감사와 이전 감사와의 차이
schedule.enabled를 true로 하면 페어링된 모든 단말을 정기적으로 감사합니다(기본 24시간마다). 이전과의 차이는 roamswitch-sensor diff로 확인할 수 있습니다. 열려 있던 포트가 모두 보이지 않게 되면 정지 중인 것과 구별할 수 없으므로 도달 불능 의심으로 처리합니다.
무인 감사에서도 「합의한 단말만 감사한다」는 보증은 깨지 않습니다. 단말이 마지막으로 인증한 시점의 MAC을 저장해 두고, 감사 전후에 같은 MAC이 그 IP에서 응답하는지를 nmap의 ARP로 확인합니다. 다르면 감사하지 않고(또는 결과를 폐기하고) 알립니다.
다른 VLAN의 단말은 기본적으로 대상이 아닙니다. schedule.allow_routed_endpoints(기본 꺼짐)에서는, 서명된 요청이 schedule.routed_proof_minutes(기본 30분, 5~1440) 이내에 같은 주소에서 도착했는지 등으로 확인합니다.
동작하지 않는 이유(nmap 없음, 주소가 없는 단말, 본인 확인 결속이 없는 단말)는 status의 “보이는 범위”에 경고로 표시됩니다. 알림 대상이 있으면 coverage_gap이 한 번 전달되고, 해소되면 coverage_restored가 전달됩니다. 락다운 중과 시간대 밖에서는 경고로 하지 않고 status에 한 줄을 표시합니다.
11.2 알림 (Webhook·syslog)
notify.webhook_urls와 notify.syslog.host(RFC 5424, UDP 또는 TCP)로 리그레션·신규 기기·ARP 스푸핑 등을 보냅니다. notify.min_severity와 재전송 간격으로 좁힐 수 있고, roamswitch-sensor notify-test로 연결을 확인할 수 있습니다.
status에 알림 대상과 마지막 전달 결과가 표시됩니다. 전달에 실패하는 동안은 경고가 표시되므로 roamswitch-sensor notify-test로 확인합니다. 성공하면 경고는 사라집니다.
11.3 감사 증적 내보내기
roamswitch-sensor export <scans|inventory|audit-log|all> --format csv|json|html [--out 파일] [--endpoint 공개 키의 앞부분] [--since 날짜]. html은 브라우저에서 PDF로 저장할 수 있습니다. CSV는 수식 주입에 대한 대책이 되어 있습니다. 출력은 0600이며, 내보내기 자체도 작업 로그에 남습니다. TUI에서는 e 키로 같은 지정을 할 수 있습니다.
11.4 작업·승인 로그 (변조 감지)
페어링·감사·설정 변경·거부한 접근을 실행자와 함께 기록합니다. 각 행이 직전 행의 SHA-256을 포함하는 해시 체인이며, 변조는 roamswitch-sensor audit-log verify로 알 수 있습니다(이상이면 종료 코드 2). Webhook URL의 값은 남기지 않습니다. 끝부분 삭제에 대비해 컬렉터(§11.6)에도 선두를 보냅니다.
11.5 보존 기간
retention.scan_history_days·retention.audit_log_days·retention.inventory_stale_days에 일수를 설정하면 오래된 감사 이력·작업 로그·오랫동안 보이지 않는 기기를 자동으로 삭제합니다(0 = 기간으로는 삭제하지 않음, 기본값). 메모를 등록한 기기는 대장에서 삭제되지 않습니다.
11.6 여러 Sensor 집계 (중앙 컬렉터, 선택 사항)
여러 거점에서 여러 Sensor를 운영하는 경우, 별도 호스트에서 roamswitch-sensor-collector(패키지에 포함, 기본 비활성)를 실행해 각 Sensor의 서명된 요약을 수집합니다.
# On the collector host (a separate host from the Sensor is recommended)
sudo systemctl enable --now roamswitch-sensor-collector # listens on 127.0.0.1:8443 by default
sudo roamswitch-sensor-collector token # read token for the dashboard
sudo roamswitch-sensor-collector enroll <Sensor public key> --name Tokyo --site Tokyo
# On each Sensor
sudo roamswitch-sensor config set collector.url https://collector.example.org:8443
sudo roamswitch-sensor config set collector.enabled true
- 등록(
enroll)한 Sensor의 Ed25519 서명이 있는 요청만 받아들입니다. 타임스탬프로 재전송도 거부합니다. - LAN 밖에 공개할 때는 TLS가 필요합니다.
/etc/default/roamswitch-sensor-collector의COLLECTOR_ARGS에--bind 0.0.0.0:8443 --tls-cert … --tls-key …를 지정하거나, TLS를 종단하는 리버스 프록시 뒤에서--allow-plain-http를 지정하세요. TLS 없이 127.0.0.1 이외에서 대기하려 하면 시작을 거부합니다. - 대시보드는 토큰으로 보호되며 거점별 필터, 심각도별 이벤트, CSV 내보내기를 제공합니다. 응답이 없는 Sensor와 감사 로그의 절단·되감기·분기가 감지된 Sensor를 강조 표시합니다(조사 후
clear-anomaly <공개 키>로 해제). collector.send_unmanaged_devices(기본값true)에서는 페어링하지 않은 기기도 요약에 포함하고, 「페어링되지 않은 RoamSwitch 호스트」와 「알 수 없는 기기」로 나눕니다. 보내는 것은 MAC·벤더·기기 클래스·최초 탐지뿐이며, 통신 내용은 포함하지 않습니다.collector.send_unmanaged_audits(기본값false)를 활성화하면, 미도입 기기의 최신 경량 감사에서 KEV에 오른 제품, 인증 없이 응답한 서비스, 탐지 건수를 보냅니다(최대 200대). 배너, 요청과 응답, 승인자의 기록은 보내지 않습니다. 「미확인」은 취약하다는 뜻이 아닐 수 있습니다.- Sensor는
summary.behavior_learned_devices(학습 기간이 끝난 기기 수)와summary.behavior_anomalies_active(최근 24시간에 평소와 다른 동작이 있었던 기기 수)를 보냅니다. 숫자뿐이며 기기 이름은 보내지 않습니다. 동작 학습이 꺼져 있으면 0입니다. 대시보드의 카드와 Sensor 상세에 표시됩니다. - 같은 기기(MAC)나 페어링된 단말이 다른 거점의 Sensor에서 보고되면 「거점 간 로밍」으로 기록합니다(
/api/roaming, 대시보드). 거점은enroll --site의 이름으로 비교합니다. 기록은 90일, 500건까지이며, 저장하는 것은 MAC·공개 키·거점 이름·시각뿐입니다. - 멈추거나 도난당한 Sensor는 스스로 알릴 수 없으므로, 컬렉터가 Webhook / syslog로 알립니다. 대상은
--stale-minutes(기본 60분)를 넘도록 전송이 없는 Sensor, 감사 로그의 이상(critical), 거점 간 로밍(info)입니다. 재전송은 기본 30분으로 억제하고, 재시작 후 20분은 멈췄다고 판정하지 않습니다. 전송 대상을 설정할 때까지는 아무것도 보내지 않고 차단도 하지 않습니다. Webhook URL은 표준 입력으로 전달하며 리다이렉트는 따라가지 않습니다.
# On the collector host: where the collector's own alerts go
echo 'https://hooks.example.org/…' | sudo roamswitch-sensor-collector notify set --add-webhook - --min-severity high
sudo roamswitch-sensor-collector notify set --syslog-host 192.0.2.10 --syslog-protocol tcp
sudo roamswitch-sensor-collector notify show # a Webhook URL is shown up to its host only
sudo roamswitch-sensor-collector notify test
컬렉터가 이력(scans.jsonl·events.jsonl)을 읽지 못했을 때는 「데이터 없음」으로 오인하지 않도록, 읽지 못한 분량을 셉니다. 손상된 행은 그 행만 건너뛰고, 날짜를 읽을 수 없는 행은 정리에서 지우지 않습니다. 결과는 /api/overview의 storage_health, 대시보드, 시작 시 로그에 나옵니다. 새로운 통신은 하지 않습니다.
11.7 탐지 데이터 취득(updates.fetch_cve_map)
Sensor는 서명된 CVE 맵(능동 진단에 사용하는 알려진 취약점 데이터)과 nmap NSE 데이터베이스를 업데이트 서비스에서 매일 가져옵니다. 이 통신에는 기기·감사 데이터가 포함되지 않습니다. 완전 오프라인으로 운용하는 경우에는 sudo roamswitch-sensor config set updates.fetch_cve_map false를 실행하십시오(변경은 재시작 없이 다음 주기부터 반영되며, 이후에는 기본 제공 데이터만 사용합니다).
11.8 설정 키 목록
roamswitch-sensor config show로 현재 값을 확인하고, config set <키> <값> [<키> <값> …]로 변경합니다(여러 키는 원자적으로 저장되며, TUI에서는 C의 설정 편집기에서도 변경할 수 있습니다). 「재시작」 열이 「필요」인 키만 데몬 재시작(sudo systemctl restart roamswitch-sensor)으로 반영됩니다.
| 키 | 형식 / 가능한 값 | 기본값 | 재시작 |
|---|---|---|---|
site | string | (empty) | 불필요 |
language | ja | en | ko | zh-Hans | zh-Hant | de | fr | es | it | pt-PT | (empty = system locale) | 불필요 |
schedule.enabled | bool | false | 불필요 |
schedule.interval_hours | int | 24 | 불필요 |
schedule.window_start_hour | int 0–23 | (unset = always) | 불필요 |
schedule.window_end_hour | int 0–23 | (unset = always) | 불필요 |
schedule.max_parallel | int 1–8 | 1 | 불필요 |
schedule.allow_routed_endpoints | bool | false | 불필요 |
schedule.routed_proof_minutes | int 5–1440 | 30 | 불필요 |
notify.webhook_urls | URL list | (empty) | 불필요 |
notify.min_severity | info | medium | high | critical | medium | 불필요 |
notify.cooldown_minutes | int | 30 | 불필요 |
notify.syslog.host | string | (empty = off) | 불필요 |
notify.syslog.port | int | 514 | 불필요 |
notify.syslog.protocol | udp | tcp | udp | 불필요 |
retention.scan_history_days | int (0 = never prune) | 0 | 불필요 |
retention.audit_log_days | int (0 = never prune) | 0 | 불필요 |
retention.inventory_stale_days | int (0 = never prune) | 0 | 불필요 |
collector.enabled | bool | false | 불필요 |
collector.url | URL | (empty) | 불필요 |
collector.push_interval_minutes | int | 15 | 불필요 |
collector.send_unmanaged_devices | bool | true | 불필요 |
collector.send_unmanaged_audits | bool | false | 불필요 |
collector.probe_control_port | bool | false | 불필요 |
control.bind_addr | IP address | 0.0.0.0 | 필요 |
control.tls | off | optional | required | optional | 필요 |
control.allow_legacy_signatures | bool | true | 불필요 |
updates.fetch_cve_map | bool | true | 불필요 |
control.listen_ipv6 | bool | false | 필요 |
capture.rcvbuf_mb | int 0–256 (MiB, 0 = system default) | 4 | 필요 |
dhcp.active_probe | bool | true | 불필요 |
dhcp.allowed_servers | MAC / IP list | (empty = learn the first) | 불필요 |
ipv6.enabled | bool | true | 불필요 |
ipv6.active_probe | bool | true | 불필요 |
ipv6.allowed_routers | MAC / IP list | (empty = trust the IPv4 gateway) | 불필요 |
unmanaged_audit.enabled | bool (needs authorization + allowed_cidrs first) | false | 불필요 |
unmanaged_audit.authorization | string | (empty) | 불필요 |
unmanaged_audit.allowed_cidrs | CIDR list (IPv4 ≤ /16 and IPv6 ≤ /48 refused) | (empty) | 불필요 |
unmanaged_audit.exclude | IP / CIDR / MAC list | (empty) | 불필요 |
unmanaged_audit.interval_hours | int | 168 | 불필요 |
unmanaged_audit.max_parallel | int 1–4 | 2 | 불필요 |
unmanaged_audit.product_check | bool (needs unmanaged_audit.enabled) | false | 불필요 |
unmanaged_audit.noauth_check | bool (needs unmanaged_audit.enabled) | false | 불필요 |
design_flaw.enabled | bool | false | 불필요 |
design_flaw.llm.tool | claude | opencode | codex | agy | (empty) | (empty) | 불필요 |
design_flaw.llm.model | string | (empty) | 불필요 |
design_flaw.llm.timeout_secs | int (0 or 5–600) | 0 | 불필요 |
security.on_revoked | lockdown | wipe | none | lockdown | 불필요 |
security.lockdown_after_offline_days | int (0 = off) | 0 | 불필요 |
12. 불법 DHCP·IPv6 탐지
반입된 라우터 등이 정규 장비인 척하며 단말의 통신 경로를 가로채는 공격을 찾아냅니다. 탐지와 알림만 하며, 통신은 차단하지 않습니다. 기본적으로 활성화되어 있고 수동 캡처는 필요 없습니다. 결과는 roamswitch-sensor network-threats, TUI, 알림, 로그, 내보내기에 나옵니다.
12.1 불법 DHCP 서버(IPv4·DHCPv6)
1시간마다 무작위 MAC으로 DHCP 탐색을 하나만 보내 응답한 모든 서버를 셉니다. REQUEST는 보내지 않으며 주소를 빌리지 않습니다. 처음 응답한 서버를 정규로 학습하고, 나중에 나타난 서버를 알립니다. 다른 게이트웨이나 DNS를 배포하는 것은 critical입니다.
12.2 IPv6(불법 라우터 광고·NDP 스푸핑·IPv6에서만 보이는 기기)
불법 라우터 광고: IPv4 게이트웨이와 다른 기기가 IPv6 라우터로 동작하면 알립니다(정상 구성이면 ipv6.allowed_routers에 등록). 홉 리밋이 255가 아닌 광고는 무시합니다. NDP 스푸핑: IPv6 주소의 MAC이 바뀌면 알립니다(라우터면 high). IPv6에서만 보이는 기기: 이웃 테이블에만 나타난 기기를 보고합니다.
12.3 무엇을 정상으로 볼지와 설정
dhcp.allowed_servers와 ipv6.allowed_routers를 설정하면 그 이외의 응답을 모두 보고합니다(비어 있으면 처음 것을 학습). ipv6.enabled로 IPv6 감시를 끌 수 있습니다. 제어 API(50543)의 IPv6 대기는 control.listen_ipv6(기본값 false)로 추가합니다. 글로벌 IPv6는 인터넷에서 도달할 수 있으므로 기본적으로 비활성화되어 있습니다.
13. RoamSwitch 미도입 기기의 경량 감사(옵트인)
§5의 능동적 취약점 감사는 페어링하여 합의한 단말만 대상입니다. 페어링하지 않은 프린터·카메라·NAS 등에서 「무엇이 외부에 열려 있는가」를 확인하고 싶다면, 훨씬 한정된 별도의 검사를 쓸 수 있습니다. OpenVAS 같은 깊은 진단, 로그인 시도, 취약점 악용, nmap NSE, 전체 포트 스캔은 합의한 단말에만 합니다.
13.1 하는 일
정해진 55개 포트에 대한 TCP 연결 확인, 열린 포트가 스스로 보내는 표시(배너)의 읽기(웹에는 HEAD /를 1회), 공개된 취약점의 주석만 합니다. 결과는 「LAN에서 닿는다」이지 「취약하다」라고는 하지 않습니다. 제품 확인과 인증 확인은 각각 별도의 옵트인입니다(기본 꺼짐).
13.2 켜기
활성화하기 전에 unmanaged_audit.authorization(승인자)과 unmanaged_audit.allowed_cidrs(범위. IPv4는 /16, IPv6는 /48보다 넓으면 거부)를 설정합니다. 정기 실행은 기본 168시간마다이며, 수동 실행에는 --confirm이 필요합니다.
sudo roamswitch-sensor config set unmanaged_audit.authorization "IT policy 2026-07, approved by A. Suzuki"
sudo roamswitch-sensor config set unmanaged_audit.allowed_cidrs 192.168.10.0/24
sudo roamswitch-sensor config set unmanaged_audit.exclude 192.168.10.1
sudo roamswitch-sensor config set unmanaged_audit.enabled true
sudo roamswitch-sensor audit-unmanaged 192.168.10.40 --confirm
roamswitch-sensor unmanaged-audits --detail
13.3 지켜지는 것
allowed_cidrs 밖의 기기, unmanaged_audit.exclude에 있는 기기, 페어링된 단말, Sensor 자신은 어떤 경우에도 조사하지 않습니다. 전후에 MAC을 확인하여 다른 기기라면 중단하거나 결과를 폐기합니다. authorization의 문면은 실행할 때마다 로그에 남습니다.
13.4 제품 확인(CISA KEV에 오른 취약점이 있는 제품인가. 옵트인)
unmanaged_audit.product_check(기본 꺼짐)는 기기의 웹 화면에서 제품명을 읽고 CISA KEV 취약점이 있는지 알려 줍니다. 보내는 것은 웹용 포트(80·8080·8181·443·8443·10443)로의 GET /과 리다이렉트(최대 2회)뿐입니다. 로그인, 비밀번호 시도, 추측한 경로, 취약점을 노리는 입력은 보내지 않습니다. 기기 1대당 최대 12회 요청, 150밀리초 간격입니다.
제품의 표지가 같은 응답에서 모두 확인될 때만 제품명을 지목합니다. 기기가 알린 버전에 NVD 영향 범위의 CVE가 있으면 '해당'(high), 버전을 읽을 수 없으면 '미확인' 주의(medium)로 표시하며, 취약하다고는 말하지 않습니다. 버전을 읽을 수 있는 것은 MikroTik RouterOS뿐입니다. 대응 제품은 Fortinet FortiGate, Ivanti Connect Secure, Citrix NetScaler 등입니다. 표지는 공개된 탐지 시그니처에 기반하며 실제 기기에서는 확인하지 않았습니다.
KEV 사본은 동봉되어 있으며, product_check와 updates.fetch_cve_map가 둘 다 활성화된 경우에만 24시간마다 CISA의 공개 피드 1개 파일을 가져옵니다(LAN 정보는 일절 보내지 않습니다).
인증 없이 응답하는지 확인(unmanaged_audit.noauth_check. 기본 꺼짐, 옵트인) 열려 있던 다음 포트에만 읽기 전용 요청을 하나씩 보냅니다. Redis(6379, PING), Memcached(11211), Docker API(2375), Elasticsearch(9200), etcd(2379), CouchDB(5984), kubelet(10250), ZooKeeper(2181), Ollama(11434)입니다. 쓰기, 설정 변경, AUTH, 비밀번호 전송이나 추측, 로그인은 하지 않습니다.
MongoDB·MySQL 등은 시도가 로그인이 될 수 있으므로 조사하지 않습니다. 결과는 '인증 없이 응답함', '인증 필요', '거부됨', '판단 불가' 중 하나입니다. 경량 감사와 같은 동의 아래에서만 동작합니다. 직접 관리하는 기기에만 사용하십시오.
14. 분실·도난·폐기 시
Sensor에는 단말별 취약점 목록, 페어링된 단말의 주소, 서명 키가 들어 있습니다. 또한 페어링한 단말은 이 Sensor를 '포트 스캔을 허용한 상대'로 취급하므로, 도난당한 Sensor가 같은 LAN에 연결되면 그 상대로 행세할 수 있습니다. 다음 장치로 막습니다.
14.1 컬렉터에서의 폐기와 락다운
roamswitch-sensor-collector revoke <공개 키> --reason 이유로 폐기하면 해당 Sensor의 전송은 403 sensor_revoked로 거부됩니다. 폐기를 알게 된 Sensor는 스스로 정지(락다운)하여 감사·전송·알림·탐색을 모두 멈춥니다. 정지는 재시작 후에도 이어지며 데이터는 남습니다. 소유자의 손에 있다고 확실할 때만 roamswitch-sensor lockdown off로 해제할 수 있습니다.
14.2 삭제·폐기·오프라인 감지
security.on_revoked를 wipe로 하면, 폐기 시 키·TLS 키·설정(Webhook URL 포함)·단말 목록·감사 결과·기기 대장을 0으로 덮어쓰고 삭제합니다. 조작·승인 로그만은 증거로 남깁니다. 기본값인 lockdown은 정지만 합니다. security.lockdown_after_offline_days(기본 0=비활성)로, 오래 전송하지 못하는 Sensor도 스스로 정지합니다.
14.3 이 장치로 할 수 없는 것
단말은 각자가 해제할 때까지 이 Sensor를 계속 신뢰하며, Sensor 쪽에서는 알릴 수 없습니다. 표시된 각 단말에서 Linux는 roamswitch sensor unpair <이 Sensor의 공개 키>, Mac은 설정 > Sensor > 페어링 해제를 실행하십시오. 전원이 꺼진 채 반출된 Sensor에는 정지 지시가 닿지 않으므로, 디스크 암호화(LUKS 등)가 실질적인 방어입니다. 덮어쓰기 삭제는 플래시나 CoW에서는 완전한 삭제를 보장하지 않습니다.