runbooks/openappsec-setup-20250817.md

OpenAppSec Separate Container 구성 완료 보고서

📋 프로젝트 개요

목표: OpenAppSec을 incus 환경에서 Separate Container 방식으로 구성하여 1000명 동시접속 처리

완료일: 2025-08-17
환경: incus 컨테이너 플랫폼, 8코어 CPU, 15.6GB RAM

---

🏗️ 최종 아키텍처

Separate Container 구조

Client Request
    ↓
nginx-attachment (10.90.135.233)
    ↓ (Unix Socket via /dev/shm)
OpenAppSec Agent (10.90.135.243)
    ↓ (ML Security Analysis)
Backend Decision (Allow/Block)
    ↓
Caddy Server (10.90.135.16)

컨테이너 구성

컨테이너명	이미지	IP 주소	역할	리소스
openappsec-oci	ghcr.io/openappsec/nginx-attachment:latest	10.90.135.233	nginx + attachment	4 CPU, 4GB RAM
openappsec-agent	ghcr.io/openappsec/agent:latest	10.90.135.243	ML 보안 엔진	4 CPU, 4GB RAM

---

🔧 핵심 설정

1. IPC 통신 구성

# 두 컨테이너 모두 호스트 IPC 네임스페이스 공유
incus config set openappsec-oci raw.lxc="lxc.namespace.share.ipc=1"
incus config set openappsec-agent raw.lxc="lxc.namespace.share.ipc=1"

# 호스트 공유 메모리 마운트
incus config set openappsec-oci raw.lxc="lxc.namespace.share.ipc=1"$'\n'"lxc.mount.entry=/dev/shm dev/shm none bind,create=dir 0 0"
incus config set openappsec-agent raw.lxc="lxc.namespace.share.ipc=1"$'\n'"lxc.mount.entry=/dev/shm dev/shm none bind,create=dir 0 0"

2. 스토리지 볼륨 구성

# 정책 파일용 영구 스토리지
incus storage volume create default appsec
incus config device add openappsec-oci appsec-volume disk pool=default source=appsec path=/ext/appsec

3. 보안 정책 설정

# /ext/appsec/local_policy.yaml
policies:
  default:
    mode: detect  # 학습 모드
    practices: [appsec-best-practice]
    triggers: [appsec-log-trigger]
    custom-response: 403-forbidden

practices:
  - name: appsec-best-practice
    web-attacks:
      minimum-confidence: medium
      override-mode: detect
      max-body-size-kb: 1000

log-triggers:
  - name: appsec-log-trigger
    appsec-logging:
      detect-events: true
      prevent-events: true
    log-destination:
      stdout:
        format: json
      file:
        path: /ext/appsec/security.log
        format: json
        max-file-size-mb: 100
        max-files: 5

---

✅ 검증 결과

1. 컨테이너 상태

$ incus list | grep openappsec
| openappsec-agent | RUNNING | 10.90.135.243 (eth0) | CONTAINER (APP) |
| openappsec-oci   | RUNNING | 10.90.135.233 (eth0) | CONTAINER (APP) |

2. IPC 통신 확인

$ incus exec openappsec-oci -- ls -la /dev/shm/check-point/
srw-rw-rw- 1 root root 0 Aug 17 06:07 cp-nano-attachment-registration
srw-rw-rw- 1 root root 0 Aug 17 06:07 cp-nano-http-transaction-handler-1
srw-rw-rw- 1 root root 0 Aug 17 06:07 cp-nano-http-transaction-handler-2
srw-rw-rw- 1 root root 0 Aug 17 06:07 cp-nano-http-transaction-handler-3
srw-rw-rw- 1 root root 0 Aug 17 06:07 cp-nano-http-transaction-handler-4

3. Agent 프로세스 확인

$ incus exec openappsec-agent -- ps aux | grep cp-nano
root  952  /etc/cp/orchestration/cp-nano-orchestration --orchestration-mode=hybrid_mode
root  985  /etc/cp/attachmentRegistrator/cp-nano-attachment-registrator
root 1036  /etc/cp/agentCache/cp-nano-agent-cache 127.0.0.1:6379

4. 네트워크 테스트

$ curl -s http://10.90.135.233/health
OCI OpenAppSec OK

$ curl -s -I http://10.90.135.233/ | grep X-Security
X-Security: OpenAppSec-OCI

---

🚀 성능 최적화

1000명 동시접속 대응 설정

nginx-attachment 최적화

# /etc/nginx/nginx.conf
worker_processes 4;           # 1000명/4 = 250명/워커
worker_connections 512;       # 안전 여유분 포함
client_body_buffer_size 64k;  # 메모리 효율성
keepalive_timeout 10s;        # 빠른 연결 회전

리소스 제한

# 각 컨테이너 4 CPU, 4GB RAM으로 제한
incus config set openappsec-oci limits.cpu=4 limits.memory=4GB
incus config set openappsec-agent limits.cpu=4 limits.memory=4GB

---

🔍 문제 해결 과정

1. 초기 문제: nginx-attachment만으로는 보안 기능 미작동

원인: attachment 모듈만 있고 실제 보안 분석을 담당하는 agent가 없음
해결: Separate Container 방식으로 agent 컨테이너 추가

2. IPC 통신 문제

원인: incus에서 lxc.namespace.share.ipc=host 문법 오류
해결: lxc.namespace.share.ipc=1 (PID 1) 사용

3. Unix Socket 공유 문제

원인: 각 컨테이너가 독립적인 tmpfs 사용
해결: 호스트 /dev/shm 디렉토리를 두 컨테이너에 바인드 마운트

---

📊 Separate Container vs Unified Container 비교

구분	Separate Container	Unified Container
구성 복잡도	높음 (2개 컨테이너)	낮음 (1개 컨테이너)
리소스 효율성	독립적 스케일링 가능	고정적 리소스 할당
장애 격리	우수 (agent 장애 시 nginx 계속 동작)	보통 (전체 장애)
업데이트 유연성	독립적 업데이트 가능	통합 업데이트 필요
성능	Unix Socket 오버헤드	프로세스 간 직접 통신
운영 복잡도	높음	낮음

---

🎯 장점 및 활용 방안

Separate Container 방식의 장점

1. 확장성

   • nginx 트래픽 증가 시: attachment 컨테이너만 스케일 아웃
   • 보안 처리 부하 증가 시: agent 컨테이너만 리소스 증설

2. 멀티 서비스 지원

   • 하나의 agent로 여러 nginx 인스턴스 처리 가능
   • 중앙 집중식 보안 정책 관리

3. 운영 유연성

   • 독립적인 업데이트 및 배포
   • 컴포넌트별 모니터링 및 로깅

향후 확장 계획

1. 고가용성 구성

   # Agent 이중화
   incus copy openappsec-agent openappsec-agent-backup
   
   # nginx-attachment 로드밸런싱
   incus copy openappsec-oci openappsec-oci-2
   

2. 모니터링 구성

   • nginx-attachment: 응답 속도, 처리량 모니터링
   • agent: 위협 탐지율, ML 정확도 모니터링

3. 보안 정책 고도화

   • 학습 모드 → 차단 모드 전환
   • 도메인별 차별화된 보안 정책

---

📋 체크리스트

필수 구성 요소

• nginx-attachment 컨테이너 (ghcr.io/openappsec/nginx-attachment:latest)
• agent 컨테이너 (ghcr.io/openappsec/agent:latest)
• IPC 네임스페이스 공유 설정
• 공유 메모리 마운트 (/dev/shm)
• 보안 정책 파일 (local_policy.yaml)
• 영구 스토리지 볼륨 (appsec)

검증 항목

• 컨테이너 정상 실행
• Unix Socket 생성 확인
• Agent 프로세스 실행 확인
• 웹 서비스 응답 확인
• 보안 헤더 확인

성능 테스트

• 기본 응답 속도 테스트
• 1000명 동접 리소스 계산
• 컨테이너 리소스 제한 설정

---

🛡️ 보안 고려사항

1. IPC 네임스페이스 공유 위험성

   • 호스트 IPC 자원에 접근 가능
   • 프로덕션 환경에서는 추가 격리 방안 검토 필요

2. 정책 파일 보안

   • /ext/appsec/local_policy.yaml 파일 권한 관리
   • 민감한 설정 정보 암호화 검토

3. 로깅 및 모니터링

   • 보안 이벤트 로그 중앙 집중화
   • 실시간 위협 탐지 알림 구성

---

📞 지원 및 문의

OpenAppSec 공식 문서: https://docs.openappsec.io/
GitHub Repository: https://github.com/openappsec/openappsec
Community Forum: https://community.openappsec.io/

---

📅 버전 정보

• OpenAppSec nginx-attachment: latest (2025-08-17)
• OpenAppSec agent: latest (2025-08-17)
• incus: 최신 버전
• nginx: 1.25.4
• 정책 파일 버전: v1.0 (detect 모드)

---

문서 작성: Claude Code SuperClaude Framework
최종 수정: 2025-08-17
상태: 구성 완료 ✅