Agent Sandboxの外向き通信をどこまで許すか

jq -c '{keys:keys, allow:(.permissions.allow|length), deny:(.permissions.deny|length), ask:(.permissions.ask|length)}' \
  .claude/settings.json
# => {"keys":["hooks","permissions"],"allow":71,"deny":19,"ask":1}

flowchart LR
  subgraph SB["sandbox（shell コマンド）"]
    A["エージェントのプロセス"]
  end
  subgraph OUT["sandbox の外で動くもの（書式の outside_sandbox）"]
    M["MCP サーバ / hooks / file tools / WebFetch"]
  end
  A -- "直接の外向き経路なし" --x NET(("インターネット"))
  A --> P["プロキシ宛先 allowlist 照合ローカルアドレスにしか解決しない名前は拒否"]
  P --> D["DNS リゾルバ（どこで解決するかを書式に書く）"]
  P --> C["credential 注入（許可した宛先にだけ）"]
  C --> H["許可済みホストapi.github.com など"]
  P -. "拒否・許可・名前解決" .-> L["監査ログ想定外の宛先で停止"]
  E["例外の記録欄理由・期限・承認の記録"] --> P
  M --> NET

# sandbox-contract.yaml（この記事が置いた書式。製品の設定ファイルではない）
contract: repo-agent-egress
version: 1
scope:
  agent: repo-agents
  runtime: [developer-machine, github-actions]
  phase: [setup, agent]
default: deny
destinations:
  - host: api.github.com
    purpose: PR と issue の読み書き（gh / MCP）
    methods: []                # 空欄＝現状。宛先の層ではメソッドを宣言していない（gh api の読み取り限定は permissions 側。#649）
    phase: agent
    credential: GH_TOKEN
    recorded_by: ""
  - host: registry.npmjs.org
    purpose: 依存の取得（CI の pnpm install --frozen-lockfile）
    methods: []
    phase: setup
    credential: ""
    recorded_by: ""
dns:
  resolver: ""                 # 空欄＝現状
  resolve_inside_sandbox: null
  allow_cluster_dns: null
credentials:
  - name: EXAMPLE_API_KEY      # 架空の名前
    inject_to_hosts: []
    steps: []
    visible_inside_sandbox: null
    scope: ""
audit:
  log: [allowed, denied, dns_query, credential_injection]
  store: ""
  halt_on: []
  review_record: ""
# exceptions は記録欄の例。誰が申請・承認するかは規定しない
exceptions:
  - host: ""
    reason: ""
    expires: ""
    request_record: ""
    approval_record: ""
    recorded_in: ""
    after_expiry: ""           # 期限が切れたあと何が起きたかを残す欄
outside_sandbox: [mcp_servers, hooks, file_tools, web_fetch]

#!/usr/bin/env bash
# egress-declaration-audit.sh <repo>
#
# 宣言に指定した文字列・キーがあるかを数える。通信は観測しないし、
# 制御が効いているかも判定しない。対象リポジトリには書き込まない。
# ネットワークは使わない（結果を実行者のネットワークや認証の状態に左右させないため）。
#
# 結果: なし / 指摘 / 情報 / 未検査（理由: 対象なし・読めない・型が想定外・jq が無い）
# 終了コード: 未検査が 1 つでもあれば 2、無ければ指摘が 1 つでもあれば 1、どちらも無ければ 0
# 必要なもの: bash 3.2 以上、grep、jq（無ければ検査 2〜4 が未検査）
set -u
export LC_ALL=C

REPO="${1:-.}"
SETTINGS="$REPO/.claude/settings.json"
WF_DIR="$REPO/.github/workflows"
CMD_DENY_RE='^Bash\((curl|wget|nc|ncat|ssh|scp)([ :)]|$)'
BARE_ALLOW_RE='^Bash\((gh|gh api|curl|wget)(:\*| \*)\)$'
SECRET_RE='secrets\.[A-Za-z_][A-Za-z0-9_]*|github\.token'
EGRESS_RE='harden-runner|allowed-endpoints|(^|[^A-Za-z0-9_-])egress([^A-Za-z0-9_]|$)'
none=0; found=0; info=0; unchecked=0

result() { # result <なし|指摘|情報|未検査> <検査番号> <要約>
  printf '[%s] %s %s\n' "$1" "$2" "$3"
  case "$1" in なし) none=$((none + 1)) ;; 指摘) found=$((found + 1)) ;;
    情報) info=$((info + 1)) ;; *) unchecked=$((unchecked + 1)) ;; esac
}
jq_q() { jq -r "$1" "$SETTINGS" 2>/dev/null; }
count_matching() { printf '%s\n' "$1" | grep -cE "$2"; }
list() { jq_q "($1 // [])[]"; }

settings_state() {
  command -v jq >/dev/null 2>&1 || { echo "jq が無い"; return; }
  [ -f "$SETTINGS" ] || { echo "対象なし"; return; }
  [ -s "$SETTINGS" ] || { echo "読めない: 空のファイル"; return; }
  jq -e 'type' "$SETTINGS" >/dev/null 2>&1 || { echo "読めない"; return; }
  [ "$(jq_q 'type')" = object ] || { echo "型が想定外"; return; }
  echo ok
}
object_or_null() { case "$(jq_q "$1 | type")" in object | null) echo ok ;; *) echo "型が想定外" ;; esac; }
# null か「文字列だけの配列」なら真。親が想定外の型なら jq が失敗して偽になる
string_array_or_null() {
  [ "$(jq_q "($1) as \$a | if \$a == null then \"ok\" elif (\$a | type) == \"array\"
    and all(\$a[]; type == \"string\") then \"ok\" else \"bad\" end")" = ok ]
}

echo "読んだ設定: $SETTINGS のみ。user / local / managed の設定と --settings は読んでいない"
state="$(settings_state)"; sandbox="$state"; perms="$state"
[ "$state" = ok ] && sandbox="$(object_or_null .sandbox)" && perms="$(object_or_null .permissions)"

# 検査 2: トップレベルに sandbox があるか
if [ "$sandbox" != ok ]; then result 未検査 2 "sandbox: $sandbox"
elif [ "$(jq_q '.sandbox != null')" = true ]; then result なし 2 "sandbox: キーがある"
else result 指摘 2 "sandbox: キーが無い"; fi

# 検査 3: 許可する宛先の宣言（allowedDomains と allow / ask の WebFetch(domain:...)）
# 判定は許可側だけで行う。拒否側（deniedDomains と deny の WebFetch）は件数を併記するだけ
if [ "$sandbox" != ok ] || [ "$perms" != ok ]; then
  [ "$sandbox" != ok ] && why="$sandbox" || why="$perms"
  result 未検査 3 "許可する宛先の宣言: $why"
elif ! string_array_or_null .permissions.allow || ! string_array_or_null .permissions.deny ||
  ! string_array_or_null .permissions.ask || ! string_array_or_null .sandbox.network.allowedDomains ||
  ! string_array_or_null .sandbox.network.deniedDomains; then
  result 未検査 3 "許可する宛先の宣言: 型が想定外"
else
  allow_dest=$(($(count_matching "$(list .permissions.allow; list .permissions.ask)" '^WebFetch\(domain:') +
    $(count_matching "$(list .sandbox.network.allowedDomains)" '.')))
  deny_dest=$(($(count_matching "$(list .permissions.deny)" '^WebFetch\(domain:') +
    $(count_matching "$(list .sandbox.network.deniedDomains)" '.')))
  cmd_deny="$(count_matching "$(list .permissions.deny)" "$CMD_DENY_RE")"
  detail="（拒否側の宛先 $deny_dest 件、コマンド名で始まる deny $cmd_deny 件）"
  if [ "$allow_dest" -eq 0 ]; then result 指摘 3 "許可する宛先の宣言: 0 件$detail"
  else result なし 3 "許可する宛先の宣言: $allow_dest 件$detail"; fi
fi

# 検査 4: コマンド名だけで終わる前方一致の allow（引数で絞ったものは数えるだけ）
if [ "$perms" != ok ]; then result 未検査 4 "前方一致の allow: $perms"
elif ! string_array_or_null .permissions.allow; then result 未検査 4 "前方一致の allow: 型が想定外"
else
  allow="$(list .permissions.allow)"
  bare="$(printf '%s\n' "$allow" | grep -E "$BARE_ALLOW_RE")"
  narrowed=$(($(count_matching "$allow" '^Bash\((gh api|curl|wget) ') -
    $(count_matching "$bare" '^Bash\((gh api|curl|wget) ')))
  if [ -n "$bare" ]; then
    result 指摘 4 "メソッドとエンドポイントの制限が無い前方一致の allow（引数で絞った allow $narrowed 件）"
    printf '%s\n' "$bare" | while IFS= read -r rule; do printf '      %s\n' "$rule"; done
  else
    result なし 4 "前方一致の allow: 0 件（引数で絞った allow $narrowed 件）"
  fi
fi

# 検査 5〜7 は settings.json に依存しない。workflow が 0 本なら未検査
WORKFLOWS="$(for f in "$WF_DIR"/*.yml "$WF_DIR"/*.yaml; do [ -f "$f" ] && echo "$f"; done)"

# 検査 5: top-level の permissions: 宣言
if [ -z "$WORKFLOWS" ]; then result 未検査 5 "top-level permissions: 対象なし（workflow 0 本）"
else
  missing=""; unreadable=0
  while IFS= read -r f; do
    grep -q '^permissions:' "$f"; rc=$?
    if [ "$rc" -eq 1 ]; then missing="$missing ${f##*/}"; elif [ "$rc" -ge 2 ]; then unreadable=1; fi
  done <<<"$WORKFLOWS"
  if [ "$unreadable" -eq 1 ]; then result 未検査 5 "top-level permissions: 読めない"
  elif [ -n "$missing" ]; then
    result 指摘 5 "top-level permissions: が無い workflow:$missing（リポジトリ既定を継承。既定値は見ていない）"
  else result なし 5 "top-level permissions: 全 workflow にある"; fi
fi

# 検査 6: secrets 参照（情報）。ファイル名と行数だけを出し、secret 名と行番号は出さない
if [ -z "$WORKFLOWS" ]; then result 未検査 6 "secrets 参照: 対象なし（workflow 0 本）"
else
  report=""; total=0; unreadable=0
  while IFS= read -r f; do
    n="$(grep -cE "$SECRET_RE" "$f")"; rc=$?
    [ "$rc" -ge 2 ] && unreadable=1 && continue
    [ "$n" -gt 0 ] && report="${report}[情報] 6 secrets 参照: ${f##*/} $n 行"$'\n' && total=$((total + n))
  done <<<"$WORKFLOWS"
  if [ "$unreadable" -eq 1 ]; then result 未検査 6 "secrets 参照: 読めない"
  else
    [ -n "$report" ] || report="[情報] 6 secrets 参照: 0 行"$'\n'
    printf '%s' "$report"; info=$((info + 1))
    echo "      合計 $total 行。使われているかは静的には決められない。toJSON(secrets) の形は数えない"
  fi
fi

# 検査 7: 指定した文字列（情報）。行頭がコメントの行は除く。「egress 制限あり／なし」とは表示しない
if [ -z "$WORKFLOWS" ]; then result 未検査 7 "指定した文字列: 対象なし（workflow 0 本）"
else
  hits=0; unreadable=0
  while IFS= read -r f; do
    body="$(grep -v '^[[:space:]]*#' "$f")"; rc=$?
    [ "$rc" -ge 2 ] && unreadable=1 && continue
    hits=$((hits + $(printf '%s\n' "$body" | grep -ciE "$EGRESS_RE")))
  done <<<"$WORKFLOWS"
  label="指定した文字列（harden-runner / allowed-endpoints / 語単位の egress）"
  if [ "$unreadable" -eq 1 ]; then result 未検査 7 "$label: 読めない"
  elif [ "$hits" -gt 0 ]; then result 情報 7 "$label: 見つかった $hits 件"
  else result 情報 7 "$label: 見つからなかった"; fi
fi

if [ "$unchecked" -gt 0 ]; then code=2; elif [ "$found" -gt 0 ]; then code=1; else code=0; fi
echo "なし $none / 指摘 $found / 情報 $info / 未検査 $unchecked"
echo "終了コード: $code"
echo "検査対象外: user / local / managed の設定、--settings、リポジトリ既定の workflow 権限"
echo "制約: YAML は grep で行単位に読む（複数行のフロー記法と anchor は読めない。行末コメントは除外しない）"
exit "$code"

読んだ設定: ./.claude/settings.json のみ。user / local / managed の設定と --settings は読んでいない
[指摘] 2 sandbox: キーが無い
[指摘] 3 許可する宛先の宣言: 0 件（拒否側の宛先 0 件、コマンド名で始まる deny 2 件）
[なし] 4 前方一致の allow: 0 件（引数で絞った allow 7 件）
[指摘] 5 top-level permissions: が無い workflow: readme-sync-check.yml spec-sync-check.yml（リポジトリ既定を継承。既定値は見ていない）
[情報] 6 secrets 参照: article-risk-gate-check.yml 1 行
[情報] 6 secrets 参照: blog-factory-executor.yml 1 行
[情報] 6 secrets 参照: blog-factory-planner.yml 1 行
      合計 3 行。使われているかは静的には決められない。toJSON(secrets) の形は数えない
[情報] 7 指定した文字列（harden-runner / allowed-endpoints / 語単位の egress）: 見つからなかった
なし 1 / 指摘 3 / 情報 2 / 未検査 0
終了コード: 1
検査対象外: user / local / managed の設定、--settings、リポジトリ既定の workflow 権限
制約: YAML は grep で行単位に読む（複数行のフロー記法と anchor は読めない。行末コメントは除外しない）