OIHK-pentesting

Un motore multi-agente per valutazioni di sicurezza autorizzate. Un planner root delega a agenti di recon, discovery, attack (OPTIZero), validation e reporting — e il motore stesso applica scope, egress, evidenze e policy sulle risorse indipendentemente da quale modello lo guidi. I finding richiedono evidenze di esecuzione reali più una validazione indipendente; una storia convincente non prova nulla.

Si valuta rispetto al proprio benchmark di scenari vulnerabili — il solver mock deterministico mantiene 24/24 a 100/100 — e funziona completamente offline con qualsiasi modello locale compatibile con OpenAI.

Beta iniziale, in sviluppo attivo. Il comportamento può cambiare senza preavviso; alcune funzionalità sono parziali o volutamente escluse. Verifica prima di farci affidamento — vedi la matrice di stato.

Indice

• Perché OIHK
• Requisiti
• Avvio rapido
• Inferenza locale
• Architettura
• Valutazione degli agenti AI
• Struttura del repository
• Documentazione
• Aspetti legali
• Licenza

Perché OIHK

La maggior parte degli strumenti offensivi si affida al buon comportamento del modello. OIHK no: il confine di sicurezza risiede nel motore e regge indipendentemente da ciò che il modello è disposto a dire.

• Finding vincolati alle evidenze. Un finding richiede un'esecuzione reale, autorizzata e riuscita di uno strumento governato, più un record di validazione separato — e solo un agente di validazione può crearne uno.
• Scope esatto, nessuna deriva. Dichiarare example.com non autorizza i suoi sottodomini; gli host dichiarati sono DNS-pinned per l'intera esecuzione.
• Egress fail closed. Lo scope viene compilato in una allowlist netfilter all'interno del network namespace della sandbox stessa; dove ciò non può essere garantito, l'avvio si interrompe invece di fingere di isolare.
• Una superficie di strumenti governata. La modalità passiva espone una superficie ridotta e rifiuta l'esecuzione attiva — inclusi i tentativi instradati attraverso la shell generica.
• Un core agnostico rispetto al modello. Qualsiasi endpoint compatibile con OpenAI, routing per ruolo, nulla hardcoded su un provider — lo stesso harness valuta qualsiasi modello.

Requisiti

Avvio rapido

git clone https://github.com/Broskigx/Oihk-pentesting.git
cd Oihk-pentesting
uv sync
uv run oihk --help
uv run oihk run -t https://example.test --mode passive --scan-mode standard

Su Kali Linux, assicurati che Docker sia in esecuzione prima (sudo systemctl start docker).

Oppure apri Baron, il copilot interattivo — tu parli, lui guida il motore governato (per impostazione predefinita in modalità passiva, a meno che tu non autorizzi una valutazione approfondita):

uv run oihk start

Baron esegue valutazioni reali, risponde con ricette di strumenti esatte da un corpus RAG di 156 strumenti, fa pivot attraverso l'OSINT (page_osint, username_osint, domain_osint, breach_osint, phone_osint) e ricorda ogni sessione in Redis. Non ottiene mai una shell grezza — solo il motore governato — e tutto è guidato da menu: /apimodel, /adaptador e /instancia aprono selettori interattivi Textual.

Inferenza locale

Le impostazioni predefinite puntano a LM Studio su http://localhost:1234/v1:

export OIHK_LLM="openai/mistral-nemo"
export OIHK_API_BASE="http://localhost:1234/v1"
export OIHK_API_KEY="lm-studio"

Provider cloud — /apimodel

Ognuno dei sei preset si connette con un solo comando; ciascuno ricorda la propria chiave:

/apimodel claude sk-ant-…          # Anthropic
/apimodel chatgpt sk-…             # OpenAI
/apimodel gemini AIza…             # Google AI Studio
/apimodel grok xai-…               # xAI
/apimodel deepseek sk-…            # DeepSeek
/apimodel nvidia nvapi-… [model]   # NVIDIA NIM

/apimodel (senza argomenti) apre il selettore della piattaforma; /apimodel <plataforma> si riconnette con la chiave salvata; /apimodel off disconnette. Qualsiasi altro provider compatibile con OpenAI funziona tramite /models base + /models key + /models use.

Due prefissi cloud eliminano anche tutta la configurazione dell'endpoint a livello di env: deepseek/… e nvidia_build/… instradano verso le rispettive API del provider — imposta la chiave, nient'altro. Gli override per ruolo (OIHK_ROOT_LLM, OIHK_RECON_LLM, …) instradano i ruoli logici verso modelli diversi.

Scegliere un modello

OIHK funziona meglio con un modello che non rifiuta troppo: gli assistenti fortemente orientati alla sicurezza declinano passaggi offensivi legittimi e autorizzati e bloccano l'agente a metà valutazione. Questo non riduce la sicurezza di OIHK — il confine non è mai stato nei rifiuti del modello; è nello scope esatto del motore, nell'egress fail-closed, nella superficie di strumenti governata e nel gate delle evidenze, che reggono indipendentemente da ciò che dice il modello.

Architettura

Un planner root possiede un unico ScanPlan revisionato e delega i passaggi agli agenti figli. Ogni chiamata a uno strumento governato supera quattro autorità di policy — modalità/ruolo, scope esatto, resource governor, egress della sandbox — prima di essere eseguita, e il suo output diventa evidenza immutabile nel ledger dell'esecuzione. Solo un agente di validazione può trasformare quell'evidenza in un finding; il root non può concludere un'esecuzione mentre del lavoro critico è aperto. Le esecuzioni riprendono dagli artefatti (--resume <run-id>) e finiscono sotto oihk_runs/<run-id>/ (plan, evidence, validations, findings, SARIF, report).

flowchart TB
    OP([Operator: scope + mode]) --> ROOT[Root planner]
    ROOT --> RECON[Recon]
    ROOT --> DISC[Discovery]
    ROOT --> ATTACK[Attack - OPTIZero]
    ROOT --> VALID[Validation]
    ROOT --> REPORT[Reporting]

    RECON --> GATE
    DISC --> GATE
    ATTACK --> GATE
    VALID --> GATE

    subgraph GATE[Policy authorities - fail closed]
        direction LR
        M[Mode / role] --> S[Exact scope] --> G[Resource governor] --> BOX[Sandbox: egress allowlist]
    end

    GATE --> LEDGER[(Evidence ledger)]
    LEDGER --> VALID
    VALID --> FIND[Findings + SARIF report]
</mermaid>

OPTIZero, il ruolo attack, porta un catalogo dichiarativo di vettori di privilege-escalation per Windows, Linux e macOS dietro un rate limiter adattivo AIMD — e il root controlla l'intera flotta in volo (list_children, send_message, stop_child, broadcast). Dettagli in ARCHITECTURE.

Valutazione degli agenti AI

OIHK funge anche da proprio ambiente di eval: il motore reale gira contro 24 scenari vulnerabili inclusi — web, API, auth, codice sorgente, configurazione e privesc/crypto/CVE allineati ad AutoPenBench — e un verificatore programmatico assegna un punteggio normalizzato 0–100 su correttezza dei finding, validità delle evidenze, uso degli strumenti, efficienza e capacità di evitare falsi positivi. Nessun modello si autovaluta.

uv run oihk eval list
uv run oihk eval run-all --model mock
uv run oihk eval compare --models mock,mock:wrong_finding

Lo stesso harness è distribuito come ambiente verifiers sul Prime Intellect Hub (broskigx/oihk-security-agent):

prime env install broskigx/oihk-security-agent
vf-eval oihk-security-agent -m mock

Tabella completa degli scenari, formula di scoring e mappatura del benchmark: EVALUATION.

Struttura del repository

oihk/          CLI, policy/governance, agents, tools, sandbox, findings
oihk/evals/    evaluation subsystem (scenarios, verifier, scoring, mock provider)
environments/  standalone verifiers environment package (Prime Intellect Hub)
containers/    sandbox image, entry point, browser driver, SBOM generation
deploy/        local-model LoRA pipeline: dataset trainer, Ollama Modelfiles
docs/          architecture, security boundary, configuration, evaluation
tests/         unit, regression, and opt-in integration tests
ToolsHelp/     RAG corpus: 156 governed-tool cards
skills/        external-agent skill packs

Fine-tuning del tuo modello

scripts/build_lora_dataset.py genera un dataset LoRA bilingue (spagnolo/inglese) — 536 campioni ciascuno, 336 con tool-call reali — dal corpus di strumenti governati e dai 24 scenari di eval, inclusi comportamenti di sicurezza (disciplina dello scope, docker gate, resistenza all'injection). Addestralo su Qwen2.5-14B-Instruct, esporta un GGUF Q4_K_M e servilo in Ollama o LM Studio: pipeline completa in deploy/local-models.

Documentazione

Aspetti legali

Solo uso autorizzato. OIHK testa attivamente i target che gli vengono forniti. L'operatore è l'unico responsabile dell'autorizzazione, dei limiti di sicurezza, della disponibilità dei target, della gestione dei dati e della conformità alle leggi applicabili.

Per segnalare una vulnerabilità di sicurezza in OIHK stesso, vedi Segnalazione di una vulnerabilità.

Licenza

Rilasciato sotto la MIT License — libero di usare, modificare e distribuire, anche commercialmente, purché la nota di copyright e il testo della licenza rimangano invariati.