trustdex 0.5.0 → 0.6.0

package/docs/ARCHITECTURE.md

@@ -1,10 +1,14 @@
 # Architecture
 
+<p align="right">
+  <strong>English</strong> | <a href="./ARCHITECTURE.ko.md">한국어</a>
+</p>
+
 TrustDex is a dependency-free Node.js CLI that separates observation, policy, gating, and review evidence.
 
 ## Data flow
 
-1. An adapter reads an MCP JSON file, a focused Codex TOML subset, a skill, or a plugin manifest.
+1. An adapter reads an MCP JSON file, a focused Codex TOML subset, a Claude/Codex permission settings file, a skill, or a plugin manifest.
 2. Inspection normalizes the source and emits observable signals. Secret values are not retained in reports.
 3. Optional trust-store claims attach explicit provenance evidence.
 4. The policy engine produces ALLOW, ASK, or BLOCK.
@@ -19,6 +23,8 @@ The gate is the enforcement boundary. Reports alone do not prevent an agent from
 | --- | --- |
 | src/inspect.mjs | MCP source classification, redaction, fingerprinting, and signals |
 | src/codex-config.mjs | Focused fail-closed Codex MCP parsing and section filtering |
+| src/codex-settings.mjs | Codex approval, sandbox, network, writable-root, web-search, and subagent settings inspection |
+| src/claude-settings.mjs | Claude Code permission rules and adjacent executable settings inspection |
 | src/extensions.mjs | Skill and plugin manifest inspection |
 | src/provenance.mjs | Explicit local trust-store claims |
 | src/provenance-online.mjs | User-invoked GitHub, npm, and MCP Registry observations plus local artifact-digest verification |
@@ -32,12 +38,17 @@ The gate is the enforcement boundary. Reports alone do not prevent an agent from
 
 - Inspection must not execute the inspected extension.
 - Secret values must not be printed or stored in snapshots.
+- Permission rule values, writable-root paths, hook/helper bodies, and unrelated settings values must not be retained in agent-settings reports.
 - Unknown evidence must not become trust.
 - A blocking signal must not be lowered by provenance.
 - Unsupported security-relevant syntax must fail closed.
 - Network lookup is explicit and observation is not approval.
 - ALLOW is a policy result, not a safety certification.
 
+Settings inspection is currently advisory. It reads one source file at a time and does
+not calculate the merged effective runtime policy. MCP gates remain the implemented
+enforcement boundary; operating-system and runtime sandboxes enforce agent actions.
+
 ## Dependency policy
 
 Runtime code currently uses only Node.js built-ins. A new dependency requires an issue explaining why the feature cannot reasonably be implemented with the platform, the package's maintenance and security posture, and the effect on the supply-chain boundary.

package/docs/CLAUDE.ko.md

@@ -0,0 +1,122 @@
+# Claude에서 TrustDex 사용하기
+
+<p align="right">
+  <a href="./CLAUDE.md">English</a> | <strong>한국어</strong>
+</p>
+
+TrustDex는 Claude Code 또는 Claude Desktop이 MCP JSON을 받기 전에 이를 검사할 수 있습니다. 설정 증거를 로컬에서 평가하고, MCP 서버를 시작하지 않으며, 설정을 업로드하지 않습니다. ALLOW 결정은 증거가 정책과 일치한다는 뜻이며 서버 코드가 안전하다는 것을 증명하지 않습니다.
+
+Claude 전용 명령은 TrustDex 0.5.0 이상에서 사용할 수 있습니다. 게시된 CLI를 실행하려면 아래 예제의 `node ./bin/trustdex.mjs` 대신 `npx trustdex@0.6.0`을 사용하거나, 소스 체크아웃에서 명령을 직접 사용하세요.
+
+## 지원되는 설정
+
+최상위 `mcpServers` 객체가 있는 전용 JSON 파일을 사용하세요.
+
+```json
+{
+  "mcpServers": {
+    "reviewed-tools": {
+      "type": "http",
+      "url": "https://your-reviewed-server.example/mcp"
+    }
+  }
+}
+```
+
+위 URL은 설명용입니다. 직접 검토한 서버와 신뢰 정책을 설정하세요.
+
+지원되는 서버 필드:
+
+| 전송 방식 | 필드 |
+| --- | --- |
+| `stdio`(`type`을 생략한 경우의 기본값이기도 함) | `type`, `command`, `args`, `env` |
+| `http` 또는 `sse` | `type`, `url`, `headers`, `headersHelper` |
+
+원격 항목에는 명시적인 `type`이 필요합니다. 명령 인수와 환경/헤더 값은 문자열이어야 합니다. 알 수 없는 루트/서버 필드, 다른 전송 방식, 잘못된 항목, 해석되지 않은 명령/인수/엔드포인트 변수, 자격 증명·쿼리 매개변수·프래그먼트가 포함된 URL은 안전하게 실패합니다. 이는 명시적인 검사 구현이 마련될 때까지 사용자 지정 `oauth`, `alwaysLoad`, WebSocket 설정 및 향후 제어 기능을 의도적으로 제외합니다. 일반적인 서버 관리형 OAuth에는 `oauth` 필드가 필요 없으며 Claude가 계속 책임집니다.
+
+인증 헤더는 `static-http-headers` 및/또는 `env-http-headers` 신호를 추가합니다. 기본 제공 팩에서는 이에 대한 검토를 요구합니다. `headersHelper`는 `header-helper-command`를 추가하며, Claude가 셸에서 실행하므로 기본 제공 팩에서는 이를 차단합니다. TrustDex는 도우미를 절대 실행하지 않습니다.
+
+지문에는 전송 방식, 헤더 이름, 참조된 환경 변수 이름 및 도우미 존재 여부가 포함됩니다. 헤더/변수 값, 기본값 및 도우미 명령 텍스트는 제외됩니다. 자격 증명 값만 교체해도 검토는 무효화되지 않지만 헤더 이름이나 환경 변수 참조를 변경하면 무효화됩니다. 자격 증명을 명령 인수나 URL 경로에 넣지 마세요. 게이트된 파일은 허용된 원본 항목을 보존하며 입력에 제공된 자격 증명을 포함할 수 있습니다. 로컬에 보관하고 버전 관리에서 제외하세요.
+
+## Claude Code
+
+Claude Code는 `.mcp.json`에서 프로젝트 MCP 설정을 읽습니다. Claude 어댑터로 검사한 뒤 해당 세션에는 생성된 설정만 제공하세요.
+
+소스 체크아웃의 PowerShell에서:
+
+```powershell
+node ./bin/trustdex.mjs inspect-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json
+
+node ./bin/trustdex.mjs gate-claude ./.mcp.json --pack strict --policy ./trustdex.policy.json --out ./.trustdex/claude-mcp.json
+if ($LASTEXITCODE -ne 0) { throw "Resolve the gate error or pending reviews before starting Claude." }
+
+claude --strict-mcp-config --mcp-config ./.trustdex/claude-mcp.json
+```
+
+정책 파일은 공급업체 이름에서 추론한 목록이 아니라 사용자의 명시적인 신뢰 정책입니다. 엄격한 기본값을 사용하려면 `--policy`를 생략하세요. 엄격한 기본값은 알 수 없는 소스를 차단하고 로컬 프로그램에 대해 묻습니다. 기본적으로 게이트에는 ALLOW 항목만 포함됩니다. ASK와 BLOCK 항목은 제외됩니다. 게이트 종료 코드 `1`은 처리되지 않은 ASK 결정, `2`는 실패를 나타냅니다. 게이트가 실패한 뒤 이전 출력 파일로 실행하지 마세요.
+
+`--strict-mcp-config` 플래그가 중요합니다. `--mcp-config`만 사용하면 다른 MCP 소스와 함께 설정이 추가됩니다. 관리형 MCP 설정을 사용하는 조직은 관리 정책의 실제 서버도 확인해야 합니다. 이 워크플로는 Claude의 기본 제공 도구를 게이트하거나 모든 스킬/플러그인을 자동으로 검사하지 않습니다.
+
+생성된 Claude Code 세션 안에서 `/mcp`를 사용해 실제로 로드된 서버를 확인하세요. 설정/단위 테스트가 이 런타임 확인을 대신할 수는 없습니다.
+
+공식 참고 자료: [Claude Code MCP](https://code.claude.com/docs/en/mcp) 및 [CLI 플래그](https://code.claude.com/docs/en/cli-reference).
+
+## Claude Code 권한 설정
+
+MCP 게이트는 노출되는 외부 서버를 제어합니다. Claude Code 자체 권한 규칙은 별도 확인 없이 실행되는 에이전트 작업을 따로 제어합니다. 사용자, 프로젝트, 로컬 또는 관리형 설정 파일을 별도 단계로 검사하세요.
+
+```bash
+node ./bin/trustdex.mjs inspect-claude-settings \
+  ./.claude/settings.json \
+  --pack strict \
+  --json
+```
+
+어댑터는 문서화된 `permissions` 필드인 `allow`, `ask`, `deny`, `defaultMode`, `additionalDirectories`, `disableBypassPermissionsMode`, `disableAutoMode` 및 `blockReadsOutsideWorkingDirectories`를 검증합니다. 알 수 없는 권한 필드, 잘못된 규칙 배열, 빈 규칙, 지원하지 않는 모드, 고정되지 않은 와일드카드 허용 규칙 및 괄호가 있는 MCP 규칙은 안전하게 실패합니다.
+
+자동 권한은 값을 그대로 출력하는 대신 기능 종류에 따라 분류합니다.
+
+| 관찰된 설정 | 엄격한 정책 결과 |
+| --- | --- |
+| 좁은 셸 자동 승인 | `BLOCK` |
+| 광범위한 셸, 파일 시스템, 네트워크 또는 서브에이전트 자동 승인 | `BLOCK` |
+| 파일 시스템, 네트워크, MCP 또는 서브에이전트 자동 승인 | 최소 `ASK` |
+| `bypassPermissions` 기본 모드 | `BLOCK` |
+| `auto` 또는 `acceptEdits` 기본 모드 | 최소 `ASK` |
+| 추가 디렉터리 또는 명시적으로 허용된 작업 디렉터리 외부 읽기 | 최소 `ASK` |
+| 훅 또는 API 키 도우미 | `BLOCK` |
+| 환경, 샌드박스, 플러그인 또는 검사하지 않은 루트 설정 | 최소 `ASK` |
+
+`ask`와 `deny` 규칙은 제한적이므로 그 자체로 위험 신호를 추가하지 않습니다. 보고서에는 규칙 개수와 기능 범주가 포함되지만 명령 패턴, 경로, 도메인, 훅 본문, 도우미 명령, 디렉터리 값, 환경 값 또는 플러그인 식별자는 포함되지 않습니다. 같은 이유로 이 첫 번째 어댑터는 설정 파일용 콘텐츠 지문이나 서명된 검토 기록을 만들지 않습니다.
+
+이 명령은 한 번에 파일 하나만 검사합니다. Claude Code는 여러 범위의 설정을 병합하고 명령줄 플래그가 세션 권한을 추가할 수 있으므로 이 결과가 실제 런타임 정책은 아닙니다. Claude Code에서 로드된 소스와 권한을 확인하고 강제 적용에는 운영체제 수준 샌드박싱을 사용하세요. 공식 참고 자료: [설정 파일 및 우선순위](https://code.claude.com/docs/en/settings), [권한](https://code.claude.com/docs/en/permissions), [보안](https://code.claude.com/docs/en/security).
+
+## 서명된 검토 및 드리프트
+
+검토 워크플로 전체에서 Claude 어댑터를 유지하세요. 일반 MCP 명령은 Claude 전용 제어를 검사하지 않습니다.
+
+```bash
+node ./bin/trustdex.mjs keygen --private .trustdex/private.pem --public .trustdex/public.pem
+node ./bin/trustdex.mjs approve-claude ./.mcp.json --private .trustdex/private.pem --dir .trustdex/claude-review --pack strict --policy ./trustdex.policy.json
+node ./bin/trustdex.mjs recheck-claude ./.mcp.json --review-dir .trustdex/claude-review --public .trustdex/public.pem
+node ./bin/trustdex.mjs snapshot-claude ./.mcp.json --out .trustdex/claude-snapshot.json --pack strict --policy ./trustdex.policy.json
+```
+
+승인은 BLOCK 결정을 거부합니다. ASK 결정에는 명시적인 사람의 검토가 필요합니다. `approve-claude`를 실행하면 해당 검토가 기록되지만 게이트 정책이 자동으로 변경되지는 않습니다. 재검사는 APPROVED, NEEDS_REVIEW 또는 INVALID를 반환합니다. 기존 일반 검토는 지문이 다르므로 Claude 어댑터로 다시 검토해야 합니다. 비공개 키는 절대 커밋하면 안 됩니다.
+
+## Claude Desktop
+
+로컬 stdio MCP 설정에서는 `claude_desktop_config.json`의 `mcpServers` 객체만 전용 입력 파일로 내보내세요. 관련 없는 Desktop 환경설정을 MCP 어댑터에 입력하지 마세요. 해당 파일에 `inspect-claude`와 `gate-claude`를 사용하고 결과를 검토한 뒤, Desktop 설정의 `mcpServers` 섹션만 게이트된 섹션으로 교체하고 Claude Desktop을 다시 시작하세요. 원본 설정의 백업을 보관하세요.
+
+TrustDex는 활성 Desktop 설정을 수정하거나 커넥터를 설치하지 않습니다. Desktop 확장과 계정 수준 원격 커넥터에는 별도 검토가 필요합니다. 이 JSON 게이트가 이를 자동으로 관리하지는 않습니다.
+
+## 비활성 예제
+
+`examples/claude.mcp.json`은 예약된 `.invalid` 도메인, 자리표시자 환경 변수 참조 및 비활성 도우미 문자열을 사용합니다. Claude에서 실행하지 마세요. 정적 검사 전용입니다.
+
+```bash
+node ./bin/trustdex.mjs inspect-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json
+node ./bin/trustdex.mjs gate-claude ./examples/claude.mcp.json --pack strict --policy ./examples/claude.policy.json --out .trustdex/example-claude.json
+```
+
+검사는 의도적으로 `2`로 종료됩니다. 예상 결정은 ALLOW 1개, ASK 1개, BLOCK 2개입니다. 게이트는 `reviewed`만 기록하고 검토가 남아 있으므로 `1`로 종료됩니다.

package/docs/CLAUDE.md

@@ -1,12 +1,16 @@
 # Using TrustDex with Claude
 
+<p align="right">
+  <strong>English</strong> | <a href="./CLAUDE.ko.md">한국어</a>
+</p>
+
 TrustDex can inspect Claude MCP JSON before Claude Code or Claude Desktop receives it.
 It evaluates configuration evidence locally, does not start MCP servers, and does not
 upload your configuration. An ALLOW decision means the evidence matched your policy;
 it does not prove that server code is safe.
 
 The Claude-specific commands are available in TrustDex 0.5.0 and later.
-Use `npx trustdex@0.5.0` in place of `node ./bin/trustdex.mjs` in the examples
+Use `npx trustdex@0.6.0` in place of `node ./bin/trustdex.mjs` in the examples
 below to run the published CLI, or use the commands directly from a source checkout.
 
 ## Supported configuration
@@ -87,6 +91,51 @@ Official references:
 [Claude Code MCP](https://code.claude.com/docs/en/mcp) and
 [CLI flags](https://code.claude.com/docs/en/cli-reference).
 
+## Claude Code permission settings
+
+MCP gating controls which external servers are exposed. Claude Code's own permission
+rules separately control which agent actions run without prompting. Inspect a user,
+project, local, or managed settings file as a separate step:
+
+```bash
+node ./bin/trustdex.mjs inspect-claude-settings \
+  ./.claude/settings.json \
+  --pack strict \
+  --json
+```
+
+The adapter validates the documented `permissions` fields `allow`, `ask`, `deny`,
+`defaultMode`, `additionalDirectories`, `disableBypassPermissionsMode`,
+`disableAutoMode`, and `blockReadsOutsideWorkingDirectories`. Unknown permission
+fields, malformed rule arrays, empty rules, unsupported modes, unanchored wildcard
+allow rules, and parenthesized MCP rules fail closed.
+
+Automatic grants are classified by capability rather than echoing their values:
+
+| Observed setting | Strict result |
+| --- | --- |
+| narrow shell auto-approval | `BLOCK` |
+| broad shell, filesystem, network, or subagent auto-approval | `BLOCK` |
+| filesystem, network, MCP, or subagent auto-approval | at least `ASK` |
+| `bypassPermissions` default mode | `BLOCK` |
+| `auto` or `acceptEdits` default mode | at least `ASK` |
+| additional directories or explicitly unblocked outside reads | at least `ASK` |
+| hooks or an API-key helper | `BLOCK` |
+| environment, sandbox, plugin, or uninspected root settings | at least `ASK` |
+
+`ask` and `deny` rules are restrictive and do not add a risk signal by themselves.
+The report includes rule counts and capability categories, but not command patterns,
+paths, domains, hook bodies, helper commands, directory values, environment values,
+or plugin identifiers. For the same reason, this first adapter does not create a
+content fingerprint or signed review record for settings files.
+
+This command inspects one file at a time. Claude Code merges settings across scopes
+and command-line flags can add session permissions, so the result is not the effective
+runtime policy. Confirm loaded sources and permissions in Claude Code and use OS-level
+sandboxing for enforcement. Official references: [settings files and precedence](https://code.claude.com/docs/en/settings),
+[permissions](https://code.claude.com/docs/en/permissions), and
+[security](https://code.claude.com/docs/en/security).
+
 ## Signed review and drift
 
 Keep the Claude adapter throughout a review workflow; generic MCP commands do not

package/docs/CODEX.ko.md

@@ -0,0 +1,98 @@
+# Codex에서 TrustDex 사용하기
+
+<p align="right">
+  <a href="./CODEX.md">English</a> | <strong>한국어</strong>
+</p>
+
+이 가이드는 Codex 클라이언트가 시작할 수 있는 MCP 서버를 게이트하는 방법과 TrustDex 자체를 Codex로 유지관리하는 방법을 설명합니다.
+
+TrustDex는 독립 프로젝트입니다. OpenAI와 제휴하거나 OpenAI의 보증 또는 인증을 받지 않았으며, ALLOW 결정은 OpenAI 또는 TrustDex의 안전 인증이 아닙니다.
+
+## Codex MCP 서버 게이트
+
+Codex 클라이언트는 `config.toml`(기본적으로 `~/.codex/` 아래)의 `[mcp_servers.<name>]` 테이블에서 MCP 서버 정의를 읽습니다. 각 항목은 로컬 프로세스를 시작하거나 제공된 자격 증명으로 원격 엔드포인트에 연결할 수 있습니다.
+
+### 1. 현재 설정 검사
+
+```bash
+npx trustdex@0.6.0 inspect-codex ~/.codex/config.toml --pack strict
+```
+
+이 명령은 파일을 로컬에서 읽으며 네트워크 요청을 하지 않습니다. 출력에는 각 MCP 서버, 소스 유형, 신뢰 신호 및 ALLOW / ASK / BLOCK 결정이 표시됩니다. 환경 변수 이름은 표시될 수 있지만 값은 절대 표시되지 않습니다.
+
+기계가 읽을 수 있는 출력에는 `--json`을 사용하고, 명시적인 게시자 증거를 연결하려면 `--trust-store ./trust-store.json`을 사용하세요([TRUST_STORE.ko.md](TRUST_STORE.ko.md) 참고).
+
+### 2. 게이트된 사본 작성
+
+```bash
+npx trustdex@0.6.0 gate-codex ~/.codex/config.toml \
+  --pack official-first \
+  --trust-store ./trust-store.json \
+  --out ./gated-config.toml
+```
+
+게이트된 파일은 관련 없는 TOML 섹션(모델, 기능, 프로필)을 그대로 유지하며 ALLOW가 아닌 모든 MCP 섹션을 제거합니다. 다른 승인 계층이 있을 때만 사용해야 하는 `--include-ask`를 전달하지 않는 한 `ASK` 항목도 제외됩니다.
+
+사용하기 전에 차이를 검토하세요.
+
+```bash
+diff ~/.codex/config.toml ./gated-config.toml
+```
+
+TrustDex는 `config.toml`을 직접 수정하지 않습니다. 원본 파일을 교체하거나 Codex 설치가 게이트된 사본을 가리키도록 하는 작업은 검토 후 사용자가 명시적으로 수행합니다.
+
+### 3. 변경할 때마다 다시 실행
+
+패키지 버전이 올라가거나, 런처가 바뀌거나, 새 환경 변수가 전달되면 MCP 항목이 변경됩니다. `config.toml`이 변경될 때마다 `inspect-codex`와 `gate-codex`를 다시 실행하세요. dotfiles 저장소의 CI 작업 또는 pre-commit 훅이 적합합니다.
+
+[README](../README.ko.md#기능-및-출처-드리프트)의 서명된 `snapshot`, `approve`, `recheck` 드리프트 워크플로는 현재 MCP JSON만 받습니다. Codex `config.toml`로 확장하는 작업은 [로드맵](ROADMAP.ko.md)에 기록되어 있습니다.
+
+### 안전하게 실패하는 파싱
+
+TrustDex는 Codex MCP 섹션에 사용되는 TOML 구성만 파싱합니다. 지원하지 않는 MCP 키, 중첩 하위 섹션 또는 구문은 건너뛰지 않고 오류로 보고되므로 TrustDex가 완전히 읽을 수 없는 설정이 조용히 ALLOW가 되지 않습니다.
+
+## Codex 실행 권한 검사
+
+MCP 게이트는 외부 도구를 제어하고 Codex 승인·샌드박스 설정은 에이전트가 로컬에서 할 수 있는 일을 제어합니다. 이 설정을 별도로 검사하세요.
+
+```bash
+node ./bin/trustdex.mjs inspect-codex-settings \
+  ./examples/codex.permissions.toml \
+  --pack strict \
+  --json
+```
+
+어댑터는 `approval_policy`, `approvals_reviewer`, `sandbox_mode`, `default_permissions`, `web_search` 및 문서화된 `sandbox_workspace_write` 키를 검증합니다. 다음을 보고합니다.
+
+- `danger-full-access`는 `BLOCK`
+- `workspace-write`, 외부 네트워크 접근, 추가 쓰기 가능 루트, 실시간 웹 검색, 자동 검토 및 `approval_policy = "never"`는 최소 `ASK`
+- 명시적인 멀티 에이전트 활성화, 사용자 정의 권한 프로필, 앱/플러그인 섹션 및 완전히 검사하지 않는 설정은 `ASK`
+
+보안 관련 값의 타입이나 열거 값이 지원되지 않으면 안전하게 실패합니다. 공식 설정 레퍼런스가 함께 사용하지 말라고 명시하므로 `default_permissions`와 기존 샌드박스 설정을 같이 사용해도 실패합니다. 쓰기 가능 루트 경로와 관련 없는 설정의 값은 보관·출력·지문화하지 않습니다.
+
+이 첫 번째 어댑터는 한 번에 파일 하나를 검사하며 사용자, 프로젝트, 프로필, 관리형, 시스템 또는 명령줄 설정을 하나의 실제 정책으로 병합하지 않습니다. 이는 정적 증거이며 Codex 샌드박스 자체가 아닙니다. 클라이언트에서 활성 권한 프로필을 확인하세요. 공식 OpenAI 문서는 샌드박스 경계와 승인 처리를 구분하며 `workspace-write`와 `on-request` 조합을 더 낮은 위험의 로컬 자동화 구성으로 안내합니다. [설정 레퍼런스](https://developers.openai.com/codex/config-reference)와 [샌드박스 가이드](https://developers.openai.com/codex/sandboxing)를 참고하세요.
+
+### 스킬 및 플러그인
+
+에이전트 스킬과 플러그인 매니페스트도 같은 방법으로 검사할 수 있습니다.
+
+```bash
+npx trustdex@0.6.0 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.6.0 inspect-plugin ./path/to/plugin.json --pack strict
+```
+
+이 명령은 파이프로 연결된 셸 설치 프로그램, 민감한 경로 참조, 네트워크 URL 및 와일드카드 도구 범위와 같은 관찰 가능한 신호를 보고합니다. 스킬이나 플러그인이 안전하다는 것을 증명하지는 않습니다.
+
+## CI에서 MCP 설정 게이트
+
+에이전트용 MCP 설정을 제공하는 저장소는 모든 풀 리퀘스트에서 [TrustDex GitHub Action](../README.ko.md#github-action)으로 게이트할 수 있습니다. Action을 검토된 커밋 SHA에 고정하세요.
+
+## Codex를 사용한 TrustDex 유지관리
+
+TrustDex는 사용자에게 적용하도록 요청하는 것과 동일한 신뢰 경계를 사용해 Codex를 검토자 및 유지관리 도우미로 사용합니다.
+
+- [AGENTS.ko.md](../AGENTS.ko.md)에는 개발 규칙과 Codex 코드 검토가 TrustDex 풀 리퀘스트에 적용하는 **검토 지침** 섹션이 있습니다. 지침은 프로젝트의 보안 불변 조건(조용한 ALLOW 금지, 출력에 비밀 값 금지, 출처가 차단 신호를 무시하지 못함, 안전하게 실패하는 파싱, Action 고정)을 명시적인 검토 발견 사항으로 전환합니다.
+- Codex 제안은 다른 기여와 동일하게 취급됩니다. 풀 리퀘스트를 거치고, 크로스 플랫폼 CI 매트릭스와 CodeQL을 통과해야 하며, 유지관리자 검토 후에만 병합됩니다.
+- Codex는 릴리스 자격 증명을 보유하지 않습니다. npm 게시는 유지관리자가 트리거하는 `.github/workflows/publish.yml`에서 Sigstore 출처가 포함된 Trusted Publisher OIDC를 사용합니다.
+
+Codex 또는 다른 코딩 에이전트로 기여하는 경우 변경 사항에도 동일한 AGENTS.md 규칙이 적용됩니다.

package/docs/CODEX.md

@@ -1,5 +1,9 @@
 # Using TrustDex with Codex
 
+<p align="right">
+  <strong>English</strong> | <a href="./CODEX.ko.md">한국어</a>
+</p>
+
 This guide covers two things: gating the MCP servers a Codex client may start, and how TrustDex itself is maintained with Codex.
 
 TrustDex is an independent project. It is not affiliated with, endorsed by, or certified by OpenAI, and an ALLOW decision is not an OpenAI or TrustDex safety certification.
@@ -11,7 +15,7 @@ Codex clients read MCP server definitions from `[mcp_servers.<name>]` tables in
 ### 1. Inspect the current configuration
 
 ```bash
-npx trustdex@0.4.4 inspect-codex ~/.codex/config.toml --pack strict
+npx trustdex@0.6.0 inspect-codex ~/.codex/config.toml --pack strict
 ```
 
 This reads the file locally and makes no network request. The output lists each MCP server, its source type, trust signals, and an ALLOW / ASK / BLOCK decision. Environment variable names may appear; their values never do.
@@ -21,7 +25,7 @@ Use `--json` for machine-readable output and `--trust-store ./trust-store.json`
 ### 2. Write a gated copy
 
 ```bash
-npx trustdex@0.4.4 gate-codex ~/.codex/config.toml \
+npx trustdex@0.6.0 gate-codex ~/.codex/config.toml \
   --pack official-first \
   --trust-store ./trust-store.json \
   --out ./gated-config.toml
@@ -47,13 +51,46 @@ The signed `snapshot`, `approve`, and `recheck` drift workflow in the [README](.
 
 TrustDex parses only the TOML constructs used by Codex MCP sections. An unsupported MCP key, nested subsection, or syntax is reported as an error instead of being skipped, so a configuration TrustDex cannot fully read never silently becomes ALLOW.
 
+## Inspect Codex execution permissions
+
+MCP gating controls external tools, while Codex approval and sandbox settings control
+what the agent can do locally. Inspect those settings separately:
+
+```bash
+node ./bin/trustdex.mjs inspect-codex-settings \
+  ./examples/codex.permissions.toml \
+  --pack strict \
+  --json
+```
+
+The adapter validates `approval_policy`, `approvals_reviewer`, `sandbox_mode`,
+`default_permissions`, `web_search`, and the documented
+`sandbox_workspace_write` keys. It reports:
+
+- `danger-full-access` as `BLOCK`
+- `workspace-write`, outbound network access, additional writable roots, live web search, automatic review, and `approval_policy = "never"` as at least `ASK`
+- explicit multi-agent enablement, custom permission profiles, app/plugin sections, and settings it does not fully inspect as `ASK`
+
+Security-relevant values fail closed when their type or enum value is unsupported.
+`default_permissions` also fails when combined with the legacy sandbox settings, as
+the official configuration reference says not to combine them. Writable-root paths
+and values from unrelated settings are not retained, printed, or fingerprinted.
+
+This first adapter inspects one file at a time; it does not merge user, project,
+profile, managed, system, or command-line configuration into an effective policy.
+It is static evidence, not the Codex sandbox itself. Confirm the active permission
+profile in the client. The official OpenAI documentation distinguishes the sandbox
+boundary from approval handling and documents `workspace-write` plus `on-request`
+as the lower-risk local automation combination. See the [configuration reference](https://developers.openai.com/codex/config-reference)
+and [sandbox guide](https://developers.openai.com/codex/sandboxing).
+
 ### Skills and plugins
 
 Agent skills and plugin manifests can be inspected the same way:
 
 ```bash
-npx trustdex@0.4.4 inspect-skill ./path/to/SKILL.md --pack strict
-npx trustdex@0.4.4 inspect-plugin ./path/to/plugin.json --pack strict
+npx trustdex@0.6.0 inspect-skill ./path/to/SKILL.md --pack strict
+npx trustdex@0.6.0 inspect-plugin ./path/to/plugin.json --pack strict
 ```
 
 These report observable signals such as piped shell installers, references to sensitive paths, network URLs, and wildcard tool scopes. They do not prove a skill or plugin is safe.

package/docs/DEFENSIVE_USE_CASE.ko.md

@@ -0,0 +1,85 @@
+# 방어적 AI 에이전트 보안 사용 사례
+
+<p align="right">
+  <a href="./DEFENSIVE_USE_CASE.md">English</a> | <strong>한국어</strong>
+</p>
+
+이 문서는 TrustDex의 합법적인 방어 목적과 운영 경계를 쉽게 검증할 수 있도록 정리한 증거 색인입니다. Anthropic의 보증, CVP 승인 또는 특정 운영자가 계정 수준 보안 요구사항을 충족한다는 진술이 아닙니다.
+
+## 해결하려는 문제
+
+코딩 에이전트의 자율성이 커질수록 실제 공격 표면은 모델에만 머물지 않습니다. 에이전트가 불러올 수 있는 도구, 별도 확인 없이 받는 권한, 도구가 참조하는 자격 증명, 시간이 지나면서 접근 범위를 조용히 넓힐 수 있는 설정 변경도 공격 표면에 포함됩니다.
+
+TrustDex는 이 표면에 대한 노출 전 통제를 연구하고 구현합니다. 현재 프로젝트는 두 가지 구체적인 질문을 다룹니다.
+
+1. 명시적인 로컬 정책에 따라 에이전트가 특정 MCP 서버, 스킬 또는 플러그인을 보고 호출하도록 허용해야 하는가?
+2. Claude Code 또는 Codex 설정이 자동 셸, 파일 시스템, 네트워크, MCP, 서브에이전트 또는 샌드박스 기능을 부여하여 검토나 차단이 필요한가?
+
+## 의도한 방어 작업
+
+이 프로젝트는 TrustDex 자체와 운영자가 소유하거나 명시적으로 테스트 허가를 받은 시스템에 대한 작업에 AI 지원을 사용합니다. 일반적인 작업은 다음과 같습니다.
+
+- 파서와 정책 코드에서 fail-open 동작 검토
+- 비활성 적대적 설정 픽스처 개발
+- 보고서, 스냅샷 및 지문에 비밀 값이 남지 않는지 확인
+- 권한 확장, 출처 대체 및 검토 드리프트 위협 모델링
+- 방어적 발견 사항과 완화책에 대한 회귀 테스트 작성
+- 민감 정보를 완전히 제거한 파일럿 피드백의 거짓 양성·거짓 음성 분석
+
+이 작업은 방어적 엔지니어링입니다. 자격 증명 탈취, 지속성 확보, 파괴 행위, 데이터 유출, 악성 코드 배포, 대량 악용 또는 무단 접근을 필요로 하지 않습니다.
+
+## 허가 및 데이터 경계
+
+- 테스트는 운영자 소유의 저장소와 계정, 명시적으로 허가된 시스템 및 격리된 로컬 테스트 환경으로 제한합니다.
+- 체크인된 적대적 입력은 비활성 데이터입니다. 예약된 `.invalid` 도메인, 존재하지 않는 패키지 식별자 및 자리표시자 값을 사용합니다.
+- 일반 검사는 로컬에서만 수행하며 검사 대상 MCP 서버, Claude 권한 규칙, 스킬, 플러그인 또는 훅을 실행하지 않습니다.
+- 명시적인 출처 명령은 공개 GitHub, npm 또는 MCP Registry 메타데이터를 조회할 수 있습니다. 별도의 사용자 작업 없이는 관찰 결과가 신뢰로 변환되지 않습니다.
+- 실제 자격 증명, 비공개 엔드포인트, 고객 데이터, 독점 프롬프트 및 공격용 자료는 공개 픽스처나 보고서에 포함하지 않습니다.
+
+## 이 저장소가 보여 주는 통제 증거
+
+| 통제 목표 | 공개 증거 |
+| --- | --- |
+| 검토되지 않은 도구를 에이전트에서 분리 | ALLOW/ASK/BLOCK 정책 엔진과 필터링된 MCP 게이트 |
+| 기능 범위 확장 감지 | MCP, Claude Code 및 Codex 설정 신호와 적대적 회귀 테스트 |
+| 조용한 파서 우회 방지 | 지원하지 않는 보안 관련 구문을 거부하는 전용 어댑터 |
+| 증거에서 비밀 값 제외 | 출력, 스냅샷 및 설정 지문에서 비밀 값을 제거하는 테스트 |
+| 승인 상태의 드리프트 표시 | 결정론적 스냅샷, Ed25519 검토 기록 및 재검사 명령 |
+| 공급망 모호성 감소 | 명시적 출처 관찰, 아티팩트 다이제스트 검증, 릴리스 체크섬, SBOM 및 빌드 증명 |
+| 연구 재현성 유지 | 비활성 픽스처, 문서화된 기대 결과, 크로스 플랫폼 CI 및 CodeQL |
+
+ALLOW 결과는 여전히 관찰된 증거에 대한 정책 결과일 뿐입니다. TrustDex는 샌드박스, 악성 코드 스캐너 또는 서드파티 코드가 안전하다는 증명이 아닙니다.
+
+## Claude Code 및 Codex 권한 연구
+
+`inspect-claude-settings`는 문서화된 `permissions` 객체를 검사하고 셸, 파일 시스템, 네트워크, MCP 및 서브에이전트 기능의 자동 승인을 보고합니다. 또한 훅, 자격 증명 도우미, 환경 설정, 샌드박스 설정 및 플러그인 로딩의 존재를 값은 보관하지 않은 채 드러냅니다.
+
+이는 정적 증거이지 런타임 강제 적용이 아닙니다. 모든 Claude 설정 범위를 병합하거나, 명령줄 플래그를 검사하거나, 관리형 설정이 세션에 실제 적용되었음을 증명하거나, Claude Code 샌드박싱을 대체하지 않습니다. 운영자는 실제 런타임 설정을 별도로 확인해야 합니다.
+
+`inspect-codex-settings`는 Codex 승인 정책, 검토자 선택, 샌드박스 종류, 네트워크 접근, 추가 쓰기 가능 루트 개수, 웹 검색 모드 및 명시적인 서브에이전트 활성화를 평가합니다. 완전히 파싱하지 않는 사용자 정의 권한, 앱 및 플러그인 표면은 값은 보관하지 않고 보고합니다. 마찬가지로 모든 Codex 설정 계층을 병합하거나 활성 Codex 샌드박스를 대체하지 않습니다.
+
+## CVP 신청 경계
+
+Anthropic의 현재 Cyber Verification Program 신청은 검증 가능한 개인 또는 조직 정보, 보안 작업 설명 및 요청 티어에 해당하는 통제 준수 확인을 요구합니다. 이 저장소는 보안 작업 설명을 뒷받침할 수 있지만, 저장소 변경만으로 운영자 신원을 증명하거나 계정·기기 통제를 충족할 수는 없습니다.
+
+개인 신청자는 신청 전에 최신 요구사항을 공식 문서에서 직접 확인해야 합니다. 2026년 10월 기준 Anthropic은 개인에게 Defense Access만 제공하며, 공유 세션이 아닌 개인 접근, MFA 활성화, 공개된 기한까지 피싱 방지 MFA 전환 및 장기 자격 증명 중단을 요구한다고 안내합니다. Claude Code의 OAuth 로그인이 퍼스트파티 사용 경로입니다. 공식 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-cyber-verification-program)과 [CVP 보안 요구사항](https://support.claude.com/en/articles/17202708-cyber-verification-program-security-requirements)을 확인하세요.
+
+실제로 구현되어 있고 증거를 제시할 수 있는 통제만 신청서에 기재하세요. 내부 작업용 CVP 접근 권한은 고객 대상 보안 서비스나 제품을 자동으로 허가하지 않습니다.
+
+## 재현 가능한 증거
+
+```bash
+npm test
+npm run check
+npm run test:research
+
+node ./bin/trustdex.mjs inspect-claude-settings \
+  ./examples/claude.settings.json \
+  --pack strict
+
+node ./bin/trustdex.mjs inspect-codex-settings \
+  ./examples/codex.permissions.toml \
+  --pack strict
+```
+
+Claude 명령은 예제에 셸 자동 승인 규칙이 포함되어 있어 의도적으로 종료 코드 `2`를 반환합니다. Codex 명령은 제한된 작업 공간 쓰기 기능에도 검토가 필요하므로 종료 코드 `1`을 반환합니다. 예상 결과와 한계는 [방어적 평가](EVALUATION.ko.md), [보안 연구](SECURITY_RESEARCH.ko.md) 및 [위협 모델](THREAT_MODEL.ko.md)을 참고하세요.

package/docs/DEFENSIVE_USE_CASE.md

@@ -0,0 +1,89 @@
+# Defensive AI-agent security use case
+
+<p align="right">
+  <strong>English</strong> | <a href="./DEFENSIVE_USE_CASE.ko.md">한국어</a>
+</p>
+
+This document makes the legitimate defensive purpose and operating boundary of TrustDex easy to verify. It is an evidence index, not an Anthropic endorsement, a CVP approval, or an attestation that any particular operator satisfies account-level security requirements.
+
+## Problem being addressed
+
+As coding agents become more autonomous, their effective attack surface includes more than the model. It also includes the tools they can load, the permissions they receive without a prompt, the credentials those tools can reference, and the configuration changes that may silently widen access over time.
+
+TrustDex researches and implements pre-exposure controls for that surface. The current project asks two concrete questions:
+
+1. Should an agent be allowed to see and invoke a particular MCP server, skill, or plugin under an explicit local policy?
+2. Do Claude Code or Codex settings grant automatic shell, filesystem, network, MCP, subagent, or sandbox capabilities that need review or blocking?
+
+## Intended defensive work
+
+The project uses AI assistance for work on TrustDex itself and other systems the operator owns or is explicitly authorized to test. Typical tasks include:
+
+- reviewing parsers and policy code for fail-open behavior
+- developing inert adversarial configuration fixtures
+- checking that reports, snapshots, and fingerprints do not retain secret values
+- threat modeling permission expansion, provenance substitution, and review drift
+- writing regression tests for defensive findings and proposed mitigations
+- analyzing false positives and false negatives from fully redacted pilot feedback
+
+This work is defensive engineering. It does not require credential theft, persistence, destructive actions, data exfiltration, malware deployment, mass exploitation, or unauthorized access.
+
+## Authorization and data boundary
+
+- Testing is limited to the operator's own repositories and accounts, explicitly authorized systems, and isolated local test environments.
+- Checked-in adversarial inputs are inert data. They use reserved `.invalid` domains, nonexistent package identities, and placeholder values.
+- Normal inspection is local-only and does not execute inspected MCP servers, Claude permission rules, skills, plugins, or hooks.
+- Explicit provenance commands may query public GitHub, npm, or MCP Registry metadata. Observation is never converted into trust without a separate user action.
+- Real credentials, private endpoints, customer data, proprietary prompts, and exploit material do not belong in public fixtures or reports.
+
+## Controls evidenced by this repository
+
+| Control objective | Public evidence |
+| --- | --- |
+| Keep unreviewed tools away from the agent | ALLOW/ASK/BLOCK policy engine and filtered MCP gates |
+| Detect capability expansion | MCP, Claude Code, and Codex settings signals plus adversarial regression tests |
+| Avoid silent parser bypass | focused adapters reject unsupported security-relevant syntax |
+| Keep secrets out of evidence | tests for redaction from output, snapshots, and configuration fingerprints |
+| Make approval drift visible | deterministic snapshots, Ed25519 review records, and recheck commands |
+| Reduce supply-chain ambiguity | explicit provenance observations, artifact digest verification, release checksums, SBOMs, and build attestations |
+| Keep research reproducible | inert fixtures, documented expectations, cross-platform CI, and CodeQL |
+
+An ALLOW result is still only a policy result over observed evidence. TrustDex is not a sandbox, malware scanner, or proof that third-party code is safe.
+
+## Claude Code and Codex permission research
+
+`inspect-claude-settings` examines the documented `permissions` object and reports automatic approval of shell, filesystem, network, MCP, and subagent capabilities. It also surfaces the presence of hooks, credential helpers, environment settings, sandbox configuration, and plugin loading without retaining their values.
+
+This is static evidence, not runtime enforcement. It does not merge every Claude settings scope, inspect command-line flags, prove that managed settings reached a session, or replace Claude Code sandboxing. The operator must confirm the effective runtime configuration separately.
+
+`inspect-codex-settings` evaluates Codex approval policy, reviewer choice, sandbox
+class, network access, additional writable-root count, web-search mode, and explicit
+subagent enablement. It reports custom permission, app, and plugin surfaces that it
+does not fully parse without retaining their values. It likewise does not merge every
+Codex configuration layer or replace the active Codex sandbox.
+
+## CVP application boundary
+
+Anthropic's current Cyber Verification Program application asks for verifiable identity or organization details, a description of security work, and an attestation to the controls for the requested tier. This repository can support the security-work description, but repository changes cannot establish the operator's identity or satisfy account and device controls by themselves.
+
+An individual applicant should verify current requirements directly before applying. As of October 2026, Anthropic states that individuals are eligible for Defense Access only, must use personal access rather than shared sessions, must enable MFA, and must transition to phishing-resistant MFA and away from long-lived credentials by the published cutoff. Claude Code's OAuth sign-in is the intended first-party path. See the official [Cyber Verification Program](https://support.claude.com/en/articles/14604842-cyber-verification-program) and [CVP security requirements](https://support.claude.com/en/articles/17202708-cyber-verification-program-security-requirements).
+
+Do not claim a control in an application unless it is actually implemented and can be evidenced. CVP access for internal work does not automatically authorize a customer-facing security service or product.
+
+## Reproducible evidence
+
+```bash
+npm test
+npm run check
+npm run test:research
+
+node ./bin/trustdex.mjs inspect-claude-settings \
+  ./examples/claude.settings.json \
+  --pack strict
+
+node ./bin/trustdex.mjs inspect-codex-settings \
+  ./examples/codex.permissions.toml \
+  --pack strict
+```
+
+The Claude command intentionally exits with code `2` because its example contains a shell auto-approval rule. The Codex command exits with code `1` because bounded workspace-write capabilities still require review. See [Defensive evaluation](EVALUATION.md), [Security research](SECURITY_RESEARCH.md), and the [Threat model](THREAT_MODEL.md) for the expected results and limitations.