dela
0335d572de
20 KiB
기여 가이드 (Contributing)
한국어 · English
ARTEX 한국어판(artex-ko)에 관심을 가져 주셔서 고맙습니다. 이 문서는 기여를 시작하기 전에
알아 두어야 할 범위·방침·절차를 한국어로 정리한 것입니다. 기여를 보내기 전에 반드시
사용 범위와 법적 책임과 현지화 방침을 먼저 읽어 주십시오.
- 버그를 신고하거나 기능을 제안하려면 → 이슈 템플릿을 사용하십시오.
- 번역·현지화 오류를 발견했다면 → "번역·현지화 오류" 이슈 템플릿을 사용하십시오.
- 보안 취약점을 발견했다면 → 공개 이슈로 올리지 말고 SECURITY.md의 절차를 따라 주십시오.
- 모든 참여자는 행동 강령(CODE_OF_CONDUCT.md)을 지켜야 합니다.
사용 범위와 법적 책임
ARTEX 는 LLM 멀티 에이전트가 자율적으로 침투 테스트를 수행하는 공격 보안 도구입니다. 기여자도 사용자와 똑같은 범위 제한을 받습니다.
- 코드를 검증할 때는 자신이 소유했거나 서면으로 명시적 허가를 받은 대상, 또는 로컬 격리 환경(예: Docker 로 띄운 OWASP Juice Shop·DVWA 같은, 의도적으로 취약하며 본인이 소유한 대상)에만 도구를 실행하십시오.
- 허가 범위를 벗어난 실제·운영·원격 시스템에 스캐닝·탐지·익스플로잇을 수행하는 코드, 또는 그런 사용을 조장하는 변경은 받지 않습니다.
- 대한민국에서 권한 없이 타인의 정보통신망에 침입하거나 장애를 일으키는 행위는 「정보통신망 이용촉진 및 정보보호 등에 관한 법률」 위반이며, 수집·노출되는 개인정보는 「개인정보 보호법」의 적용을 받습니다. 자세한 고지는 README에 있습니다.
기여로 제출한 코드·문서가 어떻게 쓰이는지에 대한 법적 책임은 그것을 실행하는 사용자 본인이 부담합니다. 이 저장소는 "있는 그대로(AS IS)" 제공됩니다.
현지화 방침
이 저장소의 존재 이유는 원본 Autumn-27/ARTEX의 판단 성능을 그대로 보존하면서 사용자에게 보이는 산출물만 한국어로 바꾸는 것입니다. 이 방침을 벗어나는 번역 기여는 성능을 떨어뜨릴 수 있으므로 받지 않습니다.
- 에이전트의 내부 추론 프롬프트(행동 지침 본문)는 번역하지 마십시오. 원문(중국어)으로
벤치마크된 동작을 유지해야 합니다. 이 본문은
agent/promptcatalog.go와 DB 시드 (agent_prompts)에 있습니다. 번역은 에이전트의 판단에 드리프트를 일으킵니다. - 사용자에게 노출되는 산출물만 한국어로 강제합니다. 탐지 결과(
report_finding), 사실 요약(record_fact), 최종 리포트, 대화 응답이 여기에 해당합니다. 이 강제는agent/prompt.go의langDirective()라는 코드 고정 꼬리로 각 역할의 system 프롬프트 말미에 붙습니다. 출력 언어를 바꾸려면 이 함수를 수정하십시오. - 명령·페이로드·코드·URL·로그 원문은 번역하지 않습니다. 분석에 필요한 원본이므로 그대로 둡니다.
- 원본 중국어는 보존합니다. 문서는
README.zh.md, UI 문자열은web/messages/zh.json에 원문을 그대로 남겨 상류(upstream) 저장소의 변경과 대조하기 쉽게 합니다. 한국어 번역은web/messages/ko.json에 채웁니다. - UI 문자열을 새로 번역할 때는 하드코딩하지 말고 메시지 파일의 키로 추가하십시오.
- 출력 언어 강제는 하드 캡이 아니라 프롬프트 유도입니다.
langDirective()는 출력 언어를 한국어로 지시할 뿐, 강제로 고정하지는 않습니다. 그래서 한국어 충실도는 모델 역량·역할· 맥락에 따라 달라집니다. 현지화 변경을 검증할 때는 역량 있는 모델(프런티어급)을 쓰십시오. 저가·소형 모델은 리포트·요약이 원문(중국어)으로 되돌아갈 수 있으므로, 번역이 제대로 적용됐는지를 저가 모델의 출력만으로 판단하지 마십시오. OpenAI 계열 모델을 쓸 때의max_tokens설정 함정은 README 의 "모델 선택과 출력 언어" 절에 정리되어 있습니다. - 상류(upstream) 변경을 따라잡는 절차는 메인테이너 안내 문서에 있습니다. 원본 ARTEX 가 갱신됐을 때 보존 자산과 번역 대상을 가려서 반영하고, 번역 대칭과 드리프트를 검사하는 런북은 MAINTAINING.md에 정리되어 있습니다.
개발 환경
이 프로젝트는 Go 백엔드(단일 바이너리에 프런트엔드를 내장) + Next.js 프런트엔드로 구성됩니다.
주요 기능의 설계 의도는 docs/ 의 설계 문서에 정리되어 있습니다. 취약점과 트래픽 증거를
연결하는 기능(보고서 에이전트의 자동 바인딩, report_finding 의 traffic_refs 등)을
다룰 때는 취약점 다중 트래픽 증거 설계 문서를 먼저
읽으십시오. 원문(중국어)은 같은 폴더의 finding-traffic-evidence-zh.md 에 보존되어 있습니다.
요구 버전
- Go 1.26 이상 (
go.mod기준) - Node.js 22 이상 (릴리스 워크플로 기준)
- Docker 와 Docker Compose (로컬 실행·검증용)
백엔드 (Go)
로컬에 Go 가 설치되어 있다면 저장소 루트에서 다음을 실행합니다.
go build ./...
go vet ./agent/
go test ./agent/
로컬에 Go 가 없다면 Docker 로 동일하게 검증할 수 있습니다. 모듈·빌드 캐시를 named volume 에 두면 재실행이 빨라집니다.
docker run --rm -v "$PWD":/src -w /src \
-v artexko-gomod:/go/pkg/mod -v artexko-gocache:/root/.cache/go-build \
golang:1.26 sh -c 'go build ./... && go vet ./agent/ && go test ./agent/'
DB 통합 테스트 (postgres 필요)
위의 go test ./agent/ 는 PostgreSQL 에 붙어야 도는 DB 통합 테스트를 조용히
건너뜁니다. agent·config·db·evidence·llmrec·server 여섯 패키지에는 실제
데이터베이스가 있어야 도는 테스트가 들어 있는데, 환경 변수 ARTEX_PG_DSN 도 없고 설정
파일에도 database 항목이 없으면 그 테스트들은 --- SKIP 으로 넘어가고 패키지는 ok 로
끝납니다. 그래서 이 여섯 패키지를 고친 뒤 DSN 없이 검증하면 로컬은 통과(ok)하는데 PR 의
go-db 작업은 실패할 수 있습니다.
이 테스트들을 로컬에서 돌리려면 PostgreSQL 을 띄우고 ARTEX_PG_DSN 을 건넵니다. 아래는
CI 와 같은 postgres:16-alpine 을 격리 네트워크에 띄워 돌리는 예시이며, 위와 같은 named
volume 을 재사용합니다.
# 1) 격리 네트워크와 빈 postgres 를 띄웁니다 (CI 와 같은 이미지·계정).
docker network create artexko-db 2>/dev/null || true
docker run -d --name artexko-pg --network artexko-db \
-e POSTGRES_USER=artex -e POSTGRES_PASSWORD=artex -e POSTGRES_DB=artex \
postgres:16-alpine
until docker exec artexko-pg pg_isready -U artex -d artex >/dev/null 2>&1; do sleep 1; done
# 2) DSN 을 건네 DB 통합 패키지를 돌립니다 (DSN 의 host 는 컨테이너 이름입니다).
# 고친 패키지만 돌리려면 ./agent/ 자리를 config·db·evidence·llmrec·server 로 바꿉니다.
docker run --rm --network artexko-db -v "$PWD":/src -w /src \
-v artexko-gomod:/go/pkg/mod -v artexko-gocache:/root/.cache/go-build \
-e ARTEX_PG_DSN='postgres://artex:artex@artexko-pg:5432/artex?sslmode=disable' \
golang:1.26 sh -c 'go test ./agent/ -count=1'
# 3) 정리합니다.
docker rm -f artexko-pg && docker network rm artexko-db
CI 의 go-db 작업은 이 여섯 패키지를 각각 자체 postgres 로 격리해 머지 전에 강제로
돌립니다(.github/workflows/ci.yml). DB 통합 패키지를 고쳤다면 PR 을 올리기 전에 위
방법으로 해당 패키지를 직접 확인하기를 권합니다.
프런트엔드 (web)
cd web
npm ci
npm run dev # 개발 서버
npm run build # 프로덕션 빌드
npm run build:static # 정적 내보내기 빌드(머지 게이트 · TypeScript 타입 검사 포함)
npm run check # Biome 린트·포맷 검사(정보용 · 선재 부채로 아직 머지 게이트 아님)
npm run check:fix # 자동 수정
커밋 전 포맷·린트는 Biome 으로 관리합니다. lint-staged 가 스테이징된 파일에 대해
biome check --write 를 자동으로 돌립니다.
전체 실행 (Docker Compose)
cp .env.example .env # POSTGRES_PASSWORD 설정
docker compose up -d # artex + postgres 기동 → http://localhost:8787
기여 절차
- 먼저 이슈를 엽니다. 큰 변경은 작업을 시작하기 전에 이슈로 방향을 맞추는 편이 좋습니다. 작은 수정(오타·링크·명백한 버그)은 바로 PR 을 보내도 됩니다.
- 저장소를 포크하고 주제 브랜치를 만듭니다. 브랜치 이름은
feat/...,fix/...,docs/...,i18n/...처럼 변경 성격을 앞에 둡니다. - 변경을 작성하고 해당 범위의 검증을 직접 돌립니다. Go 변경이면 위의
build·vet·test를 통과시킵니다. web 변경이면npm run build:static(머지 게이트 · TypeScript 타입 검사를 함께 수행합니다)을 통과시킵니다.npm run check(Biome)는 상류에서 딸려온 선재 린트 부채가 남아 있어 아직 머지 게이트가 아니고web.yml에서 정보용 단계로만 돌리므로, 전체를 통과시킬 필요는 없습니다. 대신 내 변경이 새 오류를 더하지 않았는지만 확인하면 됩니다(커밋할 때lint-staged가 스테이징한 파일에만biome check --write를 자동으로 적용합니다). 문서(.md)를 바꿨다면python3 -I scripts/check-doc-links.py로 저장소 안 링크·이미지 참조와 문서 앵커(#헤딩) 링크가 깨지지 않았는지 확인합니다. 앵커는 GitHub 과 같은 규칙으로 헤딩에서 slug 를 만들어 대조하므로, 헤딩 글자를 바꾸면서 그 헤딩을 가리키던 앵커 링크를 함께 고치지 않으면 여기서 걸립니다(CI 의docs워크플로가 같은 검사를 머지 게이트로 강제합니다). 이 검사는 저장소 루트의.pre-commit-config.yaml에docs훅으로도 들어 있어,pre-commit install을 해 두면 커밋할 때 자동으로 돌아갑니다(파이썬 표준 라이브러리만 쓰고 네트워크에 접속하지 않아 Docker 없이 끝납니다). - PR 을 엽니다. 제목·설명은 PR 템플릿을 따르고, 무엇을 왜 바꿨는지와 어떻게 검증했는지를 적습니다. UI 를 바꿨다면 스크린샷을 첨부합니다.
- 사용자에게 보이는 변경(기능·현지화·문서·탐지 규칙 등)이라면 변경 이력(CHANGELOG.md)
의
[Unreleased]절에 한 줄을 더합니다. 내부 리팩터링이나 테스트 전용 변경은 생략해도 됩니다.
커밋 메시지
기존 커밋 이력의 관례를 따릅니다. 형식은 type(scope): 설명 이며, 설명은 한국어로 씁니다.
type:feat·fix·docs·chore·refactor·test·i18n등scope: 바뀐 영역(agent·web·server등), 생략 가능
예시입니다.
feat(agent): 사용자 노출 출력을 한국어로 강제 (langDirective)
docs: 한국어 README 작성, 원본은 README.zh.md 로 보존
i18n(web): 대시보드 네비게이션 라벨 한국어 번역
탐지 규칙·탐지 테스트 기여
이 저장소는 ARTEX 같은 자율 AI 공격을 방어·탐지하기 위한 규칙을 detections/에 함께
둡니다. 배포 가능한 Sigma 규칙(detections/sigma/), 네트워크용
Suricata 규칙(detections/suricata/),
MITRE ATT&CK 커버리지 레이어(detections/attack/), 그리고
이 규칙들이 실제로 발화하는지 재현 가능하게 증명하는 테스트(detections/tests/)로
이루어져 있습니다. 탐지 규칙을 새로 보내거나 고칠 때는 아래 계약을 지켜 주십시오. 여덟 테스트 스위트가 이
계약의 상당 부분을 기계적으로 강제하므로, 규칙만 바꾸고 테스트·레이어를 갱신하지 않으면 테스트가 실패합니다.
- 모든 지표를 관측 가능한 사실에 접지합니다. 규칙이 쓰는 문자열·User-Agent·행동 임계값은 이 저장소
소스에서 실제로 확인되는 것이어야 하고, 추정으로 만들지 않습니다. 근거가 되는 소스 파일을 규칙 안에
밝혀 주십시오(예:
artex-enrich/1.0지표는enrich/enrich.go에서 확인됩니다). 지표 일치 테스트 (detections/tests/indicators/)가 각 지표가 상류 소스와 규칙 양쪽에 여전히 있는지 검사하므로, 상류 재동기화로 소스 문자열이 바뀌면 규칙을 함께 고치지 않는 한 테스트가 실패합니다. 기계 판독 지표 목록(detections/indicators/artex_indicators.csv)을 바꾸면, 그 지표를 그대로 담은 MISP 이벤트(detections/indicators/artex_indicators.misp.json)도 함께 갱신합니다. MISP 내보내기 테스트(detections/tests/misp/)가 두 파일이 행 단위로 일치하는지, 그리고 그 이벤트가 pymisp 로 적재되는 유효한 MISP 문서인지 강제합니다. - 한계를 정직하게 적습니다. Sigma 규칙은
description에, Suricata 규칙은 주석에 그 규칙이 못 잡는 경우와 오탐 가능성을 적습니다. ARTEX 고유 시그니처가 아니라 일반 헌팅 리드(예: 파괴 명령)라면 그렇게 명시해, 한 번의 적중만으로 공격자를 ARTEX 로 단정하지 않게 합니다. - 정적 검증을 통과시킵니다. Sigma 규칙은 SigmaHQ 검증기 기준을 이슈 0 으로 통과해야 합니다
(
sigma check --validation-config detections/tests/sigma_lint/validators.yml). 기본sigma check는 pySigma 핵심 검증기만 돌리므로, 제목 표기·필드/로그소스 분류·참조 링크 같은 SigmaHQ 관례는 이 기준으로만 걸러집니다. 네 가지 예외는 단독 규칙 세트에 맞지 않는 SigmaHQ 모노레포 관례이고, 그 사유를detections/tests/sigma_lint/validators.yml에 적어 두었습니다. Suricata 규칙은suricata -T로 깨끗이 로드되어야 합니다. - 재현 가능한 테스트를 함께 보냅니다. 규칙이 발화하는지(또는 구조가 유효한지)를
detections/tests/아래 테스트로 증명합니다. 입력은 바이너리를 저장소에 넣지 말고 매번 결정론적으로 생성하고, 엔진 버전에 무관한 속성(발화 존재·오탐 없음)은 정확히 단언하며, 버전에 따라 흔들리는 수치는 하한으로 단언하고 기준값을 따로 기록합니다. Sigma 상관 규칙을 더하거나 고치면 백엔드 이식성 테스트(detections/tests/sigma_backends/)가 그 규칙이 여러 백엔드에서 변환되는지 확인하므로,detections/README.md의 백엔드 지원 설명과 어긋나지 않게 유지해 주십시오. - ATT&CK 레이어를 함께 갱신합니다. 규칙에
attack.*태그를 더하거나 바꾸면detections/attack/artex_navigator_layer.json의 기법·점수도 맞춰 갱신합니다. 정합 테스트가 규칙↔레이어 양방향 일치를 강제하므로, 레이어에 없는 규칙 태그나 규칙에 없는 레이어 기법이 있으면 실패합니다. - 공격 안내로 읽히는 내용을 넣지 않습니다. 이 저장소의 탐지 자료는 방어·탐지 포지셔닝만 유지합니다. 익스플로잇 수행 방법이나 탐지 우회 기법처럼 공격을 돕는 서술은 받지 않습니다.
여덟 테스트 스위트는 Docker 만 있으면 그대로 돌릴 수 있고, 생성물을 저장소에 커밋하지 않습니다. 각 스크립트는 단언이 하나라도 실패하면 0 이 아닌 코드로 끝나므로 CI 나 pre-commit 훅에 바로 넣을 수 있습니다.
detections/tests/sigma/run.sh # Sigma: sigma check + 백엔드 변환 + 지표 보존
detections/tests/sigma_match/run.sh # Sigma: 원자 규칙이 악성 샘플에 발화·정상 샘플에 침묵
detections/tests/sigma_lint/run.sh # Sigma: SigmaHQ 관례 전체 검증기 + 문서화된 기준
detections/tests/sigma_backends/run.sh # Sigma 이식성: 상관 규칙이 여러 백엔드에서 변환되는지
detections/tests/suricata/run.sh # Suricata: pcap 합성 → suricata -r → 경보 수 단언
detections/tests/attack/run.sh # ATT&CK: 레이어 ↔ 규칙 양방향 정합
detections/tests/indicators/run.sh # 지표: 규칙의 고정 지표 ↔ 상류 소스 양방향 일치
detections/tests/misp/run.sh # MISP: 지표 CSV ↔ MISP 이벤트 동기화 + pymisp 유효성
여덟을 한 번에 돌리려면 detections/tests/run-all.sh를 쓰십시오. CI 와 같은
순서로 여덟을 순차 실행하고, 앞선 스위트가 실패해도 나머지를 끝까지 돌린 뒤 스위트별 PASS/FAIL 요약을
출력하며, 하나라도 실패하면 0 이 아닌 코드로 끝납니다. 이 러너를 pre-commit 훅으로 바로 거는 설정 예시가
저장소 루트의 .pre-commit-config.yaml에 있습니다. pip install pre-commit && pre-commit install 로 설치하면, 탐지 규칙이나 그 규칙이 고정한 상류 소스가 바뀌는 커밋에서만(CI 와 같은
범위) 러너가 돌아 규칙·테스트 불일치를 푸시 전에 잡습니다. 같은 설정 파일에는 문서 내부 링크·이미지·앵커를
검사하는 docs 훅(위 기여 절차 3번의 check-doc-links.py)도 함께 들어 있습니다.
이 여덟 테스트는 저장소 CI(.github/workflows/detections.yml)가
detections/ 아래가 바뀐 푸시·PR 마다 돌립니다. 지표 일치 테스트는 그 지표가 가리키는 상류 소스 파일
(enrich/·selfupdate/·guard/·db/·cmd/artex/main.go)이 바뀔 때도 돌아, 상류 재동기화가 User-Agent·
마커·기본 포트를 바꿔 규칙이 조용히 낡는 경우를 함께 잡습니다. 따라서 규칙만 바꾸고 테스트·레이어를 갱신하지 않은 변경, SigmaHQ 관례를
깨뜨린 규칙, 또는 소스와 어긋난 규칙은 머지 전에 CI 에서 빨갛게 드러납니다.
규칙 색인과 각 규칙의 근거·한계는 detections/README.md에, 테스트의 단언 항목과
실행법은 detections/tests/README.md에 정리되어 있습니다.
라이선스
이 프로젝트는 GNU Affero General Public License v3.0(AGPL-3.0) 으로 배포됩니다. 기여물을 제출하면, 그 기여물도 AGPL-3.0 으로 공개된다는 데 동의하는 것으로 봅니다. 특히 이 프로젝트를 수정해 네트워크를 통해(예: 온라인 서비스로) 사용자에게 제공한다면, 그 사용자에게 대응하는 완전한 소스 코드를 공개해야 합니다. 전체 조항은 LICENSE 파일에 있습니다.