DocVault X-Ray

DocVault를 endpoint부터 hash-chain까지 설명하는 페이지

목표는 보안 용어를 외우는 게 아니다. 무엇을 탐지하는 제품인지, 왜 Go/Postgres/htmx인지, endpoint agent가 어떻게 들어오는지, 감사 로그 무결성을 어떻게 보장하는지, 어디까지가 한계인지를 네 입으로 설명하게 만드는 것이다.

cards

domains

flows

One sentence

DocVault is a self-hosted insider-risk event collection and audit tool: endpoint agents send activity, Go normalizes it, Postgres stores tamper-evident logs, and admins review alerts through an htmx console.

핵심은 “차단”이 아니라 “탐지와 감사”다. Go/Postgres/htmx를 쓴 이유도 이 범위와 endpoint agent 배포 문제에서 나온다.

Tech stack from absolute zero

Go, Postgres, chi, pgx, htmx, osquery, JWT, TOTP, AES-GCM, hash chain, Docker Compose, Caddy 같은 단어를 누르면 이게 뭔지, 왜 썼는지, 대안과 trade-off가 뭔지, 어디 코드에 있는지 바로 볼 수 있다.

stack cards

0. Product shape

0. Product shapeCore

Insider-risk event collection product

직원 PC 이벤트를 모아 내부자 위협을 사후 탐지하는 제품이다.

DocVault is a detection and audit product for small teams, not a DRM or full EDR replacement.

What it does

osquery와 자체 clipboard agent가 endpoint activity를 보내고, Go server가 Postgres에 저장한 뒤 관리자가 web UI에서 조회한다.

Why this stack

이 제품의 목적은 DRM처럼 차단하는 것이 아니라 작은 팀이 유출 징후를 빨리 보고 조사 근거를 남기는 것이다.

Trade-off

차단을 못 한다. 사고 후 탐지와 감사에는 맞지만 강제 DRM/EDR 대체품으로 팔면 틀린다.

Alternative

DRM은 차단이 강하지만 업무 마찰이 크고, EDR은 깊은 가시성이 있지만 비용/운영이 무겁다.

Terms you must know

insider risk = 내부 구성원에 의한 정보 유출 위험
detection = 일이 발생한 뒤 찾는 것
prevention = 일이 발생하기 전에 막는 것

Where

docvault/README.md, docs/ARCHITECTURE.md

Beginner trap

감시 제품이라고 말하기 전에 합법적 동의와 회사 소유 PC 범위를 말해야 한다.

1. Languages

1. LanguagesCore

Go 1.26

서버와 endpoint agent를 같은 언어로 만든다.

Go was chosen mainly because the same codebase can ship the server and lightweight cross-platform endpoint agents.

What it does

HTTP server, clipboard agent, crypto, DB access, scheduled background work를 Go binary로 실행한다.

Why this stack

에이전트 배포가 핵심이라 JVM/Python runtime 없이 Windows/macOS 단일 실행파일을 만들 수 있는 Go가 맞다.

Trade-off

ML/data science 생태계는 Python보다 약하고 고수준 추상화는 Java/Kotlin보다 단순하다.

Alternative

Java/Spring은 enterprise 서버에 강하지만 agent 배포가 무겁고, Rust는 안전하지만 개발 속도 비용이 크다.

Terms you must know

compiled language = 실행파일로 번역되는 언어
static binary = dependency를 많이 품은 단일 실행파일
goroutine = Go의 가벼운 동시 작업 단위

Where

go.mod, cmd/server, cmd/clipagent

Beginner trap

서버만 보고 Go를 골랐다고 말하지 말고 agent 배포 동기를 반드시 말해야 한다.

2. Runtime

2. RuntimeCore

osquery

PC 상태를 SQL처럼 조회하는 오픈소스 endpoint agent다.

osquery is used for endpoint telemetry so DocVault does not reinvent file, USB, and process collection from scratch.

What it does

파일 변경, USB, process 같은 endpoint telemetry를 scheduled query로 수집한다.

Why this stack

검증된 endpoint collector를 재사용하고 DocVault는 normalize/store/analyze에 집중할 수 있다.

Trade-off

user-mode라 kernel-level 공격이나 직접 차단은 못 한다.

Alternative

직접 agent를 만들면 통제는 강하지만 비용이 크고, 상용 EDR은 강하지만 가격/운영이 무겁다.

Terms you must know

telemetry = 시스템에서 수집한 관측 데이터
scheduled query = 일정마다 실행되는 query
user-mode = 일반 사용자 공간에서 도는 프로그램

Where

deploy/osquery, internal/endpoint/osquery.go

Beginner trap

osquery를 쓴다고 EDR 수준의 커널 가시성이 생기는 건 아니다.

2. RuntimeCore

Go clipboard agent

직원 PC에서 clipboard 변화를 감시하는 자체 agent다.

The custom clipboard agent covers a specific exfiltration signal that osquery does not handle well.

What it does

Windows/macOS별 clipboard API를 읽고 이벤트, heartbeat, self-test를 서버에 POST한다.

Why this stack

osquery가 clipboard를 직접 커버하지 못하므로 유출 위험이 큰 복사 동작을 별도 agent로 잡는다.

Trade-off

OS별 API와 권한 문제가 있고 Windows에서는 서비스가 아닌 사용자 세션 실행이 필요하다.

Alternative

클립보드 감시를 포기하면 설치는 쉬워지지만 핵심 유출 채널 하나가 빠진다.

Terms you must know

clipboard = 복사/붙여넣기 임시 저장소
agent = endpoint에 설치되는 작은 프로그램
heartbeat = 살아있음을 주기적으로 알리는 신호

Where

cmd/clipagent, internal/endpoint/clipboard.go

Beginner trap

클립보드 감시는 민감하므로 회사 장비/동의/고지 범위를 분명히 해야 한다.

2. RuntimeCore

Windows Scheduled Task

Windows에서 사용자 로그인 세션에 agent를 자동 실행하는 방식이다.

The Windows agent runs as a per-user scheduled task because clipboard capture requires an interactive user session.

What it does

installer bat가 DocVaultClipAgent scheduled task를 만들고 interactive session에서 clipboard를 읽게 한다.

Why this stack

LocalSystem service는 Session 0 문제 때문에 clipboard 접근이 안 되므로 Scheduled Task가 현실적 선택이다.

Trade-off

서비스보다 중앙 관리/격리감은 약하고 사용자 session 상태에 의존한다.

Alternative

Windows service는 백그라운드 운영이 강하지만 clipboard에는 부적합하고, 수동 실행은 신뢰성이 낮다.

Terms you must know

Session 0 = Windows service가 도는 비상호작용 세션
interactive session = 사용자가 보는 화면 세션
Scheduled Task = Windows 자동 실행 작업

Where

internal/web/pages.go installer, docs/DEPLOY.md

Beginner trap

서비스로 만들면 더 professional해 보인다고 무조건 맞는 게 아니다.

3. Frontend

3. FrontendCore

htmx

서버가 만든 HTML 조각으로 화면 일부를 갱신하는 작은 JS library다.

htmx is a pragmatic frontend choice because DocVault is an admin console, not a highly interactive consumer SPA.

What it does

관리자 화면에서 React SPA 없이 search, form submit, partial update, dashboard UI를 만든다.

Why this stack

페이지 수가 제한된 admin tool이라 빌드 스텝 없는 htmx가 복잡도를 크게 줄인다.

Trade-off

클라이언트 상태가 매우 복잡해지면 round-trip과 DOM fragment 관리가 부담된다.

Alternative

React/Vue SPA는 복잡한 client state에 강하지만 build chain과 frontend architecture가 필요하다.

Terms you must know

server-rendered HTML = 서버가 만든 HTML을 브라우저가 받는 방식
partial update = 페이지 전체가 아니라 일부만 갈아끼움
round-trip = 브라우저와 서버를 왕복하는 요청

Where

internal/web/static/htmx.min.js, templates

Beginner trap

htmx를 쓰면 프론트엔드가 없다는 뜻이 아니라 서버 렌더링 프론트엔드라는 뜻이다.

3. FrontendCore

Go html/template

서버에서 HTML 화면을 만드는 template engine이다.

Go templates keep the admin UI server-rendered and deployable as a single Go service.

What it does

layout, dashboard, files, audit, agents, admin pages를 data map과 template로 렌더링한다.

Why this stack

Go binary 안에서 UI와 backend를 같이 배포할 수 있고 XSS escaping 기본값이 있다.

Trade-off

template가 커지면 component 재사용과 타입 안정성이 약해진다.

Alternative

React server components, templ, Jet, Jinja 같은 template engine이 대안이다.

Terms you must know

template = data를 끼워 HTML을 만드는 파일
escaping = 위험 문자를 안전하게 바꾸는 처리
server-side rendering = 서버가 화면을 만들어 보내는 방식

Where

internal/web/templates, internal/web/render.go

Beginner trap

template escaping이 있다고 모든 XSS가 자동 방어되는 건 아니다.

3. FrontendCore

Server-Sent Events

서버가 브라우저로 실시간 이벤트를 밀어주는 단방향 stream이다.

SSE gives the dashboard live updates without introducing a full bidirectional WebSocket system.

What it does

dashboard에 endpoint event나 alert가 들어왔을 때 refresh 없이 보여주는 데 사용한다.

Why this stack

관리자 console에는 WebSocket 양방향 통신보다 단순한 SSE가 충분하다.

Trade-off

client에서 server로도 실시간 메시지를 많이 보내야 하면 WebSocket이 더 맞다.

Alternative

polling은 단순하지만 지연/부하가 있고, WebSocket은 강력하지만 상태 관리가 무겁다.

Terms you must know

SSE = HTTP로 서버가 이벤트를 계속 보내는 방식
stream = 연결을 유지하며 데이터가 흐르는 통로
polling = 주기적으로 새 데이터가 있는지 묻는 방식

Where

internal/web/sse.go, router /api/events/stream

Beginner trap

SSE는 오래 열린 연결이라 server timeout/write timeout 설정을 신경 써야 한다.

5. Backend

5. BackendCore

net/http

Go 표준 HTTP server 기반이다.

The server stays close to Go's standard net/http model, which keeps routing and middleware explicit.

What it does

chi router가 표준 net/http handler 위에서 request/response를 처리한다.

Why this stack

표준 library라 dependency가 작고, middleware/handler model이 단순해서 보안 경계를 추적하기 쉽다.

Trade-off

framework가 제공하는 고급 기능은 직접 조립해야 한다.

Alternative

Gin/Echo/Fiber는 더 많은 convenience를 주지만 framework convention과 dependency가 늘어난다.

Terms you must know

handler = HTTP 요청을 처리하는 함수
ResponseWriter = 응답을 쓰는 객체
Request = 들어온 HTTP 요청 객체

Where

internal/web/router.go, cmd/server/main.go

Beginner trap

net/http는 router가 아니라 HTTP server primitive다.

5. BackendCore

chi router

HTTP 경로를 handler와 middleware로 연결하는 Go router다.

chi gives DocVault a small, explicit routing layer around authentication, audit logging, and admin-only routes.

What it does

JWT, audit, CSRF, role check 같은 middleware chain을 route group별로 붙인다.

Why this stack

표준 net/http와 잘 맞고 router 자체가 작아서 admin tool backend에 충분하다.

Trade-off

대형 framework처럼 validation/DI/ORM을 자동 제공하지 않는다.

Alternative

순수 net/http는 더 수동이고, Gin/Echo는 기능이 많지만 lock-in과 추상화가 늘어난다.

Terms you must know

router = URL을 알맞은 handler로 보내는 교통정리
middleware = request 전후에 공통으로 끼는 처리
route group = 같은 middleware를 공유하는 경로 묶음

Where

internal/web/router.go

Beginner trap

라우터가 보안 정책을 대신하는 게 아니라 middleware를 어디에 붙였는지가 중요하다.

5. BackendCore

Agent enrollment

endpoint agent를 서버에 등록하고 hostname을 사용자와 연결하는 흐름이다.

Enrollment turns raw endpoint hostnames into accountable user timelines.

What it does

install token, reported username, hostname, source를 받아 endpoint_agents와 user mapping을 갱신한다.

Why this stack

이벤트를 사람에게 귀속해야 dashboard와 audit timeline이 의미를 갖는다.

Trade-off

hostname/user 자동 매핑이 틀리면 잘못된 사람에게 이벤트가 붙을 수 있다.

Alternative

수동 admin assignment는 안전하지만 번거롭고, directory integration은 정확하지만 구축이 무겁다.

Terms you must know

enrollment = agent 최초 등록
hostname = PC 이름
attribution = 이벤트를 사용자에게 귀속하는 것

Where

internal/endpoint/handler.go, internal/web/pages.go

Beginner trap

agent가 보내는 username만 맹신하면 안 된다.

5. BackendCore

Audit middleware

인증된 요청을 자동으로 audit_logs에 남기는 공통 계층이다.

Audit logging belongs in middleware because every protected action must be recorded consistently.

What it does

핸들러마다 log 호출을 넣지 않고 middleware가 action, target, status를 기록한다.

Why this stack

감사는 cross-cutting concern이라 누락을 줄이려면 공통 경계에 강제하는 게 맞다.

Trade-off

path 기반 action derivation은 라우트 추가 때 깨질 수 있다.

Alternative

명시 route metadata 방식은 안전하지만 route 등록 코드가 더 복잡해진다.

Terms you must know

cross-cutting concern = 여러 기능에 공통으로 걸치는 관심사
status recorder = 응답 코드를 캡처하는 wrapper
target_id = 감사 대상의 식별자

Where

internal/audit/middleware.go, router protected groups

Beginner trap

미들웨어가 있다고 모든 path가 정확한 action으로 기록된다고 단정하면 안 된다.

5. BackendCore

Streaming I/O

큰 파일을 메모리에 모두 올리지 않고 조금씩 읽고 쓰는 방식이다.

Streaming I/O keeps large encrypted uploads from turning into memory spikes.

What it does

multipart upload, encryption stream, disk writer, download response가 io.Reader/Writer로 이어진다.

Why this stack

CAD 파일처럼 큰 파일을 다룰 수 있어야 하므로 Go streaming abstraction이 중요하다.

Trade-off

중간 실패 시 partial file cleanup과 transaction boundary를 신경 써야 한다.

Alternative

전체 buffering은 구현은 쉽지만 메모리 사용량이 파일 크기에 비례한다.

Terms you must know

io.Reader = 조금씩 읽는 인터페이스
io.Writer = 조금씩 쓰는 인터페이스
backpressure = 느린 쪽에 맞춰 흐름이 제한되는 현상

Where

internal/vault/encryption.go, vault/handler.go

Beginner trap

streaming은 성능만이 아니라 failure cleanup까지 같이 설계해야 한다.

5. BackendCore

Rule-based anomaly scoring

머신러닝이 아니라 임계값 rule로 위험 점수를 계산하는 분석기다.

The honest label is rule-based anomaly scoring, not full ML-based UEBA.

What it does

야간 활동, 새 IP, 대량 다운로드, messenger/process 같은 factor를 가중치로 risk score에 누적한다.

Why this stack

작은 팀과 설명 가능한 보안 운영에는 ML보다 규칙 기반 scoring이 현실적이다.

Trade-off

정교한 UEBA처럼 사용자별 복잡한 패턴을 학습하지 못하고 false positive/negative가 있다.

Alternative

Python ML service, statistical anomaly detection, commercial UEBA가 확장 대안이다.

Terms you must know

baseline = 평소 행동 기준선
risk score = 위험 요소를 더한 점수
false positive = 정상인데 위험으로 잡는 경우

Where

internal/ueba, docs/LIMITATIONS.md

Beginner trap

디렉터리명이 ueba라고 해서 업계 의미의 UEBA라고 말하면 안 된다.

5. BackendCore

Alert engine

저장된 endpoint event를 rule과 비교해 alert를 만드는 계층이다.

The alert engine turns raw endpoint telemetry into actionable security signals.

What it does

alert rules와 monitoring config를 보고 Slack/email notifier나 dashboard alert로 연결한다.

Why this stack

이벤트 저장만으로는 운영자가 바로 대응하기 어려우므로 rule engine이 필요하다.

Trade-off

inline evaluation이라 외부 webhook 지연이나 실패가 request path에 영향을 줄 수 있다.

Alternative

비동기 queue를 두면 내구성과 격리가 좋아지지만 시스템이 복잡해진다.

Terms you must know

rule engine = 조건을 평가해 action을 만드는 코드
notifier = 외부 알림을 보내는 계층
inline = 요청 처리 중 바로 실행

Where

internal/alert, endpoint handler fan-out

Beginner trap

alert가 있다고 incident response process가 완성된 건 아니다.

5. BackendCore

DB-based monitoring config

감시할 process, extension, path, disguise rule을 DB에서 관리하는 구조다.

Moving monitoring rules into the database makes the security policy configurable from the admin UI.

What it does

hardcoded list 대신 admin UI에서 monitoring 대상과 rule을 바꿀 수 있다.

Why this stack

운영자가 제품 재배포 없이 감시 기준을 조정할 수 있어야 한다.

Trade-off

잘못된 config가 탐지 품질을 망칠 수 있어 validation과 audit가 필요하다.

Alternative

config file은 단순하지만 runtime 변경이 어렵고, policy engine은 강하지만 복잡하다.

Terms you must know

monitoring config = 무엇을 감시할지 정한 설정
process group = 감시할 앱 묶음
extension rule = 파일 확장자 기준

Where

internal/monitoring, admin/monitoring routes

Beginner trap

설정을 바꿀 수 있다고 좋은 탐지 정책이 자동 생성되는 것은 아니다.

5. BackendCore

Hash-based file tracking

중요 파일 hash를 등록하고 endpoint event에서 같은 hash를 찾는 기능이다.

Hash-based tracking can identify known sensitive files even if the filename changes.

What it does

SHA256/MD5가 일치하면 파일 이름이 바뀌어도 추적 대상 파일로 감지한다.

Why this stack

단순 파일명 기반보다 증거력이 높고 extension disguise 탐지와 연결된다.

Trade-off

파일 내용이 조금만 바뀌면 hash가 달라져 놓칠 수 있다.

Alternative

fuzzy hashing, magic byte 검사, DLP fingerprinting이 더 정교한 대안이다.

Terms you must know

SHA256 = 파일 내용을 대표하는 강한 hash
MD5 = 오래됐지만 호환용으로 쓰이는 hash
fuzzy hash = 비슷한 파일을 찾는 hash

Where

internal/tracking, endpoint fileTracker

Beginner trap

hash tracking은 등록된 파일과 동일/거의 동일한 경우에만 강하다.

6. Data

6. DataCore

pgx / pgxpool

Go에서 PostgreSQL에 연결하는 driver와 connection pool이다.

pgx keeps database access explicit while still giving a proper PostgreSQL connection pool.

What it does

repository들이 pgx pool을 통해 SQL query, transaction, batch insert를 실행한다.

Why this stack

Postgres native 기능과 성능을 직접 쓰고 ORM magic 없이 query shape를 통제하기 좋다.

Trade-off

SQL을 직접 작성해야 하므로 반복과 migration/schema drift를 조심해야 한다.

Alternative

GORM은 CRUD가 빠르지만 복잡 query와 성능이 불투명하고, database/sql은 표준이지만 pgx native 기능이 약하다.

Terms you must know

driver = DB와 통신하는 library
connection pool = DB 연결을 재사용하는 묶음
repository = DB 접근을 모아둔 코드 계층

Where

go.mod, internal/*/repository.go

Beginner trap

pgx를 쓴다고 SQL injection이 자동으로 막히는 건 아니고 parameter binding을 써야 한다.

6. DataCore

PostgreSQL 16

이벤트와 감사 로그의 중심 저장소다.

Postgres is the system of record because DocVault needs constraints, triggers, indexes, and audit integrity in one place.

What it does

users, files, endpoint_events, audit_logs, alerts, baselines, agent_actions를 저장한다.

Why this stack

해시 체인 trigger, indexes, tsvector, constraints가 필요해서 단일 Postgres가 초기 규모에 맞다.

Trade-off

단일 DB가 SPOF이고 30M+ endpoint_events 규모에서는 partitioning/retention이 필요하다.

Alternative

Kafka/Elasticsearch/Redis를 붙이면 확장은 좋지만 현재 40명 규모에서는 운영 복잡도가 과하다.

Terms you must know

RDBMS = table과 transaction을 제공하는 DB
SPOF = 하나가 죽으면 전체가 멈추는 지점
partitioning = 큰 table을 시간/범위별로 나누는 설계

Where

docker-compose.prod.yml, internal/database/migrations

Beginner trap

Postgres 하나로 모든 미래 규모를 버틴다고 말하면 안 된다.

6. DataCore

Embedded SQL migrations

DB schema 변경을 Go binary 안에 넣어 적용한다.

Embedding migrations lets the same server artifact carry the database schema changes it expects.

What it does

migrate command가 embedded migration SQL을 순서대로 실행해 table/index/trigger를 만든다.

Why this stack

배포 파일이 단순하고 서버와 schema version을 같이 움직이게 할 수 있다.

Trade-off

잘못된 migration은 운영 DB에 직접 영향을 주므로 backward-compatible 전략이 필요하다.

Alternative

Flyway/Liquibase는 더 풍부한 migration ecosystem이고, 수동 SQL은 추적성이 약하다.

Terms you must know

migration = DB 구조 변경 기록
go:embed = 파일을 Go binary 안에 포함하는 기능
schema version = DB 구조의 적용 순서

Where

internal/database/migrations.go, cmd/server/migrate.go

Beginner trap

migration이 있으면 rollback이 자동으로 쉬운 것은 아니다.

6. DataCore

Postgres advisory lock

해시 체인 INSERT를 테이블별로 직렬화하는 DB lock이다.

The advisory lock fixes the hash-chain fork race by serializing inserts per audited table.

What it does

동시 INSERT가 같은 prev_hash를 읽는 race를 막기 위해 trigger에서 pg_advisory_xact_lock을 잡는다.

Why this stack

무결성 구조에서는 race condition 하나가 전체 증거성을 흔들 수 있어서 필요하다.

Trade-off

INSERT 처리량이 테이블별로 직렬화되므로 초당 많은 이벤트에서는 병목이 될 수 있다.

Alternative

SERIALIZABLE transaction, batch chain, external append log 같은 대안이 있다.

Terms you must know

race condition = 동시에 실행되어 결과가 꼬이는 문제
serialization = 한 번에 하나씩 순서대로 처리
transaction-scoped = transaction 끝나면 자동 해제

Where

migrations/013_audit_advisory_lock.up.sql

Beginner trap

lock을 넣었다고 무한 처리량이 유지되는 건 아니다.

7. AI

7. AICore

AI security briefing

최근 이벤트 digest를 LLM에게 보내 한국어 보안 브리핑을 받는 기능이다.

The AI briefing summarizes factual database digests; it should not invent events beyond the digest.

What it does

DB에서 event counts, notable events, unacknowledged alerts를 압축해 Claude/Gemini에 요약시킨다.

Why this stack

비전문 관리자에게 raw table보다 짧은 위험 요약이 필요하다.

Trade-off

LLM 비용/지연/환각 위험이 있어 factual digest와 admin-only 경계가 필요하다.

Alternative

순수 rule dashboard는 결정론적이지만 자연어 설명이 약하고, RAG는 문서 Q&A에 더 맞다.

Terms you must know

digest = 원본 데이터를 압축한 요약 입력
hallucination = 없는 일을 지어내는 모델 오류
provider = AI API 제공자

Where

internal/insight/summarizer.go

Beginner trap

AI 요약을 보안 판단의 단일 근거로 쓰면 안 된다.

7. AICore

Tool-use AI assistant

관리자가 자연어로 live data 조회와 제한된 행동을 요청하는 AI assistant다.

The assistant uses tools over live tables because DocVault's data is structured and action-oriented.

What it does

read tools는 이벤트/사용자/경보를 조회하고 action tools는 create_user, assign_host, acknowledge_alert를 수행한다.

Why this stack

정형 데이터라 RAG보다 SQL-backed tool-use가 더 정확한 grounding을 준다.

Trade-off

tool output에는 파일명/창제목 같은 공격자 영향 데이터가 들어가 prompt injection 위험이 있다.

Alternative

수동 admin UI는 안전하지만 느리고, RAG chat은 문서 답변에는 좋지만 row-level action에는 약하다.

Terms you must know

tool-use = 모델이 정해진 함수 호출을 선택하는 방식
grounding = 실제 데이터에 근거하게 만드는 것
prompt injection = 데이터 속 명령으로 AI를 속이는 공격

Where

internal/agent/agent.go, internal/agent/actions.go

Beginner trap

AI assistant가 있다고 모든 운영 변경을 자동화해도 된다는 뜻은 아니다.

8. Infra

8. InfraCore

Docker

Go server와 Postgres 실행 환경을 container로 묶는다.

Docker makes the deployment reproducible across a dedicated server and an all-in-one demo machine.

What it does

Dockerfile은 server binary를 만들고 compose는 db/migrate/seed/server/caddy를 함께 실행한다.

Why this stack

친구 PC all-in-one과 dedicated VM을 같은 방식으로 재현하기 좋다.

Trade-off

Docker Desktop, volume, network, backup 같은 운영 지식이 필요하다.

Alternative

직접 설치는 단순해 보이지만 환경 drift가 크고, Kubernetes는 1인 운영에는 과하다.

Terms you must know

container = 격리된 실행 단위
image = container를 만드는 스냅샷
volume = container 밖에 보존되는 데이터 저장소

Where

Dockerfile, docker-compose.prod.yml

Beginner trap

Docker가 backup이나 security를 자동으로 해주는 것은 아니다.

8. InfraCore

Docker Compose

db, migration, seed, server, caddy를 한 파일에서 띄우는 orchestrator다.

Compose is enough for the intended single-host deployment and keeps the operational model explainable.

What it does

depends_on healthcheck로 DB 준비 후 migration/seed/server 순서가 맞게 실행된다.

Why this stack

작은 self-hosted 제품에는 Kubernetes보다 이해와 복구가 쉬운 compose가 맞다.

Trade-off

HA/rolling deploy/autoscaling은 약하고 한 host 장애에 취약하다.

Alternative

ECS/Kubernetes/Nomad는 orchestration은 강하지만 초기 운영 복잡도가 크다.

Terms you must know

orchestrator = 여러 서비스를 순서/상태에 맞게 실행하는 도구
healthcheck = 서비스가 준비됐는지 검사
one-shot service = 실행 후 종료되는 작업

Where

docker-compose.prod.yml

Beginner trap

Compose를 쓴다고 고가용성 아키텍처가 되는 건 아니다.

8. InfraCore

Caddy reverse proxy

HTTPS 인증서와 외부 요청 전달을 맡는 reverse proxy다.

Caddy keeps HTTPS and reverse proxying simple for a self-hosted single-server deployment.

What it does

80/443을 받고 내부 server container의 :8080으로 proxy한다.

Why this stack

Let's Encrypt 자동 인증서와 단순 Caddyfile이 self-hosted 배포에 잘 맞다.

Trade-off

복잡한 enterprise routing이나 WAF 기능은 별도 계층이 필요할 수 있다.

Alternative

Nginx는 널리 쓰이지만 cert 자동화가 더 수동이고, ALB는 managed지만 cloud 의존이 생긴다.

Terms you must know

reverse proxy = 앞단에서 요청을 받아 내부 서비스로 넘기는 서버
TLS termination = HTTPS 암호화 처리를 proxy에서 끝내는 것
Caddyfile = Caddy 설정 파일

Where

deploy/caddy/Caddyfile, docker-compose.prod.yml

Beginner trap

Caddy가 application authentication을 대신하지 않는다.

9. Security

9. SecurityCore

Pre-shared key agent auth

agent가 서버에 이벤트를 보낼 때 쓰는 공유 비밀키다.

PSK is an intentionally simple enrollment/auth mechanism, but the honest upgrade path is per-agent mTLS.

What it does

X-Agent-PSK 또는 X-Osquery-PSK header를 constant-time compare로 검증한다.

Why this stack

초기 설치와 작은 팀 운영에서는 단순하고 빠르다.

Trade-off

키가 유출되면 모든 agent가 영향받고 개별 취소/회전이 어렵다.

Alternative

mTLS certificate는 agent별 식별/취소가 가능하지만 발급/배포/회전이 복잡하다.

Terms you must know

PSK = 미리 나눠 가진 비밀키
constant-time compare = timing leak을 줄이는 비교
mTLS = client certificate로 agent를 인증하는 방식

Where

internal/endpoint/handler.go, docs/LIMITATIONS.md

Beginner trap

PSK가 있으니 endpoint identity가 완벽하다고 말하면 안 된다.

9. SecurityCore

DB trigger hash chain

로그 행마다 이전 행 hash를 연결해 변조를 탐지하는 구조다.

The hash chain is an application-level tamper-evidence mechanism, not a legal-grade immutable ledger.

What it does

audit_logs와 endpoint_events INSERT trigger가 prev_hash와 row_hash를 계산하고 update/delete trigger가 수정을 막는다.

Why this stack

application code를 우회해도 DB insert 시 자동 적용되므로 audit integrity가 강해진다.

Trade-off

DB superuser가 trigger를 끄고 재계산하면 우회할 수 있어 법적 증거 수준은 아니다.

Alternative

외부 timestamping, WORM storage, 별도 hash mirror가 더 강한 증거성을 준다.

Terms you must know

hash chain = 이전 hash와 내 데이터를 연결한 사슬
trigger = DB 이벤트에 자동 실행되는 함수
tamper-evident = 변조되면 흔적이 남는 성질

Where

migrations/008_log_integrity.up.sql, 013_audit_advisory_lock.up.sql

Beginner trap

해시체인을 블록체인이나 법적 불변 저장소처럼 과장하면 안 된다.

9. SecurityCore

JWT access and refresh tokens

로그인 상태를 나타내는 서명된 token pair다.

JWT gives DocVault a simple signed identity mechanism for both web and API flows.

What it does

15분 access token, 24시간 refresh token, pending 2FA token을 HMAC 서명으로 검증한다.

Why this stack

관리자 UI와 JSON API가 stateless하게 identity를 확인할 수 있다.

Trade-off

토큰 탈취 시 만료 전까지 위험하고 server-side immediate revoke는 약하다.

Alternative

서버 세션은 revoke가 쉽지만 저장소가 필요하고, opaque token은 조회 비용이 있다.

Terms you must know

access token = API 접근용 짧은 토큰
refresh token = 새 access token을 받는 긴 토큰
claim = 토큰 안의 정보

Where

internal/auth/jwt.go

Beginner trap

JWT payload는 암호화된 비밀 데이터가 아니다.

9. SecurityCore

TOTP 2FA

앱에서 생성되는 6자리 일회용 코드로 2차 인증을 한다.

TOTP adds a second authentication factor for admin access without relying on SMS.

What it does

비밀번호 확인 후 pending_2fa token을 주고 TOTP 검증이 성공해야 최종 token을 발급한다.

Why this stack

관리자 보안 제품에서는 password 하나만으로는 부족하다.

Trade-off

복구 코드와 secret 보관, 시간 drift, 사용자 onboarding 부담이 있다.

Alternative

WebAuthn/passkey는 phishing resistance가 더 좋지만 구현/사용자 장벽이 높다.

Terms you must know

TOTP = time-based one-time password
HOTP = counter 기반 one-time password
skew = 시간 오차 허용 범위

Where

internal/auth/totp.go, login_2fa templates

Beginner trap

2FA가 있다고 세션 탈취나 recovery code 보관 문제가 사라지는 건 아니다.

9. SecurityCore

SecretProtector

TOTP secret 같은 작은 인증 비밀을 master key로 암호화한다.

SecretProtector encrypts new authentication secrets while still allowing legacy values until users rotate them.

What it does

enc:v1 prefix가 있는 값은 AES-GCM으로 열고, legacy plaintext는 rotation 전까지 유지한다.

Why this stack

기존 사용자를 깨지 않으면서 새 secret은 암호화할 수 있는 migration-safe 구조다.

Trade-off

legacy plaintext가 남아 있고 recovery code 보관은 별도 개선이 필요하다.

Alternative

전용 KMS를 쓰면 키 관리가 좋아지지만 self-hosted 단순성이 떨어진다.

Terms you must know

secret = 인증에 쓰이는 민감값
legacy plaintext = 예전 방식으로 암호화되지 않은 값
prefix = 저장 형식을 구분하는 앞부분 문자열

Where

internal/auth/secret.go, docs/DEPLOY.md open items

Beginner trap

새 secret 암호화와 기존 secret 완전 정리는 다른 작업이다.

9. SecurityCore

CSRF protection

로그인된 브라우저가 다른 사이트에 속아 요청하는 것을 막는 장치다.

CSRF protection is necessary because DocVault has cookie-authenticated admin forms that mutate state.

What it does

보호된 web form POST에서 cookie token과 submitted token을 비교한다.

Why this stack

서버 렌더 form과 htmx POST가 많기 때문에 CSRF 방어가 필요하다.

Trade-off

현재 구현은 double-submit 형태라 cookie scope와 SameSite 설정에 의존한다.

Alternative

server-side synchronizer token은 더 강하지만 session storage가 필요하다.

Terms you must know

CSRF = 다른 사이트가 네 로그인 상태로 요청을 보내는 공격
SameSite = cookie가 cross-site 요청에 붙는 조건
double-submit = cookie token과 form token을 비교하는 방식

Where

internal/web/csrf.go

Beginner trap

CSRF token이 있다고 XSS가 막히는 것은 아니다.

9. SecurityCore

Login rate limiter

로그인 실패를 IP별로 제한하는 in-memory 보호 장치다.

The login rate limiter is a local defense against repeated password guessing, not a complete abuse platform.

What it does

10분 동안 5회 실패하면 15분 lock하고 성공하면 record를 지운다.

Why this stack

admin login brute force를 최소한으로 막아야 인터넷 노출 시 기본 방어가 된다.

Trade-off

메모리 기반이라 서버 재시작/멀티 인스턴스에서는 상태가 사라지거나 분산되지 않는다.

Alternative

Redis-backed limiter, reverse proxy/WAF, account-level lockout이 확장 대안이다.

Terms you must know

brute force = 비밀번호를 반복 대입하는 공격
lockout = 일정 시간 차단
X-Forwarded-For = proxy가 전달한 원래 IP header

Where

internal/web/ratelimit.go

Beginner trap

IP 기반 제한만으로 credential stuffing을 완전히 막는다고 말하지 말라.

9. SecurityCore

Chunked AES-256-GCM

파일을 64KiB 단위로 나눠 암호화와 무결성 검증을 같이 한다.

Chunked AES-GCM is the corrected design because file confidentiality without integrity is not enough for a security product.

What it does

각 chunk에 GCM tag가 붙고 final flag/chunk index nonce로 truncation/reorder를 탐지한다.

Why this stack

큰 파일을 메모리에 전부 올리지 않고도 변조 탐지가 되는 vault storage가 필요했다.

Trade-off

CTR보다 약간 무겁고 chunk format/version migration을 관리해야 한다.

Alternative

CTR+HMAC은 전체 파일 검증이 필요하고, 단일 GCM은 큰 파일 streaming에 불편하다.

Terms you must know

AEAD = 암호화와 인증을 함께 제공하는 방식
GCM tag = 변조를 감지하는 인증 태그
nonce = 같은 key에서 재사용하면 안 되는 값

Where

internal/vault/encryption.go, docs/LIMITATIONS.md

Beginner trap

AES라고만 말하면 안 되고 mode와 integrity를 같이 말해야 한다.

9. SecurityCore

Envelope encryption

파일별 key로 파일을 암호화하고 그 key를 master key로 봉인한다.

Envelope encryption separates file data keys from the master key so each file can be protected independently.

What it does

DB에는 encrypted_key/key_nonce가 있고 disk에는 encrypted blob이 저장된다.

Why this stack

파일마다 key를 분리하고 master key만 안전하게 관리하는 표준 KMS-like 패턴이다.

Trade-off

master key rotation tool은 아직 미구현이라 운영 절차가 필요하다.

Alternative

파일을 master key 하나로 직접 암호화하면 단순하지만 격리와 rotation이 약하다.

Terms you must know

data key = 실제 파일을 암호화하는 key
master key = data key를 보호하는 상위 key
key rotation = key를 새 것으로 바꾸는 작업

Where

internal/vault/keymanager.go, vault repository/migrations

Beginner trap

봉투 암호화가 있다고 master key 운영 문제가 사라지는 건 아니다.

10. Safety

10. SafetyCore

Mutating tool confirmation

AI action tool 실행 전에 사람의 명시 확인을 요구하는 gate다.

Mutating AI tools are server-gated behind an explicit human confirmation turn.

What it does

create_user, assign_host, acknowledge_alert 같은 mutating tools는 assistant가 confirmation prompt를 먼저 반환한다.

Why this stack

감시 대상 PC의 파일명/창제목이 tool output으로 들어와도 그것을 실행 승인으로 인정하지 않게 한다.

Trade-off

확인 문구 UX가 번거롭고 완전한 policy engine은 아니다.

Alternative

separate approval queue, signed action intent, role-based policy engine이 더 강한 대안이다.

Terms you must know

mutating tool = 시스템 상태를 바꾸는 도구
confirmation turn = 실행 전 사용자가 승인하는 대화 단계
untrusted output = 공격자가 영향을 줄 수 있는 데이터

Where

internal/agent/agent.go hasActionConfirmation/historyHasPendingConfirmation

Beginner trap

LLM이 조심하겠다고 말하는 것과 서버가 실행을 막는 것은 다르다.

10. SafetyCore

Agent action rollback

AI가 수행한 변경을 되돌릴 수 있게 action 기록을 남기는 구조다.

Rollback makes AI-assisted administration less risky by recording enough previous state to undo supported actions.

What it does

agent_actions table에 action_type, target_id, prev_state, performed_by를 저장하고 rollback handler가 복구한다.

Why this stack

AI action의 blast radius를 줄이려면 실행 기록과 inverse operation이 필요하다.

Trade-off

모든 외부 부작용을 완벽히 되돌릴 수는 없고 DB 상태 복구 중심이다.

Alternative

event sourcing은 더 체계적이지만 구현량이 크고, manual undo는 운영 부담이 크다.

Terms you must know

rollback = 이전 상태로 되돌림
prev_state = 변경 전 상태
blast radius = 실패/오작동이 퍼지는 범위

Where

internal/agent/actions.go, migration 015

Beginner trap

rollback이 있다고 위험한 action을 마음대로 실행해도 되는 건 아니다.

11. Testing

11. TestingCore

Go tests, vet, Windows CI

Go package test와 정적 검사, Windows agent 검증을 묶은 검증 체계다.

The test suite covers core packages, but the honest gap is load testing and real osquery end-to-end verification.

What it does

Makefile test-all이 build/vet/internal package tests를 순서대로 돌리고 Windows 관련 CI가 agent onboarding을 검증한다.

Why this stack

보안 제품은 암호화, auth, endpoint parsing, audit middleware를 자동 테스트로 지켜야 한다.

Trade-off

부하 테스트와 실제 osquery daemon end-to-end 검증은 아직 한계로 남아 있다.

Alternative

Playwright/e2e, load test, real Windows hardware smoke test가 보완책이다.

Terms you must know

go test = Go 테스트 실행
go vet = 의심스러운 Go 코드 정적 검사
CI = 코드 변경마다 자동 검증

Where

Makefile, internal/*/*_test.go, docs/WINDOWS_VM_TEST.md

Beginner trap

테스트 통과를 운영 성능 검증으로 착각하면 안 된다.

12. Ops

12. OpsCore

Agent heartbeat and self-test

agent가 살아있는지와 clipboard 캡처 가능 여부를 알려주는 신호다.

Heartbeat-based liveness prevents idle machines from looking dead just because no clipboard event occurred.

What it does

heartbeat는 last_checkin을 갱신하고 self-test는 interactive mode와 clipboard availability를 기록한다.

Why this stack

클립보드 변화가 없어도 PC가 보고 중인지 관리자에게 보여줘야 한다.

Trade-off

heartbeat는 agent가 떠 있다는 증거이지 실제 탐지 품질 전체를 보장하지 않는다.

Alternative

이벤트 timestamp만으로 liveness를 판단하면 idle PC가 offline처럼 보이는 문제가 생긴다.

Terms you must know

liveness = 살아있는지 상태
self-test = agent가 자기 기능을 검사해 보고
last_checkin = 마지막 보고 시각

Where

ReceiveHeartbeat, ReceiveSelfTest, endpoint_agents

Beginner trap

heartbeat가 있다고 모든 event가 빠짐없이 수집됐다고 말하면 안 된다.

12. OpsCore

pg_dump and vault backup

Postgres와 vault blob을 복구 가능하게 보관하는 운영 절차다.

For a single-box product, backup and restore discipline is the real reliability story.

What it does

deploy/backup/backup.sh와 rsync 기반으로 DB dump와 encrypted files를 외부로 옮기는 구상이다.

Why this stack

단일 서버 제품에서는 backup/restore가 HA보다 먼저인 생존 조건이다.

Trade-off

백업 암호화, off-host storage, restore drill이 없으면 절반짜리다.

Alternative

managed RDS snapshot/S3 lifecycle은 강하지만 self-hosted 단순성이 줄어든다.

Terms you must know

backup = 복구용 사본
restore drill = 실제 복구 연습
off-host = 같은 서버가 아닌 다른 위치

Where

deploy/backup/backup.sh, docs/LIMITATIONS.md

Beginner trap

백업 스크립트가 있다는 것과 복구가 검증됐다는 것은 다르다.

12. OpsCore

slog JSON logging

Go 표준 structured logger로 서버 이벤트를 남긴다.

slog gives a structured log trail, but DocVault still lacks full metrics and tracing.

What it does

startup, agent enrollment, endpoint processing, AI/tool errors를 key-value log로 출력한다.

Why this stack

container stdout과 잘 맞고 문제 원인 추적에 필요한 context를 붙이기 쉽다.

Trade-off

Prometheus/OpenTelemetry 같은 metric/trace는 아직 없어서 운영 관측성은 약하다.

Alternative

zap/zerolog는 더 빠르고, OpenTelemetry는 trace/metrics correlation에 강하다.

Terms you must know

structured log = key-value 형태의 로그
stdout = container가 내보내는 기본 출력
observability = 시스템 상태를 밖에서 이해하는 능력

Where

cmd/server/main.go, docs/LIMITATIONS.md

Beginner trap

로그가 있다고 p95/p99나 alerting이 준비된 것은 아니다.

12. OpsCore

Health endpoint

서버가 살아있는지 확인하는 간단한 HTTP endpoint다.

The health endpoint is a minimal liveness check, not a complete production readiness probe.

What it does

/health가 JSON ok를 반환해 reverse proxy나 smoke test가 확인할 수 있다.

Why this stack

배포/운영에서 최소한 process liveness를 확인하는 기준점이다.

Trade-off

DB 연결, migration 상태, queue 상태까지 깊게 검증하지는 않는다.

Alternative

readiness/liveness를 나누고 DB ping/critical dependency check를 넣는 것이 더 좋다.

Terms you must know

health check = 서비스 상태 확인 요청
liveness = 프로세스가 살아있는지
readiness = 요청을 처리할 준비가 됐는지

Where

internal/web/router.go /health

Beginner trap

health 200만 보고 전체 기능이 정상이라고 말하면 안 된다.

12. OpsCore

Windows code signing

Windows agent 실행파일에 신뢰 가능한 디지털 서명을 붙이는 배포 단계다.

Code signing is a shipping problem, not a coding problem: unsigned agents create user trust and install friction.

What it does

make sign-windows는 osslsigncode와 유료 Authenticode cert로 agent binary를 서명하도록 준비한다.

Why this stack

SmartScreen friction을 줄이고 비전문 사용자 설치 성공률을 높이기 위해 필요하다.

Trade-off

진짜 신뢰 인증서는 비용과 신원 검증이 필요하며 self-signed로 해결되지 않는다.

Alternative

원격 설치 지원은 빠르지만 확장성이 낮고, Microsoft Store/MDM 배포는 신뢰성은 높지만 절차가 무겁다.

Terms you must know

Authenticode = Windows 실행파일 서명 방식
SmartScreen = Windows 다운로드 실행 경고
timestamp server = 서명 시점을 증명하는 서버

Where

Makefile sign-windows, docs/CODE_SIGNING.md

Beginner trap

자체 서명으로 SmartScreen 문제가 완전히 해결된다고 말하면 안 된다.

12. OpsCore

Portfolio demo isolation

실제 고객/친구 DB와 분리된 demo stack이다.

The demo stack is intentionally isolated so portfolio access never touches the real product database.

What it does

docker-compose.demo.yml은 별도 project/volume/seed/demo login을 사용해 public portfolio demo를 만든다.

Why this stack

포트폴리오 검증을 위해 실제 데이터와 demo 데이터를 절대 섞지 않는 것이 중요하다.

Trade-off

demo convenience가 product instance에 켜지면 보안 사고가 된다.

Alternative

snapshot anonymization이나 staging environment도 대안이지만 격리 원칙은 같아야 한다.

Terms you must know

demo seed = 샘플 데이터를 자동 생성
isolation = 서로 영향을 주지 않게 분리
volume = Docker가 보존하는 데이터 저장소

Where

docker-compose.demo.yml, docs/DEPLOY.md, content logs

Beginner trap

demo login 기능을 production에 켜두면 안 된다.

Start from zero path

이 순서대로 말하면 product scope에서 운영 한계까지 끊기지 않는다.

steps

Say what it is not

DRM/EDR/UEBA가 아니라는 선을 긋는다.

DocVault는 파일 유출을 막는 DRM이 아니라 직원 PC 활동을 수집해 사후 탐지와 감사를 돕는 도구다.

DocVault is a detection and audit tool, not a DRM or full EDR replacement.

detectionauditsmall-team

Code focus: README + LIMITATIONS 먼저 읽기

Explain the topology

PC agent -> Go server -> Postgres -> web UI 흐름을 말한다.

직원 PC의 osquery와 clipboard agent가 HTTPS로 이벤트를 보내고 서버가 저장/분석/표시한다.

Endpoint agents send activity to a Go server, which stores it in Postgres and exposes it through an admin console.

osqueryclipboard agentPostgres

Code focus: docs/ARCHITECTURE topology

Defend Go

Go 선택 이유를 agent 배포 중심으로 말한다.

Go를 쓴 핵심 이유는 서버보다 endpoint agent 배포다. Windows/macOS 단일 바이너리가 중요했다.

The main reason for Go was endpoint deployment: one static binary for the server and cross-platform agents.

Gostatic binarycross-platform

Code focus: go.mod, Makefile GOOS/GOARCH

Walk the web boundary

chi route group과 middleware 경계를 말한다.

public, agent, protected API, protected web route가 서로 다른 middleware 경계를 가진다.

The router separates public, agent, API, and web routes with different authentication and audit boundaries.

chiJWTaudit middlewareCSRF

Code focus: internal/web/router.go

Explain endpoint ingestion

clipboard와 osquery를 구분한다.

osquery와 clipboard event는 들어오는 형식은 다르지만 endpoint_events schema로 normalize된다.

Different endpoint payloads are normalized into one endpoint_events schema for timeline, alerts, and analysis.

PSKnormalizeendpoint_events

Code focus: internal/endpoint/handler.go

Explain hash-chain integrity

무결성 구조와 한계를 같이 말한다.

DB trigger가 prev_hash/row_hash를 계산하고 advisory lock으로 동시성 분기를 막지만 DB superuser 우회는 가능하다.

Database triggers make logs tamper-evident, while advisory locks prevent hash-chain fork races.

triggerhash chainadvisory lock

Code focus: migrations 008 and 013

Explain encrypted vault

envelope encryption과 chunked GCM을 말한다.

파일별 key로 본문을 chunked AES-GCM 암호화하고 그 key를 master key로 봉인한다.

The vault uses per-file keys sealed by a master key, and streams file contents through chunked AES-GCM.

file keymaster keyGCMstreaming

Code focus: internal/vault/encryption.go

Explain rule-based detection

UEBA 과장을 피한다.

이건 ML UEBA가 아니라 30일 baseline과 임계값 rule로 위험 점수를 계산하는 구조다.

The honest label is rule-based anomaly scoring, not machine-learning UEBA.

baselinerisk scorealert

Code focus: internal/ueba and internal/alert

Explain AI as helper

AI가 핵심 수집기가 아니라 운영 보조임을 말한다.

AI는 이벤트를 수집하는 핵심이 아니라 요약과 제한된 admin action을 돕는 보조 계층이다.

AI is an operations helper on top of the security system, not the core ingestion engine.

AI briefingtool-useconfirmation

Code focus: internal/insight and internal/agent

Explain deployment

Compose single host와 Caddy를 말한다.

Compose가 db, migrate, seed, server, Caddy를 한 host에서 띄우고 Caddy가 HTTPS를 처리한다.

The deployment is a single-host Compose stack with Caddy in front of the Go server.

Docker ComposeCaddyvolumes

Code focus: docker-compose.prod.yml

Attack the limits

한계를 먼저 말해 신뢰를 만든다.

한계는 명확하다. HA 없음, PSK 단독, 커널 가시성 없음, 부하테스트 미실시다.

The key limits are no HA, PSK-based agent auth, no kernel visibility, and no load-test numbers.

no HAPSKno load testno kernel

Code focus: docs/LIMITATIONS.md

Give the 60-second interview answer

전체를 한 문단으로 말한다.

DocVault는 endpoint event collection, tamper-evident audit, encrypted vault, rule-based alerts를 한 Go/Postgres self-hosted stack으로 묶은 제품이다.

DocVault combines endpoint collection, tamper-evident audit logs, encrypted file storage, and rule-based alerts in a self-hosted Go/Postgres stack.

topologyintegrityencryptionlimits

Code focus: README 5-minute script + actual source

Architecture layers

각 layer는 “역할, 왜 이 기술, 어디 코드”까지 같이 봐라.

Admin console

Admins inspect endpoint events, audit logs, files, alerts, agents, monitoring config, and AI summaries.

관리자가 보는 화면이다. 직원별 활동, 파일, 경보, 에이전트 상태, 설치 링크, AI 브리핑을 한 곳에서 본다.

Why: 관리자 도구라 복잡한 SPA보다 htmx + Go template로 서버 렌더링하는 것이 단순하고 배포가 쉽다.

htmxGo templatesSSECSRF

internal/web

Go HTTP server

The single backend process serves web pages, APIs, agent receivers, background schedulers, and AI endpoints.

서버 한 프로세스가 웹 UI, API, agent 이벤트 수신, baseline 재계산, AI endpoint까지 책임진다.

Why: 작은 self-hosted 제품은 서비스 분산보다 단일 Go binary가 설치와 운영을 단순하게 만든다.

cmd/servernet/httpchislog

cmd/server/main.go

Middleware chain

Authentication, audit logging, CSRF, role checks, rate limiting, and recovery are enforced around handlers.

요청이 handler에 닿기 전후로 인증, 감사, CSRF, 관리자 권한 같은 공통 검문소를 통과한다.

Why: 보안/감사는 모든 route에 반복되므로 handler마다 흩뿌리면 누락된다. middleware가 공통 경계다.

JWTaudit middlewareCSRFRequireRole

internal/web/router.go

PostgreSQL core

Stores users, files, endpoint events, audit logs, alert state, baselines, install tokens, and agent actions.

제품의 사실을 저장하는 중심이다. endpoint 이벤트, 감사 로그, 파일 메타데이터, 경보, AI action 기록이 들어간다.

Why: 트리거, transaction, index, constraint가 필요해서 단일 Postgres가 초기 규모에 맞다.

pgxpoolmigrationstriggersindexes

internal/database/migrations

Endpoint collection layer

osquery and the custom clipboard agent collect host activity and send it to the server.

직원 PC에 있는 수집 계층이다. 파일/USB/process는 osquery, clipboard는 자체 Go agent가 맡는다.

Why: 검증된 osquery를 재사용하고, osquery가 약한 clipboard만 직접 만든다.

osqueryclipboard agentheartbeatself-test

cmd/clipagent, deploy/osquery, internal/endpoint

Event normalization

Raw osquery and clipboard payloads are converted into the common endpoint_events schema.

서로 다른 agent payload를 하나의 이벤트 테이블 모양으로 맞춘다.

Why: 통합 timeline, alert, AI assistant, dashboard가 같은 schema를 읽어야 한다.

NormalizeOsqueryEventsNormalizeClipboardEventhostname mappingevent_type

internal/endpoint

Audit and integrity layer

Every protected request is audited, and audit/event rows are chained with DB-trigger hashes.

관리자 행동과 endpoint 이벤트가 변조 흔적을 남기도록 DB hash chain으로 묶인다.

Why: application code보다 DB trigger가 누락과 우회를 줄인다. advisory lock으로 동시성 race도 막았다.

audit_logsendpoint_eventsprev_hashrow_hash

internal/audit, migrations 008/013

Encrypted vault storage

Files are encrypted with per-file keys and stored as encrypted blobs on disk.

파일 본문은 디스크에 암호화 blob으로 저장되고, DB에는 key와 metadata가 들어간다.

Why: 문서 보안 제품에서 confidentiality와 integrity를 같이 말해야 하므로 chunked AES-GCM을 쓴다.

Envelope encryptionAES-256-GCM64KiB chunksfile_versions

internal/vault

Detection and alert layer

Rule-based anomaly scoring and alert rules turn raw events into risk signals.

raw 이벤트를 경보와 위험 점수로 바꾸는 계층이다. 머신러닝이 아니라 규칙 기반이다.

Why: 작은 팀에서는 설명 가능한 임계값 rule이 ML보다 구현/운영/분쟁 설명에 현실적이다.

ueba analyzeralert enginemonitoring configrisk scores

internal/ueba, internal/alert, internal/monitoring

AI operations layer

Optional AI briefing and tool-use assistant help admins understand and operate the system.

AI는 핵심 수집기가 아니라 운영 보조다. 최근 이벤트 요약과 제한된 admin action을 돕는다.

Why: 데이터가 table에 있으므로 문서 RAG보다 SQL tool-use가 더 정확한 grounding을 준다.

insight summarizeragent toolsconfirmation gateagent_actions

internal/insight, internal/agent

Single-host deployment

Docker Compose runs db, migrate, seed, server, and Caddy on one host.

작은 팀이 한 서버에 올려 직접 운영하는 구조다. Caddy가 HTTPS를 맡고 Go server는 내부에서 돈다.

Why: 초기 self-hosted 제품은 Kubernetes보다 Compose가 이해와 복구가 쉽다.

Dockerfiledocker-compose.prod.ymlCaddyvolumes

docker-compose.prod.yml, deploy

Known limitations

The product explicitly documents where it is not production security, HA, legal evidence, or full UEBA.

과장하면 안 되는 한계다. 차단 불가, HA 없음, PSK 한계, 법적 증거 한계, 부하테스트 미실시가 있다.

Why: 면접에서는 만든 것보다 한계를 정확히 말하는 것이 신뢰다.

LIMITATIONS.mdrule-based scoringPSKno HA

docs/LIMITATIONS.md

Runtime flows

구조보다 더 중요한 건 요청과 데이터가 어디로 흐르는지다.

Selected flow

Clipboard event ingestion

직원 PC에서 복사가 발생하면 Go clipboard agent가 PSK와 함께 이벤트를 보내고 서버가 endpoint_events에 저장한 뒤 alert/UEBA/SSE로 fan-out한다.

1clipboard changes

2agent POST /api/events/clipboard

3PSK check

4install token/user resolution

5normalize event

6insert endpoint_events

7hash trigger

8alert + scoring + SSE

Failure checks

PSK가 없으면 fail-closed 되는가
Windows interactive session에서 실행 중인가
hostname이 잘못 매핑되지 않았는가
clipboard event와 heartbeat를 혼동하지 않는가

Say it

Clipboard collection is a custom Go agent path: authenticate, normalize, store, hash-chain, then evaluate alerts and risk.

Backend domains

도메인을 책임, 파일, 테이블, 면접 문장으로 연결한다.

auth

JWT, refresh token, pending 2FA token, TOTP, secret protection, auth middleware.

Auth uses signed JWTs plus optional TOTP; new TOTP secrets are protected by the master key, while legacy plaintext remains an honest migration caveat.

Files: internal/auth/jwt.go, internal/auth/totp.go, internal/auth/secret.go, internal/auth/middleware.go

Tables: users

user

직원/admin 계정, role, password hashing, admin user management.

Users are the human identity layer; endpoint agents are mapped back to users for accountable timelines.

Files: internal/user, internal/web/form handlers

Tables: users

endpoint

osquery/clipboard events, enrollment, heartbeat, self-test, hostname attribution.

Endpoint collection is split: osquery covers general host telemetry, and the custom Go agent covers clipboard capture and liveness.

Files: internal/endpoint, cmd/clipagent, deploy/osquery

Tables: endpoint_events, endpoint_agents, install_tokens

audit

모든 보호 route의 관리자 행동 기록, CSV export, integrity verification.

Audit logging is middleware because it is a cross-cutting requirement, not something each handler should remember manually.

Files: internal/audit, internal/web/router.go

Tables: audit_logs

vault

파일 업로드/다운로드/버전/checkout/checkin, envelope encryption, storage.

The vault stores encrypted blobs on disk and metadata in Postgres, using envelope encryption and chunked GCM for integrity.

Files: internal/vault, internal/folder

Tables: files, file_versions, folders, folder_permissions, encryption_keys

monitoring

감시 process/extension/path/disguise rule을 DB 기반으로 관리.

Monitoring config is data-driven so admins can tune detection policy without redeploying the server.

Files: internal/monitoring

Tables: monitored_process_groups, monitored_extensions, monitored_paths, disguise_rules

alert

이벤트 rule 평가, alert 생성, Slack/email notifier, acknowledge.

The alert engine turns stored telemetry into actionable signals, but inline evaluation is a simplicity trade-off.

Files: internal/alert

Tables: alerts, alert_rules

ueba

30일 baseline 재계산, rule-based anomaly factors, risk scores.

The honest name is rule-based anomaly scoring, not ML-based UEBA.

Files: internal/ueba

Tables: user_behavior_baselines, anomaly_events, risk_scores

tracking

민감 파일 hash 등록과 endpoint event hash match detection.

Hash-based file tracking can find renamed known files, but it will miss modified or unknown files.

Files: internal/tracking

Tables: tracked_files, tracked_file_detections

web

Server-rendered admin UI, templates, forms, SSE, CSRF, install pages.

The frontend is server-rendered HTML with htmx, which is appropriate for an internal admin console.

Files: internal/web

Tables: many read/write through handlers

insight

최근 이벤트 digest를 AI provider에 보내 짧은 보안 브리핑 생성.

The AI summary sees a compact factual digest, not arbitrary database access.

Files: internal/insight

Tables: endpoint_events, alerts

agent-ai

agent AI

Why it matters

운영 성숙도 질문에서 빠질 수 없는 한계다.

Trap

로그를 관측성 완성으로 말하면 안 된다.

Where

LIMITATIONS L-OPS-1

metricstracing

Source map

이 페이지가 어떤 docvault 문서/코드에서 왔는지 기억해라.

Product README

docvault/README.md

Product definition, stack, quick start, honest non-goals

Architecture

docvault/docs/ARCHITECTURE.md

Topology, flows, core patterns, 5-minute script

Decisions

docvault/docs/DECISIONS.md

Why Go, Postgres-only, htmx, detection not prevention

Limitations

docvault/docs/LIMITATIONS.md

Security, scale, ops, UI, scope caveats

Beginner guide

docvault/docs/STUDY_GUIDE_BEGINNER.ko.md

Zero-jargon technology explanations

Server entry

docvault/cmd/server/main.go

Runtime wiring, schedulers, AI, shutdown

Router

docvault/internal/web/router.go

Auth, audit, CSRF, agent endpoints, protected pages

Endpoint domain

docvault/internal/endpoint

osquery, clipboard, heartbeat, enrollment, normalization

Vault domain

docvault/internal/vault

Envelope encryption and chunked AES-GCM

Infra

docvault/docker-compose.prod.yml + deploy

문서에 live osquery daemon 검증 한계가 명시돼 있다.

에이전트 전체가 field-proven이라고 과장하면 안 된다.

Next: real Windows/osquery smoke test 기록.