VS Code Workspace Trust 초보자 가이드: 낯선 프로젝트 안전하게 열기

VS Code 초보자 시리즈 · Workspace Trust 1부

낯선 프로젝트를
안전하게 열기

Restricted Mode에서 파일을 먼저 점검하고, 신뢰할 근거가 생긴 뒤 실행 기능을 여는 습관을 익힙니다.

GitHub에서 예제 프로젝트를 내려받았다고 가정해 보겠습니다. README에 적힌 명령부터 실행하면 빠를 것 같지만, 프로젝트에는 터미널 명령·Tasks·디버그 설정·확장 설정처럼 코드를 실행할 수 있는 요소가 함께 들어 있을 수 있습니다. 이번 글에서는 workspace-trust-practice 프로젝트를 Restricted Mode로 열고, 실행하지 않은 채 내용을 확인한 다음, 안전하다고 판단했을 때만 신뢰하는 전체 과정을 직접 따라 합니다.

목차

1. Workspace Trust가 필요한 이유
2. Restricted Mode에서 달라지는 것
3. 실습 준비와 단축키
4. 연습 프로젝트 만들기
5. Restricted Mode로 열기
6. 실행하지 않고 파일 점검하기
7. 차단되는 기능 직접 확인하기
8. 확인 후 신뢰하고 실행하기
9. 신뢰 취소와 원래 상태 복구
10. 자주 하는 실수와 해결 방법
11. 직접 따라 하기와 연습 과제
12. 핵심 정리와 다음 편 예고

1. Workspace Trust가 필요한 이유

Workspace Trust는 “이 폴더의 작성자와 파일 내용을 믿고 실행 기능을 허용할 것인가?”를 사용자가 결정하게 해 주는 안전장치입니다. 신뢰하지 않은 폴더는 Restricted Mode로 열어 자동 코드 실행 가능성을 낮춥니다. 공식 문서는 확신이 없을 때 제한 모드를 유지하고, 검토가 끝난 뒤 나중에 신뢰해도 된다고 안내합니다. 안전한 코드 탐색 공식 문서

파일을 보기만 하는데 왜 주의해야 할까요?

프로젝트 폴더에는 소스 코드만 들어 있지 않습니다. VS Code가 읽는 Workspace 설정, 자동화 작업, 디버그 구성, 확장 기능 설정도 함께 공유될 수 있습니다. 이 중 일부는 외부 프로그램이나 스크립트를 실행하도록 구성할 수 있습니다.

파일 또는 기능	초보자가 보는 용도	확인해야 하는 이유
package.json	프로젝트 정보와 실행 명령	scripts에 실제 실행 명령이 들어 있음
.vscode/tasks.json	반복 작업 자동화	셸 명령이나 프로그램을 실행할 수 있음
.vscode/launch.json	디버깅 시작 방법	디버거와 사전 작업을 실행할 수 있음
.vscode/settings.json	프로젝트별 편집기 설정	일부 설정은 실행 파일 경로에 영향을 줄 수 있음
확장 기능	언어 지원·포맷·검사	VS Code와 비슷한 권한으로 파일·네트워크·프로세스에 접근할 수 있음

공식 확장 보안 문서는 Extension Host에서 실행되는 확장이 파일 읽기·쓰기, 네트워크 요청, 외부 프로세스 실행, Workspace 설정 변경을 할 수 있다고 설명합니다. 따라서 Workspace Trust만 믿고 출처가 불분명한 확장을 설치하는 것도 안전하지 않습니다. 확장 런타임 보안 공식 문서

2. Restricted Mode에서 달라지는 것

Restricted Mode는 프로젝트를 삭제하거나 잠그는 기능이 아닙니다. 소스 코드를 읽고 편집하는 기본 작업은 계속할 수 있지만, 자동 실행 가능성이 있는 기능을 차단하거나 제한합니다.

기능	Restricted Mode의 기본 동작	초보자 관점
코드 열람·편집	사용 가능	먼저 내용을 살펴볼 수 있음
통합 터미널	기본적으로 신뢰 확인 후 열림	명령 실행 전에 한 번 더 멈춤
Tasks	실행 또는 목록 확인 시 신뢰 요청	공유된 자동화 명령의 무심코 실행 방지
디버깅	신뢰 전까지 제한	디버거 바이너리와 사전 작업 실행 방지
Workspace 설정	신뢰가 필요한 일부 설정 무시	프로젝트가 실행 경로를 바꾸는 위험 완화
확장 기능	지원 수준에 따라 활성·제한·비활성	확장이 사라진 것이 아니라 제한될 수 있음
AI 에이전트	신뢰하지 않은 Workspace에서 비활성	파일·터미널을 대신 조작하는 기능 차단

현재 공식 문서에는 터미널, Tasks, 디버깅, Workspace 설정, 확장 기능과 AI 에이전트가 제한 대상이라고 명시되어 있습니다. VS Code 창과 Agents 창은 같은 Workspace 신뢰 상태를 공유합니다. Restricted Mode 공식 문서

중요 Restricted Mode는 추가 방어선이지 모든 위험을 막는 샌드박스가 아닙니다. 공식 문서도 악성 확장이 Restricted Mode를 무시하고 코드를 실행하는 것까지 막을 수는 없다고 경고합니다. 출처와 게시자를 신뢰할 수 있는 확장만 설치하세요.

3. 실습 준비와 단축키

이번 실습에는 VS Code만 있으면 됩니다. Node.js나 별도 확장을 설치하지 않아도 Task의 단순 출력까지 확인할 수 있도록 구성했습니다.

작업	Windows	macOS	이번 글의 용도
명령 팔레트 열기	Ctrl + Shift + P	⇧ + ⌘ + P	Workspace Trust 관리
Explorer 열기	Ctrl + Shift + E	⇧ + ⌘ + E	검토할 파일 찾기
전체 검색	Ctrl + Shift + F	⇧ + ⌘ + F	실행 명령·경로 검색
통합 터미널	Ctrl + `	⌃ + `	제한 동작 확인
디버깅 시작	F5	F5	신뢰 전후 차이 확인

명령 팔레트와 Workspace Trust 관리 단축키는 Workspace Trust 문서에, Explorer·검색·터미널·디버깅 단축키는 기본 단축키 참조에 명시되어 있습니다. 기본 단축키 공식 문서

4. 연습 프로젝트 만들기

실제 다운로드 프로젝트 대신 우리가 내용을 아는 안전한 파일을 만들어 “처음 받은 프로젝트” 상황을 연습합니다. 운영체제의 파일 탐색기에서 문서 폴더 아래에 ForEvaluation 폴더를 만들고, 그 안에 workspace-trust-practice 폴더를 만드세요.

1단계: 기본 파일 만들기

VS Code에서 File → Open Folder로 workspace-trust-practice를 연 뒤 Explorer에서 다음 파일을 만듭니다.

workspace-trust-practice/
├─ README.md
├─ app.js
├─ package.json
└─ .vscode/
   ├─ settings.json
   └─ tasks.json

2단계: 내용을 입력하기

README.md에는 프로젝트의 목적과 실행 전 점검 항목을 적습니다.

# Workspace Trust Practice

This is a safe project created for Workspace Trust practice.

Before running:
1. Review package.json scripts.
2. Review .vscode/tasks.json.
3. Review .vscode/settings.json.
4. Trust the folder only after the review.

app.js에는 실행 결과를 확인할 짧은 코드를 넣습니다.

const message = 'Workspace Trust practice completed';
console.log(message);

package.json에는 실행 스크립트가 어디에 있는지 확인하는 연습용 항목을 넣습니다.

{
  "name": "workspace-trust-practice",
  "private": true,
  "scripts": {
    "start": "node app.js"
  }
}

.vscode/settings.json은 실행과 관계없는 편집기 설정 하나만 사용합니다.

{
  "editor.wordWrap": "on"
}

.vscode/tasks.json에는 외부 패키지가 필요 없는 출력 Task를 넣습니다.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Workspace Trust 확인",
      "type": "shell",
      "command": "echo",
      "args": ["Workspace Trust check passed"],
      "problemMatcher": []
    }
  ]
}

정상 결과 Explorer에 다섯 파일이 보이고, JSON 파일에는 빨간 오류 표시가 없어야 합니다. 지금은 Task나 npm start를 실행하지 않습니다.

5. Restricted Mode로 열기

새 폴더를 열었을 때 VS Code가 Restricted Mode 배너를 표시한다면 Manage를 선택해 상태만 확인하고 아직 신뢰하지 마세요. 시작 시 팝업이 나타나면 No, I don't trust the authors를 선택합니다.

배너가 보이지 않을 때

1. 명령 팔레트를 엽니다: Windows는 Ctrl + Shift + P, macOS는 ⇧ + ⌘ + P입니다.
2. Workspaces: Manage Workspace Trust를 실행합니다.
3. Don't Trust를 선택합니다.
4. 상단 배너 또는 상태 표시줄에 Restricted Mode가 표시되는지 확인합니다.

공식 문서는 상단 배너의 Manage 링크, 상태 표시줄의 Restricted Mode 항목, 명령 팔레트의 Workspaces: Manage Workspace Trust에서 신뢰 상태를 관리할 수 있다고 설명합니다. Workspace 신뢰 관리 공식 문서

정상 결과 파일은 계속 열고 수정할 수 있지만 상태 표시줄이나 상단 배너에서 Restricted Mode를 확인할 수 있습니다.

Don't Trust가 없다면 상위 폴더가 이미 신뢰 목록에 들어 있을 가능성이 큽니다. 이 경우 현재 하위 폴더만 따로 제한할 수 없으므로 Trusted Folders & Workspaces 목록에서 상위 폴더 신뢰를 먼저 검토해야 합니다.

6. 실행하지 않고 파일 점검하기

신뢰 여부를 결정하기 전에는 “파일을 읽는 단계”와 “명령을 실행하는 단계”를 분리해야 합니다. README에 명령이 적혀 있어도 바로 복사해 실행하지 마세요.

1단계: 출처 확인

• 프로젝트를 받은 주소와 작성자·조직이 예상한 곳인지 확인합니다.
• 압축 파일이나 저장소 이름이 원본과 비슷하게 위장되지 않았는지 봅니다.
• 설치하려는 확장은 게시자, 저장소, 라이선스, 최근 변경 이력을 확인합니다.

2단계: 실행 진입점 확인

Explorer에서 다음 항목을 우선 확인합니다.

• package.json의 scripts
• .vscode/tasks.json의 command와 args
• .vscode/launch.json의 실행 파일, 프로그램 경로, preLaunchTask
• .vscode/settings.json의 실행 파일 경로 관련 설정
• 셸 스크립트, 설치 스크립트, 다운로드 명령

3단계: 검색으로 놓친 명령 찾기

Windows는 Ctrl + Shift + F, macOS는 ⇧ + ⌘ + F로 전체 검색을 열어 다음 단어를 하나씩 찾아봅니다.

command
scripts
preLaunchTask
executablePath
curl
wget

검색 결과가 있다고 모두 위험한 것은 아닙니다. 중요한 것은 어떤 파일이 어느 명령을 언제 실행하는지 이해하는 것입니다.

이번 예제의 판단 package.json은 우리가 만든 app.js만 실행하고, Task는 고정된 문장을 출력하며, Workspace 설정은 줄 바꿈만 켭니다. 파일 내용을 직접 만들었고 실행 범위도 확인했으므로 이후 단계에서 신뢰해도 됩니다.

7. 차단되는 기능 직접 확인하기

Restricted Mode가 실제로 무엇을 막는지 확인해 보겠습니다. 경고가 나오면 신뢰로 전환하지 말고 취소해 제한 상태를 유지하세요.

실습 A: 터미널 열기

1. Windows는 Ctrl + `, macOS는 ⌃ + `을 누릅니다.
2. 신뢰 확인 대화상자가 나타나면 취소합니다.
3. Restricted Mode가 그대로인지 확인합니다.

공식 문서에 따르면 셸은 현재 폴더를 참조하는 초기화 스크립트나 환경 파일을 통해 코드를 자동 실행할 수 있어, 제한 모드에서 터미널은 기본적으로 차단됩니다. Restricted Mode의 터미널 동작

실습 B: Task 실행 시도

1. 명령 팔레트에서 Tasks: Run Task를 실행합니다.
2. 신뢰 확인이 나타나면 취소합니다.
3. Task가 실행되지 않고 출력 패널도 열리지 않는지 확인합니다.

.vscode/tasks.json은 저장소에 포함되어 다른 사람과 공유될 수 있고 셸 명령이나 도구를 실행할 수 있기 때문에 Restricted Mode에서 제한됩니다. Restricted Mode의 Tasks 동작

실습 C: 확장 상태 확인

Workspace Trust 편집기에서 “확장이 비활성화되었거나 기능이 제한됨” 링크를 선택하면 @workspaceUnsupported 필터가 적용된 Extensions 화면을 볼 수 있습니다. 확장마다 Restricted Mode를 완전히 지원하거나, 일부 기능만 지원하거나, 신뢰 전까지 비활성화될 수 있습니다. Restricted Mode의 확장 동작

정상 결과 터미널과 Task 실행을 시도하면 신뢰 확인이 나타나고, 취소하면 아무 명령도 실행되지 않은 채 Restricted Mode가 유지됩니다.

8. 확인 후 신뢰하고 실행하기

프로젝트 출처와 실행 파일을 확인했다면 현재 폴더에만 신뢰를 부여합니다. 초보자는 편의를 위해 문서 폴더 전체나 다운로드 폴더 전체를 신뢰하지 않는 편이 안전합니다.

1. 상단 Restricted Mode 배너에서 Manage를 선택합니다.
2. Workspace Trust 편집기에서 현재 경로가 workspace-trust-practice인지 확인합니다.
3. Trust를 선택합니다.
4. 창이 다시 로드되면 Restricted Mode 표시가 사라졌는지 확인합니다.
5. 명령 팔레트에서 Tasks: Run Task를 실행합니다.
6. Workspace Trust 확인을 선택합니다.

정상 결과 터미널에 Workspace Trust check passed가 출력되고 Task가 정상 종료됩니다. 이제 신뢰가 필요한 Workspace 설정과 지원 확장도 다시 활성화될 수 있습니다.

VS Code 1.57 릴리스 노트는 Workspace Trust를 낯선 소스 코드를 탐색할 때 코드 실행을 제한하는 추가 보안 기능으로 소개했습니다. 현재도 신뢰는 “프로젝트를 실행해도 된다는 판단”이지 “모든 파일이 무조건 안전하다는 인증”은 아닙니다. VS Code 1.57 Workspace Trust 릴리스 노트

9. 신뢰 취소와 원래 상태 복구

신뢰한 뒤 수상한 파일이나 예상하지 못한 명령을 발견했다면 즉시 실행을 멈추고 다시 Restricted Mode로 전환할 수 있습니다.

1. 명령 팔레트를 엽니다.
2. Workspaces: Manage Workspace Trust를 실행합니다.
3. Don't Trust를 선택합니다.
4. 창이 다시 로드된 뒤 Restricted Mode 표시를 확인합니다.
5. 실행한 명령이 있었다면 해당 명령이 만든 파일과 변경 내역을 별도로 점검합니다.

또는 Workspace Trust 편집기의 Trusted Folders & Workspaces 목록에서 해당 폴더를 제거할 수 있습니다. 공식 문서가 안내하는 두 가지 신뢰 취소 방법입니다. 신뢰 취소 공식 안내

신뢰 취소의 한계 Restricted Mode로 되돌려도 이미 실행된 명령의 효과가 자동으로 취소되지는 않습니다. 파일 삭제·설치·네트워크 전송 등이 발생했다면 Git 변경 내역, 설치된 패키지, 실행 기록을 따로 확인해야 합니다.

10. 자주 하는 실수와 해결 방법

상황	원인	해결 방법
확장이 갑자기 사라짐	Restricted Mode에서 해당 확장이 비활성 또는 제한됨	Workspace Trust 편집기의 확장 상태 링크에서 확인하고, 출처 검토 후 폴더 신뢰 여부 결정
터미널이 열리지 않음	제한 모드가 터미널 실행을 막음	경고를 우회하지 말고 먼저 프로젝트 파일을 검토
Workspace 설정이 적용되지 않음	신뢰가 필요한 설정이 무시됨	Workspace Trust 편집기에서 적용되지 않은 설정 링크 확인
Don't Trust 버튼이 없음	상위 폴더의 신뢰를 상속함	Trusted Folders & Workspaces 목록에서 상위 경로 검토
모든 다운로드 프로젝트가 자동 신뢰됨	Downloads 같은 넓은 상위 폴더를 신뢰함	넓은 경로 신뢰를 제거하고 개별 프로젝트만 선택적으로 신뢰
경고가 번거로워 기능 자체를 끔	security.workspace.trust.enabled를 비활성화함	기본값인 활성 상태로 복구하고 프로젝트별로 판단

Workspace Trust 기능 전체를 끄는 것은 가능하지만 공식 문서는 권장하지 않습니다. 시작 팝업의 기본값은 현재 never이며, 새 폴더는 팝업 대신 Restricted Mode 배너로 열립니다. 필요하면 security.workspace.trust.startupPrompt를 once로 바꿔 새 폴더를 처음 열 때 확인받을 수 있습니다. Workspace Trust 설정 공식 문서

11. 직접 따라 하기와 연습 과제

15분 종합 실습

1. ForEvaluation 아래에 workspace-trust-practice-2 폴더를 만듭니다.
2. Restricted Mode로 열고 상태 표시를 확인합니다.
3. README.md, package.json, .vscode/tasks.json을 직접 만듭니다.
4. package.json의 scripts와 Task의 command를 말로 설명해 봅니다.
5. 터미널과 Task 실행을 시도하되 신뢰 요청에서는 취소합니다.
6. 검토가 끝난 뒤 현재 프로젝트 폴더만 신뢰합니다.
7. Task를 실행해 예상한 문장이 출력되는지 확인합니다.
8. 다시 Don't Trust를 선택해 Restricted Mode로 복구합니다.

완료 체크리스트

• Restricted Mode에서도 파일을 읽고 수정할 수 있다는 것을 확인했다.
• 신뢰 전에는 README의 명령을 바로 실행하지 않았다.
• package.json, Tasks, 디버그·Workspace 설정을 먼저 살펴봤다.
• 상위 폴더 전체가 아니라 현재 프로젝트만 신뢰했다.
• 신뢰를 다시 취소하는 방법을 직접 실행했다.

추가 연습 과제

1. ForEvaluation과 TrustedRepos 폴더를 따로 만들고 어떤 프로젝트를 어디에 둘지 기준을 적어 보세요.
2. Workspace Trust 편집기에서 Trusted Folders & Workspaces 목록을 열고 너무 넓게 신뢰된 상위 경로가 없는지 확인하세요.
3. 설치된 확장 하나를 골라 게시자, 저장소, 라이선스, Restricted Mode 지원 상태를 확인하세요.

12. 핵심 정리와 다음 편 예고

• 낯선 폴더는 먼저 Restricted Mode에서 읽고 검토합니다.
• 코드 열람과 명령 실행을 별개의 단계로 생각합니다.
• package.json, Tasks, 디버그 구성, Workspace 설정, 확장 기능을 우선 확인합니다.
• 확신이 생긴 뒤 현재 프로젝트 범위에만 신뢰를 부여합니다.
• 문제를 발견하면 Don't Trust로 되돌리되 이미 실행된 작업은 별도로 점검합니다.

다음 편 예고 Workspace Trust 2부에서는 TrustedRepos와 ForEvaluation을 이용해 신뢰 경계를 설계하고, 상위 폴더 신뢰·외부 파일·확장 게시자 신뢰를 실무 기준으로 정리합니다.

공식 참고 문서

• Workspace Trust
• Extension runtime security
• Default keyboard shortcuts reference
• VS Code 1.57 릴리스 노트
• VS Code 1.73 Workspace Trust 설정 표시 개선

이 글의 기능 설명과 단축키는 2026년 7월 28일 기준 VS Code 공식 문서와 공식 릴리스 노트로 확인했습니다.