각종 API 문서, 보안 스캐닝 도구 또는 CI/CD 파이프라인 로그를 읽을 때 Manifest, Report, Finding, Evidence와 같은 용어를 자주 만난 적이 있나요? 이 용어들은 특정 프로그래밍 언어의 문법이 아니라 업계 관례의 데이터 계층 대명사입니다. 과연 이 용어들은 무슨 뜻일까요?
핵심 개념: ‘건강검진’으로 이해하는 데이터 계층
병원에서 건강검진을 받는 과정으로 비유하면 이해하기 쉽습니다. 이 4가지 용어는 고위험 요약부터 최하위 로우 데이터까지의 데이터 계층과 정확히 대응합니다.
| 용어 | 건강검진 비유 | 소프트웨어 아키텍처 대응 설명 |
|---|---|---|
Manifest |
검진 접수표 | 실행 항목, 버전 및 환경 설정을 선언하는 기술적 메타데이터. |
Report |
종합 검진 결과 보고서 | 실행 완료 후의 종합 요약. 전체 상태와 감사 결과를 포함. |
Finding |
보고서의 빨간 글씨 메모 | 보고서에서 구체적으로 지적된 발견 사항 (예: “고혈압 발견” 또는 보안 취약점). |
Evidence |
혈압계 데이터 출력지 | 발견 사항을 뒷받침하는 원시 객관적 증거 (로그 기록 또는 측정값). |
이 용어들은 프로그래밍 언어의 예약어가 아닌, 업계 공통의 데이터 모델입니다.
Mermaid 다이어그램을 사용하여 이 4가지의 데이터 구조상 상하관계 및 포함 관계를 시각화할 수 있습니다:
graph TD
A["Manifest (실행 명세/메타데이터)"] -->|범위 정의 및 실행| B["Report (종합 요약 보고서)"]
B -->|다수 포함| C["Finding (구체적 발견/관찰)"]
C -->|다수 연관| D["Evidence (객관적 원시 증거)"]
왜 이렇게 계층화하여 설계할까? 데이터 계층의 3가지 장점
왜 데이터를 하나의 거대한 JSON에 다 집어넣지 않고 세분화하여 분리할까요? 이러한 설계에는 다음과 같은 큰 장점이 있습니다:
훌륭한 API 아키텍처 설계는 프론트엔드 렌더링을 원활하게 하고 데이터의 신뢰성과 확장성을 높여줍니다.
| 장점 | 설명 |
|---|---|
| 관심사의 분리 | 프론트엔드는 먼저 Finding 개요를 로드하여 빠르게 보여주고, 상세 조회가 필요할 때만 대용량 Evidence를 요청할 수 있습니다. |
| 높은 신뢰성 | 원시 증거 Evidence를 제공하여 Finding이 오탐(False Positive)이 아님을 증명하고 시스템 감사 가능성을 대폭 향상시킵니다. |
| 유연한 확장성 | 기존 데이터 형식을 깨뜨리지 않고 하나의 Finding에 여러 Evidence를 유연하게 연관시킬 수 있습니다. |
기타 자주 사용되는 용어: Metadata, Artifact, Payload
4가지 핵심 계층 외에도 API 설계, 파이프라인 구축 또는 전송 포맷 정의 시 자주 접하는 3가지 용어 Metadata, Artifact, Payload의 역할을 살펴보겠습니다:
| 용어 | 핵심 정의 | 일상생활 비유 | 소프트웨어 아키텍처 실제 활용 예시 |
|---|---|---|---|
Metadata |
데이터 자체를 설명하는 데이터 | 택배 상자 겉면 라벨, 사진 EXIF 정보 | HTTP Header, 요청 타임스탬프 timestamp, 페이징 정보 page. |
Artifact |
프로세스 실행 후 생성된 실체 산출물 | 공장에서 생산된 자동차, 검진 CD | 빌드된 .apk 파일, Docker Image, 감사 PDF 보고서. |
Payload |
전송 시 실제 전달하고자 하는 핵심 비즈니스 데이터 | 택배 상자 안에 실제로 들어있는 스마트폰 | HTTP POST Body 내부의 JSON 비즈니스 본문 내용. |
Payload는 우편 택배 상자 안의 물품과 같고,Metadata는 상자 겉면에 붙은 송장 라벨과 같습니다.
이 3가지가 어떻게 협력하여 작동하는지 이해하기 위해 전형적인 API Request 데이터 구조를 확인해 보겠습니다:
{
"metadata": {
"version": "v1.2.0",
"timestamp": "2026-08-02T15:08:41Z",
"request_id": "req-98765"
},
"payload": {
"report_id": "REP-2026-001",
"status": "COMPLETED",
"artifact_url": "https://example.com/artifacts/build-report.pdf"
}
}
이 JSON 예시에서:
metadata는 전송 및 환경 컨텍스트(버전, 타임스탬프, 요청 ID)를 제공합니다.payload는 실제로 전송되는 비즈니스 로직 데이터(보고서 ID, 상태)를 포함합니다.artifact_url은 이번 빌드 작업에서 실제로 생성된 실체 파일(Artifact)을 가리킵니다.
공통 어휘의 힘: 시스템 간 커뮤니케이션의 다리
서로 다른 도구와 팀이 이 유사한 데이터 모델(Report -> Findings -> Evidence)을 채택하면 팀 간 커뮤니케이션 비용이 크게 감소합니다.
CI/CD 도구에서 생성된 Report를 보안 시스템으로 직접 전달하여 분석할 수 있는 것—이것이 바로 공통 어휘가 가져다주는 통합의 위력입니다.
sequenceDiagram
autonumber
actor CI as CI/CD 파이프라인
participant Scanner as 보안 스캐너
participant Dashboard as 관리 대시보드
CI->>Scanner: Manifest 제공하여 스캔 실행
Scanner->>Scanner: Report 및 Findings 생성
Scanner->>Dashboard: 구조화된 Payload (Finding + Evidence) 전송
Dashboard-->>CI: 감사 결과 표시
요약
결국 이 용어들의 목적은 대규모 시스템 간의 데이터 커뮤니케이션 및 구조화 문제를 해결하는 데 있습니다.
시스템을 연동하거나 API를 설계할 때 이러한 데이터 계층 개념을 Payload 구조에 녹여내어 훨씬 전문적이고 확장성 있는 시스템을 구축해 보세요!