kaffa/runbooks
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Add runbooks collection

Browse Source 
- anvil-load-test-report.md
- claude_communication_flow.md
- incus-crowdsec-architecture.md
- incus-meilisearch-manual.md
- kitty-setup-guide.md
- OpenAppSec_WAF_Operations_Guide.md
- openappsec-setup-20250817.md
- xray-proxy-guide.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
kappa
2026-01-16 00:31:54 +09:00
commit 53a655d4d5
8 changed files with 2835 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

305
OpenAppSec_WAF_Operations_Guide.md Normal file
View File

@@ -0,0 +1,305 @@
# OpenAppSec WAF 운영 가이드
## 📋 시스템 개요
**구축 환경**: incus 컨테이너 기반
**구성**: Agent (보안 엔진) + OCI (프록시)
**IP 주소**:
- Agent: 10.90.135.243
- OCI: 10.90.135.233
**메모리 사용량**: Agent 184MB + OCI 58MB = 242MB
**성능**: 290+ RPS, 15-25ms 응답시간
## 🔧 핵심 설정 파일 위치
### Agent 컨테이너 (openappsec-agent)
```bash
# 정책 파일들
/etc/cp/conf/production_policy.yaml # 운영 정책 (현재 적용)
/etc/cp/conf/local_policy_learning.yaml # Learning 모드
/etc/cp/conf/local_policy_high_confidence.yaml # High Confidence
/etc/cp/conf/local_policy_with_exceptions.yaml # Exception 규칙 포함
# 제어 스크립트
/etc/cp/scripts/open-appsec-ctl.sh # 메인 제어 스크립트
/usr/local/bin/waf-monitor.sh # 모니터링 스크립트
/usr/local/bin/waf-emergency.sh # 비상 복구 스크립트
# 로그 파일
/var/log/nano_agent/cp-nano-http-transaction-handler.log*
/var/log/waf-monitor.log # 모니터링 로그
/var/log/waf-emergency.log # 비상 작업 로그
```
### OCI 컨테이너 (openappsec-oci)
```bash
# nginx 설정
/etc/nginx/conf.d/production.conf # 운영 환경 설정
/etc/nginx/conf.d/default.conf # 기본 설정 (백업)
# 로그 파일
/var/log/nginx/access.log
/var/log/nginx/error.log
```
## 🚀 일상 운영 명령어
### 상태 확인
```bash
# WAF 전체 상태 확인
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --status
# 확장 상태 정보
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --status --extended
# 현재 적용 정책 확인
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --view-policy
# 컨테이너 리소스 사용량
incus info openappsec-agent | grep "Memory usage"
incus info openappsec-oci | grep "Memory usage"
```
### 정책 관리
```bash
# 정책 변경 (Learning 모드)
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/local_policy_learning.yaml
# 정책 변경 (High Confidence)
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/local_policy_high_confidence.yaml
# 정책 변경 (운영 모드)
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/production_policy.yaml
```
### 로그 모니터링
```bash
# 실시간 보안 이벤트 확인
incus exec openappsec-agent -- tail -f /var/log/nano_agent/cp-nano-http-transaction-handler.log1
# 최근 차단/탐지 이벤트 분석
incus exec openappsec-agent -- grep "Web Request" /var/log/nano_agent/*.log* | tail -10 | jq '.eventData'
# 모니터링 로그 확인
incus exec openappsec-agent -- tail -20 /var/log/waf-monitor.log
# nginx 접근 로그
incus exec openappsec-oci -- tail -f /var/log/nginx/access.log
```
## 🆘 비상 대응 절차
### 긴급 상황별 대응
```bash
# 1. 오탐으로 정상 사용자 차단 시 (즉시 실행)
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh bypass
# 2. WAF 서비스 문제 시
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh restart
# 3. 심각한 서비스 장애 시
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh disable
# 4. 정상 상태로 복구
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh restore
```
### 롤백 절차
1. **백업 정책 복원**: 이전 정책 파일로 복구
2. **서비스 재시작**: WAF 서비스 재시작
3. **상태 확인**: 정상 동작 검증
4. **모니터링 강화**: 24시간 집중 관찰
## 📊 성능 모니터링
### 일일 체크리스트
- [ ] WAF 서비스 상태 정상
- [ ] 메모리 사용량 < 300MB
- [ ] 응답 시간 < 50ms
- [ ] 오탐 이벤트 < 5건/일
### 성능 측정 명령어
```bash
# 응답 시간 테스트
for i in {1..5}; do curl -w "응답시간: %{time_total}s\n" -s -o /dev/null "http://10.90.135.233/health"; done
# 동시 연결 처리 테스트
time (seq 1 50 | xargs -n1 -P10 -I{} curl -s -o /dev/null "http://10.90.135.233/health" 2>/dev/null)
# 메모리 사용량 상세 확인
incus exec openappsec-agent -- ps -eo pid,rss,vsz,comm,args | grep cp-nano
```
## 🔄 정책 전환 가이드
### Phase 1: Learning Mode (1-2주)
**목적**: 정상 트래픽 패턴 학습
**설정**: `detect-learn` 모드, 모든 요청 로깅
**모니터링**: 일일 로그 분석, 학습 진행도 확인
```bash
# Learning 모드 적용
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/local_policy_learning.yaml
# 학습 데이터 확인
incus exec openappsec-agent -- wc -l /var/log/nano_agent/*handler*.log*
```
### Phase 2: High Confidence (테스트)
**목적**: 고신뢰도 탐지만 차단, 오탐 최소화
**기준**: 일일 요청 1000+, 안정적 패턴 확립
```bash
# High Confidence 모드 적용
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/local_policy_high_confidence.yaml
```
**전환 조건**:
- ✅ 7-14일간 안정적 학습 데이터 축적
- ✅ 일일 오탐률 < 1%
- ✅ 모든 핵심 기능 정상 접근 확인
- ✅ 사용자 컴플레인 없음
### Phase 3: Production (운영)
**목적**: 전체 보안 기능 활성화
**설정**: `prevent` 모드, Exception 규칙 적용
## 🔍 트러블슈팅
### 일반적인 문제
**1. WAF 서비스 응답 없음**
```bash
# 프로세스 확인
incus exec openappsec-agent -- ps aux | grep cp-nano
# 포트 확인
incus exec openappsec-agent -- netstat -tlnp | grep 1200
# 재시작
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh restart
```
**2. 높은 오탐률**
```bash
# 최근 차단 이벤트 분석
incus exec openappsec-agent -- grep "Prevent" /var/log/nano_agent/*.log* | tail -20
# Learning 모드로 임시 전환
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh bypass
# Confidence 임계값 조정 (high로 변경)
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --apply-policy /etc/cp/conf/local_policy_high_confidence.yaml
```
**3. 성능 저하**
```bash
# 메모리 사용량 확인
incus exec openappsec-agent -- free -h
incus exec openappsec-agent -- ps aux --sort=-%mem | head -10
# 로그 파일 크기 확인
incus exec openappsec-agent -- du -sh /var/log/nano_agent/
# 오래된 로그 정리
incus exec openappsec-agent -- find /var/log/nano_agent -name "*.log*" -mtime +3 -delete
```
## 📈 보안 이벤트 분석
### 이벤트 타입별 분석
```bash
# XSS 공격 탐지 현황
incus exec openappsec-agent -- grep "Cross Site Scripting" /var/log/nano_agent/*.log* | wc -l
# SQL Injection 탐지 현황
incus exec openappsec-agent -- grep "SQL Injection" /var/log/nano_agent/*.log* | wc -l
# 신뢰도별 이벤트 분석
incus exec openappsec-agent -- grep "eventConfidence" /var/log/nano_agent/*.log* | jq -r '.eventData.eventConfidence' | sort | uniq -c
```
### 공격자 IP 분석
```bash
# 최다 차단 IP 확인
incus exec openappsec-agent -- grep "sourceIP" /var/log/nano_agent/*.log* | jq -r '.eventData.sourceIP' | sort | uniq -c | sort -nr | head -10
# 특정 IP 차단 이력
incus exec openappsec-agent -- grep "1.2.3.4" /var/log/nano_agent/*.log* | jq '.eventData'
```
## 🔐 보안 정책 튜닝
### Exception 규칙 추가
```yaml
# /etc/cp/conf/local_policy_with_exceptions.yaml 수정 예시
exceptions:
- rule-id: "admin-panel"
uri-prefix: "/admin"
source-ip: ["10.90.135.0/24", "192.168.1.0/24"]
- rule-id: "api-endpoints"
uri-prefix: "/api"
specific-protections: ["csrf-protection"]
- rule-id: "file-upload"
uri-prefix: "/upload"
specific-protections: ["open-redirect"]
```
### Confidence 임계값 조정
- `low`: 모든 의심 활동 탐지 (높은 오탐)
- `medium`: 균형잡힌 탐지 (권장)
- `high`: 고신뢰도만 탐지 (낮은 오탐)
- `critical`: 매우 확실한 공격만 탐지
## 📅 정기 점검 일정
### 일일 (평일 오전 9시)
- WAF 서비스 상태 확인
- 전날 보안 이벤트 검토
- 메모리/CPU 사용량 확인
### 주간 (매주 월요일)
- 오탐 패턴 분석
- 성능 지표 리뷰
- 로그 용량 관리
### 월간 (매월 첫째 주)
- 전체 보안 정책 검토
- Exception 규칙 업데이트
- 백업 및 복구 테스트
- 보안 이벤트 통계 리포트
## 📞 에스컬레이션 연락처
**Level 1**: 일반 운영 이슈
**Level 2**: 보안 이벤트 급증
**Level 3**: 서비스 전면 장애
---
**문서 최종 업데이트**: 2025-08-17
**다음 검토 예정일**: 2025-09-17
## 🔖 빠른 참조
### 자주 사용하는 명령어
```bash
# 상태 확인
incus exec openappsec-agent -- /etc/cp/scripts/open-appsec-ctl.sh --status
# 비상 bypass
incus exec openappsec-agent -- /usr/local/bin/waf-emergency.sh bypass
# 로그 확인
incus exec openappsec-agent -- tail -f /var/log/nano_agent/cp-nano-http-transaction-handler.log1
# 성능 테스트
curl -w "응답시간: %{time_total}s\n" -s -o /dev/null "http://10.90.135.233/health"
```
### 정책 파일 경로 요약
- Learning: `/etc/cp/conf/local_policy_learning.yaml`
- High Confidence: `/etc/cp/conf/local_policy_high_confidence.yaml`
- Production: `/etc/cp/conf/production_policy.yaml`
- With Exceptions: `/etc/cp/conf/local_policy_with_exceptions.yaml`