제XI부: 빠른 참조 카드¶
터미널 옆에 두고 보세요. 빌드, 실행, 설정, 라우팅, 관찰, 진단을 다룹니다. 전체 표는 제X부에 있고, 이 카드에는 운영자가 실제로 입력하는 내용을 담았습니다.
빌드¶
cargo build --release -p sibuna # 데몬 + SQLite + 콘솔
cargo build --release -p sibuna --no-default-features # 메모리 전용, 외부 crate 없음
cargo build --release -p sibuna --features postgres-tls # 공유 PostgreSQL 클러스터
rustup target add wasm32-unknown-unknown # 또는 SIBUNA_POW_WASM / SIBUNA_CONSOLE_WASM 설정
cargo test # 단위, 실행 중인 데몬, 저장소, 콘솔 테스트
cargo clippy --all-targets && cargo fmt --check
cargo xtask check # 70줄 / 1,408줄 / 99열 검사
cargo xtask browser # 헤드리스 Chromium 검사
cargo xtask bench product # wrk 부하 아래의 전체 제품 -> benchmarks/results/
guidedog build # 이 책 (guidedog dsc: SID 기록)
실행¶
# Shield(기본값): PoW + WAF, :3000으로 프록시
sibuna -p 8080 -u 3000 -s /etc/sibuna/secret
# Gate: PoW만
sibuna --gate -p 8080 -u 3000 -s /etc/sibuna/secret
# Nginx/Caddy 뒤의 forward-auth (X-Forwarded-For를 신뢰)
sibuna -m forward_auth --host 127.0.0.1 -p 8080 -s /etc/sibuna/secret
# Edge: 영속 정책, 평판, 포렌식을 <dir>/sibuna.db에 저장
sibuna -D /var/lib/sibuna -s /etc/sibuna/secret
# 신뢰할 수 있는 인그레스가 보내는 JA4 (Cloudflare 헤더; nginx 모듈: x-ja4; ATS: ja4)
sibuna --ja4-header cf-ja4 --trust-forwarded -p 8080 -u 3000 -s /etc/sibuna/secret
# 클러스터 구성원: 공유 PostgreSQL, 고유한 노드 id
sibuna --database-url-file /etc/sibuna/database-url --cluster-node 1 -s /etc/sibuna/secret
head -c 32 /dev/urandom | xxd -p -c 64 > /etc/sibuna/secret
콘솔(선택형 미리 보기)¶
# 데몬을 멈춘 상태에서 초기화한 다음 콘솔을 시작합니다
sibuna init-admin admin --data-dir ./data
sibuna --data-dir ./data --console 127.0.0.1:19446
http://127.0.0.1:19446/console/을 열고 임시 비밀번호를 바꾸세요. --console-location 1.3521,103.8198을 추가하면 지구본에 노드가 표시됩니다. 원격 접근에는 HTTPS 프록시, 명시적 origin, 신뢰할 프록시 CIDR이 필요합니다. 제IX부의 절차를 따르세요. SID 0007은 Committed 상태입니다. 콘솔은 헤드리스 Chromium에서 브라우저 워크플로 테스트를 통과합니다(SID 0010, 기준 5). 공식 성능 격리 관문은 아직 통과하지 못한 미결 항목입니다(제VIII부).
먼저 알아야 할 플래그¶
| 플래그 | 기본값 | 의미 |
|---|---|---|
-d, --difficulty |
16 | 작업 비트(PoSW 깊이 = 비트 - 3) |
-a, --algorithm |
posw | posw 또는 hashcash |
--posw-challenges |
16 | 증명당 개방 수 |
--token-ttl |
86400 | 세션 유효 시간(초) |
--challenge-ttl |
300 | 챌린지 유효 시간(초) |
--token-scheme |
mac | mac 또는 ed25519 |
--rate-limit / --rate-window |
100 / 10 | 윈도당 GCRA 버스트 |
--ban-seconds |
3600 | 허니팟 차단 |
-w, --workers |
CPU 수 | accept 스레드 |
--max-connections |
1024 | 초과 시 503 |
--max-connections-per-ip |
64 | 피어 주소별(IPv6: --ipv6-prefix별), 초과 시 503 |
--trusted-hops |
1 | 클라이언트 = 오른쪽에서 n번째 X-Forwarded-For 항목 |
--ja4-header |
꺼짐 | 인그레스의 JA4 지문을 담은 헤더. 신뢰할 때만 읽음 |
--idle-timeout |
15 | 유휴 연결 회수 시간(초) |
-P, --policy-file |
없음 | JSON 정책 |
--trust-forwarded |
꺼짐 | forward-auth에서 켜짐 |
--secure-cookie |
꺼짐 | Secure 추가 |
/__sibuna/ 아래의 엔드포인트¶
| 경로 | 응답 |
|---|---|
challenge |
중간 페이지 HTML |
challenge.json?need=&path= |
{id, algorithm, difficulty, challenges, expires_at} |
verify(POST) |
{challenge_id, nonce | proof} -> 200 + Set-Cookie, 아니면 400 |
wasm/sibuna-pow.wasm |
15,181바이트 솔버 |
worker.js |
WASM 증명자와 JS 증명자를 갖춘 워커 |
honeypot |
호출자를 차단하고 403, 하위 리소스나 교차 사이트 가져오기에는 404 |
health |
{"status":"ok",...} |
metrics |
Prometheus 텍스트 |
이 경로는 모두 원본 서버가 아니라 데몬으로 라우팅하세요.
상태 코드¶
| 코드 | 상황 |
|---|---|
| 200 | 허용(forward-auth), 중간 페이지, 내부 경로 |
| 400 | 잘못된 요청 또는 대상, 거부된 풀이(진단 본문) |
| 401 | 챌린지 필요: HTML이 아닌 클라이언트 또는 forward-auth |
| 403 | 정책 또는 WAF 거부, 차단, 허니팟 |
| 404 | 알 수 없는 /__sibuna/ 경로, 거부된 허니팟 적중 |
| 413 | 64 KB 버퍼를 넘는 풀이 본문 |
| 414 | 8 KiB를 넘는 보고된 챌린지 URL |
| 417 | 지원하지 않는 요청 기대(Expect) |
| 429 | GCRA 제한, Retry-After 초 |
| 431 | 16 KB를 넘는 헤드 |
| 501 | chunked가 아닌 전송 코딩 |
| 502 | 원본 서버에 연결할 수 없거나 응답이 잘못됨 |
| 503 | 연결 한도 도달 또는 노드가 드레이닝 중 |
헤더¶
- 업스트림(프록시):
X-Forwarded-For(소켓 피어, 신뢰하는 경우 받은 체인 뒤에 추가),X-Forwarded-Proto,X-Real-IP(판정한 클라이언트),X-Sibuna-Status: PASS,X-Sibuna-Rule: <rule>. 홉별(hop-by-hop) 필드와 그 밖의 전달 필드는 제거하며, 밑줄로 쓴 표기도 제거합니다. - forward-auth 응답:
X-Sibuna-Status,X-Sibuna-Rule,X-Sibuna-Rule-Hash. - 챌린지 응답:
X-Sibuna-Status: CHALLENGE. - 쿠키:
__sibuna_token=<75 chars, 139 with ed25519>; Path=/; Max-Age=<ttl>; HttpOnly; SameSite=Lax[; Secure]
정책 파일 골격¶
{ "default_action": "CHALLENGE", "waf": true,
"thresholds": {"challenge_at": 10, "deny_at": 40, "bits_step": 5},
"ip_rules": {"10.0.0.0/8": "ALLOW", "2001:db8::/32": "DENY"},
"rules": [
{"name": "api", "path": "/api/*", "headers": {"X-Api-Key": ".*"}, "action": "ALLOW"},
{"name": "checkout", "path": "/checkout/*", "action": "CHALLENGE",
"challenge": {"difficulty": 20, "algorithm": "posw"}},
{"name": "login", "path": "^/login$", "action": "CHALLENGE",
"limits": {"rate": 10, "window_seconds": 60, "ban_seconds": 600}},
{"name": "old-tls", "ja4": "t12*", "action": "CHALLENGE"},
{"name": "headless", "user_agent": "Headless", "action": "WEIGH", "weight": 30} ] }
JA4: 전체 지문, 또는 접두사 뒤에 *. 지문이 없으면 일치하지 않습니다. 패턴: * 또는 .*는 모두 일치, ^...$는 정확히 일치, 끝의 *는 접두사, 앞의 /는 정확한 경로, 그 밖에는 대소문자를 구별하지 않는 부분 문자열입니다. 경로는 정규형으로 비교합니다. 순서: WAF -> 트라이 deny/allow -> 규칙 -> 점수 -> 우회 -> 트라이 challenge -> 봇 -> 기본값.
SQL로 보는 저장소(Edge)¶
INSERT INTO policies (id, name, priority, path_pattern, action, difficulty, algorithm,
header_matchers, cidr_matchers, weight, enabled, created_at, updated_at)
VALUES ('p1', 'protect', 10, '/checkout/*', 'challenge', 20, 'posw', '{}', '[]', 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.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(sqlite3 <dir>/sibuna.db). 동작은 소문자로 씁니다. 점수 \(\le -50\) -> deny 접두사, \(\ge 50\) -> allow. 클러스터: 모든 노드에 같은 비밀 값, PostgreSQL 데이터베이스 하나, --features postgres-tls, 1에서 8,388,607 사이의 고유한 N으로 --database-url-file <file> --cluster-node N. 멤버 목록, 리더, 클러스터 TLS는 없습니다(SID 0011).
진단¶
| 제목 | 의미 |
|---|---|
MALFORMED CHALLENGE |
id가 수정되었거나 잘렸습니다. 새 챌린지를 받으세요 |
INVALID CHALLENGE TAG |
이 시드나 노드가 발급하지 않았습니다 |
CHALLENGE EXPIRED |
TTL보다 오래되었거나 시계 오차가 60 s 초과 |
CLIENT FINGERPRINT MISMATCH |
주소나 User-Agent가 바뀌었습니다 |
DIFFICULTY NOT MET |
nonce에 0비트가 부족합니다 |
INVALID PROOF OF SEQUENTIAL WORK |
개방이 루트에 닿지 않습니다 |
WRONG SOLUTION TYPE |
PoSW에 nonce, 또는 Hashcash에 증명을 보냈습니다 |
DOUBLE SPEND PREVENTED |
이미 사용한 챌린지입니다 |
STORE FULL |
사용 완료 집합이 포화되었습니다. TTL을 낮추거나 --spent-tags를 늘리세요 |
NETWORK BINDING MISMATCH |
쿠키가 다른 클라이언트로 복사되었습니다 |
INVALID COMMAND LINE |
알 수 없는 옵션, 잘못된 값, 또는 제거된 Zaxonlite 옵션 |
경보를 걸 지표: denied, rate_limited, overloaded, upstream_errors, incidents_dropped, incident_write_failures, bans_refused, forwarded_invalid(모두 sibuna_*_total).
기억할 숫자¶
챌린지 id 70자(36바이트 페이로드 + 16바이트 태그), 토큰 75자(40 + 16), Ed25519에서는 139자, 증명 바이트 \(32(1 + t(n+1))\), PoSW 깊이 = 비트 - 3, 범위 4에서 24, 요청 버퍼 64 KB, 헤드 한도 16 KB, 본문 검사 8 KB, 사용 완료 집합 태그 1,048,576개(--spent-tags), 속도 셀 테이블당 262,144개(--rate-table-cells), 차단 슬롯 65,536개(--ban-table-slots), 클라이언트 주소당 연결 64개, 인시던트 링 512, 배치 32, 가장 최근 임베딩 16,384개에 대한 캠페인 거리 0.35, 연결당 keep-alive 요청 4,096개, 원본 풀 소켓 256개, 저장소 작업 큐 32.
인그레스 라우팅¶
제IX부 "인그레스 뒤의 forward-auth"의 Nginx 또는 Caddy 설정 예를 사용하세요. /__sibuna/*는 직접 라우팅하고, 애플리케이션 요청은 원래 URI, 메서드, 신뢰하는 클라이언트 주소로 인가합니다. 들어오는 Sibuna 감사 헤더는 인가 결과로 교체합니다. Nginx에서는 챌린지, 429, 인가 서버를 쓸 수 없는 경우를 명시적으로 처리해야 합니다.
reverse_proxy는 허용된 HTTP/1.1 본문과 WebSocket을 전달합니다. forward_auth는 요청 허용만 결정하고 전달은 인그레스가 맡습니다. 인가 요청에 실리지 않은 본문과 원본 응답은 Sibuna가 검사하거나 집계할 수 없습니다. TLS는 인그레스에서 종료되며, 네이티브 HTTP/2는 뒤로 미뤘습니다. 업로드는 Content-Length나 chunked 코딩을 사용합니다. 검사는 최대 8 KiB 접두사만 보며, 파일 바이트는 내용을 해석하지 않습니다.