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)

# 정책 파일들
/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)

# nginx 설정
/etc/nginx/conf.d/production.conf           # 운영 환경 설정
/etc/nginx/conf.d/default.conf              # 기본 설정 (백업)

# 로그 파일
/var/log/nginx/access.log
/var/log/nginx/error.log

🚀 일상 운영 명령어

상태 확인

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

정책 관리

# 정책 변경 (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

로그 모니터링

# 실시간 보안 이벤트 확인
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

🆘 비상 대응 절차

긴급 상황별 대응

# 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건/일

성능 측정 명령어

# 응답 시간 테스트
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 모드, 모든 요청 로깅
모니터링: 일일 로그 분석, 학습 진행도 확인

# 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+, 안정적 패턴 확립

# 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 서비스 응답 없음

# 프로세스 확인
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. 높은 오탐률

# 최근 차단 이벤트 분석
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. 성능 저하

# 메모리 사용량 확인
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

📈 보안 이벤트 분석

이벤트 타입별 분석

# 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 분석

# 최다 차단 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 규칙 추가

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

🔖 빠른 참조

자주 사용하는 명령어

# 상태 확인
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