runbooks/OpenAppSec_WAF_Operations_Guide.md

# 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`