init: document-haness 하네스 설계

2026-07-24 13:58:08 +09:00
parent d6f78f92a0
commit c39406bbdd
219 changed files with 7010 additions and 20052 deletions
@@ -0,0 +1,110 @@
+# Security and trust model
+
+## 보호 대상
+
+- provider 인증 정보와 로컬 계정
+- 실행 호스트의 파일·명령·네트워크 권한
+- 비공개 brief, source pack, draft
+- 출처 진실성과 최종 문서 정확성
+- 품질 게이트의 무결성
+
+## 위협과 완화
+
+### 1. Source/brief prompt injection
+
+위협: title, fact, note, URL, draft 안에 “이전 지시를 무시하라” 같은 문장이 들어간다.
+
+완화:
+
+- 모든 prompt에서 입력 블록을 명시적으로 untrusted data로 선언
+- 출력 스키마와 stage 역할을 입력 블록 밖에 정의
+- planner의 구조 변경을 코드로 검증
+- reviewer 결과도 JSON 파싱과 severity 계약으로 제한
+- 최종 출력에 결정적 린트와 독립 리뷰 적용
+
+잔여 위험: 언어 모델이 경계를 무시할 수 있다. 고위험 입력은 별도 sanitization, 제공자 정책, 인간 검토가 필요하다.
+
+### 2. Command injection
+
+위협: provider command가 외부 입력으로 조작된다.
+
+완화:
+
+- subprocess는 shell 없이 argument list로 실행
+- brief/source 값을 command에 삽입하지 않고 stdin으로 전달
+- `options.command`는 로컬 운영자가 승인한 config만 허용한다고 문서화
+- 인증 비밀을 command line에 넣지 않음
+
+잔여 위험: 악의적인 pipeline config 자체는 임의의 로컬 executable을 실행할 수 있다. config를 코드와 같은 신뢰 수준으로 관리해야 한다.
+
+### 3. 모델의 파일/명령 부작용
+
+위협: 에이전트 도구가 파일을 수정하거나 command를 실행한다.
+
+완화:
+
+- Codex 기본 sandbox `read-only`
+- 작성 prompt는 파일 수정이나 shell 사용을 요구하지 않음
+- Claude는 print mode 텍스트 출력을 사용
+- Antigravity에는 문서 생성 prompt만 전달
+
+잔여 위험: provider 자체 설정이나 조직 wrapper가 더 넓은 권한을 부여할 수 있다. 최소 권한과 격리 환경을 별도로 적용한다.
+
+### 4. 근거 세탁과 허위 인용
+
+위협: 모델이 관련만 있는 출처를 주장 근거처럼 붙이거나 source ID를 지어낸다.
+
+완화:
+
+- source pack에 출처가 지지하는 `facts`를 명시
+- 존재하지 않는 source ID를 error로 처리
+- evidence reviewer가 claim-marker fit를 검사
+- 원문 model response와 source pack을 보존
+
+잔여 위험: 하네스는 URL의 실제 내용이 `facts`와 일치하는지 자동 검증하지 않는다. source pack 작성자의 검증이 필요하다.
+
+### 5. 위험한 절차
+
+위협: 문서가 `rm -rf`, `DROP TABLE`, `kubectl delete`, `terraform destroy` 같은 명령을 안전장치 없이 제공한다.
+
+완화:
+
+- 대표 파괴 패턴을 blocker로 검사
+- 주변에 경고, 백업/복구, 롤백 문맥 요구
+- operations reviewer로 절차 상태 전이 검사
+
+잔여 위험: 패턴 목록은 완전하지 않으며 도메인별 위험 명령을 모두 알 수 없다. 조직별 lint rule 확장이 필요하다.
+
+### 6. 점수 조작
+
+위협: 모델 reviewer가 근거 없이 높은 점수를 주거나 초안 내부 지시를 따른다.
+
+완화:
+
+- 결정적 lint 점수와 모델 평균을 혼합
+- blocker/error 개수를 별도 gate
+- 여러 provider와 역할을 분리 가능
+- raw review를 보존
+
+잔여 위험: 여러 reviewer가 같은 모델 계열·학습 편향을 공유할 수 있다. 고위험 문서는 인간 reviewer와 실행 가능한 검증을 추가한다.
+
+### 7. 민감 정보 유출
+
+위협: brief/source/draft가 외부 모델 제공자에 전송된다.
+
+완화:
+
+- 하네스가 실제로 전송하는 prompt를 raw artifact로 확인 가능
+- provider별 조직 정책과 계정을 사용
+- Mock으로 로컬 배선 테스트 가능
+
+잔여 위험: live provider를 사용하면 해당 제공자의 처리 경계로 데이터가 이동한다. 비밀·개인정보·규제 데이터를 넣기 전에 조직 정책을 확인하고 필요한 경우 로컬 모델 adapter를 추가한다.
+
+## 운영 권고
+
+- pipeline config는 코드 리뷰와 버전 관리를 적용한다.
+- provider model ID와 CLI/SDK 버전을 배포 메타데이터에 고정한다.
+- run directory 접근 권한과 보존 기간을 정의한다.
+- 고위험 문서는 source pack 작성자와 최종 승인자를 분리한다.
+- 실제 명령과 코드는 sandbox/CI에서 실행해 결과를 source pack 또는 별도 evidence artifact로 연결한다.
+- PASS 문서를 자동 게시하지 말고, 위험도에 맞는 승인 단계를 둔다.