제X부: 참고 자료와 진단¶
엔드포인트, 지표, 오류 목록, 정책 스키마, 저장소 테이블을 한곳에 모았습니다.
엔드포인트¶
| 엔드포인트 | 메서드 | 기능 |
|---|---|---|
/__sibuna/challenge |
GET | 중간 페이지 |
/__sibuna/challenge.json?need=&path= |
GET | 상태 없는 챌린지를 발급합니다. 챌린지 응답에 담긴 요구 티켓이 챌린지를 결정하며, 티켓이 없으면 보고된 URL을 정규형으로 평가합니다(8 KiB를 넘으면 414, 정규형이 없는 경로는 400). {id, algorithm, difficulty, challenges, expires_at}을 반환합니다 |
/__sibuna/verify |
POST | {"challenge_id", "nonce"} 또는 {"challenge_id", "proof"}를 받습니다. Set-Cookie와 함께 200, 진단과 함께 400, 본문이 연결 버퍼보다 크면 413을 반환합니다 |
/__sibuna/wasm/sibuna-pow.wasm |
GET | 솔버 모듈, 14,744바이트(benchmarks/results/primitives-latest.json의 wasm_bytes), 1시간 동안 캐시 가능 |
/__sibuna/worker.js |
GET | WASM 증명자와 JavaScript 증명자를 담은 Web Worker, 1시간 동안 캐시 가능 |
/__sibuna/honeypot |
GET | 호출자를 --ban-seconds 동안 차단하고 인시던트를 기록합니다. 403을 반환합니다. 최상위 요청(Sec-Fetch-Dest가 없거나 document이고, 교차 사이트 Sec-Fetch-Site가 아닌 요청)만 차단하며, 그 밖의 요청은 404로 응답하고 횟수를 셉니다 |
/__sibuna/health |
GET | 엔진 이름, 버전, 프록시 모드, 증명 알고리즘을 담은 JSON 생존 확인(liveness) 상태 |
/__sibuna/metrics |
GET | Prometheus 텍스트 형식(버전 0.0.4) |
/__sibuna/ 아래의 그 밖의 경로는 404로 응답합니다. 발급과 검증은 별도의 --challenge-rate-limit 예산을 쓰며, 차단된 주소는 모든 경로에서 403으로 거부됩니다. 챌린지 응답에는 X-Sibuna-Status: CHALLENGE가 붙습니다. 허용된 요청은 업스트림으로 X-Sibuna-Status: PASS와 X-Sibuna-Rule을 전달합니다(forward-auth 응답에는 16진수 X-Sibuna-Rule-Hash도 붙습니다). HTML을 받아들이지 않는 클라이언트는 {"error":"challenge_required","challenge":"/__sibuna/challenge.json?need=<ticket>"}와 함께 401을 받습니다.
별도로 켜는 관리 리스너는 /console/을 제공합니다. 관리자 계정은 sibuna init-admin으로 로컬에서 초기화하고, 처음 로그인할 때 임시 비밀번호를 바꿉니다. /console/api/stats와 /console/ws에는 인증된 세션(키오스크 세션 포함)이 필요합니다. WebSocket은 통계, 이벤트, 노드, 정책, 챌린지, 감사 기록을 크기가 제한된 스냅숏, 변경분, 누락 복구와 함께 다중화합니다. 관리 피어는 /console/peer에 연결하며, 모든 API 경로는 /console/api/ 아래에 있습니다. forward-auth 모드에서는 원본 서버 오류 카운터를 관찰하지 않습니다. 콘솔의 워크플로, HTTPS 배포, 현재 SID 0007의 한계는 제IX부에서 설명합니다.
지표¶
다음 카운터를 이 순서대로 sibuna_<name>_total이라는 이름으로 Prometheus 텍스트 형식에 노출합니다.
| 카운터 | 증가 조건 |
|---|---|
incidents_persisted, incident_batches |
저장소 스레드가 커밋을 확인한 레코드와 트랜잭션 |
incidents_dropped, incident_write_failures |
링이 가득 차서 거부된 큐 삽입, 그리고 실패한 커밋 시도 |
requests |
파싱된 요청이 디스패치에 도달함(예약된 경로 포함) |
allowed, denied, challenged |
정책 결정이 내려짐(허용, 거부, 챌린지 발급 또는 재발급) |
challenges_issued |
/__sibuna/challenge.json이 챌린지 레코드를 발급함 |
solutions_accepted, solutions_rejected |
/__sibuna/verify가 증명을 받아들이거나 거부함 |
rate_limited |
GCRA가 요청을 거부함(429): 요청 한도, 챌린지 예산, 또는 규칙의 할당량 |
banned |
차단된 주소가 거부되었거나, 허니팟이 주소를 차단함 |
bans_issued |
차단이 기록됨(허니팟 또는 규칙 할당량에 의한 차단) |
proxied, upstream_errors |
요청이 원본 서버로 전달되었거나, 원본 서버가 실패함(502) |
parse_errors |
형식이 잘못된 헤드, 반복된 Host, 정규형이 없는 대상(400), 또는 지원하지 않는 전송 코딩(501)이 거부됨 |
overloaded |
--max-connections 또는 --max-connections-per-ip를 넘는 연결에 503으로 응답함 |
bans_refused |
키가 들어갈 수 있는 모든 슬롯에 유효한 차단이 있어서 차단을 기록하지 못함 |
forwarded_invalid |
신뢰하는 전달된 클라이언트 주소를 파싱하지 못해, 소켓 피어로 요청을 판정함 |
honeypot_refused |
사람이 아니라 페이지가 요청했으므로 허니팟에 적중했지만 아무도 차단하지 않음 |
rate_evictions |
제한기에 새로 도착한 클라이언트가 다른 활성 클라이언트의 셀을 밀어냄 |
ja4_present |
--ja4-header를 지정하고 전달을 신뢰할 때, 요청에 JA4 지문을 담은 그 이름의 헤더가 정확히 하나 있었음 |
ja4_invalid |
--ja4-header를 지정하고 전달을 신뢰할 때, 헤더 형식이 잘못되었거나 반복되어 지문 없이 요청을 판정함 |
대기 중인 배치는 보관되므로, 재시도는 레코드를 잃지 않고도 incident_write_failures를 늘릴 수 있습니다. 일정 구간 동안의 증가량을 감시하세요. 누적값만으로는 큐 깊이를 알 수 없습니다.
상태 코드¶
| 코드 | 상황 |
|---|---|
| 200 | 허용됨(forward-auth), 중간 페이지(챌린지가 필요한 HTML 탐색), 내부 경로 |
| 302 | 현재 프로토콜에서는 쓰지 않습니다. 검증은 200으로 응답하고 페이지를 다시 불러옵니다 |
| 400 | 형식이 잘못된 요청, 반복된 Host 필드, 정규형이 없는 대상, 잘못된 전달 메타데이터, 형식이 잘못된 본문, 또는 Elm 스타일 진단과 함께 거부된 풀이 |
| 401 | HTML을 받아들이지 않는 클라이언트나 forward-auth 모드에서 챌린지가 필요함 |
| 403 | 정책 또는 WAF 거부, 차단된 주소, 허니팟 |
| 404 | /__sibuna/ 아래의 알 수 없는 경로, 또는 최상위 요청이 아닌 허니팟 적중 |
| 413 | 풀이 본문이 64 KB 연결 버퍼보다 큼 |
| 414 | 보고된 챌린지 URL이 8 KiB를 넘음 |
| 417 | 지원하지 않는 요청 기대 조건. 100-continue는 로컬에서 처리합니다 |
| 429 | GCRA 한도 초과. Retry-After는 초 단위입니다 |
| 431 | 요청 헤드가 16 KB를 넘음 |
| 501 | chunked가 아닌 코딩을 지정한 Transfer-Encoding |
| 502 | 원본 서버에 연결할 수 없거나, 원본 응답 헤드의 형식이 잘못되었거나 16 KB를 넘음 |
| 503 | 연결 한도(--max-connections 또는 --max-connections-per-ip)에 도달했거나 노드가 드레이닝 중입니다. 응답 뒤에 소켓을 닫습니다 |
오류 목록¶
INVALID COMMAND LINE은 데몬이 인식하지 못하는 옵션, 문서화된 범위를 벗어난 값, 잘못되었거나 빠졌거나 중복된 모드 선택이 있으면 시작을 멈춥니다. 오류 블록은 옵션, 지정한 값, 기대하는 범위, 오류(UnknownOption, MissingValue, InvalidValue, InvalidMode, MissingMode, DuplicateMode, Zaxonlite 클러스터 옵션에 대한 RemovedOption, 서로 배타적인 두 저장소 옵션에 대한 ConflictingOptions, --cluster-node 없이 데이터베이스 URL을 준 경우의 MissingOption)를 밝히고 힌트로 끝납니다. 데이터베이스 URL은 [redacted]로 표시됩니다. --mode reverse_proxy 또는 --mode forward_auth를 한 번만 지정하세요. -m은 같은 뜻의 짧은 옵션입니다. 거부된 정책 파일은 오류에 맞는 제목의 블록(예: INVALID POLICY ACTION)에 파일, 오류 이름, 규칙, 필드, 값을 출력합니다. 어떤 지문과도 일치할 수 없는 ja4 패턴은 INVALID POLICY JA4(InvalidJa4)를 출력하며, 그런 패턴을 담은 콘솔 관리 문서도 같은 오류 이름으로 거부됩니다. 콘솔 옵션은 따로 검사합니다. CONSOLE002는 형식이 잘못되었거나 반복된 콘솔 옵션을, CONSOLE001은 규칙을 어기는 콘솔 설정(예: 저장소 없이 콘솔을 켠 경우의 StorageRequired)을 가리킵니다.
| 오류 | 원인 | 힌트 |
|---|---|---|
MalformedChallenge |
식별자가 올바른 형식의 챌린지 레코드가 아님 | 새 챌린지를 가져와 바꾸지 않고 제출하세요 |
InvalidChallengeTag |
태그가 인증되지 않음. 이 클러스터가 발급하지 않았거나 수정됨 | 챌린지는 위조할 수 없습니다. 새 챌린지를 요청하세요 |
ChallengeExpired |
챌린지 TTL보다 오래되었거나, 미래 시각에 발급됨 | 새 챌린지를 요청하세요 |
FingerprintMismatch |
다른 주소나 User-Agent에서 제출됨 | 챌린지를 가져온 클라이언트에서 제출하세요 |
DifficultyNotMet |
Hashcash nonce에 필요한 0비트가 부족함 | nonce 탐색을 계속하세요 |
InvalidProof |
순차 작업 증명이 커밋된 라벨을 개방하지 못함 | 발급된 깊이와 개방 수로 증명자를 끝까지 실행하세요 |
WrongSolutionType |
PoSW 챌린지에 nonce를, 또는 Hashcash에 증명을 제출함 | 풀이 필드를 알고리즘에 맞추세요 |
DoubleSpendAttempt |
챌린지가 이미 사용됨 | 챌린지는 한 번만 쓸 수 있습니다 |
StoreFull |
사용 완료 집합이 가득 참 | 챌린지 TTL을 낮추거나 --spent-tags를 늘리세요 |
InvalidTokenSignature |
쿠키 태그나 서명 검증이 실패함 | 중간 페이지를 통해 다시 인증하세요 |
TokenExpired |
쿠키가 만료됨 | 다시 인증하세요 |
TokenBoundAddressMismatch |
쿠키가 다른 클라이언트 신원에서 제시됨 | 쿠키는 공유할 수 없습니다 |
콘솔 API는 실패를 {"error":"<CODE>","hint":"<sentence>"}로 응답합니다. 힌트는 인터페이스가 보여 주는 문장입니다(crates/console/src/http/reply.rs).
| 코드 | 상태 | 의미 |
|---|---|---|
CONSOLE002 |
400 | 요청의 형식이 잘못되었거나, 너무 크거나, 그 형태로는 허용되지 않음 |
CONSOLE003 |
503 / 429 | 저장소 작업 큐가 가득 찼거나(작업 32개), 비밀번호 검증기가 바쁨 |
CONSOLEQUORUM |
503 | 데이터베이스가 요청 대기 시간 10초 안에 응답하지 않음. 결과는 알 수 없으며, 데이터 평면은 마지막으로 적용된 정책으로 계속 동작함 |
CONSOLE004 |
503 | 서비스가 응답할 수 없음: 이 빌드에서 제공되지 않거나, 중지 중이거나, 내부 실패 |
CONSOLENODE |
400 / 409 / 503 | 노드 명령이 거부됨: 다른 노드를 지정했거나(400), 부팅 또는 제어 리비전이 오래되었거나(409), 다른 명령이 실행 중일 때 도착했거나 완료를 기록할 수 없었음(503). 재시도하기 전에 작업 영수증을 확인하세요 |
CONSOLEMUTATION |
429 | 한 세션에서 1분에 관리 변경이 60건을 넘음 |
정책 스키마¶
{
"default_action": "ALLOW" | "DENY" | "CHALLENGE",
"waf": true | false,
"inspection": { "path_traversal" | "sqli" | "xss" | "rce": "disabled" | "audit" | "enforce" },
"thresholds": { "challenge_at": int, "deny_at": int, "bits_step": int },
"ip_rules": { "<cidr>": "ALLOW" | "DENY" | "CHALLENGE", ... },
"rules": [ // 최대 128개
{
"name": "<kebab-case>", // 출력 가능한 바이트 1~128개
"path" | "path_regex": "<pattern>", // 최대 512바이트
"user_agent" | "user_agent_regex": "<pattern>",
"headers" | "headers_regex": { "<Header>": "<pattern>" }, // 최대 4개
"remote_addresses" | "cidrs": ["<cidr>", ...], // 최대 8개, IPv4 또는 IPv6
"action": "ALLOW" | "DENY" | "CHALLENGE" | "WEIGH",
"weight": int, // WEIGH 전용, -1000..1000
"challenge": { "difficulty": <work bits>, "algorithm": "hashcash" | "posw" },
"limits": { "rate": int, "window_seconds": int, "ban_seconds": int },
"ja4": "<fingerprint>" | "<prefix>*" // 36바이트, 또는 접두사와 *
}
]
}
challenge_at과 deny_at은 -1000에서 1000 사이이며 deny_at은 challenge_at 이상이어야 하고, bits_step은 1에서 1000 사이입니다. challenge 블록은 CHALLENGE 규칙에만 쓸 수 있으며 작업 비트는 1에서 64입니다. limits는 규칙에 자체 할당량을 줍니다. rate 1에서 1,000,000과 window_seconds 1에서 86,400은 필수이고, ban_seconds(최대 86,400)는 선택이며, WEIGH 규칙에는 한도를 둘 수 없습니다. ja4는 정확히 같아야 하는 전체 JA4 지문이거나, 지문이 그것으로 시작해야 하는 접두사 뒤에 *를 붙인 것입니다. * 하나만 쓰면 모든 지문과 일치하고, 지문이 없는 요청은 어떤 ja4 규칙과도 일치하지 않습니다. 어떤 지문과도 일치할 수 없는 패턴은 InvalidJa4로 거부됩니다(제IX부, 인그레스에서 받는 JA4 지문). ip_rules의 평판 트라이는 노드를 최대 8,192개 담습니다. 각 규칙은 조건마다 한 가지 표기만 쓸 수 있습니다.
패턴 문법: .* 또는 *는 모든 것과 일치합니다. ^...$는 정확한 경로를 고정합니다. 끝의 *, /*, .*는 접두사입니다. /로 시작하는 패턴은 정확한 경로입니다. 그 밖의 것은 대소문자를 구별하지 않는 부분 문자열입니다. 경로 패턴은 정규형 경로(세그먼트 사이에 슬래시 하나, 점 세그먼트 없음, 예약되지 않은 문자는 이스케이프 해제, 그 밖의 이스케이프는 대문자 16진수)와 대조하므로, ;, %2F, %5C, \를 담은 패턴은 아무것과도 일치하지 않으며, 경로 매칭은 대소문자를 구별합니다(SID 0003).
저장소 테이블¶
policy_revision, policies(최대 37바이트의 null 허용 ja4_pattern 조건 포함), policy_inspection, ip_reputation, incident_receipts, security_incidents(256바이트 임베딩과 null 허용 36바이트 ja4 지문 포함), 전문 검색 색인(SQLite에서는 정규 토큰에 대한 FTS5인 incidents_fts, PostgreSQL에서는 GIN 색인이 있는 tsvector 열 search), 그리고 sibuna_schema입니다. 콘솔은 console_* 테이블 33개를 더합니다. 저장되는 동작, 알고리즘, 모드 이름은 소문자입니다. 인시던트 id는 node_id << 40 | sequence로, 조정 없이도 클러스터 전체에서 유일합니다. 노드 id는 1부터 8,388,607까지입니다.
빌드 대상¶
| 명령 | 결과 |
|---|---|
cargo build --release -p sibuna |
SQLite 저장소와 콘솔을 포함한 데몬(기본 기능) |
cargo build --release -p sibuna --no-default-features |
저장소와 콘솔 없이, 외부 crate도 없이 메모리에서만 동작하는 데몬 |
cargo build --release -p sibuna --features postgres-tls |
공유 PostgreSQL 데이터베이스에도 검증된 TLS로 연결하는 데몬(postgres 기능만 켜면 TLS 없이 연결) |
cargo test |
단위 테스트, 실행 중인 데몬에 대한 통합 테스트, 저장소와 콘솔 테스트(SIBUNA_TEST_DATABASE_URL을 설정하면 PostgreSQL 테스트 포함) |
cargo clippy --all-targets, cargo fmt --check |
린트와 포맷(max_width = 99) |
cargo xtask check |
70줄 함수, 1,408줄 파일, 99/108열 줄 길이 한도. 탭 금지 |
cargo xtask browser |
헤드리스 Chromium에서 실행하는 검사(sibuna-browser) |
cargo xtask bench <primitives|product|latency> |
릴리스 모드 벤치마크. 결과는 benchmarks/results/<command>-latest.json에 저장 |
cargo build -p sibuna-pow-wasm --target wasm32-unknown-unknown --profile wasm |
브라우저 모듈만 빌드(콘솔 인터페이스는 -p sibuna-console-ui) |
cargo run -p sibuna-geoip --bin geoip-snapshot -- ... |
국가 데이터를 검증하고 내장할 수 있는 GeoIP 스냅숏을 생성 |
guidedog build / guidedog dsc |
이 책 / SID 기록 |
데몬의 빌드 스크립트(cmd/sibuna/build.rs)는 두 WebAssembly 모듈을 wasm 프로파일로 워크스페이스의 대상 디렉터리에 빌드하며, 콘솔 인터페이스가 768 KiB를 넘으면 빌드를 실패시킵니다. wasm32-unknown-unknown 대상이 없는 빌드에서는 SIBUNA_POW_WASM과 SIBUNA_CONSOLE_WASM으로 미리 빌드한 모듈을 대신 지정합니다. SIBUNA_GEOIP_DATA는 내장할 GeoIP 스냅숏을 지정합니다. 이 스냅숏은 빌드할 때 디코딩되며, 콘솔이 없는 빌드는 이를 거부합니다(GEOIP001).