netbis-sigmatch v2.3: CF Access Rules LIVE 연동 (Phase 11)

projects/netbis-sigmatch.md

@@ -13,7 +13,7 @@ Netbis NPM 로그(VictoriaLogs)를 실시간 분석해 **사람 개입 없이
 - **배포 예정**: jp1 Incus `ai-sigmatch` 컨테이너 (systemd timer 1분)
 - **책임자**: kappa 직접 개발 (Heimdall 위임 X, 개발 단계)
 
-## 핵심 설계 (v2.2, 2026-04-24 Matrix Profile 추가)
+## 핵심 설계 (v2.3, 2026-04-24 CF Access Rules LIVE 모드 추가)
 
 ### 탐지 트리거 (OR 조건, 하나라도 충족 시 attack mode ON)
 
@@ -86,8 +86,39 @@ Raw extreme:     reqs ≥ 1500 / 5min
 
 ## 조치 레벨
 
-- **challenge** (Cloudflare managed_challenge, CAPTCHA, TTL 30분): 정상 유저는 한 번 풀고 통과
+- **challenge** (Cloudflare `managed_challenge`, CAPTCHA, 내부 TTL 30분): 정상 유저는 한 번 풀고 통과
-- **block** (TTL 24시간): challenge 통과 후에도 같은 IP가 5+ 사이클 연속 공격 시
+- **block** (CF `block`, 내부 TTL 24시간): challenge 통과 후에도 같은 IP가 5+ 사이클 연속 공격 시
+- 내부 TTL이 지나면 loop이 CF rule을 DELETE (CF Access Rules 자체 TTL 없음, sigmatch가 관리)
+
+## CF 연동 (Phase 11, v2.3)
+
+### 엔드포인트
+- Account-level: `POST /accounts/{id}/firewall/access_rules/rules` (6개 zone 동시 적용)
+- 인증: `X-Auth-Email` + `X-Auth-Key` (global_api_key). API token은 Rulesets/Firewall 403
+- Vault: `secret/cloud/cloudflare-netbis` (`account_id`, `email`, `global_api_key`)
+
+### 중복 호출 최소화
+상태 변화 있을 때만 CF API 호출:
+- `없음 → challenge/block`: `create_rule` → `rule_id` 저장
+- `challenge → block`: `update_rule (PATCH mode)` (같은 rule_id 유지)
+- `같은 action 지속`: **skip-same** (CF 호출 없음, sqlite state만 갱신하여 TTL 연장)
+- `expire_actions`: 내부 TTL 만료 시 `delete_rule` + state clear
+
+### Rate Limit 대응
+- `min_interval_sec=0.3` (sleep), 429 시 exponential backoff
+- CF API 계정 제한 1200 req/5min — 지속 공격 IP 10개 × 사이클당 skip-same 로직이라 여유
+
+### Rule 태깅
+notes에 `netbis-sigmatch` prefix. startup 시 `list_sigmatch_rules()`로 우리가 만든 rule만 필터 캐시.
+
+### CLI 유틸 (`cf_client.py`)
+```bash
+# env: CF_ACCOUNT_ID, CF_EMAIL, CF_GLOBAL_API_KEY
+uv run python cf_client.py list                            # 현재 sigmatch rules 확인
+uv run python cf_client.py create --ip X --mode managed_challenge --note "..."
+uv run python cf_client.py delete --rule-id XXX
+uv run python cf_client.py purge [--yes]                   # sigmatch prefix 전체 삭제
+```
 
 ## 개발 단계
 
@@ -97,9 +128,10 @@ Raw extreme:     reqs ≥ 1500 / 5min
 - [x] Phase 6 (v2): 집계 기반 공격 모드 + 개별 극단 시그니처
 - [x] Phase 7: 롤링 baseline 자동 갱신
 - [x] Phase 8 (v2.1): CUSUM Page-Hinkley + global src IP entropy drop
-- [x] **Phase 9 (v2.2): Matrix Profile discord (stumpy.stump) 추가** ← 현재
+- [x] Phase 9 (v2.2): Matrix Profile discord (stumpy.stump) 추가
-- [ ] Phase 10: 장시간 관찰 (dry-run) — 진행 중 (백그라운드 `loop.py`). entropy baseline 20+ 샘플 쌓이려면 약 20시간
+- [x] Phase 10: bootstrap_baseline.py — 과거 24h seed로 모든 hour samples_ok 즉시 충족
-- [ ] Phase 11: CF IP Access Rules 호출 (managed_challenge → block)
+- [x] **Phase 11 (v2.3): CF Access Rules 호출 (managed_challenge/block)** ← 현재 DRY로 검증
+- [ ] Phase 11 LIVE 전환: `--live` 플래그로 실 운영 (환경변수 CF credentials 주입)
 - [ ] Phase 12: jp1 Incus 배포 (systemd timer)
 
 ## 파라미터 (사람 조정 가능)
@@ -159,9 +191,11 @@ Raw extreme:     reqs ≥ 1500 / 5min
 ├── collect_baseline.py     — retrospective seed baseline 수집
 ├── baseline_aggregate.py   — 시간대별 seed 통계 수집 (1회성)
 ├── inspect_baseline.py     — baseline DB 탐색
-├── state.py                — state DB (ip_state, baseline_samples, cusum_state 등)
+├── state.py                — state DB (ip_state + cf_rule_id, baseline_samples, cusum_state 등)
 ├── matrix_profile.py       — stumpy MP discord 판정 (v2.2)
-├── loop.py                 — 메인 실시간 루프
+├── cf_client.py            — CF Access Rules API 래퍼 + CLI 유틸 (v2.3)
+├── bootstrap_baseline.py   — 과거 N시간 seed 주입 (cold start 해소)
+├── loop.py                 — 메인 실시간 루프 (--live로 CF 호출)
 ├── simulate.py             — 과거 데이터로 로직 검증
 ├── baseline.db             — seed snapshot 24h
 ├── state.db                — 운영 상태 + 롤링 baseline