퀵스타트 및 실행 레시피

프라이버시 우선 보안 평가 및 듀얼 런타임 미들웨어 연동 표준 코드 (AMEVA-Sentinel)

Release: v2.3.0 NPM Version PyPI Version Security Guard License
핵심 가치 제안 (Why It Matters)

개인식별정보(PII)나 마우스 좌표를 절대 수집하지 않고, 브라우저 마이크로 인터랙션 엔트로피와 암호화 토큰만으로 정상 사용자와 봇 트래픽을 단 0.25ms 만에 판별합니다.

1. Node.js / Express 미들웨어 레시피

import express from 'express';
import { Sentinel } from '@ameva/sentinel';

const app = express();
const sentinel = new Sentinel({
  secretKey: process.env.SENTINEL_SECRET || 'secret_key_prod',
  riskThreshold: 80,
  shadowMode: false
});

// 미들웨어 등록: 비정상 봇 요청 선제 차단 및 타르핏 지연
app.use(sentinel.middleware());

app.get('/api/protected', (req, res) => {
  res.json({ status: 'ok', riskScore: req.sentinel.riskScore });
});

app.listen(3000, () => console.log('Sentinel 보안 미들웨어 활성화'));

2. Python FastAPI 미들웨어 레시피

from fastapi import FastAPI, Request
from ameva_sentinel import SentinelMiddleware

app = FastAPI()

# FastAPI 미들웨어 주입
app.add_middleware(
    SentinelMiddleware,
    secret_key="prod_secret_key",
    rate_limit_window_ms=60000,
    risk_threshold=80
)

@app.get("/api/data")
async def get_data(request: Request):
    return {"message": "정상 인증 통과", "risk": request.state.risk_score}

3. 브라우저 클라이언트 SDK 레시피 (Telemetry)

<script src="https://uno-km.vercel.app/lib/sentinel/sentinel.js"></script>
<script>
  // 좌표 수집 없는 순수 인터랙션 지터 엔트로피 토큰 생성
  const token = window.SentinelClient.generateAttestationToken();
  
  // 백엔드 요청 시 X-Sentinel-Token 헤더 첨부
  fetch('/api/protected', {
    headers: { 'X-Sentinel-Token': token }
  });
</script>

4. 위협 대응 프로토콜 (Threat Response Matrix)

위협 탐지 이벤트 원인 및 이상 징후 자동 방어 조치
SHANNON_ENTROPY_COLLAPSE 헤드리스 브라우저 매크로의 기계적 직선 이동 (엔트로피 < 2.5) 위협 점수 +45 부여 및 타르핏 5,000ms 강제 지연.
HONEYPOT_TRIGGERED DOM 숨김 미끼 링크(/hidden-trap) 크롤러 탐지 클라이언트 IP 즉각 차단 및 HTTP 403 Forbidden 반환.
RATE_LIMIT_EXCEEDED 윈도우 내 요청 한도(60,000ms 내 120회) 초과 시 토큰 버킷 고갈로 HTTP 429 Too Many Requests 반환.
TOKEN_HMAC_INVALID 위변조되거나 만료된 서명 토큰 감지 시 즉각 세션 무효화 및 HTTP 401 Unauthorized 처리.