wattocyber/masqReconhecimento em tempo real e auditoria de postura para infraestrutura de agentes de IA: examina configurações de MCP, logs de sessão e APIs em busca de segredos, catálogos envenenados e vazamentos de CoT.
Sente-se onde o modelo se senta. Veja o que ele consegue ver.
MASQ é uma CLI de segurança local para stacks de agentes de IA. Ela ocupa o mesmo lugar que o modelo ocupa: lê catálogos de ferramentas MCP, completa o handshake MCP, examina logs de sessão e sonda portas HTTP de modelos locais. Em seguida, imprime descobertas e remediações.
Ela fala MCP e HTTP compatível com OpenAI da mesma forma que o cliente. Ela reporta como uma ferramenta de reconhecimento de host. Ela não chama ferramentas em um servidor ativo, não descriptografa cadeia de pensamento nem gera jailbreaks.
| Use quando | Você executa Cursor, VS Code, Claude, Codex ou uma stack de modelo local e quer ver os servidores MCP, skills, logs e APIs que o agente consegue alcançar. |
| Comece com | A demonstração de dois minutos abaixo. Ela permanece dentro deste repositório. |
| Status | Beta. cargo test é o portão público. Sondagens ativas são para hosts que você possui. |
| Licença | MIT |
Você precisa do Rust stable (1.88 ou mais recente) e do Python 3. A partir de um clone deste repositório:
cargo build --locked --bin masq
alias masq=./target/debug/masq
# or run the same walkthrough as a script:
# bash scripts/demo.sh
1. Um catálogo limpo permanece limpo
masq fixtures/clean_calculator.json --trusted
CLEAN clean_calculator tools=2 hash=sha256:e680cd2e4ac6c80ec783f11a0d9272a6741797feba216eb8e79633dd59633ab4
Saída 0.
2. Um catálogo envenenado falha no gate
fixtures/t3_line_jump.json é uma ferramenta sqrt cuja descrição instrui o modelo a consultá-la primeiro em cada sessão e a prefixar comandos de shell com um curl canário. Isso é envenenamento de catálogo, não matemática.
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
Sai com 2 (achados no nível ou acima de --fail-on, padrão high).
3. Simule um MCP ao vivo da mesma forma que o modelo faz
O mock embutido no repositório fala MCP via stdio. O masq envia initialize, notifications/initialized e tools/list. Ele nunca envia 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
A descrição da ferramenta add do mock instrui o modelo a ler ~/.ssh/id_rsa antes de fazer aritmética. O masq sinaliza isso a partir do tools/list em tempo real e, em seguida, encerra com 2.
4. Inspecione um log de sessão de exemplo
fixtures/demo/chat_history.jsonl insere uma chave de API falsa e um blob de raciocínio criptografado. Aponte o masq para esse diretório — não para o seu histórico de chat real — para ver a linha do tempo.
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
A chave plantada está censurada. A cadeia de pensamento criptografada é reportada por comprimento, não decodificada.
5. Fixe um catálogo que você revisou e, em seguida, detecte desvios
masq pin fixtures/clean_calculator.json -k calc
masq check fixtures/clean_calculator.json -k calc --trusted
pin grava .masq/pins.json. check falha depois se a lista de ferramentas ou os hashes mudarem (rug-pull).
Códigos de saída em todos os casos: 0 limpo · 2 achados ≥ --fail-on · 1 erro.
Scanners estáticos de MCP fazem lint de schemas. Health checks fazem ping em initialize. A lacuna está no assento: os arquivos, listeners e handshakes que o modelo já utiliza.
initialize sem autenticação. Se você consegue completar esse handshake, você já é o agente. O masq apenas observa; ele não chama ferramentas.11434, 8000 e similares frequentemente fazem bind em 0.0.0.0 sem bearer. O masq faz fingerprint do serviço (Ollama, vLLM, LiteLLM, …) com sondagens apenas GET e, em seguida, lista os modelos.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
Requer Rust stable atual (1.88+; instale com rustup). cargo test é o gate público. Python 3 é necessário apenas para o mock stdio ao vivo na demonstração e nos testes.
Para compilar em um host Unix remoto via SSH (apenas instalação; não escaneia esse host):
MASQ_REMOTE_HOST=user@host bash scripts/deploy_remote.sh
# on that host: masq --version
A demonstração nunca sai deste repositório. Estes comandos saem, e estão limitados a esta máquina, a menos que opte por uma lista de permissões de laboratório.
Exporte ou guarde um JSON de tools/list, depois:
masq path/to/tools.json
masq path/to/tools.json --json
masq path/to/tools.json --markdown
Caminhos .json simples são reescritos para scan. Dois ou mais arquivos JSON tornam-se multi.
masq sit -- python3 -m your_mcp
masq sit --url http://127.0.0.1:PORT/mcp
Loopback é suficiente. URLs fora do loopback também precisam de --lab e de um host na lista de permissões (veja abaixo). Autenticação, caso o servidor precise: