Auditor 서비스

원문 보기 위키 갱신 2026.10.07

이 문서는 애플리케이션 내의 보안 관련 이벤트를 기록하고 보고하도록 설계된 핵심 서비스인 Auditor Service를 설명해요.

출처: 문서

본문

개요

이 문서는 애플리케이션 내의 보안 관련 이벤트를 기록하고 보고하도록 설계된 핵심 서비스인 Auditor Service를 설명해요. 기본적으로 이 서비스는 로깅을 위해 rootLogger 핵심 서비스를 사용해요.

주요 기능

보안 이벤트를 포착하는 표준화된 방법을 제공해요.
심각도 수준별 이벤트 분류를 허용해요.
각 이벤트에 대한 상세 메타데이터를 지원해요.
이벤트의 성공/실패 보고를 제공해요.
향상된 컨텍스트를 위해 인증 및 플러그인 서비스와 통합해요.
Backstage 플러그인과의 쉬운 통합을 위한 서비스 팩토리를 제공해요.

작동 방식

Auditor Service는 AuditorService 인터페이스를 구현하는 Auditor 클래스를 정의해요. 이 클래스는 logFn을 사용해 다양한 심각도 수준과 관련 메타데이터로 감사 이벤트를 기록해요. 또한 인증 및 플러그인 서비스와 통합해 행위자 세부 정보와 플러그인 컨텍스트를 포착해요.

auditorServiceFactory는 rootLogger 핵심 서비스를 감싸고 개별 플러그인용 자식 로거를 만드는 팩토리 함수를 제공해요. 이렇게 하면 각 플러그인이 상속된 메타데이터와 추가 메타데이터를 가진 자체 로거를 가질 수 있어요.

사용 지침

Auditor Service는 특별한 주의가 필요하거나 규정 준수 대상인 보안 관련 이벤트를 기록하도록 설계됐어요. 이러한 이벤트는 종종 다음과 같은 작업을 수반해요:

사용자 세션 관리
데이터 접근 및 수정
시스템 구성 변경

보안에 중요하지 않은 일반적인 애플리케이션 로깅의 경우 Backstage가 제공하는 표준 LoggerService를 사용해야 해요. 이렇게 하면 감사 로그를 집중적이고 관련성 있게 유지하는 데 도움이 돼요.

서비스 사용

Auditor Service는 Backstage 플러그인에서 의존성 주입을 통해 접근할 수 있어요. 다음은 Express 라우트 핸들러 내에서 서비스에 접근하고 감사 이벤트를 만드는 예시예요:

export async function createRouter(  options: RouterOptions,): Promise<express.Router> {  const { auditor } = options;  const router = Router();  router.use(express.json());  router.post('/my-endpoint', async (req, res) => {    const auditorEvent = await auditor.createEvent({      eventId: 'my-endpoint-call',      request: req,      meta: {        // ... metadata about the request      },    });    try {      // ... process the request      await auditorEvent.success();      res.status(200).json({ message: 'Succeeded!' });    } catch (error) {      await auditorEvent.fail({ error });      res.status(500).json({ message: 'Failed!' });      throw error;    }  });  return router;}

이 예시에서 /my-endpoint에 대한 각 요청에 대해 감사 이벤트가 생성돼요. 요청 처리 결과에 따라 success 또는 fail 메서드가 호출돼요.

명명 규칙

감사 이벤트를 정의할 때 일관성과 명확성을 보장하려면 다음 지침을 따르세요:

kebab-case 사용: 이벤트 ID는 kebab-case여야 합니다 (예: user-session, file-download, entity-fetch).
논리적 그룹화를 위한 eventId: eventId는 관련 작업의 광범위한 범주 또는 논리적 그룹을 나타내요. 예를 들어 entity-fetch는 모든 엔터티 검색 이벤트를 그룹화해요. location-mutate는 위치를 변경하는 모든 작업을 그룹화해요.
그룹 내 특정 작업을 위한 meta.queryType(또는 관련 필드): 더 넓은 eventId 그룹 내에서 발생한 특정 작업이나 쿼리를 지정하려면 meta 필드(예: queryType, actionType 등)를 사용하세요.
예를 들어 eventId: entity-fetch에서 meta: { queryType: 'by-id' }를 사용해 ID로 엔터티를 가져오는 것을 나타낼 수 있어요. 다른 예는 다음과 같을 수 있어요:
meta: { queryType: 'all' }: 모든 엔터티 가져오기.
meta: { queryType: 'by-query' }: 쿼리로 엔터티 가져오기.
meta: { actionType: 'delete' }: 엔터티가 삭제됐을 때 eventId: entity-mutate용.
meta: { actionType: 'create' }: 위치가 추가됐을 때 eventId: location-mutate용.
추적 중인 이벤트에 더 많은 컨텍스트를 추가하려면 meta 필드를 사용하세요.
중복 접두사 피하기: 이벤트 이름에 플러그인 ID와 관련된 중복 접두사를 포함하지 마세요. 플러그인 컨텍스트는 이미 별도로 제공돼요.
명확하고 간결하게: 감사 중인 이벤트를 명확하고 간결하게 설명하는 이름을 선택하세요.

일반적인 Meta 키와 값

다음 표는 감사 이벤트의 meta 객체에서 찾을 수 있는 일반적인 키와 그 형식을 자세히 설명해요:

이러한 규칙을 따르면 검색, 필터링, 이해가 더 쉬운 더 구조화되고 유익한 감사 추적을 만들 수 있어요. 이를 통해 기록되는 이벤트를 더 잘 그룹화하고 이해할 수 있어요.

감사 이벤트 예시

이러한 명명 규칙과 meta 필드가 실제로 어떻게 사용되는지 설명하기 위해 다음 예시는 일반적인 작업에 대한 대표적인 감사 이벤트를 보여줘요.

일반적인 읽기 작업 예시:

모든 엔터티를 가져오는 작업의 경우 일반적인 감사 이벤트는 다음과 같아요:

{  "eventId": "entity-fetch",  "meta": {    "queryType": "all"  }  ...}

일반적인 쓰기 작업 예시:

엔터티를 삭제하는 작업의 경우 일반적인 감사 이벤트는 다음과 같아요:

{  "eventId": "entity-mutate",  "meta": {    "actionType": "delete",    "uid": "some-entity-uid",    "entityRef": "component:default/petstore"  },  "severityLevel": "medium"  ...}

Auditor 구현을 위한 실용 예시

Auditor 기능을 효과적으로 활용하는 방법을 명확히 하기 위해 Catalog Backend를 탐색해 보시길 권장해요. 두 가지 유용한 리소스를 제공해요:

코드 구현 예시 (createRouter.ts):
Catalog Backend의 createRouter.ts 파일은 Backstage 백엔드 플러그인 내 AuditorService의 실용적인 통합을 보여줘요.
구체적으로 감사 이벤트 생성을 보여주는 줄을 확인하세요. 여기에는 eventId와 severityLevel 같은 중요한 매개변수 설정과 queryType, entityRef 같은 관련 메타데이터 통합이 포함돼요.
문서화 예시:
소프트웨어 카탈로그 감사 문서 의 "Audit Events" 섹션은 내보낸 감사 이벤트를 문서화하는 잘 구조화된 예시를 제공해요.
다양한 eventId 값과 해당 meta 필드(예: queryType, actionType)를 서로 다른 플러그인 작업에 대해 어떻게 자세히 기술하는지 보여줘요.

이 예시들은 Backstage 플러그인 내에서 AuditorService를 효과적으로 활용해 감사 이벤트를 관리하기 위한 코드 수준 데모와 문서화 지침을 모두 제공해요.

심각도 로그 수준 매핑

Auditor Service는 플러그인이 심각도로 분류된 중대한 이벤트를 기록할 수 있는 방법을 제공해요. severityLogLevelMappings 구성 옵션을 사용하면 이러한 심각도 수준이 Backstage 백엔드의 실제 로그 수준에 매핑되는 방식을 사용자 지정할 수 있어 감사 로그의 상세도를 정밀하게 제어할 수 있어요.

구성

severityLogLevelMappings는 app-config.yaml 파일의 backend.auditor 섹션 아래에 구성돼요. 이 구조를 통해 Auditor Service가 지원하는 각 심각도 수준에 대한 로그 수준을 지정할 수 있어요. 전체 매핑을 변경하지 않고 개별 심각도 수준을 재정의할 수 있어요.

구성 예시:

backend:  auditor:    severityLogLevelMappings:      low: debug      medium: info      high: warn      critical: error

심각도 수준과 기본 매핑

Auditor Service는 다음 심각도 수준을 지원해요:

low: 중요도가 낮은 이벤트를 나타내며, 일반적으로 정보 제공 또는 디버그 수준.
medium: 어느 정도 주의가 필요한 중간 중요도 이벤트를 나타내요.
high: 문제나 보안 이슈를 나타낼 수 있는 높은 중요도 이벤트를 나타내요.
critical: 즉각적인 주의가 필요한 중요 이벤트를 나타내요.

기본적으로 이러한 심각도 수준은 다음 로그 수준에 매핑돼요:

low: debug
medium: info
high: info
critical: info

결과적으로 medium, high, critical 이벤트는 기본적으로 info 수준으로 기록되고, low 수준 이벤트는 debug로 취급돼요.