🐚 ShellKit (libc + pysh)

echo가 어떻게 동작하는지, 셸에서 시스템 콜까지 Python으로 단계별 추적.

English | 简体中文 | 日本語 | 한국어

---

📖 개요

ShellKit은 Unix 스타일의 교육용 터미널 툴킷으로, 두 개의 하위 프로젝트로 구성됩니다:

• Libc: Python 으로 구현한 C 라이브러리 시뮬레이션. syscall, write, printf 등을 포함하며, 유저 모드에서 커널 모드로의 흐름을 시각화합니다.
• Pysh: Libc 위에 구축된 대화형 셸. 내부 명령어, REPL, 계층간 추적 기능과 다국어 지원을 제공합니다. 시스템 프로그래머와 터미널 마니아를 위한 도구입니다.

macOS 와 Linux 에서 사용 가능하며, Arm64 및 x86_64 아키텍처를 지원합니다.

✨ 기능

Pysh

• 🧠 내장 명령어 (cd, echo, pwd, env 등)
• 🧵 다국어 지원 (영/중/일/한 매뉴얼 제공)
• 🔍 계층 간 트레이싱 (명령 파싱 → libc 함수 → C syscall)
• 🧩 조합 가능한 REPL 실행 모델
• 🔌 플러그인 기반 명령 등록 시스템

Libc

• 🖨️ 커스텀 printf 엔진 (%s, %d, %f 및 이스케이프 시퀀스 지원)
• 📜 Python ↔ C syscall 브릿지 (syscall/syslib.so 사용)
• 🧪 pytest 테스트 포함, 핵심 함수 성능 벤치마크 제공

📦 설치 방법

Python 3.10 이상 필요

pip로 설치:

pip install shellkit

설치 후 다음 명령으로 실행:

pysh

🚀 사용법

pysh [옵션들]

명령줄 옵션

옵션	설명
--command	단일 명령 실행
--no-banner	시작 배너 출력 생략
--no-reminder	휴식 알림 비활성화
--quiet	조용한 모드 (최소 출력)
--safe	안전 모드 (rm -rf / 등의 위험 명령 차단)
--debug	셸 명령 디버깅 정보 표시
--trace-echo	echo, printf의 libc 호출 경로 추적

도움말 보기:

pysh --help

📚 예제 및 튜토리얼

ShellKit의 실제 동작을 보고 싶으신가요? 포괄적인 예제들을 확인해보세요:

→ 예제 및 데모 - 기본부터 고급 기능까지, 실제 터미널 세션

다국어 데모, 디버깅 튜토리얼, 고급 printf 포매팅이 포함되어 있습니다!

📦 프로젝트 구조 (일부)

shellkit/
├── native/         # C로 작성된 syscall 구현
├── shellkit/       # 메인 패키지
│   ├── syscall/    # Python에서 호출하는 ctypes 기반 래퍼
│   ├── libc/       # 커스텀 libc (printf, write, exit 등)
│   ├── shell/      # 핵심 엔진, 내장 명령어, REPL 실행기
│   ├── inspector/  # 디버그 및 트레이싱 도구
│   └── i18n/       # 다국어 지원 및 번역 모듈
├── benchmarks/     # 성능 벤치마크
├── examples/       # 사용 예제 및 데모 로그
└── tests/          # 테스트 스위트

🧩 지원 플랫폼 (syslib.so)

플랫폼	지원 여부	설명
Linux x86_64	✅ 지원	rax = 1 + syscall 방식
Linux ARM64	✅ 지원	x8 = 64 + svc #0 방식
macOS Intel (x86)	✅ 지원	rax = 0x2000004 + syscall 방식
macOS ARM64 (M1/M2/M3)	✅ 지원	syscall(SYS_write, ...) 방식으로 래핑 처리
Windows	❌ 미지원	Windows는 syscall() 인터페이스가 없음

🧭 로드맵

ShellKit 은 이미 안정적이고 사용 가능한 상태지만, 앞으로 아래와 같은 기능을 계획하고 있습니다:

• 🔌 플러그인 시스템: 사용자 정의 내장 명령어, 별칭, 함수 등을 등록할 수 있도록 지원
• 🧠 딥씽킹 모드: eBPF 나 저수준 시스템 호출 추적을 위한 실험적인 기능
• 🧳 영구 프로필 저장: 환경 변수, 셸 히스토리, 커스텀 설정 등을 저장
• 🧪 더 많은 내장 명령어: ls, cat, grep 과 같은 일반 명령어를 추가
• 💡 멀티라인 스크립트 실행: 여러 줄의 명령어나 스크립트 블록을 한 번에 실행 가능하게

이 기능들이 흥미롭다면, 디스커션을 열어보시거나 PR 을 보내주세요.
아이디어든 코드든, 모든 형태의 기여를 환영합니다!

💬 관심을 기여로 전환하세요 — ShellKit 은 커뮤니티의 목소리와 함께 성장합니다.

📌 변경 내역

자세한 내용은 CHANGELOG.md 참고.

📜 라이선스

MIT 라이선스. 자세한 내용은 LICENSE를 확인하세요.

🤝 감사의 말

고전 Unix Shell 의 철학에 영감을 받아 개발.
모든 시스템 프로그래머들과 터미널 애호가 여러분께 감사드립니다.