# Ferramentas do harness

> O que cada ferramenta do harness faz, quando roda, o que o resultado significa e seus limites no chat, CLI, MCP e Research API.


O harness é o conjunto de ferramentas em volta dos modelos. No chat, o modelo decide quando chamá-las, e você vê cada chamada com o alvo e a duração. Os resultados chegam ao modelo entre marcadores com id aleatório, marcados como conteúdo não confiável.

As ferramentas do servidor só leem: páginas públicas, índices de busca, nossos espelhos e os arquivos que você anexa. Nenhuma faz scan, sondagem ou envia payload a um alvo. O agente da CLI é a única parte que roda comandos, na sua máquina e com a sua aprovação.

## Quando o chat oferece cada ferramenta

| Ferramenta | Oferecida quando |
|---|---|
| `web_search`, `read_url` | **Web** está ligada |
| `darkweb_search` | **Web** está ligada e a sua mensagem pede explicitamente |
| `cve_lookup`, `cve_search`, `advisory_lookup` | **CVE** está ligado |
| `kb_search`, `kb_read` | Sempre. Não existe chave |
| `file_list`, `file_read`, `file_search`, `binary_info`, `archive_list`, `disassemble` | Há um arquivo anexado |

Uma execução para em 12 passos do modelo, 5 chamadas de ferramenta por vez, 60 segundos por ferramenta e 10 minutos no total. Os resultados entram na conversa e são cobrados como tokens de entrada, no preço do modelo.

## Busca na web

`web_search(query, count?)` recebe uma busca de até 400 caracteres e devolve títulos, URLs e trechos das páginas, 5 resultados por padrão e 10 no máximo. Resultados de NVD, cve.org, CISA, GitHub, Seclists, PortSwigger e OWASP vêm primeiro, e buscas idênticas ficam em cache por 15 minutos. Resultados podem estar errados ou velhos, então abra a fonte antes de confiar.

## Leitura de página

`read_url(url)` devolve o texto de uma página pública. No chat, só abre URLs que você digitou ou que vieram de um resultado de busca, CVE, advisory ou base de conhecimento. Links dentro de uma página e resultados `.onion` não podem ser abertos.

Aceita http(s) nas portas 80 e 443 e HTML, texto, JSON ou XML, até 10 MB e 15 segundos. Cada endereço e redirecionamento é conferido, a conexão fica fixa no IP conferido e o `robots.txt` é respeitado. Recusa IP literal, strings de ataque, caminhos de arquivo exposto como `/.git` e `/.env`, e mais de 40 caminhos distintos num host em 10 minutos. Uma URL que carrega texto de um arquivo anexado é recusada.

## Busca na dark web

`darkweb_search(query, max_results?, engines?)` recebe uma busca de até 200 caracteres e devolve até 30 entradas. Omita `engines` para usar todos os índices.

O chat só oferece essa ferramenta quando você pede explicitamente. A mensagem precisa conter dark web, deep web, darknet, `.onion`, onion site, serviços ocultos ou Tor, ou ser continuação direta de um turno que tinha isso. Citar um grupo de ransomware ou um vazamento não basta, e essas perguntas vão para `web_search`. Com **Web** desligada, a ferramenta fica desligada.

Cada resultado é um registro de índice de busca: título, URL `.onion`, trecho e o índice de origem. O harness lê as páginas de resultado dos índices por Tor e nunca abre, rastreia ou baixa uma página listada. Trate cada entrada como pista não verificada e possivelmente hostil.

O limite é de 5 buscas por minuto por usuário. Resultados patrocinados são descartados. Um filtro de segurança recusa buscas e descarta resultados sobre material de abuso sexual infantil. Sem rota Tor, a ferramenta avisa e pode usar um índice da web aberta.

No MCP, chamar `darkweb_search` já é o pedido explícito. A Research API e a CLI não têm rota de dark web.

## Dados de CVE

`cve_lookup(id)` devolve um registro consolidado: descrição do NVD, score e vetor CVSS 3.1 ou 4.0, CWE, CPEs afetados com versão de correção quando o NVD tem, referências, score e percentil EPSS, e status no CISA KEV com data de entrada e uso conhecido em ransomware. Cada fonte mostra quando foi obtida. CVE sem CVSS aparece como não pontuado e nada é estimado. Um ID que o espelho não tem é buscado nas fontes uma vez.

`cve_search(query?, vendor?, kev?, min_cvss?, min_epss?)` devolve até 20 resultados ordenados por relevância do texto e EPSS. Só pergunta ao NVD por palavra-chave quando o espelho não acha nada.

## Advisories de pacote

`advisory_lookup(name, ecosystem, version?)` devolve vulnerabilidades conhecidas do OSV, até 50. Informa o que o OSV lista para aquele nome e versão. Provar que o código vulnerável é alcançável no seu build continua com você. No MCP a ferramenta se chama `advisory_query`.

## Base de conhecimento

`kb_search(query, domain?, source?, tool?)` busca na [base de conhecimento](/pt-br/chat/knowledge-base) curada e `kb_read(id, from?, limit?)` abre um documento seção por seção. Os domínios são `web`, `api`, `mobile`, `offensive`, `tools`, `cloud`, `ir` e `attack`. Cada resultado traz fonte, licença e atribuição. Uma técnica de nicho pode não estar lá, e a busca na web é o passo seguinte.

## Arquivos

As ferramentas de arquivo leem o que o parser estático extraiu de um anexo. Nada do que você envia é executado, e não há análise dinâmica. Cada arquivo é analisado num contêiner gVisor descartável, sem rede, com raiz somente leitura e sem segredos. Um arquivo acima dos limites ou uma falha do parser termina como `rejected`, com o motivo.

| Ferramenta | Devolve |
|---|---|
| `file_list` | Arquivos anexados com status, tipo, tamanho e avisos |
| `file_read(file_id, from?, limit?)` | Texto extraído por trecho, com localizador de arquivo e linha |
| `file_search(query)` | Trechos que contêm suas palavras, em todos os anexos |
| `binary_info(file_id)` | SHA-256, tamanho, entropia, e formato, entry point, seções e imports para ELF e PE |
| `archive_list(file_id)` | O índice do pacote |
| `disassemble(file_id)` | Uma prévia: os primeiros 4 KB do arquivo decodificados como x86-64, no máximo 200 instruções |

Não há decompilador nem grafo de fluxo. Pacotes param em profundidade 3, 10.000 entradas, 2 GB expandidos e razão de 100:1. O texto para em 5 milhões de caracteres por arquivo. Imagens dão só as dimensões. O aviso `credentials_detected` significa que o parser encontrou um padrão de chave ou token. Veja os tipos em [Arquivos no chat](/pt-br/chat/files).

## Onde cada ferramenta existe

| Capacidade | Chat | CLI | MCP | Research API |
|---|---|---|---|---|
| Busca na web | `web_search` | agente `web_search` | `web_search` | `POST /v1/web/search` |
| Leitor de página | `read_url` | | `read_url` | `POST /v1/web/read` |
| Busca na dark web | `darkweb_search` | | `darkweb_search` | |
| Registro de CVE | `cve_lookup` | `notholy cve`, agente `cve_lookup` | `cve_lookup` | `GET /v1/cve/{id}` |
| Busca de CVE | `cve_search` | `notholy cve search` | `cve_search` | `GET /v1/cve/search` |
| Advisories de pacote | `advisory_lookup` | | `advisory_query` | `POST /v1/advisories/query` |
| Base de conhecimento | `kb_search`, `kb_read` | `notholy kb`, agente `kb_search` | `kb_search`, `kb_read` | `GET /v1/kb/search`, `GET /v1/kb/{id}` |
| Análise de arquivos | Ferramentas de arquivo acima | `notholy analyze` | `analyze_file` | `POST /v1/files` |
| Arquivos locais e comandos | | Agente `read`, `grep`, `glob`, `edit`, `write`, `bash` | | |
| Escopo e log de engagement | | [`notholy engage`](/pt-br/cli/agent#engagements) | | |

`POST /v1/chat/completions`, `/v1/responses` e `/v1/messages` são os endpoints crus dos modelos e não têm ferramentas do harness. O modelo recebe só as function tools que você manda, e quem as executa é o seu código. Para usar esses dados no seu código, chame a [Research API](/pt-br/api/research) ou o [MCP](/pt-br/mcp/local).

## Próximos passos

- [Agente no terminal](/pt-br/cli/agent)
- [Research API](/pt-br/api/research)