k-safeguard

Imported from jinseok3639/k-safeguard (AGENTS.md). Install upstream with npx skills add jinseok3639/k-safeguard. Copyright stays with the author.

k-safeguard — 에이전트 작업 지침

이 파일은 이 저장소에서 작업하는 모든 에이전트(Codex, Claude Code 등)가 따라야 할 프로젝트 지침이다. 전체 배경과 근거는 README.md를 참고한다. 이 파일과 실제 저장소 상태가 다르면 코드와 최신 커밋을 우선 확인하고 사용자에게 차이를 알린다.

한 줄 요약

한글 자모 단위 표기 난독화(된소리·연음·자모분해·초성체 등)에 대한 한국어 프롬프트 가드레일의 취약성을 실측하고, 모델 재학습 없이 기존 가드레일 앞단에 붙여 방어력을 복원하는 정규화 미들웨어를 만드는 오픈소스 프로젝트. 팀 온돌, 2026 오픈소스 SW 개발대회 자유과제(보안·안전) 트랙 출품작.

현재 상태를 알아내는 법

이 파일은 진행 상황·수치·날짜를 기록하지 않는다. 낡기 때문이다. 매 세션 직접 확인한다.

이 표와 실제 저장소가 다르면 저장소가 맞다. 그때는 이 표를 고친다.

절대 다시 논쟁하지 말 것

• 탐지 모델(가드레일) 자체를 새로 학습해 경쟁하지 않는다. Kanana Safeguard-Prompt가 이미 이 자리를 선점했고 탈옥 분류기+데이터셋도 포화 상태다. "기존 가드레일 앞단 전처리"로 포지셔닝한다.
• 최우선 산출물은 벤치마크가 아니라 정규화 하드닝 미들웨어다. 대회가 기능테스트·시연영상을 중시하는 실물 SW 대회라는 점 때문이다. 벤치마크·난독화 라이브러리는 근거이자 부산물로 다룬다.
• 범위는 한국어 표기 난독화와 순수 텍스트 대화형 챗봇의 콘텐츠 분류기 레이어로 한정한다. 코드스위칭 입력은 포함하되 한국어 부분의 표기 변형만 평가한다. 타 언어 우회, 멀티모달 공격, 에이전트형(도구호출·파일접근) 위협은 범위 밖이다.
• "세계 최초 발견"이라는 과장된 클레임을 쓰지 않는다. 아래 포지셔닝 규칙을 따른다.
• Git 운영은 2인 팀 연구형 프로젝트에 맞춘 경량 GitHub Flow를 쓴다. Git Flow, 강제 브랜치 보호, semantic-release 같은 무거운 프로세스로 바꾸지 않는다.

결정 로그

되돌리려면 팀 합의가 필요하다. 항목은 추가만 하고 지우지 않는다.

• 2026-08 구현 언어·패키징: Python + setuptools, src/ 레이아웃, 모노레포. 런타임 의존성 0개 유지
• 2026-08 시드 데이터셋: 505 시드(공격 301/정상 204) → 파생 5,555행, HF kimchunsik03/KoreanGuardrail, 데이터 CC-BY-4.0
• 2026-08 SLM 파인튜닝 노선 폐기. 규칙 기반 무손실 정규화 + opt-in 후보 provider로 확정. "모델 재학습 없이"가 프로젝트의 핵심 주장이므로 재론하지 않는다
• 2026-08 lossy provider(초성·된소리)는 기본 비활성 유지. 근거는 experiments/benchmark/TENSIFY_LOCKED_RESULT.md, CHOSUNG_GUARDRAIL_IMPACT.md
• 2026-08-25 초성·된소리 다중 view provider는 배포 공개 API에서 제거. 기존 후보 구현은 과거 실험 재현용 내부 모듈로만 보존하며 Gateway 권장 경로에 연결하지 않는다
• (미결) 평가 규격(EVALUATION_SPEC.md)의 주력 트랙 재정의 — GitHub Issue "EVALUATION_SPEC.md 0.2.0 개정 필요" 참고. 결정되면 여기에 한 줄 추가

포지셔닝 규칙

문서·보고서·발표자료·코드 설명에서 다음 톤을 벗어나면 교정한다.

1. 취약점 발견은 "단일 분류기형 가드레일은 구조적으로 뚫린다"는 국제적으로 이미 확립된 패턴을 한국어·한글난독화 축에서 처음 정량 확인한 것으로 서술한다 — 세계 최초 발견 주장 금지.
2. 미들웨어는 "완전한 해법"이 아니라 기존 배포된 단일-분류기 가드레일에 즉시 적용 가능한 진단도구 + 임시 완화책으로 서술한다 — "가드레일을 대체한다" 같은 과장 금지.
3. "가드레일 자체가 무의미한 거 아니냐"는 반론에는 "guardrails-by-construction(구조적 방어)은 에이전트형 위협 대응이고, 권한 제한 레버가 없는 순수 대화형 챗봇에는 분류기가 유일한 실질 방어"라는 논지로 답한다.

용어집

산출물 우선순위와 경계

1. 정규화 하드닝 미들웨어

기존 배포 가드레일 앞단에 붙는 전처리 레이어. 난독화를 보수적으로 정규화해 원래 가드레일의 탐지 성능을 복원한다. 정상 입력의 오탐·과잉 정규화도 함께 측정한다.

2. 벤치마크와 평가 하네스

난독화 전후 탐지율·회피율을 재현 가능하게 측정한다. 통합 하네스는 가칭 kanana_test_suite.py (미구현, experiments/benchmark/run_*.py로 분산). 평가 대상은 세 갈래다: Kanana Safeguard-Prompt 직접 입력, PromptGuard·LlamaGuard 등 다국어 가드레일 직접 입력, 번역 후 영어 가드레일 입력. 번역 파이프라인은 고전 NMT 충실도 실험과 LLM 번역기 하이재킹 실험을 분리한다.

3. 난독화 생성 라이브러리 (hf_repo/ko_obfuscator.py)

미들웨어에 종속되지 않는 독립 레드팀 도구. 구현 완료 5종: 자모 분해(jamo_decompose), 초성체(chosung), 된소리(tensify), 띄어쓰기 파괴(break_spacing), 투명문자 삽입(zwsp_inject). 연음·종성 크래밍·호모글리프는 미구현, 후속 과제다. 변형 강도와 무작위 시드를 기록해 재현 가능하게 한다.

패키지 불변식

• 원문 view는 항상 첫 번째로 보존한다.
• 기본 Gateway 경로는 무손실 정규화만 연결한다. 초성·된소리 다중 view provider는 공개 배포 경로에 제공하지 않는다.
• 전역 Unicode NFC를 적용하지 않는다. 현대 한글 자모열만 조합해 코드스위칭·이모지 ZWJ를 보존한다.
• 새 정규화·후보 생성 규칙에는 경계 케이스 테스트(빈 입력, 문장부호, 한영 혼용, 독립 자모)를 추가한다.

실험 규약

• locked-test는 사전등록 → seal → 단일 실행 순서를 지킨다. 결과를 본 뒤 threshold나 시드를 바꾸지 않는다.
• 모든 실험 결과 문서에는 상태 라벨(PROVISIONAL_DEV_ONLY, DO_NOT_PROMOTE 등)과 "해석 제한" 절을 단다.
• 모델 추론이 필요한 실험은 experiments/guardrail/enter-env.ps1로 격리 환경을 활성화한 뒤 실행한다.
• results/, predictions.jsonl은 공격 원문을 포함하므로 Git에 커밋하지 않는다.

구현 및 검증 원칙

• 공격 생성, 정규화, 평가 로직은 서로 분리한다.
• 원본 입력을 보존하고 적용한 변환 규칙과 중간 결과를 추적할 수 있게 한다.
• 공개 API에는 해당 언어 생태계에 맞는 타입 정보와 간결한 문서화를 제공한다.
• 새 변형 규칙과 정규화 규칙에는 단위 테스트를 추가한다.
• 한글 음절, 호환 자모, 분해 자모, 공백, 문장부호, 한영 혼용 입력의 경계 사례를 검증한다.
• 정규화 전후 탐지 성능뿐 아니라 정상 입력의 오탐 변화도 측정한다.
• 실험에는 시드 데이터, 변형 규칙과 강도, 모델과 버전, 판정 기준을 기록한다.
• 비교 실험은 가능한 한 동일한 데이터와 판정 기준을 사용한다.
• 외부 모델과 데이터셋의 출처, 버전, 라이선스를 명시한다.
• 비밀키, 토큰, 실제 사용자 데이터는 저장소에 커밋하지 않는다.
• 테스트나 실험을 실행하지 못했다면 완료 보고에 이유와 미검증 범위를 명시한다.

문서화 원칙

• 사용자 대상 문서와 주요 설명은 한국어를 우선한다.
• 연구 주장에는 출처 또는 재현 가능한 실험 결과를 연결한다.
• 프로젝트 명칭은 k-safeguard로 통일한다.
• 실제 공격 예시는 연구와 방어 검증에 필요한 최소 범위로 다루고 안전한 사용 목적을 명시한다.
• 사용자 작업과 관계없는 파일은 수정하지 않는다.
• 수치를 인용할 땐 생성기·모델 버전을 함께 확인한다. 실험 문서가 버전을 명시했다면 최신 버전 결과를 우선한다.
• 실험 결과 문서의 상태 라벨과 해석 제한 문구를 지우거나 요약하지 않는다.

안전·환경 경계

• experiments/benchmark/results/와 predictions.jsonl은 공격 원문이 들어 있으므로 열지 않는다.
• 실험 실행(모델 추론)은 GPU와 D:\local llm\guardrails 가중치가 필요하다. 환경이 없으면 실행했다고 보고하지 말고 미검증 범위를 명시한다.

Git 워크플로

2인 팀과 제출 마감이 있는 연구형 프로젝트에 맞춘 경량 GitHub Flow를 유지한다. Git Flow, 강제 브랜치 보호, semantic-release 같은 무거운 프로세스는 도입하지 않는다.

브랜치 — main은 항상 데모 가능한 상태를 유지하며 직접 push는 지양한다.

• 기능: feature/<산출물명> (예: feature/middleware)
• 실험: experiment/<실험명> (예: experiment/seed-expansion)
• 수정·문서: fix/<내용>, docs/<내용>
• 작업 완료 후 PR로 병합하고 브랜치를 삭제한다.

커밋 — type(scope): 한글 설명 형식.

• 표준 타입: feat, fix, docs, chore, refactor, test
• 연구 타입: exp(실험), data(데이터셋), eval(평가 결과)
• 예: feat(middleware): 자모 정규화 로직 추가, eval(benchmark): Kanana Safeguard 회피율 측정

PR·태그·대용량 파일

• 기능·실험 단위로 PR을 열고 상호 리뷰 뒤 병합한다. 오타·사소한 문서 수정은 PR 없이 커밋해도 된다.
• 실험 PR 설명에는 결과 요약을 남긴다 — 보고서·심사 근거로 재사용한다.
• 마일스톤 태그는 <version>-<milestone> 형식 (예: v0.1.0-gate).
• 모델 체크포인트·대용량 데이터셋은 Git에 넣지 않는다. HF Hub나 릴리스 첨부로 분리한다.

명령어

python -m pip install -e ".[dev,mutation]" build          # 개발 설치 (build·mutmut 포함)
python -m unittest discover -s tests                      # 코어 테스트
python -m coverage run -m unittest discover -s tests && python -m coverage report
python -m build && python tools/release/verify_artifacts.py   # 배포 산출물 검증
mutmut run && mutmut results                               # 변이 테스트

실험(모델 추론)은 별도 환경이 필요하다. PowerShell에서:

. .\experiments\guardrail\enter-env.ps1
python -m unittest discover -s experiments\benchmark\tests