그누보드7 감사 로그 모듈 - Glitter Audit Log

개요

glitter-audit_log는 그누보드7(G7) 환경에서 기존 Activity Log를 기반으로
감사 이벤트를 탐색하고, 이벤트 정의와 구조적 Coverage 상태를 진단하기 위한
읽기 전용 Audit Log 모듈입니다.

별도의 감사 로그 원장을 새로 만들지 않고,
G7 코어의 활동 로그를 단일 원장으로 활용하면서
관리자에게 조회·분석·진단 기능을 추가로 제공합니다.

현재 버전은 v0.4.1이며,
모듈 설명은 Audit Explorer + Event Registry + Coverage Diagnostics를 핵심으로 구성됨.

주요 기능

Audit Explorer

• G7 Activity Log 기반 감사 로그 조회
• Actor 기준 필터링
• Action 기준 필터링
• Resource Type / Resource ID 필터링
• Source Type / Source Identifier 필터링
• Log Type 필터링
• 기간별 검색
• 검색어 기반 조회
• 페이지네이션
• 변경 내역 및 Properties 상세 확인

Source Normalization

감사 로그의 발생 출처를 다음 유형으로 정규화하여 조회할 수 있습니다.

• Core
• Module
• Plugin
• Template
• Unknown

모듈·플러그인·템플릿에서 발생한 감사 이벤트를 하나의 탐색 화면에서 확인할 수 있도록 구성.

Audit Event Registry

각 확장에서 선언한 감사 이벤트 메타데이터를 Registry 형태로 조회할 수 있습니다.

관리 대상 메타데이터의 예시는 다음과 같습니다.

• Event Key
• Source Type
• Source Identifier
• Category
• Severity
• Description Key
• Expected Action

활성화된 Module, Plugin, Template의 감사 이벤트 선언을 탐색할 수 있도록 구성되어 있습니다.

Coverage Diagnostics

감사 이벤트의 상태를 단순히 "로그가 존재하는가"로 판단하지 않고 두 영역으로 나누어 진단.

Structural Coverage

이벤트가 실제 감사 로그 구조와 연결되어 있는지를 확인합니다.

• Source 활성 상태
• Activity Log Listener 연결 여부
• Expected Action 연결 상태
• Description / Translation 연결 상태
• 구조 분석 결과

구조 진단 상태는 다음과 같이 구분할 수 있습니다.

• Covered
• Partial
• Uncovered
• Unknown

Observational Evidence

현재 Activity Log 원장에서 해당 이벤트가 실제로 관측되었는지를 별도로 확인합니다.

• Observed / Not Observed
• Observation Count
• First Seen
• Last Seen

Not Observed는 해당 기능이 구현되지 않았다는 의미가 아니라,
현재 보존된 감사 로그에서 아직 해당 이벤트가 관측되지 않았다는 의미입니다.

v0.4.0에서는 Structural Coverage와 Observational Evidence를 분리한
Coverage 진단과 읽기 전용 Coverage Aggregate API, 관리자 Coverage 화면이 추가됨.

Administration

• 관리자 Audit Explorer
• 관리자 Coverage Diagnostics
• 권한 기반 접근 제어
• G7 기존 Activity Log 접근 범위 유지
• 한국어 / 영어 인터페이스

설계 방향

glitter-audit_log는 새로운 감사 로그 시스템을 별도로 구축하는 모듈이 아닙니다.

G7에서 이미 기록하고 있는 Activity Log를 그대로 활용하고,
그 위에 다음과 같은 분석 계층을 추가하는 것을 목표로 합니다.

G7 Activity Log
       ↓
Audit Explorer
       ↓
Audit Event Registry
       ↓
Structural Coverage
       ↓
Observational Evidence

따라서 동일한 이벤트를 별도의 테이블에 중복 저장하지 않습니다.

활용 사례

• 관리자 활동 감사
• 운영자 변경 이력 확인
• 모듈별 감사 이벤트 탐색
• Plugin / Template 감사 이벤트 확인
• 중요 이벤트의 감사 로그 연결 상태 점검
• 신규 모듈의 Audit Log Coverage 검증
• 운영 환경에서 실제 이벤트 발생 여부 확인
• G7 확장 모듈의 Audit 규약 정리
• 감사 로그 누락 가능성 진단
• 운영 및 보안 점검 보조

기술 스택

• PHP 8.2+
• Laravel 12.x
• GnuBoard7 Activity Log
• JSON Layout
• TypeScript
• Vitest

요구 사항

• GnuBoard7 >= 7.0.9
• PHP >= 8.2

현재 module.json 기준 버전은 0.4.1, 라이선스는 MIT, Vendor는 Glitter.kr입니다.

관리자 페이지에서 설치

1. GitHub 저장소에서 설치 (권장)

관리자 → 모듈 관리 → 수동 설치 → GitHub

아래의 저장소 URL을 입력합니다.

https://github.com/glitter-node/glitter-audit_log

설치가 완료된 후 감사 로그 모듈을 활성화하면 관리자 메뉴에 감사 로그가 생성됩니다.

주요 관리자 기능은 다음 두 영역으로 구성됩니다.

• 감사 로그 탐색
• Coverage 진단

2. ZIP 패키지 설치

GitHub Release에서 zip 패키지를 다운로드합니다.

• ZIP 템플릿 패키지를 다운로드

ZIP 패키지를 다운로드한 후

관리자 → 모듈 관리 → 수동 설치 → 파일 업로드

방식으로 설치할 수도 있습니다.

3. 설치 후 페이지 로드 오류 발생 시

관리자 → 환경설정 → 고급 → 캐시 모두 삭제

를 실행한 후 다시 확인합니다.

저장소

GitHub

https://github.com/glitter-node/glitter-audit_log

Release

https://github.com/glitter-node/glitter-audit_log/releases/tag/v0.4.1

버전별 주요 변경

v0.4.1

• GnuBoard7 코어 업데이트 및 확장 lifecycle 과정의 모듈 bootstrap 호환성 개선
• module.php의 ProvidesAuditEventsInterface 직접 의존성 제거
• 모듈 autoload 이전에도 안전하게 bootstrap되도록 개선
• 기존 getAuditEvents() 기반 Audit Event 탐색 방식 유지

v0.4.0

• Structural Coverage와 Observational Evidence 분리
• Read-only Coverage Aggregate API 추가
• 관리자 Coverage Diagnostics 화면 추가
• Coverage / Resource / Permission / Layout 테스트 추가

v0.3.0

• Audit Event Registry 추가
• Event Definition 공개 Contract 추가
• 활성 Module / Plugin / Template 이벤트 선언 탐색
• 관리자 Event Definitions API 추가

v0.2.0

• 관리자 Audit Explorer 추가
• Route / Menu / Filter / Pagination 지원
• Structured Details 지원
• 한국어 / 영어 번역 추가

v0.1.0

• G7 Activity Log 원장 기반 Read-only Audit Query API 추가

개발 상태

v0.4.1 — Fixed Release

G7의 기존 Activity Log를 변경하거나 별도의 감사 원장을 추가하지 않고,
감사 로그 탐색과 이벤트 Registry, Coverage 진단 기능을 제공하는 읽기 전용 구조로 개발됨.

향후에는 실제 G7 확장 모듈들이 Audit Event Registry를 선언하도록 점진적으로 연동하여,
모듈별 Audit Coverage를 확인할 수 있는 구조로 확장할 수 있습니다.

라이선스

MIT License.

Copyright (c) 2026 Glitter.kr

최적의 설치

이 버전은 ZIP 설치보다 GitHub 저장소 설치를 권장합니다.

G7 관리자에서 GitHub 저장소 URL을 이용해 설치하면 모듈 업데이트와 버전 관리 흐름을 유지하기 쉽습니다.

https://github.com/glitter-node/glitter-audit_log

핵심 구조

glitter-audit_log의 핵심은 감사 로그를 새로 기록하는 것이 아니라,
이미 존재하는 G7 Activity Log를 기준으로

무슨 이벤트가 있었는지,
어디에서 발생했는지,
어떤 이벤트가 선언되어 있는지,
그 이벤트가 감사 로그 구조와 실제로 연결되어 있는지,
운영 환경에서 실제로 관측된 적이 있는지

를 하나의 관리자 영역에서 확인할 수 있도록 하는 것입니다.