Claude Enterprise Inference hooks 설정: 보안 서버로 프롬프트 허용·차단하기

Claude Enterprise의 Inference hooks는 적용 대상 요청을 추론 전에 조직이 지정한 보안 서버로 보내 허용·차단 판정을 받는 기능입니다. 집행 상태에서 거부된 프롬프트는 모델에 도달하지 않습니다. 이 글은 Enterprise 관리자와 연동 개발자를 위한 공식 문서 기반 설정 안내입니다.

먼저 구분할 용어

용어이 글에서의 의미

Inference hooks	추론 전 대화 내용을 외부 보안 서버에 보내 판정을 받는 기능
엔드포인트	판정 요청을 받는 보안 서버의 HTTPS 주소
Shadow mode	서버 판정을 받되 요청을 차단하지 않는 관찰 모드
서명 비밀값	수신 요청의 서명을 검증하는 데 사용하는 비밀값

Claude의 Inference hooks 개요에 따르면 Claude Platform API 조직은 대상이 아닙니다. 일반 개인 계정용 설정으로도 사용할 수 없습니다.

1. 권한과 서버 준비하기

설정에는 organization:manage 권한이 필요합니다. Owner 또는 Primary owner가 담당하며, Admin 역할만으로는 부족합니다.

서버는 공개 IPv4 호스트에서 HTTPS 443으로 접근할 수 있어야 합니다. 공인 인증서와 리디렉션 없는 최종 URL을 준비하세요. localhost, 사설 주소, ngrok 같은 역방향 터널은 사용할 수 없습니다.

2. 관리자 화면에서 연결하기

Anthropic의 Configure Inference hooks 문서는 다음 순서를 안내합니다.

1. claude.ai에서 Organization settings → Data and privacy → Inference hooks로 이동합니다.
2. Allow for your organization을 켜고 설정 페이지를 엽니다. 이 스위치만으로 검사가 시작되지는 않습니다.
3. Configure에서 Endpoint URL을 저장합니다.
4. 한 번만 표시되는 서명 비밀값을 안전하게 보관하고 서버의 서명 검증에 연결합니다.
5. 필요하면 Custom request headers를 입력하고 Test connection을 실행합니다. 테스트는 저장값이 아닌 폼의 현재 값을 사용합니다.

연결 테스트에서 판정과 연결 상태를 확인하세요. 실제 계정 연결이나 서버 실행은 이 글에서 수행하지 않았습니다.

3. 서버는 HTTP 200으로 판정 반환하기

Develop an Inference hooks integration 문서에 따르면 요청은 HTTPS POST입니다. type은 프롬프트 검사인 prompt, 또는 Validate tool calls가 켜져 있을 때 도구 실행 전에 보내는 tool_call입니다.

다음은 미실행 응답 형식 예제입니다. 두 응답 모두 HTTP 200과 Content-Type: application/json으로 반환합니다.

허용:

{"action":"allow"}

차단:

{"action":"deny","deny_reason":"조직 정책에 따라 민감정보 전송을 차단했습니다."}

HTTP 403은 정책 거부가 아니라 웹훅 실패로 처리됩니다. 따라서 장애 시 허용하도록 설정했다면 의도한 차단이 되지 않을 수 있습니다.

실제 서버에는 서명 검증과 조직 정책 평가가 필요합니다. webhook-id, webhook-timestamp, webhook-signature를 사용해 JSON 재직렬화 전 원본 바이트를 검증하세요. 공식 구현 문서는 whsec_ 뒤 비밀값의 표준 Base64 디코딩, HMAC-SHA256, 상수시간 비교와 5분 시각 오차 검사를 제시합니다. 항상 allow를 반환하는 서버는 연결 확인용으로만 사용하세요.

4. Shadow에서 확인한 뒤 차단 적용하기

Enforce verdicts와 장애 모드를 함께 봐야 실제 동작을 알 수 있습니다.

설정동작

Enforce verdicts 꺼짐	서버를 호출하지 않음
Enforce verdicts 켜짐 + Shadow mode	검사하되 거부·장애 모두 차단하지 않음
Enforce verdicts 켜짐 + Shadow mode 꺼짐 + Allow the request	deny는 차단, 서버 장애는 허용
Enforce verdicts 켜짐 + Shadow mode 꺼짐 + Block the request	deny와 서버 장애 모두 차단

기본 장애 정책은 Allow the request, 시간 제한은 5,000ms입니다. 제한은 1~10,000ms에서 정합니다. Rollout 표본 밖 요청은 Block 설정이어도 검사하지 않으므로 적용 비율과 역할 제외 설정을 함께 점검하세요.

먼저 Shadow mode에서 정상 허용·거부와 시간 초과를 시험하세요. 판정이 의도대로 나오는지 확인한 뒤 장애 정책을 선택하고, Enforce verdicts를 켜고 Shadow mode를 해제해 실제 집행으로 전환합니다.

검사 범위와 반복 차단 주의하기

보안 서버에는 대화 텍스트, 도구 호출·결과, 첨부에서 추출한 텍스트가 전달됩니다. 원본 파일·이미지 바이트와 시스템 프롬프트는 제외되므로 이미지 속 민감정보까지 검사한다고 가정하면 안 됩니다. 프롬프트 수정·마스킹도 지원하지 않습니다.

차단된 내용이 대화 이력에 남으면 다음 요청도 거부될 수 있습니다. claude.ai 사용자는 해당 메시지와 첨부를 수정하거나 새 대화를 시작할 수 있습니다. 음성·일부 자체 도구 등의 예외는 Anthropic의 Inference hooks 적용 범위를 참고하세요.

도입 전 첫 검증은 정상 deny와 서버 장애를 구분하는 것입니다. 같은 차단처럼 보여도 응답 형식과 장애 설정에 따라 결과가 달라집니다.

참고 링크

• Anthropic — Configure Inference hooks
• Anthropic — Develop an Inference hooks integration