Skip to content

LogPipeline Development Guide

Jump to bottom
seungwon9201 edited this page Aug 20, 2025 · 1 revision

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에서 조정

Clone this wiki locally