제IX부: 운영과 배포¶
두 가지 운영 구성, 모든 명령줄 플래그, forward-auth 구성 예, 정책 파일, SQLite 또는 PostgreSQL을 쓰는 영속 저장소, 공유 데이터베이스 하나를 쓰는 클러스터, 패키징을 다룹니다.
운영 구성과 설정¶
운영 구성 선택¶
- Gate (
--gate, 별칭--no-waf): 작업 증명 요청 허용, 세션, 선언형 규칙, 평판, GCRA 제한, 차단을 제공합니다. - Shield (기본값,
--shield, 별칭--waf): Gate에 의미 기반 방화벽을 더합니다. - 분산 배포 (두 운영 구성 모두에서 선택 가능):
--data-dir는 정책, 평판, 포렌식 기록을 로컬 SQLite 파일에 보관합니다.--database-url과--cluster-node를 함께 쓰면 여러 노드가 하나의 PostgreSQL 데이터베이스에 연결됩니다(SID 0011).
명령줄 레퍼런스¶
이 표는 sibuna --help의 모든 옵션을 나열합니다. 범위는 파서가 강제하는 값입니다.
| 플래그 | 기본값 | 의미 |
|---|---|---|
--port, -p |
8080 |
수신 포트, 1에서 65535까지 |
--host, -h |
0.0.0.0 |
수신 주소, IP 주소 리터럴 |
--upstream-host |
127.0.0.1 |
원본 서버 호스트(리버스 프록시 모드) |
--upstream-port, -u |
3000 |
원본 서버 포트 |
--mode, -m |
reverse_proxy |
reverse_proxy 또는 forward_auth (proxy와 auth도 가능), 한 번만 지정 |
--workers, -w |
CPU당 하나 | 수신 소켓을 공유하는 accept 스레드 수, 0(CPU당 하나)에서 64까지. 수락한 연결마다 전용 스레드를 하나씩 둡니다 |
--max-connections |
1024 |
동시에 처리하는 연결 수, 1에서 8192까지. 그 이상은 503으로 응답합니다 |
--max-connections-per-ip |
64 |
소켓 피어 주소 하나가 유지할 수 있는 연결 수, 0(제한 없음)에서 8192까지. IPv6 피어는 --ipv6-prefix 네트워크 단위로 세며, 전달된 헤더는 관여하지 않습니다. 그 이상은 503으로 응답합니다 |
--idle-timeout |
15 |
가장 긴 무활동 시간(초), 0에서 86400까지. 요청 헤드는 이 시간 안에 도착해야 합니다. 원본 서버 응답은 읽을 때마다 이 시간을 갱신하므로, 느린 스트림은 바이트가 흐르는 동안 유지되고 아무것도 보내지 않는 원본 서버는 양쪽 소켓 모두 연결이 끊깁니다. 프록시를 거치는 업로드는 주기마다 16 KiB를 전달해야 합니다(느린 본문 공격에 대한 최소 속도). 클라이언트 소켓에도 같은 길이의 쓰기 타임아웃이 걸리므로, 그 시간 동안 한 바이트도 받지 않는 클라이언트는 연결을 잃습니다 |
--websocket-idle-timeout |
300 |
업그레이드된 연결의 유휴 기한(초), 0에서 86400까지 |
--trust-forwarded |
꺼짐. forward-auth에서는 켜짐 | 피어가 보낸 X-Forwarded-For / X-Real-IP를 신뢰합니다 |
--no-trust-forwarded |
꺼짐 | forward-auth 모드에서도 이 헤더를 신뢰하지 않습니다 |
--trusted-hops |
1 |
전달된 신원을 신뢰할 때, 오른쪽에서 이 수만큼 떨어진 위치의 X-Forwarded-For 항목을 클라이언트로 봅니다. 1에서 8까지 |
--ja4-header |
꺼짐 | 신뢰할 수 있는 인그레스가 클라이언트의 JA4 TLS 지문을 보내는 요청 헤더(예: cf-ja4). 토큰 문자 1개에서 64개이며, X-Forwarded-*, X-Real-IP, X-Sibuna-*, Forwarded는 쓸 수 없습니다. 전달된 신원을 신뢰할 때만 읽습니다("인그레스에서 받는 JA4 지문" 참조) |
--ipv6-prefix |
64 |
속도 제한, 차단, 클라이언트별 연결 상한이 적용되는 IPv6 접두사 길이, 32에서 128까지 |
--algorithm, -a |
posw |
posw 또는 hashcash |
--difficulty, -d |
16 |
작업 비트, 1에서 64까지: Hashcash의 0비트 수 또는 PoSW 깊이에 3을 더한 값 |
--posw-challenges |
16 |
순차 작업 증명 하나당 개방 수, 1에서 32까지 |
--token-scheme |
mac |
mac (키 기반 BLAKE3) 또는 ed25519 |
--token-ttl |
86400 |
세션 수명(초), 1에서 31,536,000까지 |
--challenge-ttl |
300 |
챌린지 수명(초), 1에서 86,400까지 |
--secret-file, -s |
무작위 생성 | 16진수 문자 64개 또는 원시 바이트 32개. SIBUNA_SECRET (16진수 문자 64개)도 사용할 수 있습니다 |
--cookie-name |
__sibuna_token |
세션 쿠키 이름, 토큰 문자 1개에서 64개 |
--secure-cookie |
꺼짐 | Secure 속성을 추가합니다 |
--gate / --shield |
shield | 운영 구성 선택 |
--rate-limit |
100 |
클라이언트별 윈도당 요청 수(GCRA 버스트) |
--rate-window |
10 |
윈도(초), 1에서 86400까지 |
--challenge-rate-limit |
30 |
클라이언트별 윈도당 챌린지 발급과 검증 횟수, 요청 예산과 별개 |
--ban-seconds |
3600 |
허니팟 차단 기간, 0에서 31,536,000까지 |
--policy-file, -P |
없음 | 선언형 JSON 정책 |
--rate-table-cells |
262144 |
속도 제한 테이블당 셀 수, 셀마다 16바이트, 4,096에서 16,777,216까지, 2의 거듭제곱으로 올림 |
--ban-table-slots |
65536 |
차단 테이블 슬롯 수, 슬롯마다 24바이트, 1,024에서 16,777,216까지, 2의 거듭제곱으로 올림 |
--spent-tags |
1048576 |
재전송을 막기 위해 기억하는 해결된 챌린지 수, 항목마다 24바이트, 65,536에서 16,777,216까지 |
--data-dir, -D |
없음 | 단일 노드: SQLite 파일 <path>/sibuna.db에 영속 저장합니다 |
--database-url |
없음 | 클러스터: 공유 PostgreSQL 데이터베이스(postgres:// 또는 postgresql://) |
--database-url-file |
없음 | 소유자만 읽을 수 있는 파일에서 데이터베이스 URL을 읽습니다 |
--cluster-node |
없음 | 이 노드의 id. 챌린지 키에 묶이고 인시던트 식별자의 상위 비트가 됩니다. 데이터베이스 URL을 쓸 때 반드시 지정해야 합니다 |
--storage-poll-ms |
500 |
저장소 틱 간격, 1에서 60,000 ms까지 |
--verbose, -v |
꺼짐 | 상세 로그 출력 |
--help / --version |
도움말(콘솔이 컴파일되어 있으면 콘솔 옵션 먼저) 또는 버전을 출력하고 종료합니다 |
--data-dir와 데이터베이스 URL은 함께 쓸 수 없고, --database-url과 --database-url-file도 함께 쓸 수 없습니다. --cluster-node 없이 데이터베이스 URL을 지정하면 거부합니다. Zaxonlite 클러스터 옵션 --cluster-listen, --cluster-peer, --cluster-secret-file, --cluster-tls-cert, --cluster-tls-key, --cluster-tls-ca는 제거되었습니다. 이 중 하나를 지정하면 RemovedOption과 SID 0011을 가리키는 힌트를 내고 시작을 멈춥니다. 콘솔 옵션은 다음 장에 나와 있습니다.
콘솔 미리보기¶
콘솔은 기본 console 기능으로 데몬에 컴파일되지만 --console을 지정할 때만 시작합니다. 콘솔에는 저장소가 필요합니다. --data-dir이나 --database-url 없이 --console을 지정하면 CONSOLE001 (StorageRequired)로 거부됩니다. 콘솔을 빼고 컴파일하려면 cargo build --release -p sibuna --no-default-features --features sqlite를 사용하세요. --no-default-features만 지정한 빌드에는 저장소도 콘솔도 없습니다. 데몬을 중지한 상태에서 로컬로 초기 설정을 합니다:
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
sibuna console init-admin도 같은 명령입니다. http://127.0.0.1:19446/console/을 열고 생성된 임시 비밀번호를 바꾸세요. 이 비밀번호는 첫 로그인 때 반드시 바꿔야 하며 한 시간 뒤 만료됩니다. 로그인한 뒤의 탐색 메뉴는 움직이는 국가 지구본, 요청과 챌린지 통계, 인시던트 조사, 정책과 검사 편집기, 사용자, 범위가 정해진 API 토큰, 감사 기록, 서비스 노드 제어를 제공합니다. 인증 화면은 지구본 형상이나 텔레메트리를 불러오지 않습니다. 인터페이스는 데몬의 빌드 스크립트가 cmd/console-ui (크레이트 sibuna-console-ui)에서 빌드한 WebAssembly 모듈입니다. 이 모듈과 커밋된 스타일시트는 일반 빌드에 포함됩니다.
| 플래그 | 의미 |
|---|---|
--console <ip:port> |
이 리스너에서 콘솔을 시작합니다(IPv6는 대괄호 안에, 포트는 0이 아님). --data-dir 또는 --database-url이 필요합니다 |
--console-key-file <path> |
16진수 문자 64개, 소유자 전용 권한. 저장된 2단계 인증 비밀 값과 웹훅 비밀 값을 보호합니다 |
--console-origin <https-origin> |
프록시 뒤에서 사용하는 정식 HTTPS 출처 |
--console-behind-proxy |
TLS를 종료하는 프록시가 모든 요청을 전달합니다 |
--console-trusted-proxy <cidr> |
전달 필드를 실어 보내도 되는 연결이 오는 네트워크. 반복 지정 가능, 최대 16개 |
--console-advertise <origin> |
다른 콘솔이 이 콘솔을 가리킬 때 보여 주는 링크 |
--console-location <latitude,longitude> |
지구본 위에 선언하는 이 노드의 위치 |
--console-probe <node-id>=<http://ip:port> |
상태를 점검할 피어 데이터 평면 리스너. 반복 지정 가능, 최대 8개 |
--console-peer <node-id>=<https://origin> |
관리 피어. 반복 지정 가능, 최대 8개 |
--console-peer-key-file <path> |
피어 키: 소유자 전용, 16진수 문자 64개, 콘솔 키와 독립적 |
--console-peer-ca-file <path> |
피어용 선택적 PEM 신뢰 앵커. 시스템 루트 인증서를 대체합니다 |
--console-query-steps <n> |
집계 읽기 한 번당 SQLite 단계 수, 100,000에서 50,000,000까지, 기본값 4,000,000 |
--console-capture-heads |
인시던트마다 마스킹한 요청 헤드와 원본 서버 응답 헤드를 저장합니다. 기본값은 꺼짐 |
--console-capture-header <name> |
저장된 헤드에 이 헤더의 값을 남깁니다. 반복 지정 가능, 최대 16개. --console-capture-heads가 필요합니다 |
--console-cookie-secure |
프록시 없이도 콘솔 쿠키에 Secure 속성을 붙입니다(파서는 받지만 --help에는 나오지 않음) |
--console 없이 지정한 콘솔 옵션, 반복된 옵션, 형식이 잘못된 값은 CONSOLE002와 해당 옵션의 오류 이름을 내고 시작을 멈춥니다. 콘솔 규칙을 어기는 설정(예: 신뢰할 수 있는 프록시 없이 루프백이 아닌 주소에서 수신)은 CONSOLE001로 시작을 멈춥니다.
콘솔 둘러보기¶
아래 화면은 SQLite 저장소를 쓰는 루프백 노드 하나에서 릴리스 빌드로 캡처했습니다. 정책은 기본 챌린지 위에 ALLOW 규칙 네 개를 두었고, 약 4분 동안 합성 트래픽을 보냈습니다. 트래픽은 문서용 대역의 주소, SQL 인젝션과 크로스 사이트 스크립팅 탐색, 허니팟 적중 세 번, 헤드리스 Chromium에서 해결한 챌린지 일곱 개로 이루어졌습니다. 따라서 모든 수치는 예시일 뿐입니다. 화면은 cargo xtask browser console --viewport-only로 캡처했습니다. 이 명령은 Chromium에서 1440 x 960 픽셀로 콘솔을 순회하며 모든 페이지를 검사합니다. 각 페이지는 제목에 적힌 질문 하나에 답하며, 제품, 서비스 노드, 페이지, 돌아가기 링크를 같은 자리에 표시합니다.
waf:sqli와 waf:xss)를 보여 주는 실시간 이벤트 피드가 있습니다. 기록되지 않은 값은 0을 보여 주는 대신 그렇다고 밝힙니다. 평판 타일은 "기록되지 않음"으로 표시됩니다. 페이지 아래쪽에는 같은 크기의 구간 60개에 걸친 탐지 결과, 공격 범주, 공격받은 경로가 있습니다.¶
--console-capture-heads를 지정하면 마스킹한 요청 헤드(리버스 프록시를 거쳐 감사 대상으로 허용된 요청이라면 원본 서버 응답 헤드도)를 요청 시 펼쳐 볼 수 있습니다. 헤드는 UTF-8 또는 Latin-1로 표시되며, 응답 조건(캡처됨, 로컬, forward-auth에서 관찰 안 됨, 원본 서버 사용 불가)과 cURL 명령으로 복사하는 기능이 함께 제공됩니다. 목록에 있는 헤더 값만 보관되며, --console-capture-header <name>으로 그 목록에 추가합니다. 그렇지 않으면 헤드는 기록되지 않음으로 표시됩니다. 거부와 허용 동작은 해당 주소가 미리 채워진 IP 그룹 양식을 엽니다.¶
선택 옵션 --console-location <latitude,longitude>는 이 노드의 위치를 선언합니다. 예를 들어 싱가포르의 배포라면 1.3521,103.8198입니다. 지구본은 처음에 이 위치를 중심으로 표시되고, Center Sibuna는 회전한 뒤 이 지점으로 돌아갑니다. 국가별 활동은 노드를 향하는 움직이는 대원 호로 표시되며, 뒤쪽 반구와 평면 지도의 날짜 변경선에서 잘립니다. 국가 위치는 대표 중심점이며, 화살표는 개별 연결이 아니라 관측된 60초 구간을 나타냅니다. 서버 위치를 설정하지 않으면 명시적으로 "알 수 없음"으로 남습니다. 설정된 표식은 텔레메트리가 끊긴 동안에도 계속 보이며, 오래된 트래픽은 움직이지 않습니다.
정책 미리보기는 설정된 파일 규칙을 포함한 비공개 후보를 만듭니다. 저장할 때는 예상 리비전을 비교하고 필드 비교 결과를 확인받습니다. 과거 버전으로 되돌리기는 현재 규칙과 비교한 뒤 새 리비전을 만듭니다. 커밋된 리비전과 로컬에 적용된 리비전은 서로 다릅니다. 감사 상세 정보는 크기가 제한된 결정 변경 내역과 실제로 동작한 역할을 보관합니다. 매처 값은 마스킹되며, 문맥이 빠진 오래된 기록은 정보가 없다고 명시됩니다. 드레인, 재개, 로컬 차단 해제에는 명령 미리보기가 필요합니다. 노드에서 다른 명령이 실행 중일 때 도착한 명령은 큐에 쌓이지 않고 503 CONSOLENODE로 거부됩니다. 응답을 잃었다면 다시 시도하기 전에 영속 영수증을 확인하세요. 커밋된 의도만으로는 실행 시점의 효과가 끝났다고 할 수 없습니다.
원격으로 운영하려면 HTTPS 프록시를 사용하고 --console-origin, --console-behind-proxy, 명시적인 --console-trusted-proxy CIDR, --console-key-file을 설정하세요. 키 파일은 16진수 문자 64개를 담고, 소유자 전용 권한을 가지며, 저장된 2단계 인증 비밀 값을 보호합니다. 재시작해도 유지하되 챌린지 시드와는 따로 보관하세요. 루프백 밖에서 접근하려면 HTTPS 출처와 프록시 허용 목록을 반드시 설정해야 합니다. Sibuna는 콘솔 리스너에서도 들어오는 TLS를 종료하지 않습니다. 콘솔은 나가는 연결에만 rustls를 통해 TLS를 사용합니다(SID 0012).
네이티브 CLI는 같은 권한 부여 및 저장소 규약을 거쳐 실행 중인 콘솔에 접근합니다. 자격 증명은 명령줄 값이 아니라 비공개 파일에서 읽습니다:
sibuna console geoip update --version 2026-09-09 \
--origin http://127.0.0.1:19446 --username admin \
--password-file ./admin-password
소유자 전용 비밀번호 파일을 사용하고, 먼저 비밀번호 설정을 마친 뒤, 필요하면 인증 앱 코드나 복구 코드를 위한 --factor-file을 추가하세요. --token-file은 계정과 GeoIP 작업에서 사용자 이름과 비밀번호를 대신합니다. 클라이언트는 HTTP/1.1을 사용하고, 리터럴 루프백 주소가 아니면 HTTPS를 요구하며, 리디렉션을 따르지 않고, 요청마다 20초, 응답마다 16 KiB로 제한합니다. geoip status는 활성 세대를 읽습니다. 업데이트는 선택한 제공자가 게시한 파일을 HTTPS로 내려받고(기본값은 퍼블릭 도메인 user-country 데이터셋, --provider dbip --version YYYY-MM을 지정하면 DB-IP Lite), 게시자의 체크섬(또는 --checksum으로 지정한 체크섬)을 검증하고, sibuna-geoip로 크기가 제한된 범위를 검증한 뒤, 새 세대를 영속 저장하고 로컬에서 활성화합니다. 업데이트에 실패하면 이전 세대가 유지됩니다. CLI 타임아웃(--timeout, 기본값 1200초)은 기다리기를 멈출 뿐, 제출된 저장소 작업을 취소하지는 않습니다. DB-IP Lite는 CC BY 4.0 저작자 표시가 필요하며, 이 표시는 해당 데이터가 활성일 때만 나타납니다. SIBUNA_GEOIP_DATA=<snapshot>으로 빌드하면 검증된 스냅숏(geoip-snapshot 도구가 작성)을 첫 영속 가져오기 전까지 내장합니다. 콘솔이 없는 빌드는 이를 GEOIP001로 거부합니다. 알 수 없는 주소, 표본 손실, 오래된 데이터는 그대로 표시됩니다. 국가 데이터를 가져와도 트래픽이 생기거나 이미 만료된 표본이 보강되지는 않습니다.
클러스터 구성원은 시작할 때, 매분, 그리고 적용된 정책 또는 제어 리비전이 바뀐 뒤 2초 안에 공유 데이터베이스의 구성원 테이블(console_nodes)에 자신을 알리며, 모든 콘솔의 노드 페이지에 나타납니다. 리더 선출은 없습니다. SQLite 노드는 역할 single과 자기 자신을 리더로 보고하고, PostgreSQL 노드는 역할 unknown과 리더 없음을 보고합니다. PostgreSQL의 장애 조치는 Sibuna에 보이지 않기 때문입니다(SID 0007). 이 콘솔이 데이터 평면 리스너의 상태를 점검할 피어는 --console-probe <node-id>=<http://ip:port>로, 다른 콘솔이 보여 줄 링크는 --console-advertise <origin>으로 설정하세요. 피어에서 직접 받는 실시간 텔레메트리는 --console-peer <node-id>=<https://origin> (반복 지정 가능, 최대 8개)와 전용 --console-peer-key-file을 사용합니다. 피어에는 --console-behind-proxy가 필요합니다. 양쪽 엔드포인트가 서로를 나열하고 신뢰할 수 있는 HTTPS 인그레스를 사용해야 합니다. 피어 키는 16진수 문자 64개를 담은 소유자 전용 파일이며, 콘솔 키 및 챌린지 시드와 독립적으로 준비합니다. 피어는 인증된 TLS WebSocket으로 통신하며, ring 제공자를 쓰는 rustls를 사용합니다(SID 0012). --console-peer-ca-file은 비공개 관리 PKI를 위한 PEM 신뢰 앵커를 선택적으로 제공합니다. 지정하지 않으면 클라이언트는 시스템 루트 인증서를 사용합니다. 호스트 이름 검증은 항상 적용되며 끌 수 없습니다. 각 관리 출처의 호스트(DNS 이름 또는 IP 주소 리터럴)는 피어 인증서에 명시되어 있어야 합니다. 인증서가 거부되면 피어를 rejected로 표시하고 peer.rejected 감사 행 하나를 씁니다. 키를 교체하거나 CA 파일을 바꾸려면 조율된 재시작이 필요합니다. 피어 인증서는 재시작 없이 갱신할 수 있습니다. 노드 API와 그 구독은 수신 경과 시간, 시계 오차, 부팅 변경, 표본 손실을 보고합니다. 누락된 관측값은 사용할 수 없음으로 남고, 연결이 끊긴 값은 오래된 값으로 남습니다. 받은 통계가 다른 노드 자신의 기여로 바뀌는 일은 없습니다. 대시보드의 실시간 트래픽 범위는 노드 하나를 선택하거나 설정된 노드를 합칩니다. 노드 범위와 위치는 누락되거나, 오래되었거나, 시계가 어긋난 소스와 관측 시각, 설정된 대상을 식별합니다. 국가 순위는 빠진 소스 행에서 오는 불확실성을 보여 줍니다. 화살표는 수신 노드를 유지하며, 누락된 노드 위치를 지어내지 않습니다. 기여하는 소스 중 하나라도 연속 구간이 없으면 합산 속도는 관측되지 않음으로 남습니다. 노드 하나를 선택하면 그 노드의 보존된 초 단위 기록과 현재 분의 경로 순위를 살펴볼 수 있습니다. 원격 질의는 인증된 피어 연결을 사용합니다. 질의 응답은 4 KiB WebSocket 메시지 하나에 들어가야 하므로, 서비스하는 콘솔은 들어가지 않는 페이지의 행 수를 절반으로 줄입니다. 누락된 피어는 사용할 수 없음으로 남고, 기록 커서는 노드 재시작을 넘어갈 수 없습니다. 분 단위 기록은 자체 노드 선택과 노드별 행을 유지합니다. 탐색 메뉴와 모바일 헤더는 선택한 트래픽 소스와 관계없이 서비스하는 콘솔 노드를 표시합니다. 로컬 명령은 계속 노드별로 동작합니다.
트래픽 타일은 선택한 노드의 보존된 마감 분 단위 기록 가운데 최근 24시간을 먼저 보여 줍니다. 기간 선택에서는 1시간, 7일, 90일, 실시간 부팅 이후 합계도 고를 수 있습니다. 어제 대비 편차를 계산하려면 선택한 모든 노드에서 일치하는 범위가 완전해야 합니다. 지구본과 스파크라인은 여전히 별도의 실시간 60초 구간을 나타냅니다. 보존 기록 스캔은 완료 1분 뒤에 갱신되며, 교체될 때까지 이전 값과 경과 시간을 계속 보여 줍니다. 소스나 기간을 바꾸면 이전 범위는 버립니다. 누락된 기록이 0이 되는 일은 없습니다.
보존된 트래픽 비교는 마감된 분 단위 구간 두 개를 나란히 보여 줍니다. 어제의 같은 구간, 직전 기간, 또는 다른 노드와 비교할 수 있습니다. 길이와 종료 오프셋 설정으로 두 UTC 범위를 고정합니다. 동작 한 번은 한쪽마다 압축 페이지를 최대 16개까지 읽으며, 페이지마다 저장된 기록이 96개 있습니다. 이 정도면 재시작이 겹치지 않는 24시간 구간을 한 번에 다룰 수 있습니다. 더 긴 스캔에서는 계속하기가 같은 경계를 유지합니다. 완전한 범위, 불완전한 범위, 누락된 기록은 명시적으로 표시됩니다. 비율 백분율은 같은 UTC 구간에서 겹치지 않는 완전한 구간이 필요하며, 관측된 밀리초로 정규화합니다. 기준값이 0인데 새 트래픽이 있으면 "새로 생김"으로 표시합니다. 기본 트래픽 기간은 독립적으로 유지됩니다. 분 단위 형식은 과거의 프록시 모드를 기록하지 않으므로, 원본 서버 응답 비교는 forward-auth의 0을 관측된 응답으로 해석하지 않고 사용할 수 없음으로 남습니다.
보존된 경로 순위 비교는 마감된 구간 두 개 또는 노드 두 개를 선택합니다. 노드 0은 운영에서 제외된 구성원을 포함해 보존된 모든 노드를 포함합니다. 동작 한 번은 변경 불가능한 아카이브를 최대 16개까지 읽고, 식별자와 체크섬을 확인하고, 표시할 행을 고르기 전에 모든 카운터를 병합합니다. 아카이브는 늦게 도착하는 표본을 기다리는 60초 구간이 지난 뒤 봉인되므로, 가장 최근에 마감된 분은 아직 대기 중일 수 있습니다. 계속하기는 원래 구간과 커서를 유지합니다. 경계값은 정확한 요청 합계가 아니라 표본으로 수집한 경로 접두사를 나타냅니다. 페이지는 부분 스캔, 잘림, 보존 경계, 보고된 큐 손실을 보여 줍니다. 누락된 아카이브로 트래픽이 0이었다거나 범위가 완전하다고 결론 낼 수는 없습니다.
보안 화면은 최근 24시간을 먼저 보여 주며, 선택한 기간을 같은 길이의 시간 구간 60개로 나눕니다. 집계는 작업량 상한 안에서 저장소 스레드가 실행합니다. SQLite에서 상한은 가상 머신 단계 --console-query-steps개입니다(100,000에서 50,000,000까지, 기본값 400만). --console과 함께 설정하세요. 잘못되었거나 반복된 값은 거부됩니다. PostgreSQL에서 상한은 읽기 트랜잭션 안에서 설정하는 2,000 ms의 문장 타임아웃입니다(SID 0013). --console-query-steps를 바꿔도 이 값은 바뀌지 않습니다. 상한을 다 쓴 질의는 더 좁은 기간을 고르라고 안내합니다. 단계 수는 질의 작업량을 제한할 뿐 경과 시간을 제한하지는 않습니다. 차트는 같은 눈금을 공유합니다. 추세 값을 펼치면 UTC 구간 시작 시각과 정확한 그룹별 수를 볼 수 있습니다. 이 값은 보존된 탐지 결과이므로, 인시던트 범위가 빠져 있다고 해서 공격이 없었다고 해석할 수는 없습니다.
벽면 디스플레이는 키오스크 세션을 사용합니다. 운영자는 계정 화면에서 디스플레이 이름을 정하고 디스플레이 코드 만들기를 선택합니다. 디스플레이는 10분 안에 일회용 코드를 로그인 양식에 붙여 넣습니다. 그 세션은 읽기 전용이고, 통계로만 제한되며, 12시간 안에 만료됩니다. 계정 페이지는 다른 화면으로 이동하거나 페이지가 숨겨지면 표시된 코드를 지웁니다. 숨겨도 사용하지 않은 권한이 취소되지는 않으며, 교환 기한은 그대로 적용됩니다. 코드는 URL에 넣으면 안 됩니다. 디스플레이는 트래픽과 보안 화면을 보여 줍니다. 보안 화면은 인시던트 주소나 페이로드 증거 없이 모듈별 집계 추세와 요청 결과만 보여 줍니다. 자동 순환은 선택 사항이며, 처음에는 꺼져 있고, 동작 줄이기 설정, 오래된 데이터, 일시 정지 중에는 멈춥니다.
알림 대상(거부 급증, 차단, 연결할 수 없는 구성원, 리더 변경에 대한 서명된 웹훅과 syslog)은 설정 아래에 있습니다. 웹훅 비밀 값에는 --console-key-file이 필요합니다. 리더 변경 종류는 저장된 대상의 의미가 유지되도록 정의된 채로 남아 있지만, 리더 선출이 없으므로 어느 노드도 이 알림을 내지 않습니다. 대상마다 자체 쿨다운과 3회 재시도 예산이 있습니다. 전달 감사 기록은 결과를 보여 줍니다. 완료된 큐 기록은 7일과 이벤트 4,096개로 제한됩니다. 웹훅에는 안정적인 Idempotency-Key가 포함되어 있어, 네트워크 완료 여부가 불확실할 때 수신자가 반복된 효과를 억제할 수 있습니다. 웹훅은 HTTPS로 보내며, 평문 HTTP는 리터럴 루프백 주소로만 보냅니다. 응답 본문은 64 KiB까지 읽습니다. syslog의 UDP/TCP 선택은 나가는 알림에만 적용되며, 보호되는 웹 트래픽과는 관계없습니다. 수동 테스트는 의도와 완료를 감사 기록에 남기고 대상 결과를 갱신합니다. 감사 완료가 확인되지 않으면 운영자가 재시도하기 전에 그 사실을 명시적으로 보여 줍니다.
설정에서는 보존 기간도 제어합니다. 분 단위 기록은 1일에서 90일, 순위는 1일에서 7일, 인시던트는 1일에서 30일, 감사 기록은 1일에서 365일입니다. 기본값은 각 최댓값이며, 순위는 512 MiB 할당량을 유지합니다. 정리 작업이 오래된 기록을 제한된 묶음 단위로 영구 삭제하므로, 보존 값을 저장하려면 확인이 필요합니다. 나중에 값을 늘려도 삭제된 기록은 복원되지 않습니다. 오래된 편집은 거부되며, 성공한 변경은 감사 기록에 나타납니다.
응답 페이지(챌린지, 거부, 속도 제한, 차단, 과부하)는 설정에서 고정된 자리 표시자를 쓰는 크기 제한 HTML로 편집할 수 있습니다. 초안은 샌드박스 탭에서 미리 보며, 저장된 페이지는 다음 정책 스냅숏부터 제공됩니다.
정책 페이지의 정책 작업: 관리 규칙의 순서를 바꾸고, 보존된 검사 탐지 결과에 초안을 재생해 보고, 활성 GeoIP 세대에 고정된 IP 그룹과 국가 차단을 관리하고, 관리 규칙 집합을 내보내거나 원자적으로 가져옵니다(sibuna console policies export와 sibuna console policies import --file <set.json>도 사용 가능). 가져오기는 요청 하나로, 각각 최대 4 KiB이고 합계 최대 256 KiB인 문서 1개에서 128개를 담습니다. 약 96 KiB를 넘는 집합에 대해서는 페이지의 안내문이 명령줄 가져오기를 알려 줍니다. 적용된 규칙에는 오늘 기록된 적중 수, 시간별 스파크라인, 접근성을 갖춘 표가 표시됩니다. 적중이란 선언형 매처 평가가 성공한 것을 말합니다. 일치한 WEIGH 규칙과 첫 번째 종결 일치가 집계됩니다. 그보다 앞선 검사 또는 평판 결정이 평가를 막을 수도 있습니다. 비공개 테스트는 이 카운터를 늘리지 않습니다. 규칙 적중 비교는 기록된 노드 하나에 대해 마감된 기간 두 개를 고정합니다. 리비전 기록에는 이 편집 전후 적중 비교가 있으며, 편집이 일어난 분을 제외하고 선택한 길이까지 같은 길이의 사용 가능한 기간을 사용합니다. 선택적인 적용 리비전 필터는 관련 없는 세대를 비교에서 제외합니다. 시작, 전환, 누락된 쓰기, 보존 정리는 범위에 눈에 보이는 공백을 남깁니다. 백분율은 양쪽 모두 범위가 완전해야 합니다. 규칙 관측과 시간별/일별 요약은 분 단위 보존 설정을 따릅니다. 편집 전후에 관측된 변화는 비교일 뿐, 그 편집이 트래픽 변화를 일으켰다는 증거가 아닙니다.
더 새로운 GeoIP 세대를 가져와도 국가에서 도출한 기존 평판 행이 자동으로 갱신되지는 않습니다. 국가 동작을 미리 보며 추가, 유지, 제거되는 접두사를 비교하세요. 적용하기 전에 검토한 차이를 페이지 단위로 넘겨 보세요. 교체는 해당 국가가 소유한 더 이상 유효하지 않은 행을 제거하고, 독립적으로 관리되는 접두사는 유지합니다. 세대나 정책 리비전이 바뀌면 미리보기를 새로 해야 하며, 겹치는 독립 편집은 거부됩니다. 이벤트 페이지에는 보존된 WAF 탐지 결과와 허니팟 인시던트가 있습니다. 완전한 접근 로그는 아닙니다. GeoIP를 불러온 상태라면 저장소 스레드가 인시던트 묶음의 트랜잭션 안에서 각 인시던트의 국가와 세대를 기록합니다. 이는 영속 저장 시점의 귀속이지, 요청 시점의 위치를 재구성한 것이 아닙니다. 이후의 가져오기는 기록된 매핑을 바꾸지 않습니다. 국가 필터는 대문자 두 글자 코드, 불러온 세대에 없는 주소를 뜻하는 unknown, 매핑 데이터가 없는 인시던트를 뜻하는 not_recorded를 받습니다. 소스 그룹은 국가가 섞여 있거나 범위가 불완전하면 그렇다고 명시적으로 보고합니다. 지구본의 이벤트 보기 동작은 선택한 노드를 유지한 채 해당 국가의 최근 1시간 보존 인시던트를 엽니다. 통계 페이지의 보안 화면은 실시간 속도 제한, 챌린지, 차단 비율을 1시간, 1일, 7일, 30일 동안의 보존된 검사 및 허니팟 탐지 결과와 함께 보여 줍니다. 범주, 소스, 경로 링크는 같은 노드와 고정된 시간 경계로 일반 인시던트 작업 화면을 엽니다. 인시던트 필터를 적용하면 새 기간이 시작됩니다. 탐지 결과에는 감사 기록이 포함되며, 차단된 요청 합계와는 다릅니다. 평판과 규칙 적중 귀속이 없으면 기록되지 않음으로 표시됩니다. 이벤트와 감사 필터는 라벨을 해당 컨트롤과 함께 두고, 적용 동작을 따로 정렬하며, 사용 가능한 콘텐츠 너비에 맞춰 열을 조정합니다. 인증된 WebSocket 하나가 화면 이동 후에도 유지되며 통계, 인시던트 요약, 노드 상태, 정책 리비전, 챌린지, 감사 요약을 전달합니다. 새 인시던트와 감사 기록은 최신 기록 불러오기 뒤에서 기다리므로, 표를 읽는 동안 표가 제자리에 머뭅니다. 정책 업데이트는 열려 있는 초안을 대체하지 않고 현재 커밋된 리비전과 적용된 리비전을 보여 줍니다. 흐름 카운터는 실시간으로 갱신됩니다. 기본값이 아닌 챌린지 시간 구분을 선택했다면 명시적으로 새로 고치세요. 과거 기록 질의, 상세 읽기, 변경 작업은 계속 HTTP 요청으로 처리합니다.
페이지 조각은 북마크할 수 있으며, 뒤로 가기와 앞으로 가기는 인증된 페이지를 다시 엽니다. 사이드바는 이 브라우저에서 테마와 간격 선택도 기억하며, 기본 테마는 시스템입니다. SID 0007은 Committed 상태입니다. 콘솔은 골든 픽스처와 헤드리스 Chromium의 브라우저 작업 흐름 테스트를 통과합니다(cargo xtask browser console, SID 0010 기준 5). 종단 간 테스트 모음은 cmd/sibuna/tests/console_*.rs이며, 그 PostgreSQL 클러스터 시나리오는 SIBUNA_TEST_DATABASE_URL을 설정했을 때 실행됩니다. SID 0010은 콘솔을 컴파일해 넣고 비활성화했을 때, 저장소만 켰을 때, 활성화했지만 유휴 상태일 때 모두 16개 제품 워크로드가 콘솔 없이 빌드한 데몬의 약 1% 이내, 즉 잡음 범위 안에 머문다고 기록합니다. 부하 상태에서 대시보드 8개를 활성화하는 SID 0007의 공식 격리 기준은 아직 측정하지 않았습니다(제VIII부). 전체 WebAssembly 애플리케이션에는 압축하지 않은 크기 기준 768 KiB 상한이 있으며, 데몬의 빌드 스크립트가 빌드를 실패시켜 이를 강제합니다. 검토 임계값은 640 KiB입니다. 1.0.0-beta.3에서 모듈 크기는 724,330바이트(gzip 압축 272,568바이트)로 검토 임계값을 넘으며, SID 0007은 이를 검토 대상으로 기록합니다. 이 프로젝트 제한은 콘솔 작업 흐름을 위한 여유를 남겨 둘 뿐, 브라우저 로딩과 응답성 측정을 대신하지는 않습니다. 모듈의 선형 메모리는 필요할 때 선언된 최대 16 MiB까지 늘어납니다.
배포 토폴로지¶
리버스 프록시¶
sibuna --port 80 --upstream-host 127.0.0.1 --upstream-port 3000 \
--secret-file /etc/sibuna/secret --difficulty 16 --algorithm posw
허용된 요청은 X-Forwarded-For, X-Forwarded-Proto, X-Real-IP, X-Sibuna-Status, X-Sibuna-Rule 헤더와 함께 원본 서버에 도달합니다. 홉별 헤더, Sibuna가 직접 쓰는 필드, 대체 전달 필드(Forwarded, X-Forwarded-Host, X-Forwarded-Port)는 제거되며, 클라이언트가 이름을 밑줄로 쓴 경우(X_Forwarded_For)에도 제거됩니다. X-Real-IP는 요청을 판정할 때 사용한 클라이언트입니다. X-Forwarded-For는 소켓 피어만 담으며, 클라이언트가 쓴 항목은 절대 담지 않습니다. 전달된 신원을 신뢰하는 경우에는 받은 체인 뒤에 소켓 피어를 붙인 값입니다. 따라서 원본 서버는 클라이언트를 X-Real-IP나 X-Forwarded-For의 오른쪽에서 읽어야 하며, 가장 왼쪽 항목에서 읽으면 안 됩니다. 원본 서버가 받는 경로는 정책이 판정한 정규형입니다(SID 0009). 정규형이 없는 경로에는 400으로 응답합니다.
HTTP/1.1 WebSocket 업그레이드는 원본 서버의 핸드셰이크를 받아들이기 전에 요청 허용과 정책 검사를 거칩니다. 하위 프로토콜과 확장 협상은 종단 간에 그대로 유지됩니다. 스레드 두 개가 방향마다 하나씩, 각각 고정 버퍼 하나로 미리 읽은 바이트와 반쪽 닫기까지 포함해 바이트를 중계합니다. 따라서 업그레이드된 연결은 스레드 두 개를 차지하며, 모든 연결이 업그레이드되면 연결 스레드 수가 --max-connections의 두 배까지 늘 수 있습니다. 업그레이드된 소켓은 일반 연결 할당량과 종료 레지스트리 안에 남지만, HTTP 유휴 기한과 별개로 --websocket-idle-timeout (기본값 300초)을 사용합니다. 어느 방향의 트래픽이든 이 기한을 갱신하지만, 기간 내내 한 바이트도 받지 않는 피어는 반대 방향이 아무리 바빠도 중계를 끝냅니다. 핸드셰이크 이후의 프레임은 WAF 검사 입력이 아닙니다. HTTPS/WSS는 Sibuna의 비공개 HTTP/1.1 리스너 앞에서 TLS를 종료하는 인그레스를 사용합니다. Sibuna는 브라우저 TLS를 직접 종료하지 않습니다.
인그레스는 브라우저와 HTTP/2를 협상하고 Sibuna에는 HTTP/1.1로 전달할 수 있습니다. Sibuna의 네이티브 HTTP/2 지원은 이후 업데이트로 미뤄졌습니다. 이 구성은 네이티브 gRPC 같은 애플리케이션에 종단 간 HTTP/2 의미론을 제공하지 않습니다.
Content-Length 요청 본문은 바이트와 MIME 헤더를 보존하며 고정 버퍼를 거쳐 스트리밍됩니다. 멀티파트 업로드는 경계, 반복된 필드 이름, 파일 이름, 파트 유형을 유지합니다. WAF는 본문의 처음 8 KiB까지만 검사합니다. 멀티파트 메타데이터와 파일이 아닌 필드는 텍스트 검사 입력으로 남고, 파일 페이로드는 불투명하게 취급됩니다. filename이 비어 있는 파트는 일반 필드입니다. 인식된 바이너리 최상위 MIME 유형(SVG를 제외한 이미지, 오디오, 비디오, PDF, ZIP, gzip, 7z, protobuf, octet-stream)의 본문은 접두사도 바이너리처럼 보일 때만 불투명하게 취급합니다. 즉 16바이트 중 적어도 1바이트가 탭, 줄 바꿈, 수직 탭, 폼 피드, 캐리지 리턴이 아닌 제어 바이트여야 합니다. 그렇지 않으면 텍스트로 검사합니다(SID 0004). JSON, XML, SVG, URL 인코딩 양식, 알 수 없는 유형은 텍스트 검사를 유지합니다. 모호하거나 형식이 잘못된 MIME 메타데이터는 텍스트 검사로 돌아갑니다. 멀티파트 파싱은 같은 접두사 안에서 파트 32개와 파트당 헤더 2 KiB로 제한되며, 구분자 뒤의 RFC 2046 전송 패딩을 허용합니다.
이는 업로드 호환성일 뿐, 파일 검증이나 악성 코드 검사가 아닙니다. 백엔드는 클라이언트의 Content-Type 선언을 믿지 말고 허용하는 미디어 유형을 직접 강제해야 합니다. 검사 접두사 뒤의 필드는 큰 업로드 파일 뒤에 오는 필드를 포함해 검사하지 않습니다. 압축된 페이로드는 검사를 위해 압축을 풀지 않습니다. 업로드도 요청 허용, 경로, 쿼리, 헤더 검사를 거치며 연결 기한의 적용을 받습니다. 청크 요청 본문은 검사 전에 연결 버퍼 안에서 디코딩됩니다(SID 0009). 버퍼 안에서 끝나는 본문은 Content-Length와 함께 백엔드에 도달합니다. 더 긴 본문은 Sibuna가 읽을 때마다 청크 하나로 다시 청크 인코딩하므로, 백엔드는 클라이언트의 청크 크기, 확장, 트레일러를 보지 못합니다. 단독 CR 또는 LF가 있거나, 크기 주변에 공백이 있거나, 확장의 형식이 잘못되었거나, 4 KiB를 넘는 청크 줄은 400으로 거부됩니다. 16 KiB를 넘는 트레일러 섹션도 마찬가지입니다. 다른 코딩을 쓰는 Transfer-Encoding은 501을 받습니다. 청크 요청을 파싱할 수 없는 백엔드도 약 44 KiB 미만의 본문은 Content-Length로 받습니다. 요청 본문을 전달한 원본 서버 연결은 그 교환이 끝나면 닫히며 풀로 돌아가지 않습니다. 100-continue를 기다리는 클라이언트는 본문을 보내기 전에 로컬에서 이를 받습니다. 지원하지 않는 Expect 값은 417을 받습니다. Expect 헤더는 백엔드로 전달하기 전에 소비됩니다.
인그레스 뒤의 forward-auth¶
--mode forward_auth에서 데몬은 인그레스의 하위 요청에 200 (감사 헤더 X-Sibuna-Status, X-Sibuna-Rule, X-Sibuna-Rule-Hash 포함), 챌린지에는 401, 거부에는 403, 속도 제한에는 429로 응답합니다. 인그레스는 클라이언트 주소와 원래 URL을 전달해야 하며, forward-auth 모드는 기본적으로 이를 신뢰합니다. 인그레스만 연결할 수 있도록 이 리스너를 비공개로 바인딩하세요. X-Forwarded-Uri (Caddy) 또는 X-Original-URI (Nginx)와 X-Forwarded-Method는 정책 평가를 위해 애플리케이션 요청을 복원합니다. 원래 경로는 요청 줄의 경로와 마찬가지로 정규형으로 바뀝니다. 원래 URL 필드가 중복되거나 충돌하는 경우, 그리고 원래 URI가 origin-form이 아닌 경우에는 400으로 거부합니다. 데몬 내부 경로는 항상 실제 요청 URI를 사용합니다. forward-auth는 인그레스가 생략한 본문을 검사하지 않습니다.
map $http_upgrade $sibuna_connection_upgrade {
default upgrade;
'' close;
}
server {
listen 443 ssl;
location / {
auth_request /__sibuna_auth;
auth_request_set $sibuna_auth_status $upstream_status;
auth_request_set $sibuna_retry_after $upstream_http_retry_after;
auth_request_set $sibuna_status $upstream_http_x_sibuna_status;
auth_request_set $sibuna_rule $upstream_http_x_sibuna_rule;
auth_request_set $sibuna_rule_hash $upstream_http_x_sibuna_rule_hash;
error_page 401 = @sibuna_challenge;
error_page 500 = @sibuna_auth_error;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $sibuna_connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Sibuna-Status $sibuna_status;
proxy_set_header X-Sibuna-Rule $sibuna_rule;
proxy_set_header X-Sibuna-Rule-Hash $sibuna_rule_hash;
proxy_read_timeout 300s;
proxy_pass http://127.0.0.1:3000;
}
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Uri "";
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header User-Agent $http_user_agent;
proxy_set_header Cookie $http_cookie;
}
location @sibuna_challenge {
rewrite ^ /__sibuna/challenge break;
proxy_pass http://127.0.0.1:8080;
proxy_pass_request_body off;
proxy_set_header Content-Length "";
proxy_set_header X-Original-URI $request_uri;
proxy_set_header X-Forwarded-Method $request_method;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
location @sibuna_auth_error {
add_header Retry-After $sibuna_retry_after always;
if ($sibuna_auth_status = 429) { return 429; }
return 503;
}
location /__sibuna/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
example.com {
handle /__sibuna/* {
reverse_proxy localhost:8080
}
handle {
forward_auth localhost:8080 {
uri /
header_up X-Forwarded-For {remote_host}
header_up -X-Original-URI
copy_headers X-Sibuna-Status X-Sibuna-Rule X-Sibuna-Rule-Hash
}
reverse_proxy localhost:3000
}
}
/__sibuna/* 네임스페이스(중간 페이지, 챌린지, 검증, 솔버 리소스)는 두 구성 예 모두에서 데몬에 직접 도달해야 합니다. nginx 오류 페이지는 원래 URI와 메서드를 전달하므로, 중간 페이지는 권한 부여 결정이 정한 요구 수준을 그대로 담습니다. 이 값이 없어도 페이지는 동작하며, 이때 발급은 브라우저가 보고한 URL을 평가하는 방식으로 대체됩니다. Caddy는 원래 URI/메서드 메타데이터를 스스로 제공합니다. 배타적인 handle 블록은 챌린지와 검증 경로가 forward-auth 사전 검사에 들어가지 않도록 합니다. Nginx에서 애플리케이션 WebSocket을 쓰려면 위에 보인 명시적인 Upgrade/Connection 헤더가 필요합니다. Nginx 오류 처리기는 두 번째 권한 부여 결정을 내리거나 업로드 본문을 소비하지 않고 내부 챌린지 경로를 렌더링합니다. Nginx의 auth 모듈은 2xx, 401, 403만 직접 받으므로, 예제는 속도 제한된 auth 오류를 Retry-After와 함께 429로 다시 바꿉니다. 그 밖의 권한 부여 실패는 계속 503으로 막습니다. Nginx는 자체 403 본문을 제공하는 반면, Caddy는 Sibuna의 거부 페이지를 전달합니다. 두 구성 예 모두 들어오는 Sibuna 감사 헤더를 실제 권한 부여 응답으로 교체합니다. 일반 TLS 인증서와 애플리케이션 업로드/기한 제한은 인그레스에서 설정하세요. 예제는 라우팅 논리를 보여 줍니다. 저장소는 아직 이 구성 예를 실제 인그레스에서 테스트하지 않습니다. 구성 예가 의존하는 전달 메타데이터 규칙은 sibuna-http의 단위 테스트가 다룹니다.
인그레스에서 받는 JA4 지문¶
JA4 지문은 클라이언트가 TLS 연결을 여는 방식을 요약합니다. 이 지문은 클라이언트의 첫 핸드셰이크 메시지인 ClientHello에서 계산합니다. 클라이언트의 TLS 라이브러리는 HTTP 바이트를 하나라도 보내기 전에 이 메시지를 확정하므로, 클라이언트는 HTTP 요청 안에서 자신의 지문을 바꿀 수 없습니다. 브라우저, 라이브러리, 봇은 이 지문이 서로 다릅니다. 그래서 JA4는 어떤 클라이언트든 마음대로 쓸 수 있는 User-Agent 값보다 강한 신호입니다(SID 0014). JA4는 FoxIO가 정의했습니다. 지문은 36문자이며, _로 이어진 세 부분으로 이루어집니다.
t13d1516h2_8daaf6152771_02713d6af862
^^^^^^^^^^ ^^^^^^^^^^^^ ^^^^^^^^^^^^
a b c
a 프로토콜(t는 TCP, q는 QUIC, d는 DTLS), TLS 버전(13은 TLS 1.3),
SNI가 있으면 d, 없으면 i, 암호 스위트 개수(두 자리),
확장 개수(두 자리), ALPN 코드(h2는 HTTP/2)
b 정렬한 암호 스위트의 12자리 소문자 16진수 해시
c 정렬한 확장과 서명 알고리즘의
12자리 소문자 16진수 해시
TLS를 종료하는 구성 요소만 ClientHello를 보므로, JA4를 계산할 수 있는 것도 그 구성 요소뿐입니다. Sibuna는 TLS를 종료하지 않습니다. Sibuna는 인그레스 뒤에서 평문 HTTP/1.1로 서비스하고, 브라우저와 TLS, HTTP/2, HTTP/3로 통신하는 것은 인그레스입니다. 여러 인그레스가 이미 JA4를 계산합니다. 그래서 우리는 인그레스가 지문을 계산해 요청 헤더로 보내게 하고, Sibuna는 그 헤더에서 지문을 읽습니다.
--ja4-header <name>은 그 헤더의 이름을 지정합니다. 이 옵션은 기본적으로 꺼져 있고 기본 이름도 없습니다. 우리는 항상 인그레스가 쓰는 헤더 이름을 지정합니다. Sibuna는 이름을 소문자로 저장하고 대소문자를 구별하지 않고 비교합니다. Sibuna가 직접 쓰거나 제거하는 필드의 이름(X-Forwarded-*, X-Real-IP, X-Sibuna-*, Forwarded, 그리고 - 대신 _를 쓴 형태)은 거부합니다. 옵션을 지정하면 시작 배너에 JA4: from cf-ja4 (trusted) 같은 줄이 출력됩니다.
헤더는 전달된 필드를 신뢰할 때만 읽습니다. 이는 X-Forwarded-For에 적용되는 것과 같은 결정으로, --trust-forwarded를 지정하거나 --no-trust-forwarded 없이 forward-auth 모드를 쓰는 경우입니다. 신뢰하지 않는 피어에서 온 헤더는 무시합니다. 신뢰할 때는 그 이름의 필드가 정확히 하나 있고 그 값이 JA4 형식이면 요청에 지문이 있는 것으로 봅니다. 값의 형식이 잘못되었거나 필드가 반복되면 요청에는 지문이 없습니다. 카운터 두 개가 이를 관찰합니다. sibuna_ja4_present_total은 지문이 있는 요청을 세고, sibuna_ja4_invalid_total은 헤더 형식이 잘못되었거나 반복된 요청을 셉니다. 신뢰하지 않는 피어의 요청은 어느 카운터도 올리지 않습니다.
리버스 프록시 모드에서는 Sibuna가 헤더를 신뢰할 때만 원본 서버가 그 헤더를 봅니다. 신뢰하지 않으면 Sibuna는 원본 서버로 보내는 요청에서 그 이름의 필드를 모두 제거하며, 클라이언트가 이름에서 - 대신 _를 쓴 경우에도 제거합니다. 따라서 클라이언트는 그 이름으로 위조한 지문을 원본 서버에 넘길 수 없습니다. 신뢰할 때는 필드가 정확한 표기 그대로 바뀌지 않고 전달되며, _를 쓴 별칭은 여전히 제거됩니다. --ja4-header가 없으면 그 이름의 필드는 평범한 필드입니다.
Cloudflare. 관리형 변환 "Add bot protection headers"는 원본 서버로 보내는 요청에 cf-bot-score, cf-verified-bot, cf-ja3-hash와 함께 cf-ja4를 추가합니다. 이 기능에는 Bot Management가 포함된 Enterprise 요금제가 필요합니다. Cloudflare와 Sibuna 사이의 인그레스는 이 필드를 바꾸지 않고 그대로 전달해야 합니다. 다음 명령으로 Sibuna를 시작합니다.
sibuna --ja4-header cf-ja4 --trust-forwarded -s /etc/sibuna/secret
Sibuna 앞의 인그레스는 Cloudflare의 주소에서 오는 연결만 받아들여야 합니다. 그렇지 않으면 클라이언트가 Cloudflare를 우회해 자신의 cf-ja4를 보낼 수 있습니다.
nginx. FoxIO의 ja4-nginx-module은 nginx 안에서 JA4를 계산해 $http_ssl_ja4로 노출합니다. 이 모듈에는 모듈의 ClientHello 캡처 패치를 적용하고 --with-http_ssl_module로 빌드한 nginx 1.26 이상이 필요합니다. proxy_set_header는 클라이언트가 보낸 같은 이름의 필드를 대체하므로, Sibuna에 도달하는 각 location이 헤더를 직접 설정합니다.
# 리버스 프록시: Sibuna는 --ja4-header x-ja4 --trust-forwarded로 실행
location / {
proxy_set_header X-JA4 $http_ssl_ja4;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_pass http://127.0.0.1:8080;
}
# forward-auth: Sibuna는 --mode forward_auth --ja4-header x-ja4로 실행
location = /__sibuna_auth {
internal;
proxy_pass http://127.0.0.1:8080/;
proxy_set_header X-JA4 $http_ssl_ja4;
# ... 위 forward-auth 구성 예의 나머지 필드
}
forward-auth 구성 예에서는 같은 proxy_set_header X-JA4 $http_ssl_ja4; 줄이 @sibuna_challenge와 location /__sibuna/에도 들어가야 합니다. 이 줄을 빠뜨린 location은 클라이언트가 보낸 X-JA4를 그대로 Sibuna에 넘기고, Sibuna는 그 값을 신뢰합니다.
Apache Traffic Server. ja4_fingerprint 플러그인은 plugin.config의 ja4_fingerprint.so 줄로 활성화합니다. 이 플러그인에는 옵션이 없습니다. 플러그인은 각 TLS 연결의 요청에 지문을 담은 ja4 필드와 프록시 이름을 담은 x-ja4-via 필드를 추가합니다. Sibuna는 --ja4-header ja4 --trust-forwarded로 시작합니다. 플러그인 문서는 클라이언트가 보낸 ja4 필드를 플러그인이 대체하는지 밝히지 않습니다. 값을 신뢰하기 전에, 우리가 쓰는 버전에서 이를 확인하거나 플러그인이 자기 필드를 추가하기 전에 클라이언트의 필드를 제거해야 합니다.
규칙은 ja4 필드로 지문을 비교합니다(제X부, 정책 스키마). 값은 정확히 같아야 하는 전체 지문이거나, 지문이 그것으로 시작해야 하는 접두사 뒤에 *를 붙인 것입니다. "*" 하나만 쓰면 모든 지문과 일치합니다. 지문이 없는 요청은 ja4 규칙과 절대 일치하지 않습니다. 로더는 대문자로 쓴 T13D*처럼 어떤 지문과도 일치할 수 없는 패턴을 INVALID POLICY JA4로 거부합니다. 비교는 바이트 단위로 이루어지며 메모리를 할당하지 않습니다.
{ "rules": [
{ "name": "deny-known-scanner", "action": "DENY",
"ja4": "t13i010400_0f2cb44170f4_5c4c70b73fa0" },
{ "name": "weigh-no-sni", "ja4": "t13i*", "action": "WEIGH", "weight": 15 },
{ "name": "weigh-headless", "user_agent": "Headless", "action": "WEIGH",
"weight": 30 },
{ "name": "challenge-tls12-checkout", "path": "/checkout/*", "ja4": "t12*",
"action": "CHALLENGE" }
] }
첫 번째 규칙은 지문 하나를 정확히 일치시켜 거부합니다. 이 값은 예시일 뿐 알려진 스캐너가 아닙니다. 다음 두 규칙은 결정하는 대신 요청의 점수에 가중치를 더합니다. 하나는 서버 이름을 보내지 않은 TLS 1.3 클라이언트이고, 다른 하나는 User-Agent로 알아본 헤드리스 브라우저입니다. 뒤의 규칙이 먼저 결정하지 않으면, 두 신호를 모두 보이는 요청은 점수가 45가 되어 기본 거부 임계값 40에 도달하고, 하나만 보이는 요청은 챌린지를 받습니다. 마지막 규칙은 결제 경로에서 TCP에서 TLS 1.2를 협상한 모든 클라이언트에게 접두사로 챌린지를 요구합니다. 정당한 오래된 클라이언트 상당수가 아직 TLS 1.2를 쓰므로 거부하지 않고 챌린지를 요구합니다. 규칙은 이렇게 JA4를 다른 신호와 함께 써야 합니다. JA4 값은 사람이나 기기가 아니라 TLS 라이브러리와 그 설정을 가리킵니다. 많은 클라이언트가 하나의 라이브러리를 공유하며, 특수한 라이브러리는 브라우저의 ClientHello를 흉내 낼 수 있습니다. JA4는 자동화의 비용을 높일 뿐 신원을 증명하지 않습니다. 같은 이유로 Sibuna는 차단과 평판을 지문이 아니라 항상 주소를 키로 관리합니다.
인시던트(WAF 거부, 허니팟 적중, 감사 탐지 결과)는 요청에 지문이 있었으면 그 지문을 security_incidents.ja4 열에 기록합니다. 콘솔은 인시던트 증거에서 이를 "JA4 fingerprint"로 표시하며, 값이나 "Not recorded"를 보여 줍니다. 이벤트 필터는 지문이나 접두사를 받습니다. 관리 규칙 편집기에는 policies.ja4_pattern에 저장되는 JA4 필드가 있고, 정책 테스트 양식은 지문을 입력받습니다.
선언형 정책¶
{
"default_action": "CHALLENGE",
"waf": true,
"thresholds": { "challenge_at": 10, "deny_at": 40, "bits_step": 5 },
"ip_rules": { "10.0.0.0/8": "ALLOW", "192.0.2.0/24": "DENY", "2001:db8::/32": "DENY" },
"rules": [
{ "name": "deny-cf-workers", "headers": { "CF-Worker": ".*" }, "action": "DENY" },
{ "name": "deny-amazonbot", "user_agent": "Amazonbot", "action": "DENY" },
{ "name": "api-with-key", "path": "/api/*", "headers": { "X-Api-Key": ".*" },
"action": "ALLOW" },
{ "name": "protect-checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": { "difficulty": 20, "algorithm": "posw" } },
{ "name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30 },
{ "name": "internal-vpc", "remote_addresses": ["10.0.0.0/8", "fd00::/8"],
"action": "ALLOW" }
]
}
로더는 오류가 하나라도 있으면 아무것도 받아들이지 않습니다(fail closed). 알 수 없는 키, 철자가 틀린 동작, 형식이 잘못된 주소, 범위를 벗어난 숫자가 하나라도 있으면 파일 전체를 거부하고, 진단 메시지가 해당 규칙과 필드를 알려 주며, 데몬은 시작하지 않습니다. 알 수 없는 옵션이나 범위를 벗어난 값이 있는 명령줄도 같은 방식으로 거부됩니다. rules가 있으면 내장 테이블을 대체합니다. ip_rules는 수천 개의 접두사까지 확장되는 평판 트라이에 들어갑니다. waf: false는 파일에서 Gate 운영 구성을 선택합니다. 스키마에는 두 가지 키가 더 있습니다(제X부). inspection은 WAF 범주마다 disabled, audit, enforce 중 하나를 설정하고, 규칙의 limits 객체는 그 규칙에 자체 할당량을 줍니다. 규칙의 ja4 필드는 신뢰할 수 있는 인그레스가 전달한 JA4 지문과 정확히, 또는 *를 붙인 접두사로 일치시킵니다. 이 필드에는 --ja4-header가 필요합니다("인그레스에서 받는 JA4 지문" 참조). 경로 패턴은 정규형의 요청 경로와 일치시키므로(SID 0003), 패턴도 그 형식으로 써야 합니다.
영속 저장소와 클러스터¶
--data-dir /var/lib/sibuna는 SQLite 파일 /var/lib/sibuna/sibuna.db (WAL 모드, synchronous=NORMAL, busy 타임아웃)를 열고 저장소 스레드를 시작합니다. --database-url (또는 --database-url-file)은 대신 PostgreSQL 데이터베이스에 연결합니다. 저장소 스레드는 단일 스레드 tokio 런타임과 작은 연결 풀을 소유하며, SQL을 실행하는 유일한 곳입니다. 시작할 때, 정책 리비전이 바뀔 때마다(policies, ip_reputation, policy_inspection에 쓰기가 일어날 때), 그리고 평판 항목이 만료될 때, 이 스레드는 정책 파일과 데이터베이스로 엔진을 다시 만들어 게시합니다. 요청은 SQL을 기다리지 않습니다. 재구성은 로드 전후에 리비전을 읽고, 그 사이에 쓰기 작업이 커밋되었으면 후보를 버립니다.
스키마¶
| 테이블 | 용도와 키 |
|---|---|
policy_revision |
정책 리비전, 한 행. 세 정책 테이블의 트리거가 이 값을 올립니다. |
policies |
순서가 있는 동적 규칙, 키는 id. null 허용 ja4_pattern은 규칙의 JA4 조건을 최대 37바이트로 담습니다. |
policy_inspection |
범주별로 저장된 WAF 모드, 한 행. |
ip_reputation |
점수, 적중 수, 만료, 키는 주소 또는 접두사. |
incident_receipts |
각 노드의 영속 인시던트 영수증(마지막으로 커밋된 묶음 다음의 시퀀스), 키는 노드. |
security_incidents |
64개 성분 임베딩(256바이트)을 포함한 제한된 크기의 이벤트 기록 하나, 키는 node_id << 40 | sequence. null 허용 ja4는 요청의 JA4 지문을 정확히 36바이트로 담습니다. |
incidents_fts |
SQLite에서는 경로와 페이로드의 정규 토큰에 대한 FTS5 테이블입니다. PostgreSQL에서는 같은 토큰을 security_incidents의 tsvector 열 search에 담고 GIN 인덱스를 둡니다. |
sibuna_schema |
적용된 모든 마이그레이션, 키는 구성 요소와 버전. |
핵심 스키마는 crates/storage/src/schema.rs이며, 방언마다 한 번씩 작성되어 있습니다. 콘솔이 있으면 구성 요소 console이 이름이 console_로 시작하는 테이블 33개를 추가합니다(SID 0013, crates/console-storage/src/schema/). 마이그레이션은 구성 요소마다 번호가 매겨져 바이너리에 컴파일됩니다. 핵심 마이그레이션 2는 JA4 열 두 개를 추가하며, 그 이전에 만든 데이터베이스는 시작할 때 마이그레이션됩니다. 대기 중인 마이그레이션은 모두 하나의 트랜잭션에서 실행되며, 노드는 어떤 구성 요소의 버전이 자신이 아는 것보다 새로운 데이터베이스를 거부합니다. 축약해 실은 스키마는 업그레이드 스크립트가 아닙니다. SQLite 테이블은 STRICT이고 CHECK 제약 조건이 Rust 타입을 그대로 반영하므로, 데몬이 표현할 수 없는 행은 데이터베이스가 거부합니다. 열거형 값은 소문자로 저장됩니다. 'DENY'를 직접 쓰면 거부됩니다.
운영 방법¶
sibuna.db에는 sqlite3 셸을 사용하고(WAL 모드 덕분에 데몬이 실행 중일 때도 읽을 수 있습니다), 클러스터 데이터베이스에는 psql을 사용하세요:
-- 동적 규칙을 추가합니다. 모든 노드가 다음 틱에 엔진을 다시 만듭니다.
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p-checkout', 'protect-checkout', 10, '/checkout/*', 'challenge', 20, 'posw',
'{"X-Api": "v2"}', '["10.0.0.0/8"]', 0, 1, unixepoch(), unixepoch());
-- 주소 하나를 클러스터 전체에서 하루 동안 차단합니다.
INSERT INTO ip_reputation (ip_or_cidr, reputation_score, banned_until,
trigger_rule, hits, last_seen)
VALUES ('198.51.100.7', -100, unixepoch() + 86400, 'analyst', 1, unixepoch());
-- 포렌식: 기록된 페이로드를 전문 검색합니다.
SELECT s.id, s.client_ip, s.violation_category, s.path, s.campaign_id
FROM incidents_fts f JOIN security_incidents s ON s.id = f.rowid
WHERE incidents_fts MATCH 'union' ORDER BY rank LIMIT 20;
이 문장들은 SQLite용으로 작성되었습니다. PostgreSQL에서는 enabled가 TRUE이고, 시간은 unixepoch() 대신 CAST(extract(epoch FROM now()) AS BIGINT)이며, 검색은 security_incidents에서 WHERE search @@ CAST('union' AS tsquery)로 읽습니다. path와 offending_payload는 원시 요청 바이트(BLOB 또는 BYTEA)를 담습니다. 제약 조건을 어기는 직접 쓰기는 데이터베이스가 거부하며 노드에 도달하지 않습니다. PostgreSQL에서는 리비전 트리거가 NOTIFY sibuna_policy도 발행하므로 다른 노드가 즉시 틱을 실행합니다. 보장은 여전히 폴링이 제공합니다.
점수가 \(-50\) 이하이면 트라이의 deny 접두사가 되고, \(50\) 이상이면 allow가 되며, banned_until은 차단 기간의 끝을 정합니다. 허니팟 적중은 \(-100\) 기록을 자동으로 삽입하므로, 공유 PostgreSQL 데이터베이스를 쓰면 한 노드에서 걸린 함정이 모든 노드에서 그 주소를 차단합니다.
트랜잭션 영수증으로 안전하게 재시도하기¶
저장소 스레드는 대기 중인 기록을 최대 32개까지 모아 SQL 트랜잭션 하나를 만듭니다. 이 트랜잭션은 인시던트를 삽입하고, 전문 검색 인덱스를 갱신하고, 허니팟 평판 변경을 적용합니다. 각 발급자(노드)에는 단조 증가하는 영수증, 즉 incident_receipts의 한 행이 있습니다. 데이터를 바꾸는 모든 문장은 이 영수증으로 보호됩니다. 트랜잭션은 영수증을 마지막에 올리며, 절대 되돌리지 않습니다.
커밋에 실패하면 대기 중인 묶음을 메모리에 유지하고 incident_write_failures를 늘립니다. 틱은 그래도 정책 폴링을 시도합니다. 기록 512개짜리 큐가 가득 차면 incidents_dropped를 셉니다. 디스크를 기다리느라 HTTP 응답을 막는 일은 없습니다. 대기 중인 묶음은 기록 32개만큼의 공간을 더합니다. 커밋 전에 프로세스가 죽으면 큐에 있던 데이터를 잃을 수 있습니다. 이는 크기가 제한된 비동기 포렌식 경로이지, 큐에 넣는 순간 영속성이 보장되는 메시지 큐가 아닙니다.
캠페인 군집화¶
각 인시던트 페이로드는 바이트 트라이그램(숫자와 대소문자는 하나로 정규화)에 해싱 트릭을 적용해 64차원 단위 벡터로 임베딩하고, security_incidents.embedding에 256바이트로 저장합니다. 저장소 스레드는 모든 노드의 가장 최근 임베딩 16,384개를 메모리(4 MiB)에 두고, 틱마다 데이터베이스에서 새로 고칩니다. 삽입하기 전에 같은 묶음의 앞선 기록을 포함해 그중 가장 가까운 것을 찾습니다. 코사인 거리가 \(0.35\) 이하이면 새 인시던트는 그 인시던트의 campaign_id에 합류하고, 그렇지 않으면 자신의 식별자를 이름으로 하는 캠페인을 시작합니다. 이 구간보다 오래된 인시던트는 비교하지 않습니다. 유사도는 휴리스틱입니다. 회귀 테스트 예제는 관련된 SQL 페이로드를 한 그룹으로 묶지만, 모든 공격 쌍이 같은 캠페인에 속한다고 보장하지는 않습니다. 실행되는 모델도 없고 학습하는 것도 없습니다.
클러스터¶
클러스터는 PostgreSQL 데이터베이스 하나를 공유하는 노드의 집합입니다. postgres-tls 기능으로 빌드하고(cargo build --release -p sibuna --features postgres-tls, postgres를 포함합니다), 각 구성원을 데이터베이스와 고유한 노드 id로 시작합니다:
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 \
--secret-file /etc/sibuna/secret
모든 구성원은 같은 마스터 비밀 값과 1에서 8,388,607 사이의 고유한 --cluster-node를 사용해야 합니다. URL 파일은 postgres:// URL 하나를 담으며 소유자만 읽을 수 있어야 합니다. 배너는 URL을 절대 출력하지 않습니다. 쓰기는 PostgreSQL 주 서버로 갑니다. 각 노드의 저장소 스레드는 커밋된 리비전 변경을 (NOTIFY 또는 폴링으로) 감지하고 엔진을 다시 만듭니다.
노드는 네트워크를 거쳐 공유 데이터베이스에 접근하므로 그 연결을 암호화하고 검증합니다. 서버에는 자체 인증 기관이 서명한 인증서를 주고, URL에 그 인증 기관을 지정합니다: postgres://sibuna:...@db.internal:5432/sibuna?sslmode=verify-full&sslrootcert=/etc/sibuna/db-ca.pem. 서버에서는 pg_hba.conf의 hostssl 줄로만 TCP를 받습니다.
데몬은 시작할 때 데이터베이스 연결에 관한 줄 하나를 출력합니다. verify-full이면 인증서와 호스트 이름이 검증되었다고 알립니다. 그보다 약한 모드이면 경고와 힌트를 출력합니다. sslmode가 없으면 모드는 prefer입니다. 이때 연결은 서버가 TLS를 제공할 때만 암호화되며, 서버는 검증되지 않습니다. postgres-tls 없이 빌드한 데몬은 require, verify-ca, verify-full을 거부하고 빠진 기능의 이름을 알려 줍니다. 평문 연결로 물러서는 일은 절대 없습니다. 인증서가 거부되면 시작이 즉시 멈추며, 힌트는 sslrootcert를 확인하고 URL의 호스트가 서버 인증서에 있는 이름인지 확인하라고 안내합니다. sslrootcert는 우리 인증 기관을 시스템 신뢰 저장소에 추가할 뿐, 시스템의 인증 기관을 제거하지는 않습니다(SID 0011, SID 0012).
Sibuna는 자체 데이터베이스를 복제하지 않으며 리더를 선출하지도 않습니다. 복제, 장애 조치, 백업은 PostgreSQL의 몫입니다(스트리밍 복제, Patroni 또는 관리형 서비스). 콘솔의 노드 화면에는 리더가 없습니다. SQLite 노드에는 역할 single, PostgreSQL 노드에는 unknown을 보여 주며, quorum은 노드의 마지막 데이터베이스 왕복이 성공했다는 뜻일 뿐입니다. 데이터베이스에 연결할 수 없으면 마지막으로 게시된 엔진이 계속 서비스하고, 인시던트는 크기가 제한된 링에 쌓였다가 가득 차면 카운터를 올리며 버려지고, 저장소 스레드는 백오프하며 재시도합니다. 노드는 다시 연결될 때까지 마지막 정책을 유지합니다. Zaxonlite 데이터 디렉터리(SID 0005)는 읽지 않습니다. 정책은 sibuna console policies export와 sibuna console policies import로 옮기며, 포렌식 기록은 이전되지 않습니다.
클러스터 챌린지 라우팅¶
챌린지 키는 --cluster-node에 묶여 있으므로, 챌린지 발급과 검증은 같은 구성원에서 처리하세요. 토큰은 공유 시드를 사용하므로 다른 구성원에서도 동작합니다. 로컬 속도 할당량이 전역 할당량이 되지는 않으며, 프로세스를 재시작하면 사용 완료 집합이 지워집니다. 로컬 PostgreSQL 하나에 노드 세 개를 둔 경우, 직접 쓴 정책 행은 틱 한 번 안에 세 노드 모두에 도달하고, 한 노드의 허니팟 차단이 다른 노드에도 도달하며, 인시던트 식별자는 절대 충돌하지 않습니다(crates/storage/tests/multi_node.rs, SID 0011 기준 2. SIBUNA_TEST_DATABASE_URL을 설정하면 실행됩니다).
패키징¶
GitHub의 모든 릴리스에는 플랫폼마다 같은 실행 파일이 들어 있습니다. 이 실행 파일은 릴리스 태그에서 기본 기능(SQLite 저장소와 콘솔)으로 빌드됩니다. PostgreSQL 클러스터에는 직접 빌드한 바이너리가 필요합니다(아래 참조).
| 플랫폼 | 릴리스 파일 |
|---|---|
| Linux x86-64, ARM64 | sibuna-linux-amd64.tar.gz와 sibuna-linux-arm64.tar.gz에는 어느 배포판에서나 실행되는 정적 musl 실행 파일이 들어 있습니다. sibuna_<version>-1_amd64.deb, sibuna_<version>-1_arm64.deb, sibuna-<version>-1.x86_64.rpm, sibuna-<version>-1.aarch64.rpm은 이 실행 파일을 systemd 서비스와 함께 설치하고, Arch Linux에서는 sibuna-bin-<version>-1-x86_64.pkg.tar.zst가 같은 일을 합니다. |
| macOS arm64, x86-64 | sibuna-macos-arm64.tar.gz, sibuna-macos-amd64.tar.gz. macOS 12 이상용입니다. |
| Windows x86-64 | sibuna-windows-amd64.zip에는 sibuna.exe가 들어 있습니다. Windows 10 또는 Server 2016 이상용입니다. |
| FreeBSD 15.1, OpenBSD 7.9 (amd64) | sibuna-<version>-freebsd-15.1-amd64.pkg와 sibuna-<version>.tgz. |
| Homebrew, Kubernetes, 컨테이너 | sibuna.rb, helm-sibuna-<version>.tgz, 그리고 amd64와 arm64용 이미지 ghcr.io/insanai/sibuna:<version>. 이미지의 다이제스트는 IMAGE-DIGEST.txt에 있습니다. |
| 소스 | sibuna-<version>-source.tar.gz. |
모든 아카이브와 패키지에는 LICENSE, NOTICE, LICENSES/ (실행 파일에 들어간 크레이트 목록인 THIRD-PARTY-RUST.txt 포함), README.md, SECURITY.md, sibuna.build.json이 들어 있습니다. 이 매니페스트는 버전, 커밋, Rust 타깃, 컴파일러 버전, 기능, 그리고 실행 파일과 두 WebAssembly 모듈의 SHA-256을 기록합니다. 릴리스 워크플로는 무엇이든 게시하기 전에 모든 실행 파일을 각자의 플랫폼에서 시작해 보고, Debian, Fedora, Arch Linux, FreeBSD, OpenBSD에서 패키지를 설치, 재설치, 제거해 봅니다.
릴리스 파일에는 서명이 없습니다. 설치하기 전에 내려받은 파일을 같은 릴리스의 SHA256SUMS와 대조해 확인합니다:
sha256sum --ignore-missing -c SHA256SUMS # Linux
shasum -a 256 --ignore-missing -c SHA256SUMS # macOS, FreeBSD
sha256 -C SHA256SUMS sibuna-1.0.0-beta.3.tgz # OpenBSD
macOS에서 브라우저로 내려받은 파일에는 서명되지 않은 실행 파일을 막는 격리 속성이 붙습니다. 확인을 마친 뒤 xattr -d com.apple.quarantine sibuna로 이 속성을 제거합니다.
systemd 서비스¶
Debian, RPM, Arch 패키지는 /usr/bin/sibuna, 유닛 sibuna.service, 계정 sibuna (systemd-sysusers를 통해), 도우미 스크립트 /usr/lib/sibuna/seed.sh, 설정 파일 /etc/sibuna/service.env를 설치합니다. 설치만으로는 아무것도 시작되지 않습니다. 설정 파일에 원본 서버를 IP 리터럴로 지정하고 서비스를 시작합니다:
sudoedit /etc/sibuna/service.env # SIBUNA_UPSTREAM_HOST, SIBUNA_UPSTREAM_PORT
sudo systemctl enable --now sibuna
curl -s http://127.0.0.1:8080/__sibuna/health
서비스는 SIBUNA_HOST와 SIBUNA_PORT로 달리 지정하지 않는 한 127.0.0.1:8080에서 수신합니다. SIBUNA_OPTIONS는 공백 기준으로 나눈 추가 옵션을 전달합니다. 예를 들면 --mode forward_auth나 --console 127.0.0.1:19446입니다. seed.sh는 매번 시작하기 전에 요청 허용 시드 /var/lib/sibuna/admission.seed (16진수 64자리, 모드 0600, 소유자 sibuna)가 없으면 만듭니다. 기존 시드는 절대 교체하지 않습니다. 새 시드는 모든 세션을 끝내기 때문입니다. 데몬은 SQLite 데이터베이스를 모드 0700 디렉터리인 /var/lib/sibuna에 둡니다. 유닛은 capability 없이 실행되며, 시스템을 읽기 전용으로 두고(ProtectSystem=strict), 비공개 /tmp와 장치를 쓰며, 새 권한 획득을 막습니다(no new privileges).
업그레이드는 설정 파일, 시드, 상태를 유지하며 서비스를 재시작하지 않습니다. 서비스는 백업한 뒤 직접 재시작합니다. 제거는 서비스를 중지하고 비활성화하지만 계정, 시드, 설정, 상태는 남겨 둡니다. 이것들은 호스트를 폐기할 때 직접 삭제합니다.
FreeBSD와 OpenBSD 패키지는 /usr/local/bin/sibuna와 그 문서만 설치합니다(pkg add, 또는 OpenBSD 미러 밖에서 받은 패키지라면 pkg_add -D unsigned). 서비스, 계정, 상태는 만들지 않습니다. 데몬은 비특권 사용자로, 전용 시드와 데이터 디렉터리를 두고 실행합니다.
Homebrew¶
sibuna.rb는 머신에 맞는 릴리스 아카이브(macOS 또는 Linux, arm64 또는 x86-64)를 설치합니다. 소스에서 빌드하지는 않습니다. 내장된 두 WebAssembly 모듈을 빌드하려면 wasm32-unknown-unknown용 표준 라이브러리가 필요한데, Homebrew의 Rust에는 이것이 없기 때문입니다. 아카이브에는 릴리스 워크플로가 이미 확인한 실행 파일이 들어 있습니다. Homebrew는 탭에서만 포뮬러를 설치하므로, 포뮬러를 로컬 탭에 넣습니다:
brew tap-new "$USER/local"
cp sibuna.rb "$(brew --repository)/Library/Taps/$USER/homebrew-local/Formula/"
brew install "$USER/local/sibuna"
포뮬러는 서비스를 시작하지 않습니다. 포뮬러의 주의 사항(caveats)은 시드를 만드는 방법을 보여 주고, 테스트는 같은 데이터 디렉터리에서 데몬을 두 번 시작합니다.
컨테이너와 Kubernetes¶
이미지 ghcr.io/insanai/sibuna:<version>는 distroless 기반 위에 정적 실행 파일을 담습니다. CA 인증서와 사용자 65532가 있고, 셸과 패키지 관리자는 없습니다. 진입점이 sibuna이므로 인수는 데몬 옵션입니다. 릴리스 워크플로는 이 이미지를 capability 없이 읽기 전용으로 실행하되, 시드는 읽기 전용으로 마운트하고 상태용 볼륨을 붙이며, 한 번 재시작해 봅니다:
docker run -d --read-only --cap-drop=ALL --security-opt=no-new-privileges \
-v "$PWD/admission.seed:/run/admission.seed:ro" -v sibuna-state:/var/lib/sibuna \
-p 8080:8080 ghcr.io/insanai/sibuna:1.0.0-beta.3 \
--host 0.0.0.0 --secret-file /run/admission.seed --data-dir /var/lib/sibuna/data \
--upstream-host 10.0.0.5 --upstream-port 3000
Helm 차트 helm-sibuna-<version>.tgz는 이 이미지의 Pod 하나를 실행합니다. 차트에는 직접 만든 Secret(secret.existingSecret, 키 admission.seed)이 필요하므로, 시드는 values나 템플릿에 절대 나타나지 않습니다. Pod는 Restricted Pod 보안 표준 아래에서 읽기 전용 루트 파일 시스템을 사용해 UID 65532로 실행됩니다. Recreate 업그레이드를 쓰는 레플리카 하나가 ReadWriteOnce 볼륨의 작성자를 하나로 유지하며, Sibuna는 이 볼륨의 data/에 SQLite 상태를 둡니다. 볼륨 클레임은 제거할 때도 남습니다. 프로브는 /__sibuna/health를 호출합니다. Service는 ClusterIP이고, 차트는 인그레스도 콘솔도 만들지 않으며, 차트의 NetworkPolicy는 networkPolicy.ingressFrom과 networkPolicy.egressTo가 클라이언트와 원본 서버를 허용할 때까지 모든 트래픽을 거부합니다. upstream.host는 IP 리터럴이어야 하며, extraArgs는 추가 데몬 옵션을 전달합니다. 워크플로는 Restricted 표준을 강제하는 kind 클러스터에서 차트를 설치, 업그레이드, 제거해 봅니다.
kubectl -n sibuna create secret generic sibuna-admission --from-file=admission.seed
helm install gateway ./helm-sibuna-1.0.0-beta.3.tgz --namespace sibuna \
--set secret.existingSecret=sibuna-admission \
--set upstream.host=10.0.0.5 --set upstream.port=3000
소스에서 빌드하기¶
우리는 Rust 1.100으로 빌드하고 테스트합니다. 최소 지원 버전은 여전히 Rust 1.94입니다.
우리는 ``rustup toolchain install 1.100.0 --profile minimal --target wasm32-unknown-unknown``으로 릴리스 도구 모음을 설치하고, 아래 명령에서 ``cargo +1.100.0``으로 선택합니다.
cargo build --release -p sibuna는 기본 기능(SQLite 저장소와 콘솔)을 갖춘target/release/sibuna를 만듭니다. sqlx는 SQLite를 번들로 포함하고,ring(rustls)은 빌드할 때 C 컴파일러가 필요합니다. 바이너리는 시스템 C 런타임을 동적으로 링크합니다. 빌드 스크립트는 WebAssembly 솔버와 콘솔 인터페이스도 빌드하며, 이를 위해rustup target add wasm32-unknown-unknown이 필요합니다.SIBUNA_POW_WASM=<path>와SIBUNA_CONSOLE_WASM=<path>를 지정하면 대신 미리 빌드한 모듈을 내장합니다.cargo build --release -p sibuna --no-default-features는 외부 크레이트가 전혀 없는 인메모리 방화벽을 만듭니다. 이때--data-dir와--database-url은 시작할 때StorageDisabled로,sibuna console은CONSOLEBUILD로 거부됩니다.cargo build --release -p sibuna --features postgres-tls는 데이터베이스와의 연결에 검증된 TLS를 쓰는 PostgreSQL 클러스터 지원을 추가합니다. OpenSSL은 필요하지 않습니다.- 릴리스의 정적 Linux 실행 파일은
musl-gcc를 C 컴파일러로 지정하고(CC_x86_64_unknown_linux_musl=musl-gcc)cargo build --release --locked -p sibuna --target x86_64-unknown-linux-musl(또는aarch64-unknown-linux-musl)로 빌드한 것입니다.
릴리스 프로필은 fat LTO와 코드 생성 단위 하나를 사용합니다. 워크플로는 두 WebAssembly 모듈을 한 번만 빌드해 모든 플랫폼에 전달하므로, 한 릴리스의 모든 실행 파일은 바이트 단위로 동일한 모듈을 내장합니다. 의존성이 바뀌면 cargo xtask licenses로 LICENSES/THIRD-PARTY-RUST.txt를 다시 생성합니다.
Windows에서 데몬은 Ctrl+C, Ctrl+Break, 콘솔 닫기 이벤트에서 멈추며, Windows 서비스로는 실행되지 않습니다. Windows 파일에는 모드 비트가 없으므로, Sibuna는 다른 사용자가 읽을 수 있는 키, 자격 증명, 데이터베이스 URL 파일을 거부할 수 없습니다. 이런 파일은 ACL로 접근을 제한합니다. 콘솔의 메모리와 CPU 게이지는 /proc에서 읽으므로 다른 시스템에서는 사용할 수 없습니다.