LogPipeline Development Guide

AI Log Anomaly Detection API

개요

웹 서버 로그의 이상 행동을 탐지하는 AI 기반 API 시스템입니다. Isolation Forest 알고리즘을 사용하여 실시간으로 로그를 분석하고 이상 점수를 계산합니다.

프로젝트 구조

app/
├── main.py                 # FastAPI 메인 애플리케이션
├── api/
│   └── predict.py         # 예측 API 엔드포인트
├── core/
│   ├── model.py          # 모델 로딩 함수
│   ├── scaler.py         # 점수 스케일링 함수
│   └── ioc.py            # IoC 패턴 로딩
├── utils/
│   └── parser.py         # 로그 파싱 유틸리티
└── model/
    ├── isolation_model.pkl    # 훈련된 Isolation Forest 모델
    ├── features.pkl          # 피처 리스트
    ├── method_cols.pkl       # HTTP 메서드 컬럼 정보
    ├── ioc_keywords.pkl      # IoC(Indicator of Compromise) 키워드
    └── scaler_params.json    # 점수 스케일링 파라미터

notebook/
└── *.ipynb               # 모델 훈련 및 실험 노트북

주요 기능

1. 로그 이상 탐지

• 알고리즘: Isolation Forest
• 입력: 웹 서버 로그 (JSON 형태)
• 출력: 이상 점수 (0-100, 높을수록 정상)

2. 피처 추출

추출되는 주요 피처들:

• URL 관련: 길이, 깊이, 쿼리 파라미터 존재 여부, 특수 문자 개수
• User-Agent 관련: 길이
• HTTP 상태: 상태 코드
• 크기: 응답 바이트 수
• Referer: 존재 여부
• IoC 탐지: URL/User-Agent에서 의심스러운 패턴 개수
• HTTP 메서드: One-hot 인코딩

3. IoC (Indicator of Compromise) 탐지

사전 정의된 악성 패턴들을 탐지:

• URL에서 발견되는 의심스러운 키워드
• User-Agent에서 발견되는 의심스러운 패턴

API 사용법

엔드포인트

POST /score

요청 형식

Content-Type: application/json Content-Encoding: gzip (선택사항)

단일 로그 객체

{
  "method": "GET",
  "url": "/index.html",
  "statusCode": 200,
  "bytesSent": 1024,
  "referer": "https://example.com",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

단일 원소 배열 (허용됨)

[
  {
    "method": "GET",
    "url": "/index.html",
    "statusCode": 200,
    "bytesSent": 1024,
    "referer": "https://example.com",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }
]

응답 형식

{
  "score": 85.43
}

점수 해석

• 0-60: 정상적인 활동
• 60-70: 약간 의심스러운 활동
• 70-100: 매우 위험한 활동

설치 및 실행

요구사항

pip install fastapi uvicorn scikit-learn joblib numpy requests

실행

uvicorn app.main:app --host 0.0.0.0 --port 8000

헬스 체크

curl http://localhost:8000/
# 응답: {"message": "AI Log API is running"}

내부 구조

1. 모델 로딩 (app/core/model.py)

서버 시작 시 다음 파일들을 로드:

• isolation_model.pkl: 훈련된 Isolation Forest 모델
• features.pkl: 피처 순서 정보
• method_cols.pkl: HTTP 메서드 원-핫 인코딩 컬럼 정보

2. 점수 스케일링 (app/core/scaler.py)

Isolation Forest의 raw decision function 값을 0-100 스케일로 변환:

def scale_score(raw_score, score_min, score_max):
    raw_score = np.clip(raw_score, score_min, score_max)
    norm_score = (raw_score - score_min) / (score_max - score_min)
    inverted_score = 1 - norm_score  # 높은 값 = 정상
    return round(inverted_score * 100, 2)

3. IoC 패턴 매칭 (app/core/ioc.py)

사전 정의된 악성 패턴들과 매칭하여 추가 피처 생성

4. 외부 API 연동

점수 계산 후 http://127.0.0.1:9000/api/logs로 결과 전송 (선택사항)

에러 처리

클라이언트 에러 (4xx)

• 400 Bad Request: 잘못된 JSON 형식 또는 다중 로그 배열
• 422 Unprocessable Entity: 필수 필드 누락

서버 에러 (5xx)

• 500 Internal Server Error: 모델 예측 실패 또는 내부 처리 오류

필수 필드

모든 요청에 다음 필드들이 반드시 포함되어야 함:

• method
• url
• statusCode
• bytesSent
• referer
• userAgent

개발 노트

모델 훈련

• notebook/ 디렉토리에 모델 훈련 과정이 담긴 Jupyter 노트북들이 있음
• 새로운 데이터로 모델을 재훈련할 때 해당 노트북들을 참고

성능 최적화

• 모델과 피처 정보는 서버 시작 시 한 번만 로드
• 스레드 안전성을 위한 Lock 사용
• gzip 압축 지원으로 네트워크 효율성 개선

확장성

• 새로운 IoC 패턴은 ioc_keywords.pkl 파일에 추가
• 새로운 피처는 extract_features() 함수에서 구현
• 스케일링 파라미터는 scaler_params.json에서 조정