.claude/settings.json으로 Claude Code 보안 지키기
Claude Code 같은 코딩 에이전트를 사내 개발 환경에서 사용할 때 가장 중요한 것은 “에이전트가 알아서 조심해주겠지”라고 기대하지 않는 것입니다. 보안은 프롬프트로 지키는 것이 아니라, 권한과 실행 환경으로 지켜야 합니다.
사내 개발 환경에서 안전하게 쓰기 위한 기본 설정
Claude Code 같은 코딩 에이전트를 사내 개발 환경에서 사용할 때 가장 중요한 것은 “에이전트가 알아서 조심해주겠지”라고 기대하지 않는 것입니다. 보안은 프롬프트로 지키는 것이 아니라, 권한과 실행 환경으로 지켜야 합니다.
특히 사내 코드, 내부 데이터, 실험 결과, 수치, 로그, 토큰, 인증 정보가 포함된 환경에서는 외부 웹 검색, 외부 URL fetch, 민감 파일 접근, Bash 기반 네트워크 호출 등을 명시적으로 제한하는 것이 좋습니다.
Claude Code는 settings.json을 통해 전역 설정, 프로젝트 설정, 개인 로컬 설정을 나눠 구성할 수 있습니다. 또한 권한 규칙은 deny → ask → allow 순서로 평가되며, deny가 가장 우선합니다. 즉, 막아야 하는 것은 먼저 확실히 막아두는 방식이 안전합니다.
참고: Claude Code settings, Configure permissions
1. 외부 웹 검색·전송 차단
사내 개발 환경에서 가장 먼저 막아야 할 것은 외부 웹 검색과 외부 전송 경로입니다.
Claude Code의 WebSearch, WebFetch 같은 도구를 막는 것은 기본이고, 여기서 한 걸음 더 나아가야 합니다.
왜냐하면 웹 도구만 막아도 Bash 명령을 통해 curl, wget, python requests, urllib, node fetch 같은 방식으로 외부 네트워크 접근이 가능할 수 있기 때문입니다.
따라서 외부 검색을 막는 것과 함께, Bash 기반 네트워크 경로도 같이 제한하는 것이 좋습니다.
예시는 다음과 같습니다.
{
"permissions": {
"deny": [
"WebSearch",
"WebFetch",
"Bash(curl *)",
"Bash(wget *)",
"Bash(python *requests*)",
"Bash(python *urllib*)",
"Bash(node *fetch*)"
]
}
}
기본 원칙은 단순합니다.
외부 웹 도구는 기본
deny, 꼭 필요한 경우에만ask.
사내 코드를 보면서 외부 레퍼런스를 검색해야 하는 상황이라면, 에이전트가 직접 검색하게 하는 것보다 사람이 공개 가능한 키워드와 정보만 분리해서 제공하는 방식이 더 안전합니다.
참고: Claude Code tools reference, Configure permissions
2. 사내 웹은 허용하고 사외 웹만 막고 싶다면

사내 개발 환경에서는 외부 웹은 막고 싶지만, 사내 문서 포털, 사내 Git, 사내 패키지 저장소, 사내 검색 포털에는 접근해야 하는 경우가 많습니다.
이때 흔히 떠올릴 수 있는 것이 NO_PROXY입니다.
하지만 결론부터 말하면, NO_PROXY를 그대로 “웹 접근 허용 리스트”로 보면 안 됩니다.
NO_PROXY는 보통 “이 주소들은 프록시를 타지 말라”는 네트워크 설정입니다.
즉, 회사 네트워크/프록시 관점의 우회 목록이지, 에이전트가 접근해도 되는 보안 허용 목록은 아닙니다.
NO_PROXY
= 회사 네트워크/프록시 관점의 우회 목록
Claude Code permissions / sandbox allowedDomains
= 에이전트 관점의 접근 허용 목록
예를 들어 NO_PROXY에 이런 값이 있을 수 있습니다.
NO_PROXY=localhost,127.0.0.1,.corp.company.net,git.corp.company.net,10.0.0.0/8,*.local
이 중 일부는 사내 접근 허용 후보가 될 수 있습니다.
git.corp.company.net
docs.corp.company.net
search.corp.company.net
pypi.corp.company.net
하지만 아래 항목은 그대로 허용하면 위험할 수 있습니다.
localhost
127.0.0.1
10.0.0.0/8
*.local
.corp.company.net 전체
이런 값들은 로컬 개발 서버, 내부 IP 대역, 임시 서버, 장비 UI, 관리자 콘솔까지 포함할 수 있습니다. 에이전트에게 무작정 열어주면 내부망의 너무 넓은 영역을 접근 가능하게 만들 수 있습니다.
따라서 NO_PROXY는 초기 후보 리스트로만 사용하는 것이 좋습니다.
1. NO_PROXY에서 내부 도메인 후보를 추출한다.
2. IP 대역, localhost, wildcard가 큰 항목은 제외한다.
3. 실제 에이전트가 접근해야 하는 서비스만 고른다.
4. Claude Code allowlist로 별도 관리한다.
5. 사내 검색, Git, 문서, 패키지 저장소 정도만 우선 허용한다.
사내 웹 접근을 허용하고 싶다면 WebSearch는 막고, 필요한 사내 도메인만 WebFetch(domain:...)로 허용하는 방식이 좋습니다.
{
"permissions": {
"deny": [
"WebSearch"
],
"allow": [
"WebFetch(domain:docs.corp.company.net)",
"WebFetch(domain:search.corp.company.net)",
"WebFetch(domain:git.corp.company.net)",
"WebFetch(domain:pypi.corp.company.net)"
],
"ask": [
"WebFetch(domain:*)"
]
}
}
여기서 주의할 점은 WebFetch 전체를 deny에 넣으면, 특정 사내 도메인을 allow해도 막힐 수 있다는 것입니다.
Claude Code 권한 평가에서 deny가 우선하기 때문입니다.
따라서 “사외만 막고 사내만 허용”하고 싶다면 WebFetch 전체 deny보다, 사내 도메인만 allow하고 나머지는 ask 또는 sandbox 네트워크 정책으로 제한하는 방식이 더 적절합니다.
3. 민감 파일·폴더 접근 차단

두 번째는 민감 파일과 폴더 접근 제한입니다.
에이전트에게 “.env 파일은 읽지 마”라고 말하는 것보다, 아예 권한 설정에서 읽지 못하게 막는 것이 안전합니다.
특히 다음 항목은 전역적으로 차단해두는 것이 좋습니다.
.env,.env.*secrets/**credentials.json~/.ssh/**~/.aws/**- 사내 confidential 폴더
- 고객/제품/실험 데이터가 들어 있는 raw data 폴더
예시는 다음과 같습니다.
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Read(./config/credentials.json)",
"Read(~/.ssh/**)",
"Read(~/.aws/**)",
"Read(~/Documents/company-confidential/**)",
"Edit(./.env)",
"Edit(./.env.*)",
"Edit(./secrets/**)",
"Edit(~/Documents/company-confidential/**)"
]
}
}
여기서 중요한 점은 deny가 있으면 allow보다 우선한다는 것입니다.
따라서 “혹시라도 열릴 수 있는 경로”를 먼저 deny에 넣어두는 것이 안전합니다.
저라면 설정을 이렇게 나눕니다.
~/.claude/settings.json
→ 개인 PC 전체에 적용할 강한 기본 보안 설정
프로젝트/.claude/settings.json
→ 팀 또는 프로젝트 공통 보안 정책
프로젝트/.claude/settings.local.json
→ 개인 실험용, 임시 허용 설정
공통으로 막아야 하는 것은 전역 설정에 넣고, 프로젝트마다 다른 민감 폴더는 프로젝트 설정에 추가하는 방식이 좋습니다.
참고: Claude Code settings, Configure permissions
4. Sandbox로 실행 범위 제한

권한 설정만으로는 부족할 수 있습니다. 특히 Bash 명령이나 그 하위 프로세스가 실행되는 경우에는 파일 시스템과 네트워크 접근 범위를 더 강하게 제한할 필요가 있습니다.
Claude Code는 sandboxed Bash 도구를 제공하며, 이를 통해 Bash 명령과 자식 프로세스가 접근할 수 있는 파일 시스템과 네트워크 범위를 제한할 수 있습니다. 공식 문서 기준으로 sandbox는 macOS, Linux, WSL2에서 동작하며, 기본 Windows 환경은 지원되지 않습니다.
참고: Configure the sandboxed Bash tool
기본적으로는 다음 옵션을 고려할 수 있습니다.
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true
}
}
여기서 failIfUnavailable: true가 중요합니다.
sandbox 실행이 실패했는데도 그냥 일반 실행으로 넘어가면 보안 경계가 사라질 수 있기 때문입니다.
조금 더 강하게 제한하고 싶다면 다음과 같은 방향을 생각할 수 있습니다.
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"filesystem": {
"denyRead": ["~/"],
"allowRead": ["."],
"denyWrite": ["~/"]
},
"credentials": {
"files": [
{ "path": "~/.ssh", "mode": "deny" },
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.git-credentials", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" },
{ "name": "NPM_TOKEN", "mode": "deny" },
{ "name": "AWS_ACCESS_KEY_ID", "mode": "deny" },
{ "name": "AWS_SECRET_ACCESS_KEY", "mode": "deny" }
]
}
}
}
핵심은 “현재 작업 폴더만 최소한으로 열고, 홈 디렉터리나 credential 파일은 닫아두는 것”입니다.
사내 도메인 접근이 꼭 필요하다면 sandbox 네트워크도 allowlist 방식으로 관리하는 것이 좋습니다. 개념적으로는 다음과 같은 형태입니다.
{
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"network": {
"allowedDomains": [
"docs.corp.company.net",
"search.corp.company.net",
"git.corp.company.net",
"pypi.corp.company.net",
"npm.corp.company.net"
]
}
}
}
실제 지원되는 세부 키와 동작은 Claude Code 버전에 따라 확인이 필요합니다. /doctor, /sandbox, 공식 문서 기준으로 검증하고 쓰는 것이 안전합니다.
물론 sandbox가 모든 보안 문제를 해결하는 것은 아닙니다. 보안 수준이 더 높아야 한다면 WSL2, 컨테이너, dev container, Docker, VM 등 더 강한 격리 환경을 함께 고려해야 합니다.
참고: Choose a sandbox environment
5. 사내 개발 환경 운영 원칙

설정 파일만 잘 만들어도 꽤 안전해지지만, 결국 운영 습관이 함께 따라와야 합니다. 제가 사내 개발 환경에서 Claude Code를 쓴다면 다음 원칙을 기본으로 둘 것 같습니다.
첫째, 작업 폴더를 최소화합니다. Claude Code를 홈 디렉터리나 넓은 사내 자료 폴더에서 실행하지 않습니다. 필요한 코드와 샘플 데이터만 들어 있는 좁은 작업 폴더에서 실행합니다.
둘째, 외부 웹 도구는 기본적으로 제한합니다.
WebSearch는 기본 차단하고, WebFetch는 필요한 사내 도메인만 허용합니다. 그 외 도메인은 ask 또는 sandbox 네트워크 정책으로 제한합니다.
셋째, 민감 파일은 전역 deny합니다.
.env, secrets, SSH key, cloud credential, 사내 confidential 폴더는 프로젝트마다 설정하는 것이 아니라 전역 설정에서 먼저 막아둡니다.
넷째, dangerously-skip-permissions는 사내 코드에서 사용하지 않습니다.
이 옵션은 편할 수 있지만, 이름 그대로 권한 확인을 건너뛰는 방식입니다. 사내 코드나 내부 데이터가 있는 환경에서는 금지하는 편이 맞습니다.
다섯째, 필요한 작업만 ask로 열어둡니다.
모든 것을 허용하기보다, Git, 테스트, 빌드, 패키지 설치 같은 작업을 ask로 두고 매번 확인하는 방식이 안전합니다.
사내 개발용 기본 조합 예시
아래는 개인 전역 설정의 출발점으로 생각해볼 수 있는 예시입니다.
{
"permissions": {
"deny": [
"WebSearch",
"Read(//**/.env)",
"Read(//**/.env.*)",
"Read(//**/secrets/**)",
"Read(//**/credentials.json)",
"Read(~/.ssh/**)",
"Read(~/.aws/**)",
"Read(~/.git-credentials)",
"Edit(//**/.env)",
"Edit(//**/.env.*)",
"Edit(//**/secrets/**)",
"Edit(~/.ssh/**)",
"Edit(~/.aws/**)",
"Bash(curl *http*)",
"Bash(wget *http*)",
"Bash(python *requests*)",
"Bash(python *urllib*)",
"Bash(node *fetch*)",
"Bash(git push *)",
"Bash(rm -rf *)",
"Bash(sudo *)"
],
"allow": [
"WebFetch(domain:docs.corp.company.net)",
"WebFetch(domain:search.corp.company.net)",
"WebFetch(domain:git.corp.company.net)",
"WebFetch(domain:pypi.corp.company.net)"
],
"ask": [
"WebFetch(domain:*)",
"Bash(git *)",
"Bash(pip *)",
"Bash(npm *)",
"Bash(uv *)",
"Bash(pytest *)"
]
},
"sandbox": {
"enabled": true,
"failIfUnavailable": true,
"filesystem": {
"denyRead": [
"~/.ssh",
"~/.aws",
"~/.git-credentials",
"~/Documents/company-confidential"
],
"denyWrite": [
"~/",
"/etc/**",
"/usr/**",
"/var/**"
]
},
"credentials": {
"files": [
{ "path": "~/.ssh", "mode": "deny" },
{ "path": "~/.aws/credentials", "mode": "deny" },
{ "path": "~/.git-credentials", "mode": "deny" }
],
"envVars": [
{ "name": "GITHUB_TOKEN", "mode": "deny" },
{ "name": "NPM_TOKEN", "mode": "deny" },
{ "name": "AWS_ACCESS_KEY_ID", "mode": "deny" },
{ "name": "AWS_SECRET_ACCESS_KEY", "mode": "deny" },
{ "name": "ANTHROPIC_API_KEY", "mode": "deny" }
]
}
}
}
프로젝트별로는 더 좁게 가져가는 것이 좋습니다.
{
"permissions": {
"deny": [
"WebSearch",
"Read(./data/raw/**)",
"Read(./confidential/**)",
"Read(./customer/**)",
"Read(./.env)",
"Read(./.env.*)",
"Edit(./data/raw/**)",
"Edit(./confidential/**)",
"Edit(./customer/**)"
],
"allow": [
"WebFetch(domain:docs.corp.company.net)",
"WebFetch(domain:search.corp.company.net)",
"WebFetch(domain:git.corp.company.net)"
],
"ask": [
"WebFetch(domain:*)",
"Bash(*)",
"Edit(*)",
"Write(*)"
]
},
"sandbox": {
"enabled": true,
"filesystem": {
"denyRead": ["~/"],
"allowRead": ["."],
"denyWrite": ["~/"]
}
}
}
이 설정이 모든 환경에서 그대로 정답이라는 뜻은 아닙니다. 프로젝트 구조, 사내 정책, 네트워크 환경, 사용하는 LLM API 경로, 패키지 저장소, Git 서버 위치에 따라 조정이 필요합니다.
다만 기본 방향은 명확합니다.
NO_PROXY는 허용 목록이 아니라 후보 목록이다. 필요한 사내 도메인만 명시적으로 열고, 나머지는 닫거나 물어보게 한다. 프롬프트보다 강한 것은 권한 설정이다.
마무리
AI 코딩 에이전트는 매우 강력한 도구입니다. 하지만 강력한 도구일수록 기본 보안 설정이 중요합니다.
특히 사내 개발 환경에서는 “잘 써보자”보다 먼저 “어디까지 접근할 수 있는가”, “어디로 전송할 수 있는가”, “어떤 명령을 실행할 수 있는가”를 정해야 합니다.
외부 웹 접근은 막되, 필요한 사내 문서·검색·Git·패키지 저장소만 좁게 열어두는 방식이 좋습니다. 이때 NO_PROXY는 참고용 후보 목록일 뿐, 그대로 보안 허용 목록이 되어서는 안 됩니다.
결국 사내 보안은 좋은 프롬프트가 아니라, 좋은 기본 설정에서 시작됩니다.
References
- Claude Code settings
- Configure permissions
- Tools reference
- Configure the sandboxed Bash tool
- Choose a sandbox environment
- Set up Claude Code for your organization
이 글은 위키독스 블로그에 처음 실었습니다.
댓글 0
첫 댓글을 남겨 주세요.
Google로 로그인하고 댓글 남기기