NetSentryx PRO 🛡️

AI 기반의 고성능 실시간 네트워크 관측 및 위협 탐지 엔진

NetSentryx PRO는 차세대 이벤트 기반 네트워크 모니터링 및 위협 인텔리전스 플랫폼입니다. 규칙 기반 시그니처와 PyTorch 딥 오토인코더를 결합하여 10ms 미만의 패킷 및 넷플로우 이상 탐지, 자동화된 다중 채널 경고(Slack, Discord, Email), 그리고 대화형 실시간 SOC 대시보드를 제공합니다.

🏗️ 시스템 아키텍처

다음 흐름 다이어그램은 데이터 수집, 실시간 딥러닝 추론, 경고 파이프라인, 그리고 WebSocket 시각화 계층을 보여줍니다:

flowchart TD
    subgraph Capture & Ingestion
        A[Network Interface / Packet Simulator] -->|Raw Traffic Events| B(Lightweight Event Bus)
        B -->|Packet Stream| C[Flow Aggregation Engine]
    end

    subgraph Deep Learning Inference
        C -->|Aggregated Telemetry Vectors| D[PyTorch TrafficAutoencoder]
        D -->|MSE Reconstruction Loss| E{Threshold Evaluation}
    end

    subgraph Alert Dispatch
        E -->|No Anomaly| F[Status: Optimal]
        E -->|Anomaly Detected| G[FastAPI BackgroundTasks]
        G -->|Save Event| H[(SQLite Datastore)]
        G -->|Broadcast WebSocket| I[HTML Live Dashboard]
        G -->|Dispatch Webhooks| J[Slack / Discord / Custom Webhook]
        G -->|Dispatch SMTP| K[Email Alerting]
    end

    style D fill:#EE4C2C,stroke:#fff,stroke-width:2px,color:#fff
    style I fill:#005571,stroke:#fff,stroke-width:2px,color:#fff
    style G fill:#00bf8f,stroke:#fff,stroke-width:2px,color:#fff

🚀 주요 기능

⚡ 실시간 트래픽 수집: 최소한의 지연으로 패킷 프레임을 풍부한 넷플로우 요약으로 즉시 집계합니다.
🧠 PyTorch 딥 오토인코더 이상 탐지: 경량 PyTorch 신경망(TrafficAutoencoder)을 활용하여 다변량 특징 재구성 오류를 기반으로 정교한 제로데이 익스플로잇, 스캐닝 또는 DDoS 공격을 탐지합니다.
📈 수동 학습 없는 시작: 서버 시작 시 자동화된 합성 피팅 및 통계적 임계값 보정(Mean + 3 * Std)을 제공하여 즉시 사용 가능합니다.
⏱️ 10ms 미만 추론 지연: 최적화된 추론 파이프라인으로 고처리량 패킷 흐름의 실시간 평가를 보장합니다.
📣 다중 채널 경고 발송: FastAPI의 BackgroundTasks를 사용하여 상세한 침입 경고를 Slack 웹훅, Discord 웹훅, 사용자 정의 HTTP API, SMTP 이메일로 비동기적으로 푸시합니다.
📊 대화형 SOC 대시보드: Tailwind CSS, Chart.js, WebSockets 기반의 우아한 다크 모드 대시보드로 처리량 지표와 실시간 위협 피드를 시각화합니다.

📁 프로젝트 구조

NetSentryx/
├── config/
│   ├── config.yaml          # System, dashboard, and alerting channel configurations
│   └── rules.yaml           # Threat detection thresholds and rule properties
├── src/
│   ├── alerts/
│   │   ├── ml_detection.py  # PyTorch TrafficAutoencoder & feature scaling
│   │   ├── manager.py       # Async alert dispatcher (Discord, Slack, Email)
│   │   └── detection.py     # Rule-based packet signature detection engine
│   ├── core/
│   │   ├── config_loader.py # Configuration loader utilities
│   │   ├── logger.py        # Database-integrated system logger
│   │   └── time_utils.py    # Timezone-aware timestamp utilities
│   ├── dashboard/
│   │   ├── templates/
│   │   │   └── index.html   # Live HTML5 Dashboard template
│   │   └── server.py        # FastAPI API Router and WebSocket broadcast controller
│   ├── database/
│   │   ├── manager.py       # SQLite connection & database actions
│   │   └── models.py        # SQLAlchemy schema definitions (Alerts, Logs, Flows)
│   ├── flows/
│   │   ├── capture.py       # Scapy packet sniffer thread
│   │   └── processor.py     # Flow aggregation and metric extractor
│   └── main.py              # Application entrypoint
└── main.py                  # Root script runner

🛠️ 빠른 시작 및 설정 가이드

1. 사전 요구 사항

**Python 3.10+**이 설치되어 있는지 확인하세요. 라이브 네트워크 인터페이스를 캡처하는 경우:

Windows: Npcap을 설치하세요 ("Install Npcap in WinPcap API-compatible Mode" 선택).
Linux: sudo apt-get install libpcap-dev를 통해 libpcap-dev를 설치하세요.

2. 설치

저장소를 복제하고 종속성을 설치하세요 (더 빠른 설치를 위해 uv 사용을 적극 권장합니다):

# Clone the repository
git clone https://github.com/yourusername/netsentryx.git
cd netsentryx

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install requirements
pip install -r requirements.txt

3. 환경 설정 (`.env`)

알림 자격 증명을 구성하려면 프로젝트 루트에 .env 파일을 생성하세요:

# Discord Configuration
DISCORD_ENABLED=true
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/your-webhook-id/your-webhook-token"

# Slack Configuration
SLACK_ENABLED=true
SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR_WORKSPACE_ID/YOUR_CHANNEL_ID/YOUR_SECRET_TOKEN"

# SMTP Email Configuration
SMTP_ENABLED=true
SMTP_SERVER="smtp.gmail.com"
SMTP_PORT=587
SMTP_USERNAME="[email protected]"
SMTP_PASSWORD="your-app-password"
SMTP_FROM_EMAIL="[email protected]"
SMTP_TO_EMAIL="[email protected]"

4. 플랫폼 실행

🧪 시뮬레이션 모드 (합성 트래픽 시뮬레이터 포함)

python main.py --simulate

🌐 라이브 스니핑 모드 (관리자/sudo 권한 필요)

python main.py

브라우저를 열고 http://localhost:8000으로 이동하여 라이브 대시보드를 확인하세요.

📖 API 문서

텔레메트리 및 추론 엔드포인트

URL: /api/v1/telemetry/analyze
Method: POST
Content-Type: application/json

요청 페이로드

{
  "packet_count": 550,
  "byte_count": 850000,
  "flow_duration": 4.5,
  "syn_flag_ratio": 0.85,
  "port_entropy": 3.2,
  "byte_rate": 188888.8,
  "source_ip": "192.168.1.120",
  "dest_ip": "10.0.0.5",
  "protocol": "TCP"
}

응답 (정상 트래픽)

{
  "status": "NORMAL",
  "threat_level": "low",
  "anomaly_score": 0.3083,
  "threshold": 2.1319
}

응답 (이상 트래픽)

{
  "status": "ANOMALOUS",
  "threat_level": "critical",
  "anomaly_score": 117999.03,
  "threshold": 2.1319,
  "alert": {
    "id": 12,
    "timestamp": "2026-08-05T14:13:31.373Z",
    "rule_id": "ml_autoencoder_anomaly",
    "rule_name": "ML Autoencoder Anomaly",
    "source_ip": "192.168.1.120",
    "severity": "critical",
    "description": "Deep autoencoder reconstruction error exceeded anomaly threshold (score: 117999.0300, threshold: 2.1320).",
    "metrics": { ... }
  }
}

이력 쿼리

🛡️ 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

`/api/alerts`	`GET`	Fetches recent threat alerts saved in DB	`[{"id": 1, "rule_name": "Port Scanning", ...}]`
`/api/flows`	`GET`	Fetches recent network flow telemetry logs	`[{"source_ip": "192.168.1.10", "packet_count": 45, ...}]`
`/api/logs`	`GET`	Fetches backend system audit logs	`[{"level": "INFO", "message": "ML engine trained...", ...}]`

netsentryx

인기