# Strumenti dell'harness

> Cosa fa ogni strumento dell'harness, quando gira, cosa significano i risultati e i limiti in chat, CLI, MCP e Research API.


L'harness è l'insieme degli strumenti attorno ai modelli. In chat il modello decide quando chiamarli, e vedi ogni chiamata con target e durata. I risultati arrivano al modello tra marcatori con un id casuale, etichettati come contenuto non attendibile.

Gli strumenti server leggono soltanto: pagine pubbliche, indici di ricerca, i nostri mirror e i file che alleghi. Nessuno esegue scansioni, sonda o invia payload a un target. L'agente CLI è l'unica parte che esegue comandi, sulla tua macchina e con la tua approvazione.

## Quando la chat offre ogni strumento

| Strumento | Offerto quando |
|---|---|
| `web_search`, `read_url` | **Web** è attivo |
| `darkweb_search` | **Web** è attivo e il messaggio lo chiede esplicitamente |
| `cve_lookup`, `cve_search`, `advisory_lookup` | **CVE** è attivo |
| `kb_search`, `kb_read` | Sempre. Non c'è un interruttore |
| `file_list`, `file_read`, `file_search`, `binary_info`, `archive_list`, `disassemble` | C'è un file allegato |

Un'esecuzione si ferma a 12 passi del modello, 5 chiamate agli strumenti alla volta, 60 secondi per strumento e 10 minuti in totale. I risultati entrano nella conversazione e sono fatturati come token di input al prezzo del modello.

## Ricerca web

`web_search(query, count?)` accetta una ricerca fino a 400 caratteri e restituisce titoli, URL ed estratti di pagina, 5 risultati di default e massimo 10. I risultati di NVD, cve.org, CISA, GitHub, Seclists, PortSwigger e OWASP vengono prima, e le ricerche identiche restano in cache per 15 minuti. Un risultato può essere sbagliato o vecchio, quindi apri la fonte prima di fidarti.

## Lettura di una pagina

`read_url(url)` restituisce il testo di una pagina pubblica. In chat apre solo URL che hai scritto o che arrivano da un risultato di ricerca, CVE, advisory o knowledge base. I link dentro una pagina e i risultati `.onion` non si possono aprire.

Accetta http(s) sulle porte 80 e 443 e HTML, testo, JSON o XML, fino a 10 MB e 15 secondi. Ogni indirizzo e redirect viene controllato, la connessione resta fissata all'IP controllato e `robots.txt` viene rispettato. Rifiuta IP letterali, stringhe di attacco, percorsi di file esposti come `/.git` e `/.env`, e più di 40 percorsi distinti su un host in 10 minuti. Viene rifiutata anche una URL che contiene testo di un file allegato.

## Ricerca nel dark web

`darkweb_search(query, max_results?, engines?)` accetta una ricerca fino a 200 caratteri e restituisce fino a 30 voci. Ometti `engines` per usare tutti gli indici.

La chat offre questo strumento solo quando lo chiedi esplicitamente. Il messaggio deve contenere dark web, deep web, darknet, `.onion`, onion site, hidden service o Tor, oppure essere il seguito diretto di un turno che li conteneva. Nominare un gruppo ransomware o un leak non basta, e quelle domande vanno a `web_search`. Con **Web** spento, lo strumento resta spento.

Ogni risultato è una voce di indice di ricerca: titolo, URL `.onion`, estratto e indice di provenienza. L'harness legge le pagine dei risultati degli indici via Tor e non apre, non scansiona e non scarica mai una pagina elencata. Tratta ogni voce come una pista non verificata e potenzialmente ostile.

Il limite è di 5 ricerche al minuto per utente. I risultati sponsorizzati vengono scartati. Un filtro di sicurezza rifiuta le ricerche e scarta i risultati su materiale di abuso sessuale su minori. Senza un percorso Tor lo strumento lo segnala e può usare un indice sul web aperto.

Via MCP, chiamare `darkweb_search` è già la richiesta esplicita. La Research API e la CLI non hanno un percorso per il dark web.

## Dati CVE

`cve_lookup(id)` restituisce un record consolidato: descrizione NVD, punteggio e vettore CVSS 3.1 o 4.0, CWE, CPE interessati con versione corretta quando NVD la riporta, riferimenti, punteggio e percentile EPSS, e stato CISA KEV con data di inserimento e uso noto in ransomware. Ogni fonte mostra quando è stata recuperata. Una CVE senza CVSS risulta non valutata e nulla viene stimato. Un ID che il mirror non ha viene chiesto alle fonti una volta.

`cve_search(query?, vendor?, kev?, min_cvss?, min_epss?)` restituisce fino a 20 risultati ordinati per corrispondenza del testo ed EPSS. Interroga NVD per parola chiave solo quando il mirror non trova nulla.

## Advisory dei pacchetti

`advisory_lookup(name, ecosystem, version?)` restituisce vulnerabilità note da OSV, fino a 50. Riporta ciò che OSV elenca per quel nome e quella versione. Dimostrare che il codice vulnerabile è raggiungibile nella tua build resta a te. Via MCP lo strumento si chiama `advisory_query`.

## Knowledge base

`kb_search(query, domain?, source?, tool?)` cerca nella [knowledge base](/it/chat/knowledge-base) curata e `kb_read(id, from?, limit?)` apre un documento sezione per sezione. I domini sono `web`, `api`, `mobile`, `offensive`, `tools`, `cloud`, `ir` e `attack`. Ogni risultato riporta fonte, licenza e attribuzione. Una tecnica di nicchia può mancare, e il passo successivo è la ricerca web.

## File

Gli strumenti sui file leggono ciò che il parser statico ha estratto da un allegato. Nulla di ciò che carichi viene eseguito, e non c'è analisi dinamica. Ogni file viene analizzato in un container gVisor usa e getta, senza rete, con root in sola lettura e senza segreti. Un file oltre i limiti o un errore del parser finiscono come `rejected`, con il motivo.

| Strumento | Restituisce |
|---|---|
| `file_list` | File allegati con stato, tipo, dimensione e avvisi |
| `file_read(file_id, from?, limit?)` | Testo estratto a blocchi, con localizzatore di file e riga |
| `file_search(query)` | Blocchi che contengono le tue parole, in tutti gli allegati |
| `binary_info(file_id)` | SHA-256, dimensione, entropia e, per ELF e PE, formato, entry point, sezioni e import |
| `archive_list(file_id)` | L'indice dell'archivio |
| `disassemble(file_id)` | Un'anteprima: i primi 4 KB del file decodificati come x86-64, massimo 200 istruzioni |

Non ci sono decompiler né grafo di flusso. Gli archivi si fermano a profondità 3, 10.000 voci, 2 GB espansi e rapporto 100:1. Il testo si ferma a 5 milioni di caratteri per file. Le immagini danno solo le dimensioni. L'avviso `credentials_detected` significa che il parser ha trovato uno schema di chiave o token. I tipi di file sono in [File nella chat](/it/chat/files).

## Dove si trova ogni strumento

| Funzione | Chat | CLI | MCP | Research API |
|---|---|---|---|---|
| Ricerca web | `web_search` | agent `web_search` | `web_search` | `POST /v1/web/search` |
| Lettore di pagine | `read_url` | | `read_url` | `POST /v1/web/read` |
| Ricerca nel dark web | `darkweb_search` | | `darkweb_search` | |
| Record CVE | `cve_lookup` | `notholy cve`, agent `cve_lookup` | `cve_lookup` | `GET /v1/cve/{id}` |
| Ricerca CVE | `cve_search` | `notholy cve search` | `cve_search` | `GET /v1/cve/search` |
| Advisory dei pacchetti | `advisory_lookup` | | `advisory_query` | `POST /v1/advisories/query` |
| Knowledge base | `kb_search`, `kb_read` | `notholy kb`, agent `kb_search` | `kb_search`, `kb_read` | `GET /v1/kb/search`, `GET /v1/kb/{id}` |
| Analisi dei file | Strumenti sui file qui sopra | `notholy analyze` | `analyze_file` | `POST /v1/files` |
| File locali e comandi | | agent `read`, `grep`, `glob`, `edit`, `write`, `bash` | | |
| Scope e log di engagement | | [`notholy engage`](/it/cli/agent#engagements) | | |

`POST /v1/chat/completions`, `/v1/responses` e `/v1/messages` sono gli endpoint grezzi dei modelli e non hanno strumenti dell'harness. Il modello riceve solo le function tool che invii, e le esegue il tuo codice. Per usare questi dati dal tuo codice, chiama la [Research API](/it/api/research) o [MCP](/it/mcp/local).

## Prossimi passi

- [Agente da terminale](/it/cli/agent)
- [Research API](/it/api/research)