wattocyber/masqAI 에이전트 인프라를 위한 실시간 정찰 및 보안 상태 감사: MCP 구성, 세션 로그, API를 스캔하여 비밀 정보, 오염된 카탈로그, CoT 유출을 탐지합니다.
모델이 앉는 자리에 앉아라. 모델이 볼 수 있는 것을 보라.
MASQ는 AI 에이전트 스택을 위한 로컬 보안 CLI입니다. 모델이 앉는 바로 그 자리에 앉습니다. MCP 도구 카탈로그를 읽고, MCP 핸드셰이크를 완료하고, 세션 로그를 살펴보고, 로컬 모델 HTTP 포트를 탐색합니다. 그런 다음 발견 사항과 해결 방안을 출력합니다.
클라이언트가 하는 방식 그대로 MCP와 OpenAI 호환 HTTP로 통신합니다. 호스트 정찰 도구가 하는 방식으로 보고합니다. 라이브 서버에서 도구를 호출하거나, 사고의 연쇄(chain-of-thought)를 복호화하거나, 탈옥(jailbreak)을 생성하지는 않습니다.
| 사용 시점 | Cursor, VS Code, Claude, Codex 또는 로컬 모델 스택을 실행 중이며 에이전트가 접근할 수 있는 MCP 서버, 스킬, 로그, API를 확인하고 싶을 때. |
| 시작하기 | 아래의 2분 데모. 이 저장소 안에서만 진행됩니다. |
| 상태 | 베타. cargo test가 공개 게이트입니다. 라이브 탐색은 소유한 호스트에만 사용하세요. |
| 라이선스 | MIT |
Rust stable(1.88 이상)과 Python 3가 필요합니다. 이 저장소를 클론한 위치에서:
cargo build --locked --bin masq
alias masq=./target/debug/masq
# or run the same walkthrough as a script:
# bash scripts/demo.sh
1. 깨끗한 카탈로그는 깨끗하게 유지된다
masq fixtures/clean_calculator.json --trusted
CLEAN clean_calculator tools=2 hash=sha256:e680cd2e4ac6c80ec783f11a0d9272a6741797feba216eb8e79633dd59633ab4
0을 종료합니다.
2. 오염된 카탈로그는 게이트를 통과하지 못한다
fixtures/t3_line_jump.json은 sqrt 도구로, 그 설명은 모델에게 모든 세션에서 먼저 이 도구를 참조하고 셸 명령 앞에 카나리 curl을 붙이라고 지시합니다. 이는 카탈로그 오염이며, 수학이 아닙니다.
masq fixtures/t3_line_jump.json
FINDINGS t3_line_jump tools=1 findings=2 max=critical
F-001 [critical] D02 mcp03=schema_poison sqrt Network exfiltration directive in schema
path: $.tools[0].description
F-002 [critical] D03 mcp03=schema_poison sqrt Line-jump: force tool consultation / session prefix
path: $.tools[0].description
2로 종료합니다(--fail-on 이상의 발견 사항, 기본값 high).
3. 모델이 하는 방식대로 라이브 MCP를 배치하기
트리 내 mock은 stdio를 통해 MCP로 통신합니다. masq는 initialize, notifications/initialized, tools/list를 전송합니다. tools/call은 절대 전송하지 않습니다.
masq sit --plain --no-color -- python3 tests/mock_mcp_server.py
01 CATALOG
M-001 CRIT live Secret path or credential exfil directive
Schema references secret file paths or credential stores in an agent-directed way.
ACT Never reference host secret paths in tool metadata.
LOCUS stdio:python3 :: add
M-002 HIGH live IPI / poison language in tool metadata
Local classifier hit `system-override` in tool `add`.
ACT Remove agent-directed instructions from the tool description.
M-003 HIGH live Instruction-override language in schema string
Text matches common prompt-injection / instruction-override phrasing in tool metadata.
M-004 HIGH live Pre-action system instruction in schema
Schema instructs the model to perform actions before the normal tool purpose.
02 SEAT
HIT stdio python3 init ok name=mock-poison tools=1
모의(mock)의 add 도구 설명은 모델에게 산술 연산을 수행하기 전에 ~/.ssh/id_rsa를 읽으라고 지시합니다. masq는 라이브 tools/list에서 이를 탐지한 뒤 2로 종료합니다.
4. 샘플 세션 로그 스니핑하기
fixtures/demo/chat_history.jsonl에는 가짜 API 키와 암호화된 사고(thinking) 블롭이 심어져 있습니다. 실제 채팅 기록이 아닌 해당 디렉터리를 masq에 지정하여 타임라인을 확인하세요.
masq sniff --timeline --plain --no-color fixtures/demo
T0001 SECRET chat_history.jsonl:2 {"content":"Authorization: Bearer sk-x……
T0002 BLOB chat_history.jsonl:3 encrypted_content len=202
배치된 키는 가려져 있습니다. 암호화된 사고 연쇄는 복호화되지 않고 길이로만 보고됩니다.
5. 검토한 카탈로그를 고정한 뒤 드리프트를 감지하세요
masq pin fixtures/clean_calculator.json -k calc
masq check fixtures/clean_calculator.json -k calc --trusted
pin은 .masq/pins.json을 기록합니다. check는 이후 도구 목록이나 해시가 변경되면 실패합니다(rug-pull).
모든 곳의 종료 코드: 0 정상 · 2 발견 사항 ≥ --fail-on · 1 오류.
정적 MCP 스캐너는 스키마를 검사합니다. 상태 확인은 initialize를 핑합니다. 빠져 있는 것은 좌석(seat), 즉 모델이 이미 사용하고 있는 파일, 리스너, 핸드셰이크입니다.
initialize를 허용합니다. 해당 핸드셰이크를 완료할 수 있다면 이미 에이전트인 셈입니다. masq는 대기할 뿐, 도구를 호출하지 않습니다.11434, 8000 등은 종종 베어러 없이 0.0.0.0에 바인딩됩니다. masq는 GET 전용 프로브로 서비스(Ollama, vLLM, LiteLLM, …)를 핑거프린팅한 다음 모델을 나열합니다.flowchart LR
A["MCP tools/list JSON"] --> M[masq]
B["Live MCP server"] --> M
C["Session logs"] --> M
D["Local model HTTP"] --> M
M --> E["Findings + remediations"]
M --> F["Optional pin store for CI"]
git clone https://gitlab.com/WattoCyber/masq.git
cd masq
cargo install --path . --locked
# command: masq
masq --version
masq --help
현재 Rust stable(1.88+; rustup으로 설치)이 필요합니다. cargo test가 공개 게이트입니다. Python 3는 데모와 테스트에서 라이브 stdio 모의에만 필요합니다.
SSH를 통해 원격 Unix 호스트에서 빌드하려면(설치만 해당; 해당 호스트를 스캔하지 않음):
MASQ_REMOTE_HOST=user@host bash scripts/deploy_remote.sh
# on that host: masq --version
데모는 이 저장소를 벗어나지 않습니다. 다음 명령들은 저장소를 벗어나며, 실험실 허용 목록에 옵트인하지 않는 한 이 머신으로 범위가 제한됩니다.
tools/list JSON을 내보내거나 저장한 후 다음을 실행하세요:
masq path/to/tools.json
masq path/to/tools.json --json
masq path/to/tools.json --markdown
.json 경로만 있으면 scan으로 재작성됩니다. JSON 파일이 두 개 이상이면 multi가 됩니다.
masq sit -- python3 -m your_mcp
masq sit --url http://127.0.0.1:PORT/mcp
Loopback이면 충분합니다. Off-loopback URL은 --lab과 허용 목록에 등록된 호스트도 필요합니다(아래 참조). 서버에 인증이 필요한 경우:
masq sit --url http://127.0.0.1:PORT/mcp --token-file /path/to/token
masq sit --url http://127.0.0.1:PORT/mcp --token-env MCP_TOKEN
masq sit --url http://127.0.0.1:PORT/mcp --header "Authorization: Bearer …"
토큰은 보고서에 절대 기록되지 않습니다.
masq --plain # recon + sniff + API + skills + harness + steer, then the report
masq --json # same, machine-readable
masq tui # boxed live view; stays until Ctrl+C
masq discover # known agent MCP config paths; no spawn
masq recon # configs, listeners, unpinned npx/uvx
masq sniff ~/path/to/sessions
masq api # fingerprint local LLM HTTP, then GET /v1/models
masq api --list-probes # show the Julius-compatible probe pack
masq harness # on-disk harness policy, binds, creds, SSRF
masq steer # rules, hooks, subagents, local runtime, CDP, messaging
TTY에서는 기본 masq 명령이 진행 상황을 스트리밍한 다음 보고서를 출력합니다. 스크립트와 cron은 --plain 또는 --no-color를 전달해야 합니다.
discover는 VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Grok, Hermes, Pi, OMP, Codex, Continue, Gemini CLI, Amp, Kiro, OpenCode, Amazon Q, Antigravity, OpenClaw에 대해 $HOME / %USERPROFILE% 아래의 일반적인 경로를 탐색하며, 추가로 cwd의 .mcp.json과 MASQ_EXTRA_CONFIG도 탐색합니다.
harness는 MCP sit 및 API fingerprint와는 별개의 섹션입니다. Hermes, Pi, OMP, Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw, Grok, Amp, Amazon Q의 디스크상 설치를 읽습니다: 승인/YOLO 정책, 메시징 allow-all, 와일드카드 바인드, 자격 증명 파일 모드, computer/browser/launch 도구, cron 자동 승인, SSRF/redaction/Tirith 옵트아웃, 페어링 및 아이덴티티 파일 모드, OMP share/autolearn, Pi 원격 패키지. harness를 실행하거나 .env 값을 덤프하지는 않습니다.