퀵스타트 및 실행 레시피

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

Release: v2.3.0 NPM Version PyPI Version Security Guard License
Documentation Correction Notice

An earlier version of this page showed fabricated code samples (sentinel.middleware(), a non-existent Python amv_sentinel.SentinelMiddleware FastAPI integration, and a non-existent window.SentinelClient.generateAttestationToken() browser global). The recipes below call the real exported API — see the API Reference for full signatures.

1. Serverless API Handler (Node.js / Vercel-style, as actually used in production)

This mirrors the real integration in this site's own api/sentinel.js:

import { createSentinel, MemoryRiskEventStore, MemoryCounterStore } from 'amv-sentinel';

const eventStore = new MemoryRiskEventStore({ maxItems: 1000 });
const counterStore = new MemoryCounterStore();

// IP fallback is required: without a rateKeyProvider, requests with no
// session identifier never get burst-counted (see API Reference §4).
function deriveRateKey(req) {
  if (req.sessionId) return `sess_${req.sessionId}`;
  const ip = String(req.headers['x-forwarded-for'] || req.headers['x-real-ip'] || '').split(',')[0].trim();
  return ip ? `ip_${ip}` : null;
}

const sentinel = createSentinel({
  mode: 'enforce',         // 'shadow' computes but never blocks
  eventStore,
  counterStore,
  rateKeyProvider: deriveRateKey
});

export default async function handler(req, res) {
  const report = await sentinel.score(req);

  if (report.action === 'TEMPORARY_DENY') return res.status(403).json({ status: 'denied', traceId: report.traceId });
  if (report.action === 'RATE_LIMIT') return res.status(429).json({ status: 'rate_limited', traceId: report.traceId });

  return res.status(200).json({ status: 'ok', report });
}

2. Edge Middleware (per-request gate before your handler runs)

The SDK's score() call does I/O (counter increment, optional DB write) and is not meant to run on every static asset request. On this site, cheap pattern-based checks (bot UA, SQLi/XSS/probe signatures, IP-keyed rate limiting) run first in middleware.js at the edge; the full SDK scoring in api/sentinel.js runs only for requests that explicitly report telemetry. If your integration needs the SDK's score to gate page requests directly, call sentinel.score(req) from your own edge/middleware layer rather than assuming the two are automatically wired together — they are separate call sites.

// Minimal illustrative pattern — adapt to your framework's middleware API
import { createSentinel } from 'amv-sentinel';
const sentinel = createSentinel({ mode: 'enforce', rateKeyProvider: (req) => req.ip });

export async function middleware(req) {
  const report = await sentinel.score(req);
  if (report.action === 'TEMPORARY_DENY' || report.action === 'RATE_LIMIT') {
    return new Response('Blocked', { status: report.action === 'RATE_LIMIT' ? 429 : 403 });
  }
  // allow through
}

3. Verified Collector Tokens (optional, cryptographic client attestation)

If you want a client to cryptographically attest telemetry (rather than sending plain, spoofable signal booleans), sign a token server-side or in a trusted context and verify it on ingest:

import { signCollectorToken, verifyCollectorToken, StaticKeyResolver } from 'amv-sentinel';

const keyResolver = new StaticKeyResolver({ keyId: 'k1', secret: process.env.SENTINEL_HMAC_SECRET });

// Issue (trusted context only — never expose the secret to the browser):
const token = await signCollectorToken({ aud: 'my-app', purpose: 'telemetry-collect' }, keyResolver.getSigningKey());

// On the collecting endpoint, createSentinel({ keyResolver, expectedAudience: 'my-app', ... })
// will verify any token presented via the Authorization: Bearer header automatically inside score().

4. SentinelAction Reference (what report.action can be)

ActionMeaningTypical response
ALLOWClean request200, proceed
OBSERVELogged only — always the result of anything non-ALLOW while mode: 'shadow'200, proceed, but record for review
RATE_LIMITBurst threshold exceeded for the rate key429 with Retry-After
REQUIRE_APP_VERIFICATIONPolicy requires a verified collector token that is missing/invalid403 or a verification challenge flow
TEMPORARY_DENYScore crossed the deny threshold with non-passive evidence403
REDIRECTRouted to a configured destination instead of blocked302/307