# Shell Execution Command Design Document
## 개요
AI FileSystem MCP에 shell 명령어 실행 기능을 추가하여 사용자가 시스템 명령어를 실행할 수 있도록 한다.
## 요구사항 분석
### 기능적 요구사항
1. **명령어 실행**: 사용자가 지정한 shell 명령어를 실행
2. **작업 디렉토리 지정**: 명령어를 실행할 디렉토리 지정 가능
3. **환경 변수 설정**: 실행 시 환경 변수 설정 가능
4. **타임아웃 설정**: 명령어 실행 시간 제한
5. **출력 캡처**: stdout, stderr 분리하여 캡처
6. **종료 코드 반환**: 명령어 실행 결과의 exit code 반환
### 비기능적 요구사항
1. **보안**: Command injection 방지
2. **성능**: 효율적인 프로세스 관리
3. **안정성**: 에러 처리 및 프로세스 종료 보장
4. **확장성**: 향후 기능 추가 용이
## 기술 선택
### Node.js child_process 모듈 옵션
1. **exec/execSync**
- 장점: 간단한 사용법, shell 기능 활용 가능
- 단점: 버퍼 크기 제한, 보안 위험
2. **spawn/spawnSync**
- 장점: 스트리밍 지원, 더 안전함, 메모리 효율적
- 단점: shell 기능 직접 사용 불가
3. **execFile/execFileSync**
- 장점: 파일 직접 실행, 보안성 높음
- 단점: shell 기능 사용 불가
**선택**: `spawn` 메서드를 기본으로 사용하되, shell 기능이 필요한 경우 옵션으로 제공
## 보안 고려사항
### 1. Command Injection 방지
- 사용자 입력 검증
- 위험한 문자 이스케이프
- 화이트리스트 기반 명령어 제한 옵션
### 2. 리소스 제한
- CPU 사용량 제한
- 메모리 사용량 제한
- 실행 시간 제한 (타임아웃)
### 3. 권한 관리
- 실행 권한 검증
- sudo 명령어 제한
- 위험한 시스템 명령어 차단
### 4. 샌드박싱
- chroot 또는 컨테이너 활용 고려
- 파일 시스템 접근 제한
## API 설계
### 명령어 이름
`execute_shell` 또는 `run_command`
### 입력 스키마
```typescript
{
type: 'object',
properties: {
command: {
type: 'string',
description: 'Shell command to execute'
},
args: {
type: 'array',
items: { type: 'string' },
description: 'Command arguments (optional)'
},
cwd: {
type: 'string',
description: 'Working directory (optional)'
},
env: {
type: 'object',
description: 'Environment variables (optional)'
},
timeout: {
type: 'number',
description: 'Timeout in milliseconds (optional)'
},
shell: {
type: 'boolean',
description: 'Use shell to execute command (default: false)'
},
encoding: {
type: 'string',
description: 'Output encoding (default: utf8)'
}
},
required: ['command']
}
```
### 출력 형식
```typescript
{
stdout: string;
stderr: string;
exitCode: number;
signal?: string;
timedOut?: boolean;
executionTime: number;
}
```
## 구현 계획
### 1단계: 기본 구현
- spawn을 사용한 기본 명령어 실행
- stdout/stderr 캡처
- 기본 에러 처리
### 2단계: 보안 강화
- 입력 검증 및 sanitization
- 위험 명령어 차단
- 권한 검증
### 3단계: 고급 기능
- 타임아웃 구현
- 환경 변수 설정
- 작업 디렉토리 설정
### 4단계: 최적화
- 스트리밍 출력 지원
- 대용량 출력 처리
- 성능 최적화
## 테스트 계획
### 단위 테스트
1. 기본 명령어 실행
2. 인자 전달
3. 에러 처리
4. 타임아웃 처리
5. 환경 변수 설정
### 통합 테스트
1. 다양한 shell 명령어 실행
2. 파이프라인 명령어
3. 백그라운드 프로세스
4. 시그널 처리
### 보안 테스트
1. Command injection 시도
2. 권한 상승 시도
3. 리소스 고갈 공격
4. 경로 탐색 공격
## 위험 요소 및 대응 방안
### 위험 요소
1. **보안 취약점**: Command injection, 권한 상승
2. **시스템 불안정**: 무한 루프, 리소스 고갈
3. **데이터 손실**: 위험한 명령어 실행
4. **성능 저하**: 장시간 실행 명령어
### 대응 방안
1. **엄격한 입력 검증**
2. **실행 가능 명령어 화이트리스트**
3. **리소스 제한 설정**
4. **로깅 및 모니터링**
5. **롤백 메커니즘**
## 참고 자료
- Node.js child_process 공식 문서
- OWASP Command Injection Prevention
- Linux Security Best Practices
- MCP Security Guidelines
