SSH Process Analyzer

Linux 원격 서버에서 실행 중인 프로세스를 주기적으로 수집하고, 현재 누가 어떤 작업을 진행 중인지 확인하는 조회 전용 모니터링 시스템이다.

MVP의 중심은 서버 관리가 아니라 프로세스 OS 소유주별 현재 작업 현황과 통계다. SSH 원격 접속, 원격 셸, 프로세스 종료와 같은 제어 기능은 MVP에 포함하지 않는다.

주요 기능

• Linux 프로세스 snapshot 주기 수집
• 프로세스 OS 소유주 이름 기준 사용자별 현재 작업 현황
• 작업 유형 분류, 미분류 작업 표시
• CPU, 메모리, 실행 시간 조회
• 사용자별 현재 작업 수와 기간별 통계
• 장시간 실행, 중복 실행 의심, stale/offline 서버 표시
• tenant membership 기반 조회 권한

아키텍처

Linux systemd timer oneshot collector
  -> HTTPS push
  -> Cloud Run collector-api
  -> Cloud Firestore
  -> React web app
  -> Firebase Hosting

collector 요청은 Ed25519로 서명한다. API는 replay 차단, agent registry binding, snapshot generation publish transaction을 처리한다. 웹앱은 조회 전용이며 raw command 전체와 환경 변수는 노출하지 않는다.

디렉터리

collector/       Linux collector와 systemd unit
collector-api/   Cloud Run API
contracts/       JSON Schema, 서명, 통계 계약
docs/            데이터 모델과 운영 정책 결정표
firebase/        Firestore Rules와 index
remote-actions/  MVP에서 비활성인 원격 액션 경계
tests/           fixture와 통합 테스트
web/             React 웹앱

사용 흐름

현재는 계약 정의 단계이므로 실행 가능한 애플리케이션은 아직 없다.

구현 완료 후 기본 흐름은 다음과 같다.

1. Linux 서버에 collector와 systemd timer를 설치한다.
2. collector가 process snapshot을 수집하고 서명하여 API로 전송한다.
3. API가 검증을 통과한 snapshot을 Firestore에 publish한다.
4. 사용자는 웹 대시보드에서 OS process 소유주별 현재 작업과 통계를 확인한다.

개발 상태

현재 단계: Phase 2 - Firestore Rules와 generation repository 구현

• 완료: monorepo 기본 구조
• 완료: snapshot JSON Schema v1
• 완료: canonical signing v1과 replay fixture
• 완료: Firestore Rules와 index 초안
• 완료: OS process 소유주 기준 통계 계약
• 완료: generation repository 상태 전이와 in-memory transaction adapter
• 완료: publish pointer 역행 방지, agent binding, quarantine, cleanup claim 단위 테스트
• 완료: Firestore emulator 실행 설정과 Rules 정적 계약 테스트
• 완료: Phase 0 MVP 운영 정책 기본값 확정
• 외부 입력 필요: staging, production GCP/Firebase project ID
• 진행 전: Firebase SDK 기반 repository adapter와 emulator 통합 테스트
• 진행 전: collector API vertical slice, collector, web 실제 구현
• 추후 반영: Figma 파일 기반 UI 컴포넌트와 스타일

운영 정책 기본값과 배포 전 외부 입력 항목은 docs/phase0-decisions.md, 전체 구현 계획은 implement.md에서 관리한다.

개발 진행 기록

진행 기록은 시계열로 누적한다. 기존 기록을 수정하거나 덮어쓰기보다 새 항목을 아래에 추가한다.

단계별 버전 관리 규칙

각 개발 단계 또는 독립적으로 검증 가능한 작업 단위가 끝날 때마다 아래 절차를 수행한다.

1. 변경 사항과 테스트 결과를 확인한다.
2. 테스트 파일이나 fixture가 추가되면 tests/ 아래 트리를 기능별로 확장한다.
3. README의 개발 상태와 개발 진행 기록에 날짜, 버전, 작업 설명, 테스트 결과를 추가한다.
4. 변경 파일을 Git commit으로 기록한다.
5. main 브랜치를 원격 저장소에 push한다.

기록에는 최소한 아래 내용을 포함한다.

• 날짜
• 버전
• 작업 설명
• 추가 또는 변경된 주요 파일
• 실행한 테스트와 결과
• 남은 작업 또는 미정 운영값

테스트 트리는 구현 범위에 따라 아래 구조에서 확장한다.

tests/
  fixtures/       signing, snapshot, process, auth 입력 데이터
  integration/    API, repository, Firestore Rules, UI 통합 검증
  unit/           모듈 단위 검증이 생기면 추가
  e2e/            staging 사용자 흐름 검증이 생기면 추가

2026-06-02 - v0.1.0

• 프로젝트 저장소 초기화
• MVP 목적을 OS process 소유주별 현재 작업 현황과 통계 조회로 확정
• Phase 1 기본 디렉터리 생성
• snapshot, signing, analytics 계약 추가
• Firestore Rules, index, env 예시 추가
• Figma 파일은 추후 제공 후 선별 반영 예정

2026-06-02 - v0.1.1

• 단계 완료 시 README 기록, Git commit, main push를 수행하는 규칙 추가
• 테스트가 생기면 tests/ 트리를 fixture, integration, unit, e2e로 확장하도록 기준 추가
• 테스트: 문서 변경만 수행했으며 애플리케이션 테스트는 아직 없음
• 남은 작업: Phase 0 운영 정책 값 확정, collector/API/web 실제 구현

2026-06-02 - v0.2.0

• Phase 2 generation repository 상태 전이 구현
• in-memory transaction adapter 추가
• immutable process staging, batch manifest 완료, 0건 snapshot publish 구현
• agent tenant/host binding, quarantine, 오래된 snapshot과 동일 시각 snapshot pointer 역행 방지 구현
• cleanup deleting claim, active resume lease 차단, idempotent delete 구현
• Firestore Rules를 현재 published generation만 브라우저에서 읽을 수 있도록 제한
• Firestore emulator 설정과 tests/unit/, tests/integration/ 트리 추가
• 테스트: npm test 통과, unit 및 Rules 정적 계약 테스트 13개 성공
• 테스트: JSON 설정 파일 jq empty 검증 성공
• 미실행: Firebase SDK 기반 emulator 통합 테스트는 adapter 연결 후 수행
• 남은 작업: Phase 0 운영 정책 값 확정, Firebase adapter와 emulator 통합 테스트, Phase 3 collector API vertical slice

2026-06-02 - v0.2.1

• Phase 0 MVP 운영 정책 기본값 확정
• 수집 주기 60초, snapshot 보존 7일, replay TTL 24시간으로 확정
• gzip 허용, wire body 8 MiB, 압축 해제 body 16 MiB, process 최대 10,000개로 확정
• 초과 요청은 HTTP 413 전체 reject, Firestore batch는 process 400개 단위로 확정
• 장시간 실행 24시간, stale 2분, warn 5분, offline 15분으로 확정
• cleanup job은 1시간 주기, 실행당 generation 100개, timeout 15분, 최대 재시도 3회로 확정
• 구현 공통값을 contracts/operational-policy-v1.json에 추가
• 테스트: jq empty 검증 성공, npm test unit 및 계약 테스트 16개 성공
• 외부 입력 필요: staging, production GCP/Firebase project ID
• 남은 작업: Firebase adapter와 emulator 통합 테스트, Phase 3 collector API vertical slice

참고 문서

• 데이터 모델 v1
• Phase 0 운영 정책 결정표
• Snapshot Schema v1
• Canonical Signing v1
• Analytics v1
• Operational Policy v1