GitHub Webhook 이벤트 보안 강화 및 배포 전략

GitHub Webhook 이벤트 보안 강화 및 배포 전략

이전 글에서는 Webhook 이벤트 최적화 및 로깅 시스템 구축을 다뤘습니다.
이번 글에서는 Webhook 보안을 강화하고, 안전한 배포 및 운영 전략을 구축하는 방법을 설명합니다.

---

1. Webhook 보안 강화의 필요성

GitHub Webhook은 공개된 엔드포인트에서 요청을 수신하기 때문에 보안 설정이 없으면 악의적인 요청을 허용할 위험이 있습니다.
이를 방지하기 위해 다음과 같은 보안 강화 전략이 필요합니다.

✅ Webhook 보안 강화 전략

✔️ 요청 서명(Signature) 검증 – GitHub이 전송한 요청인지 확인
✔️ IP 화이트리스트 적용 – GitHub Webhook 서버에서 온 요청만 허용
✔️ Rate Limiting(요청 제한) – 과도한 요청으로 서버가 다운되지 않도록 보호
✔️ HTTPS 사용 – Webhook 엔드포인트에서 SSL/TLS 암호화 적용

---

2. GitHub Webhook 요청 서명(Signature) 검증

GitHub Webhook은 X-Hub-Signature-256 헤더를 포함하여 요청을 서명합니다.
이를 검증하면 Webhook 요청이 GitHub에서 보낸 정당한 요청인지 확인할 수 있습니다.

🔹 2-1. HMAC 서명 검증을 위한 코드 추가

📌 src/utils/verifySignature.ts

import * as crypto from 'crypto';

export function verifySignature(payload: string, signature: string, secret: string): boolean {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload, 'utf-8');
  const expectedSignature = `sha256=${hmac.digest('hex')}`;
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
}

---

🔹 2-2. Webhook 컨트롤러에서 서명 검증 적용

반응형

📌 src/webhook/webhook.controller.ts

import { Controller, Post, Headers, Body, BadRequestException } from '@nestjs/common';
import { verifySignature } from '../utils/verifySignature';

const GITHUB_SECRET = process.env.GITHUB_SECRET || 'your_secret_key';

@Controller('webhook')
export class WebhookController {
  @Post()
  handleWebhook(
    @Headers('x-hub-signature-256') signature: string,
    @Body() payload: any,
  ) {
    const payloadString = JSON.stringify(payload);

    if (!verifySignature(payloadString, signature, GITHUB_SECRET)) {
      throw new BadRequestException('Invalid signature');
    }

    console.log(`✅ Valid Webhook Event received.`);
    return { message: 'Webhook processed successfully' };
  }
}

💡 GitHub Webhook 요청이 올바른 서명을 포함하지 않으면 요청을 거부합니다.

---

3. GitHub Webhook IP 화이트리스트 적용

GitHub Webhook 요청은 특정한 IP 범위에서만 들어옵니다.
따라서 화이트리스트를 설정하여 GitHub에서 오는 요청만 허용할 수 있습니다.

🔹 3-1. GitHub Webhook의 공식 IP 주소 확인

GitHub Webhook의 공식 IP 주소 목록은 GitHub Meta API를 사용하여 확인할 수 있습니다.

curl -s https://api.github.com/meta | jq '.hooks'

💡 hooks 필드에 Webhook 요청이 오는 IP 목록이 포함되어 있습니다.

---

🔹 3-2. IP 화이트리스트 필터 적용

📌 src/middleware/ipFilter.middleware.ts

import { Injectable, NestMiddleware, ForbiddenException } from '@nestjs/common';
import * as axios from 'axios';

@Injectable()
export class IpFilterMiddleware implements NestMiddleware {
  private allowedIps: string[] = [];

  constructor() {
    this.loadAllowedIps();
  }

  async loadAllowedIps() {
    const response = await axios.default.get('https://api.github.com/meta');
    this.allowedIps = response.data.hooks;
  }

  use(req, res, next) {
    const requestIp = req.ip;

    if (!this.allowedIps.includes(requestIp)) {
      throw new ForbiddenException(`Unauthorized IP: ${requestIp}`);
    }

    next();
  }
}

💡 GitHub Webhook의 공식 IP 목록을 불러와서 허용된 IP만 요청을 처리하도록 설정합니다.

---

4. Webhook 요청 Rate Limiting 적용

Rate Limiting을 적용하면 너무 많은 Webhook 요청이 한 번에 발생하는 것을 방지할 수 있습니다.
이를 위해 Express Rate Limit을 적용합니다.

🔹 4-1. express-rate-limit 설치

npm install express-rate-limit

🔹 4-2. Rate Limiting 미들웨어 적용

📌 src/middleware/rateLimit.middleware.ts

import { Injectable, NestMiddleware } from '@nestjs/common';
import * as rateLimit from 'express-rate-limit';

@Injectable()
export class RateLimitMiddleware implements NestMiddleware {
  use(req, res, next) {
    rateLimit({
      windowMs: 1 * 60 * 1000, // 1분
      max: 100, // 분당 최대 100건의 요청 허용
      message: 'Too many requests, please try again later.',
    })(req, res, next);
  }
}

💡 Rate Limiting을 적용하여 과도한 요청으로 서버가 다운되는 것을 방지합니다.

---

5. Webhook 서버의 보안 강화를 위한 배포 전략

Webhook 서버를 운영할 때 보안 강화를 위해 HTTPS 적용 및 배포 환경 보호가 필요합니다.

🔹 5-1. Nginx를 활용한 HTTPS 적용

📌 nginx.conf 설정 예시

server {
    listen 443 ssl;
    server_name webhook.example.com;

    ssl_certificate /etc/letsencrypt/live/webhook.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webhook.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

💡 Nginx를 활용하여 Webhook 서버를 SSL/TLS(HTTPS)로 보호합니다.

---

🔹 5-2. Docker 기반 배포

Webhook 서버를 Docker 컨테이너로 배포하여 운영 환경을 더욱 안전하게 만들 수 있습니다.

📌 Dockerfile 작성

FROM node:18
WORKDIR /app
COPY . .
RUN npm install
CMD ["npm", "run", "start"]
EXPOSE 3000

📌 docker-compose.yml 작성

version: '3'
services:
  webhook-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - GITHUB_SECRET=your_secret_key
      - GITHUB_TOKEN=your_github_token

💡 Webhook 서버를 Docker 컨테이너로 실행하면 일관된 환경에서 보안 유지가 가능합니다.

---

6. 마무리 및 다음 글 예고

이번 글에서는 GitHub Webhook 보안 강화를 위한 서명 검증, IP 화이트리스트 적용, Rate Limiting, HTTPS 설정 및 배포 전략을 다뤘습니다.
다음 글에서는 Webhook 이벤트 활용 사례 및 실전 프로젝트 적용 방법을 다룰 예정입니다! 🚀