# Herramientas del harness

> Qué hace cada herramienta del harness, cuándo corre, qué significan sus resultados y sus límites en chat, CLI, MCP y Research API.


El harness es el conjunto de herramientas alrededor de los modelos. En el chat, el modelo decide cuándo llamarlas, y ves cada llamada con su objetivo y su duración. Los resultados llegan al modelo entre marcadores con un id aleatorio, marcados como contenido no confiable.

Las herramientas del servidor solo leen: páginas públicas, índices de búsqueda, nuestros espejos y los archivos que adjuntas. Ninguna escanea, sondea ni envía un payload a un objetivo. El agente de la CLI es la única parte que corre comandos, en tu máquina y con tu aprobación.

## Cuándo ofrece el chat cada herramienta

| Herramienta | Se ofrece cuando |
|---|---|
| `web_search`, `read_url` | **Web** está activa |
| `darkweb_search` | **Web** está activa y tu mensaje lo pide explícitamente |
| `cve_lookup`, `cve_search`, `advisory_lookup` | **CVE** está activo |
| `kb_search`, `kb_read` | Siempre. No hay interruptor |
| `file_list`, `file_read`, `file_search`, `binary_info`, `archive_list`, `disassemble` | Hay un archivo adjunto |

Una ejecución se detiene a los 12 pasos del modelo, 5 llamadas a herramientas a la vez, 60 segundos por herramienta y 10 minutos en total. Los resultados entran en la conversación y se cobran como tokens de entrada, al precio del modelo.

## Búsqueda web

`web_search(query, count?)` recibe una búsqueda de hasta 400 caracteres y devuelve títulos, URL y extractos de página, 5 resultados por defecto y 10 como máximo. Los resultados de NVD, cve.org, CISA, GitHub, Seclists, PortSwigger y OWASP van primero, y las búsquedas idénticas quedan en caché 15 minutos. Un resultado puede estar mal o desactualizado, así que abre la fuente antes de confiar en él.

## Lectura de páginas

`read_url(url)` devuelve el texto de una página pública. En el chat solo abre URL que escribiste o que devolvió un resultado de búsqueda, CVE, advisory o base de conocimiento. Los enlaces dentro de una página y los resultados `.onion` no se pueden abrir.

Acepta http(s) en los puertos 80 y 443 y HTML, texto, JSON o XML, hasta 10 MB y 15 segundos. Cada dirección y redirección se revisa, la conexión queda fija en la IP revisada y se respeta `robots.txt`. Rechaza IP literales, cadenas de ataque, rutas de archivos expuestos como `/.git` y `/.env`, y más de 40 rutas distintas en un host en 10 minutos. También rechaza una URL que lleve texto de un archivo adjunto.

## Búsqueda en la dark web

`darkweb_search(query, max_results?, engines?)` recibe una búsqueda de hasta 200 caracteres y devuelve hasta 30 entradas. Omite `engines` para usar todos los índices.

El chat solo ofrece esta herramienta cuando lo pides explícitamente. Tu mensaje tiene que contener dark web, deep web, darknet, `.onion`, onion site, sitios ocultos, red oscura o Tor, o ser la continuación directa de un turno que lo tenía. Nombrar un grupo de ransomware o una filtración no alcanza, y esas preguntas van a `web_search`. Con **Web** apagada, la herramienta queda apagada.

Cada resultado es un registro de índice de búsqueda: título, URL `.onion`, extracto y el índice de origen. El harness lee las páginas de resultados de los índices por Tor y nunca abre, rastrea ni descarga una página listada. Trata cada entrada como una pista no verificada y posiblemente hostil.

El límite es de 5 búsquedas por minuto por usuario. Los resultados patrocinados se descartan. Un filtro de seguridad rechaza búsquedas y descarta resultados sobre material de abuso sexual infantil. Sin ruta Tor, la herramienta lo avisa y puede usar un índice de la web abierta.

En MCP, llamar a `darkweb_search` ya es el pedido explícito. La Research API y la CLI no tienen ruta de dark web.

## Datos de CVE

`cve_lookup(id)` devuelve un registro consolidado: descripción de NVD, puntuación y vector CVSS 3.1 o 4.0, CWE, CPE afectados con versión corregida cuando NVD la tiene, referencias, puntuación y percentil EPSS, y estado en CISA KEV con fecha de entrada y uso conocido en ransomware. Cada fuente muestra cuándo se obtuvo. Un CVE sin CVSS aparece como sin puntuar y no se estima nada. Un ID que el espejo no tiene se trae de las fuentes una vez.

`cve_search(query?, vendor?, kev?, min_cvss?, min_epss?)` devuelve hasta 20 resultados ordenados por coincidencia de texto y EPSS. Solo pregunta a NVD por palabra clave cuando el espejo no encuentra nada.

## Advisories de paquetes

`advisory_lookup(name, ecosystem, version?)` devuelve vulnerabilidades conocidas de OSV, hasta 50. Informa lo que OSV lista para ese nombre y versión. Demostrar que el código vulnerable se alcanza en tu build sigue siendo cosa tuya. En MCP la herramienta se llama `advisory_query`.

## Base de conocimiento

`kb_search(query, domain?, source?, tool?)` busca en la [base de conocimiento](/es/chat/knowledge-base) curada y `kb_read(id, from?, limit?)` abre un documento sección por sección. Los dominios son `web`, `api`, `mobile`, `offensive`, `tools`, `cloud`, `ir` y `attack`. Cada resultado trae fuente, licencia y atribución. Una técnica de nicho puede no estar, y la búsqueda web es el paso siguiente.

## Archivos

Las herramientas de archivos leen lo que el parser estático extrajo de un adjunto. Nada de lo que subes se ejecuta, y no hay análisis dinámico. Cada archivo se analiza en un contenedor gVisor desechable, sin red, con raíz de solo lectura y sin secretos. Un archivo que supera los límites o un fallo del parser termina como `rejected`, con el motivo.

| Herramienta | Devuelve |
|---|---|
| `file_list` | Archivos adjuntos con estado, tipo, tamaño y avisos |
| `file_read(file_id, from?, limit?)` | Texto extraído por fragmento, con localizador de archivo y línea |
| `file_search(query)` | Fragmentos que contienen tus palabras, en todos los adjuntos |
| `binary_info(file_id)` | SHA-256, tamaño, entropía, y formato, punto de entrada, secciones e imports para ELF y PE |
| `archive_list(file_id)` | El índice del comprimido |
| `disassemble(file_id)` | Una vista previa: los primeros 4 KB del archivo decodificados como x86-64, 200 instrucciones como máximo |

No hay decompilador ni grafo de flujo. Los comprimidos se detienen en profundidad 3, 10.000 entradas, 2 GB expandidos y relación de 100:1. El texto se detiene en 5 millones de caracteres por archivo. Las imágenes dan solo dimensiones. El aviso `credentials_detected` significa que el parser encontró un patrón de clave o token. Consulta los tipos en [Archivos en el chat](/es/chat/files).

## Dónde está cada herramienta

| Capacidad | Chat | CLI | MCP | Research API |
|---|---|---|---|---|
| Búsqueda web | `web_search` | agente `web_search` | `web_search` | `POST /v1/web/search` |
| Lector de páginas | `read_url` | | `read_url` | `POST /v1/web/read` |
| Búsqueda en la dark web | `darkweb_search` | | `darkweb_search` | |
| Registro de CVE | `cve_lookup` | `notholy cve`, agente `cve_lookup` | `cve_lookup` | `GET /v1/cve/{id}` |
| Búsqueda de CVE | `cve_search` | `notholy cve search` | `cve_search` | `GET /v1/cve/search` |
| Advisories de paquetes | `advisory_lookup` | | `advisory_query` | `POST /v1/advisories/query` |
| Base de conocimiento | `kb_search`, `kb_read` | `notholy kb`, agente `kb_search` | `kb_search`, `kb_read` | `GET /v1/kb/search`, `GET /v1/kb/{id}` |
| Análisis de archivos | Herramientas de archivos de arriba | `notholy analyze` | `analyze_file` | `POST /v1/files` |
| Archivos locales y comandos | | Agente `read`, `grep`, `glob`, `edit`, `write`, `bash` | | |
| Alcance y log de engagement | | [`notholy engage`](/es/cli/agent#engagements) | | |

`POST /v1/chat/completions`, `/v1/responses` y `/v1/messages` son los endpoints crudos de los modelos y no tienen herramientas del harness. El modelo recibe solo las function tools que envías, y las ejecuta tu código. Para usar estos datos desde tu código, llama a la [Research API](/es/api/research) o a [MCP](/es/mcp/local).

## Próximos pasos

- [Agente de terminal](/es/cli/agent)
- [Research API](/es/api/research)