보안 및 API 체크리스트
본 장은 TQS-S/W 인증의 보안 및 API 영역에 대한 상세 체크리스트를 정의합니다. 보안 체크리스트는 인증/인가, 암호화, 입력 검증, 취약점 방어를 검증하며, API 체크리스트는 RESTful 설계 규칙, 문서화, 에러 처리를 검증합니다. 각 항목의 분류는 필수(O), 권장(R), 선택(S)으로 구분되며, 검증 방법을 함께 명시합니다.
32.5.1. 보안
보안 체크리스트는 프로젝트의 보안 구현 수준을 검증합니다. 통신 암호화, 인증/인가, 입력 검증, 의존성 보안, 시크릿 관리 등 소프트웨어 보안의 핵심 영역을 포함합니다.
| 번호 | 항목 | 분류 | 검증 방법 |
|---|---|---|---|
| 1 | TLS 1.2 이상을 사용하여 통신을 암호화한다 | O | 서버 설정 확인 |
| 2 | 비밀번호를 BCrypt 해시로 저장한다 | O | 코드 리뷰 |
| 3 | Spring Security를 적용한다 | O | pom.xml 의존성 및 설정 파일 확인 |
| 4 | Bean Validation을 적용하여 입력값을 검증한다 | O | 코드 리뷰 |
| 5 | v-html 디렉티브를 사용하지 않는다 (불가피한 경우 DOMPurify 적용) | O | 코드 검색 |
| 6 | SQL 파라미터 바인딩을 사용한다 (문자열 연결 미사용) | O | 코드 리뷰 |
| 7 | 소스코드 내에 시크릿을 하드코딩하지 않는다 (API 키, 비밀번호 등) | O | 코드 검색 |
| 8 | OWASP Dependency-Check를 적용하여 의존성 보안을 스캔한다 | R | pom.xml 플러그인 확인 |
| 9 | CORS (Cross-Origin Resource Sharing) 정책을 명시적으로 설정한다 | O | Spring Security 설정 확인 |
| 10 | CSRF (Cross-Site Request Forgery) 방어를 구현한다 | O | Spring Security 설정 확인 |
| 11 | 보안 헤더를 설정한다 (X-Frame-Options, X-Content-Type-Options, X-XSS-Protection) | R | 응답 헤더 확인 |
| 12 | 세션 또는 토큰에 만료 정책을 적용한다 | O | 설정 파일 및 코드 확인 |
| 13 | 입력값 길이 제한을 적용한다 | O | Bean Validation 어노테이션 확인 |
| 14 | 인가 실패 시 적절한 HTTP 상태코드(403)를 반환한다 | O | 코드 리뷰 |
| 15 | 로그에 민감 정보(비밀번호, 토큰 등)를 출력하지 않는다 | O | 코드 검색 |
보안 영역은 TQS 인증에서 가장 엄격하게 검증되는 분야입니다. 보안 항목의 미충족은 프로젝트의 무결성에 직접적인 위협이 되므로, 필수 항목을 반드시 충족해야 합니다. TLS (Transport Layer Security) 적용, 비밀번호 해시, SQL 파라미터 바인딩은 기본 보안 요건입니다.
32.5.1.1. 보안 검증 세부 기준
보안 항목의 검증은 다음의 세부 기준을 적용합니다.
- TLS 1.2 이상 적용 여부는 운영 환경(prod)의 서버 설정을 기준으로 검증합니다. 개발 환경에서는 HTTP를 허용할 수 있습니다.
- BCrypt 해시의 cost factor는 10 이상을 권장합니다.
- CORS 설정은 와일드카드(
*)를 사용하지 않고, 허용 도메인을 명시적으로 나열해야 합니다. - CSRF 방어는 SPA 구조에서 토큰 기반 인증을 사용하는 경우, Spring Security의 CSRF 설정을 적절히 구성해야 합니다.
32.5.2. API 설계
API 설계 체크리스트는 RESTful API의 설계 규칙, 문서화 수준, 에러 처리 표준을 검증합니다.
| 번호 | 항목 | 분류 | 검증 방법 |
|---|---|---|---|
| 16 | RESTful URL 네이밍 규칙을 준수한다 (명사형, 복수형, kebab-case) | O | API 엔드포인트 목록 확인 |
| 17 | 표준 에러 응답 형식을 적용한다 (에러 코드, 메시지, 타임스탬프) | O | API 응답 구조 확인 |
| 18 | SpringDoc (Swagger UI)을 적용하여 API를 문서화한다 | O | pom.xml 의존성 및 Swagger UI 접근 확인 |
| 19 | 날짜 및 시간 형식에 ISO 8601을 사용한다 | O | API 요청/응답 샘플 확인 |
| 20 | 페이지네이션 표준을 적용한다 (page, size, totalElements, totalPages) | O | API 응답 구조 확인 |
| 21 | API 버저닝 전략을 적용한다 (URL 경로 또는 헤더 방식) | R | API 엔드포인트 목록 확인 |
| 22 | 요청 및 응답 예시를 API 문서에 포함한다 | R | Swagger UI 확인 |
| 23 | Rate Limiting을 적용하여 API 호출을 제한한다 | R | 설정 파일 또는 코드 확인 |
| 24 | HTTP 메서드를 올바르게 사용한다 (GET 조회, POST 생성, PUT 수정, DELETE 삭제) | O | API 엔드포인트 목록 확인 |
| 25 | 적절한 HTTP 상태코드를 반환한다 (200, 201, 204, 400, 404, 500 등) | O | API 응답 확인 |
API 설계 영역은 외부 시스템과의 상호 운용성과 개발자 경험을 결정하는 핵심 요소입니다. RESTful 규칙의 일관된 적용과 SpringDoc을 통한 API 문서화는 필수 요건입니다.
32.5.2.1. API 설계 검증 세부 기준
API 설계 항목의 검증은 다음의 세부 기준을 적용합니다.
- RESTful URL은 리소스를 명사형 복수 명칭으로 표현해야 합니다 (예:
/api/users,/api/products). - URL 경로에 동사를 사용하지 않습니다 (예:
/api/getUsers미사용). - 표준 에러 응답에는 최소한
code,message,timestamp필드를 포함해야 합니다. - ISO 8601 날짜 형식은
yyyy-MM-dd'T'HH:mm:ss.SSSZ패턴을 따릅니다. - 페이지네이션 응답에는
page,size,totalElements,totalPages필드를 포함해야 합니다.
32.5.3. 항목 요약
보안 및 API 체크리스트의 전체 항목 수와 분류별 분포는 다음과 같습니다.
| 영역 | 필수(O) | 권장(R) | 선택(S) | 합계 |
|---|---|---|---|---|
| 보안 | 12 | 3 | 0 | 15 |
| API 설계 | 7 | 3 | 0 | 10 |
| 합계 | 19 | 6 | 0 | 25 |
보안 및 API 체크리스트는 총 25개 항목으로 구성됩니다. 필수 항목 19개를 모두 충족해야 기본 인증을 획득할 수 있으며, 권장 항목 6개의 충족률에 따라 우수 또는 최우수 인증 등급이 결정됩니다.
보안 영역의 필수 항목 비율이 80%로 다른 영역보다 높은 이유는, 보안 취약점이 서비스 전체의 신뢰성에 치명적인 영향을 미치기 때문입니다.
32.5.4. 보안 검증 시 유의사항
보안 체크리스트의 검증 시 다음 사항을 유의해야 합니다.
- 보안 항목은 자동 검증과 수동 리뷰를 병행하여 검증합니다. 도구로 탐지 가능한 항목(시크릿 하드코딩, SQL 문자열 연결 등)은 자동 검증을 우선 적용합니다.
- OWASP Dependency-Check 스캔 결과, CVSS (Common Vulnerability Scoring System) 7 이상의 취약점이 발견된 경우, 해당 취약점의 해소 또는 대응 방안을 제시해야 합니다.
- 보안 헤더 설정은 운영 환경(prod)의 응답 헤더를 기준으로 검증합니다. 개발 환경(local/dev)에서는 디버깅 편의를 위해 일부 헤더를 비활성화할 수 있습니다.
- 시크릿 관리는 환경변수 또는 외부 시크릿 관리 도구를 통해 수행해야 하며,
.env파일이.gitignore에 포함되어 있는지 확인합니다.
32.5.5. API 검증 시 유의사항
API 체크리스트의 검증 시 다음 사항을 유의해야 합니다.
- API 문서화는 SpringDoc이 자동 생성한 Swagger UI를 기준으로 검증합니다. 별도의 수기 문서는 인정하지 않습니다.
- Rate Limiting 적용 여부는 운영 환경(prod)의 설정을 기준으로 검증합니다. 개발 환경에서는 Rate Limiting을 비활성화할 수 있습니다.
- API 버저닝은 URL 경로 방식(
/api/v1/)과 헤더 방식 모두 허용합니다. 프로젝트 내에서 하나의 방식을 일관되게 적용해야 합니다. - 페이지네이션 표준은 목록 조회 API에 한하여 적용합니다. 단건 조회 API에는 적용하지 않습니다.