@tumen-security/guard — 실시간 방어 미들웨어

Tumen Security의 ① 실시간 방어. AI로 앱 만든 비개발자를 위한 zero-dependency 런타임 보안 미들웨어입니다. Aikido Zen의 무료 라이트 버전 격.

내 Express / Next.js 앱에 한 줄 넣으면, 들어오는 요청을 실시간으로 검사해서 흔한 공격을 잡아냅니다.

• 공격 페이로드 탐지: SQL 인젝션, NoSQL 인젝션, 명령어 인젝션, 경로 탐색(path traversal), 반사형 XSS
• 레이트리밋: IP별 슬라이딩 윈도우(인메모리, 의존성 0)
• 스캐너 차단: sqlmap, nikto, nmap 등 악성 스캐너 User-Agent(옵션)
• 두 가지 모드: monitor(로깅만, 기본값) / block(차단 + 429/403)
• 절대 앱을 안 깨뜨림: 내부 오류는 전부 fail-open(요청 통과)

설치

npm i @tumen-security/guard

의존성이 없습니다(Node 내장 모듈만 사용). Express/Next는 여러분 앱에 이미 있는 걸 씁니다(peer, 강제 설치 안 함).

Express

import express from 'express';
import { guard } from '@tumen-security/guard';

const app = express();
app.use(express.json());   // body 검사를 원하면 body 파서를 guard보다 먼저

app.use(guard({
  mode: 'monitor',                 // 처음엔 monitor로 오탐 확인 → 익숙해지면 'block'
  apiKey: process.env.TUMEN_GUARD_API_KEY,     // 대시보드에서 발급
  reportUrl: 'https://tumensecurity.com/api/guard/events',
  rateLimit: { windowMs: 60_000, max: 100 }, // 1분에 100요청 초과 시 429
  blockScanners: true,             // sqlmap 등 스캐너 UA 차단
  onDetect: (event) => {           // 내 로깅에 꽂기(선택)
    console.warn('[tumen-guard]', event.decision, event.findings.map(f => f.kind));
  },
}));

CommonJS도 됩니다: const { guard } = require('@tumen-security/guard');

Next.js (App Router)

(A) middleware.js

import { NextResponse } from 'next/server';
import { nextGuard } from '@tumen-security/guard';

const runGuard = nextGuard({
  mode: 'block',
  apiKey: process.env.TUMEN_GUARD_API_KEY,
  reportUrl: 'https://tumensecurity.com/api/guard/events',
  // NextResponse는 여러분 앱 것을 주입(패키지가 next를 직접 import하지 않음)
  denyResponse: (code, body) => NextResponse.json(body, { status: code }),
});

export function middleware(request) {
  return runGuard(request) || NextResponse.next();
}

export const config = { matcher: ['/api/:path*'] };

(B) route handler 감싸기

import { NextResponse } from 'next/server';
import { wrapGuard } from '@tumen-security/guard';

async function handler(request) {
  return NextResponse.json({ ok: true });
}

export const POST = wrapGuard(handler, {
  mode: 'block',
  denyResponse: (code, body) => NextResponse.json(body, { status: code }),
});

Next의 Edge 미들웨어/Web Request는 body가 스트림이라 body는 기본 검사 안 함(url·query·headers만). body 검사가 필요하면 route handler에서 파싱 후 inspectRequest()를 직접 부르세요(아래).

옵션

| 옵션 | 기본값 | 설명 | |---|---|---| | mode | 'monitor' | 'monitor'=로깅만·통과, 'block'=차단 | | apiKey | null | 고객별 발급 키(보고에 사용) | | reportUrl | null | 이벤트 수신 엔드포인트 | | rateLimit | {windowMs:60000, max:100} | IP별 창/최대 | | rules | 전부 true | { payload, rateLimit, scanner } 개별 토글 | | blockScanners | false | 스캐너 UA를 실제 차단(false면 탐지만) | | trustProxy | true | x-forwarded-for에서 IP 추출 | | statusCode | 403 | 공격 차단 시 코드(레이트리밋은 항상 429) | | onDetect | null | (event) => void 탐지 콜백 | | report | true | 우리 서비스로 이벤트 보고 |

순수 함수 직접 쓰기

미들웨어 없이 판정 로직만 쓸 수도 있습니다(테스트/커스텀 통합).

import { detectAttacks, inspectRequest, RateLimiter } from '@tumen-security/guard/lib';

detectAttacks({ query: { id: "1' OR '1'='1" } });
// → [{ tool:'guard', kind:'sqli', severity:'high', rule_id:'guard-sqli', ... }]

안전 원칙

• 기본 monitor: 오탐으로 여러분 앱 사용자를 막지 않습니다. 로그로 먼저 확인하세요.
• fail-open: 미들웨어 내부에서 뭐가 터져도 요청은 통과하고 next()가 호출됩니다.
• 보고는 fire-and-forget: 우리 서버로의 이벤트 전송은 응답을 기다리지 않습니다(지연 0, 실패해도 무시).
• 개인정보 최소화: 보고 시 IP 마스킹, 쿼리스트링 제거, 시크릿 패턴 별표 처리.

테스트

node --test packages/guard/lib.test.mjs