내부 API 보안 가이드라인

개발팀을 위한 보안 체크리스트, 코드 검토 관점 및 정책 템플릿을 확인하세요.

📋 개발 전 체크리스트

새 API 엔드포인트를 개발하기 전에 확인해야 할 항목입니다.

  • API 사양(OpenAPI)이 생성되었습니다.
  • 인증 및 권한 부여 방법이 결정되었습니다.
  • 입력 매개변수 유형 및 제약 조건이 정의되었습니다.
  • 응답에 포함할 필드가 명확하게 정의되었습니다.
  • 오류 응답 형식이 표준화되었습니다.
  • 요금 제한 요건이 설정되었습니다.
  • 개인 및 민감한 데이터의 취급이 확인되었습니다.
  • 인증 방법이 결정되었습니다(OAuth 2.0, JWT, API 키).
  • 각 엔드포인트에 필요한 권한(범위/역할)이 정의되었습니다.
  • 리소스 수준 권한 확인이 설계되었습니다(BOLA 대응책).
  • 관리자 기능이 명확하게 분리되어 있습니다.
  • 토큰 만료 및 새로 고침 방법이 결정되었습니다.
  • 통신은 TLS 1.2 이상을 사용합니다.
  • 저장된 데이터의 암호화 방법이 결정되었습니다.
  • 개인정보에 대한 마스킹 및 익명화 정책이 결정되었습니다.
  • 민감한 정보(토큰, 비밀번호)는 로그에 포함되지 않습니다.
  • 디버그 정보 및 스택 추적은 API 응답에 포함되지 않습니다.

👀 코드 검토 관점

API 코드 검토 시 확인해야 할 보안 관점.

항목 확인중요성설명
인증 미들웨어는 모든 엔드포인트에 적용됩니다.필수공개 API를 제외하고 누락된 인증 검사가 없는지 확인하세요.
개체 수준 권한 부여 확인이 존재합니다.필수요청된 리소스가 요청 사용자의 소유인지 확인하기
관리자 기능에는 역할 확인 기능이 있습니다.필수일반 사용자가 관리자 API를 호출할 수 없도록 하기
JWT 확인 중에 알고리즘이 지정됩니다.필수공격 방지: 공격 없음
토큰 만료가 올바르게 구성되었습니다.추천액세스 토큰: 15분 이내
항목 확인중요성설명
요청 본문에는 스키마 유효성 검사필수유형, 길이 및 형식 유효성 검사
SQL 쿼리는 매개변수화됩니다.필수쿼리가 문자열 연결로 작성되지 않았는지 확인하기
경로 매개 변수 형식 유효성 검사가 존재합니다.필수UUID와 같은 예상 형식 확인
페이지 매김 매개변수에는 상한선이 있습니다.추천limit=999999와 같은 과도한 요청 방지
파일 업로드에는 유형 및 크기 제한이 있습니다.추천콘텐츠 유형 및 파일 크기 유효성 검사
항목 확인중요성설명
응답에 불필요한 필드가 포함되지 않음필수비밀번호_해시, 내부 ID 등의 유출을 방지합니다.
오류 응답에 스택 추적이 포함되지 않음필수프로덕션 환경에서 내부 정보 노출 금지
보안 헤더가 구성되어 있습니다.추천X-콘텐츠 유형 옵션, HSTS 등
콘텐츠 유형이 올바르게 설정되었습니다.추천application/json을 명시적으로 지정
항목 확인중요성설명
속도 제한이 적용됩니다.필수특히 인증 및 결제 엔드포인트의 경우
적절한 로그가 기록되고 있습니다.추천추적 가능: 누가 언제 무엇을 했는지
비밀은 하드코딩되지 않습니다.필수환경 변수 또는 비밀 관리자 사용
CORS 설정이 적절합니다.추천와일드카드 사용 금지
종속성에는 알려진 취약점이 없습니다.추천npm 감사 결과 확인 / Snyk

📜 보안 정책 템플릿

내부 API 개발의 기본 정책을 위한 템플릿입니다. 프로젝트에 맞게 사용자 지정하세요.

1. 인증 정책

Policy템플릿
인증 방법
  - 사용자 대면 API: OAuth 2.0(인증 코드 + PKCE)
  - 서버 대 서버 API: OAuth 2.0(클라이언트 자격증명) 또는 mTLS
  - 외부 통합 API: API 키 + HMAC 서명

토큰 관리
  - 액세스 토큰 만료: 15분
  - 토큰 만료 새로 고침: 7일(로테이션 필요)
  - 토큰 저장: HttpOnly + 보안 + 동일 사이트 쿠키

비밀번호 정책
  - 최소 12자, 대문자, 소문자, 숫자 및 기호 하나 이상 포함
  - bcrypt를 사용한 해시(비용 계수 12 이상)
  - 비밀번호 목록 공격 보호(Have I Been Pwned API 통합)

2. API 설계 정책

Policy템플릿
버전 관리
  - URL 경로를 통한 버전 관리: /api/v1/resources
  - 이전 버전에 대한 지원 기간 최소 6개월
  - 사용 중단 헤더를 통한 사용 중단 알림

요금 제한(기본값)
  - 일반 API: 요청 100건/15분
  - 인증 API: 요청 5회/15분
  - 공개 API: 요청 30건/분
  - 항상 RateLimit-* 헤더 반환

응답
  - 콘텐츠 유형: 애플리케이션/json(고정)
  - RFC 7807(문제 세부 정보) 형식의 오류 응답
  - 프로덕션 환경에서 스택 추적을 반환하지 않음
  - 페이지 매김: 기본 20개 항목, 최대 100개 항목

3. 로깅 및 감사 정책

Policy템플릿
필수 로그 필드
  - 타임스탬프(ISO 8601, UTC)
  - 요청 ID(추적성을 위한 UUID)
  - 사용자 ID / API 클라이언트 ID
  - HTTP 메소드 + 엔드포인트
  - 상태 코드
  - 소스 IP
  - 응답 시간

■ 금지 로그 필드(민감한 데이터)
  - 비밀번호 / 토큰 / API 키
  - 신용카드 번호
  - 전체 PII 표시(마스킹 필요)

모니터링 알림
  - 인증 실패: 5회 이상 알림
  - 403 오류: 10+분마다 알림
  - 500 오류 1회 발생 시 즉시 알림
  - 속도 제한을 초과했습니다: 패턴 분석

🚨 인시던트 대응 흐름

1단계: 탐지

모니터링 알림, 사용자 보고서 또는 외부 알림을 통해 인시던트를 감지합니다. 초기 분류를 통해 심각도를 결정합니다.

0~30분

2단계: 격리

피해 에스컬레이션 방지. API 키를 무효화하고, 영향을 받는 엔드포인트를 일시적으로 일시 중단하고, 영향 범위를 파악합니다.

30분~2시간

3단계: 근절 및 복구

취약점을 수정하고, 패치를 적용하고, 서비스를 복원합니다. 영향을 받는 사용자에게 알립니다.

2-24시간

4단계: 사고 후 분석

사후 조사를 실시합니다. 근본 원인 분석을 수행하고, 재발 방지 대책을 수립하고, 결과를 문서화합니다.

영업일 기준 1~5일

🤖 AI / LLM Security Checklist

Additional checklist items for systems integrating AI models and LLM-powered features.

  • Model provider has been evaluated for security and compliance (SOC 2, data processing agreement)
  • System prompts are stored securely and not exposed to end users
  • Token budget and cost limits are configured per request and per user
  • Data classification policy defines what data can be sent to external LLM APIs
  • LLM outputs are validated and sanitized before rendering or downstream processing
  • Fallback behavior is defined for model unavailability or degraded responses
  • Model version pinning strategy is documented to prevent unexpected behavior changes
OWASP References

Related: LLM06: Excessive Agency, LLM02: Insecure Output Handling

  • Agent permissions follow least privilege principle — only necessary tools and APIs are accessible
  • Tool/function calling uses an explicit allowlist (not a denylist)
  • Human-in-the-loop approval is required for high-impact actions (payments, deletions, external communications)
  • Agent memory scope is bounded — conversation history does not leak across tenants or sessions
  • Inter-agent communication is authenticated and uses signed messages
  • Goal drift detection is implemented — agents are monitored for deviation from intended objectives
  • Emergency kill switch exists to halt agent execution immediately
OWASP References

Related: ASI01: Excessive Agency, ASI03: Insecure Tool/Function Calling, ASI09: Inadequate Sandboxing

  • Training data provenance is documented with lineage tracking
  • Data integrity checks exist for training and fine-tuning datasets (hash verification)
  • Model artifacts are versioned and stored in a tamper-proof registry
  • Model drift monitoring is in place to detect performance degradation
  • Third-party models and embeddings have been evaluated for known vulnerabilities
  • PII and sensitive data scrubbing is applied to training datasets
OWASP References

Related: LLM03: Training Data Poisoning, ML02: Data Poisoning Attack, ML06: AI Supply Chain Attacks

🧐 AI / LLM Code Review Perspectives

Security check items specific to code that integrates LLMs, AI agents, and ML models.

항목 확인중요성설명
System prompts are not exposed in client-side code or API responses필수Prompt leakage enables targeted prompt injection attacks
LLM outputs are validated before rendering (HTML/JS/SQL)필수LLM-generated content may contain XSS payloads or injection vectors
User input and system instructions are clearly separated in prompts필수Prevents direct prompt injection by maintaining instruction-data boundary
Tool/function call permissions are scoped per user role필수Prevent privilege escalation through agent tool access
Token count limits are enforced per request and per session추천Prevents cost explosion and denial-of-wallet attacks
RAG retrieval results are sanitized before insertion into prompts필수Retrieved documents may contain indirect prompt injection payloads
Agent actions and tool calls are logged with full audit trail추천Essential for incident investigation and compliance in AI systems

📑 AI / LLM Security Policy Templates

Policy templates for organizations deploying AI models and LLM-powered applications.

4. AI Model Access Control Policy

Policy템플릿
■ Model Access Tiers
  - Tier 1 (Restricted): GPT-4 class / fine-tuned models — requires team lead approval
  - Tier 2 (Standard): GPT-3.5 class / embeddings — available to all developers
  - Tier 3 (Open): Open-source models (local inference) — no approval required

■ API Key Management for LLM Providers
  - One API key per service/environment (never share across projects)
  - Monthly spend alerts at 50%, 80%, 100% of budget
  - Hard spending caps enforced at the provider level
  - Key rotation: every 90 days or immediately upon team member departure

■ Data Sent to External Models
  - NEVER send: PII, credentials, internal IP, source code, customer data
  - ALLOWED with review: anonymized logs, public documentation, synthetic data
  - All prompts to external APIs must be logged (excluding PII)

5. AI Data Handling Policy

Policy템플릿
■ Training Data Requirements
  - All training data must have documented provenance and licensing
  - PII must be removed or anonymized before use in training/fine-tuning
  - Data poisoning checks: validate data integrity with hash verification
  - Retain training data snapshots for reproducibility and audit

■ RAG (Retrieval-Augmented Generation) Data
  - Document ingestion pipeline must sanitize content (strip scripts, injections)
  - Access control on vector store must mirror source document permissions
  - Embedding models must be versioned and pinned

■ Model Output Data
  - LLM outputs must not be trusted as authoritative — always verify facts
  - Generated code must pass the same security review as human-written code
  - Outputs containing PII must be flagged and redacted before storage

6. AI Incident Classification Policy

Policy템플릿
■ Severity Levels for AI-Specific Incidents
  - P1 (Critical): Prompt injection leading to data exfiltration or unauthorized actions
  - P1 (Critical): Model serving compromised or returning manipulated outputs
  - P2 (High): Training data poisoning detected, jailbreak bypass discovered
  - P2 (High): Agent performing unintended actions outside approved scope
  - P3 (Medium): Model drift causing degraded accuracy below threshold
  - P4 (Low): Cost overrun due to excessive token usage

■ Response Procedures
  - P1: Immediately disable affected model endpoint, notify security team
  - P2: Quarantine affected model version, roll back to last known good
  - P3: Trigger retraining pipeline, increase monitoring frequency
  - P4: Adjust rate limits and budget caps, review usage patterns

■ Post-Incident Requirements
  - Root cause analysis within 48 hours for P1/P2
  - Update prompt injection test suite with new attack vectors
  - Review and update guardrails configuration

⚡ 빠른 참조: HTTP 상태 코드

API 설계에 사용되는 보안 관련 HTTP 상태 코드입니다.

코드의미사용 사례
400Bad Request입력 유효성 검사 오류
401Unauthorized인증이 필요하거나 토큰이 유효하지 않습니다.
403Forbidden인증되었지만 권한이 충분하지 않음
404Not Found리소스가 존재하지 않습니다(403 대신 사용할 수도 있음).
405Method Not Allowed허용되지 않는 HTTP 메서드
413Payload Too Large요청 본문 크기 초과
422Unprocessable Entity구문은 정확하지만 의미론 오류
429Too Many Requests요금 한도 초과
500Internal Server Error내부 서버 오류(세부 정보 숨기기)