OIHK-pentesting

A multi-agent engine for authorized security assessments. A root planner delegates to recon, discovery, attack (OPTIZero), validation, and reporting agents — and the engine itself enforces scope, egress, evidence, and resource policy no matter which model drives it. Findings require real execution evidence plus independent validation; a convincing story proves nothing.

It scores against its own vulnerable-scenario benchmark — the deterministic mock solver holds 24/24 at 100/100 — and runs fully offline against any OpenAI-compatible local model.

Early beta, under active development. Behavior can change without notice; some capabilities are partial or deliberately left out. Verify before you rely on it — see the status matrix.

Table of contents

• Why OIHK
• Requirements
• Quick start
• Local inference
• Architecture
• AI agent evaluation
• Repository layout
• Documentation
• Legal
• License

Why OIHK

Most offensive tooling trusts the model's good behavior. OIHK doesn't: the safety boundary lives in the engine and holds regardless of what the model is willing to say.

• Evidence-gated findings. A finding needs a real, owned, successful governed tool execution plus a separate validation record — and only a validation agent can create one.
• Exact scope, no drift. Declaring example.com does not authorize its subdomains; declared hosts are DNS-pinned for the whole run.
• Egress fails closed. The scope compiles into a netfilter allowlist inside the sandbox's own network namespace; where that can't be guaranteed, startup aborts instead of pretending to isolate.
• A governed tool surface. Passive mode exposes a reduced surface and rejects active execution — including attempts routed through the generic shell.
• A model-agnostic core. Any OpenAI-compatible endpoint, per-role routing, nothing hardcoded to a provider — the same harness scores any model.

Requirements

Quick start

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

On Kali Linux, make sure Docker is running first (sudo systemctl start docker).

Or open Baron, the interactive copilot — you talk, it drives the governed engine (defaults to passive unless you authorize a deep assessment):

uv run oihk start

Baron runs real assessments, answers with exact tool recipes from a 156-tool RAG corpus, pivots through OSINT (page_osint, username_osint, domain_osint, breach_osint, phone_osint), and remembers every session in Redis. It never gets a raw shell — only the governed engine — and everything is menu-driven: /apimodel, /adaptador, and /instancia open interactive Textual pickers.

Local inference

Defaults point at LM Studio on http://localhost:1234/v1:

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

Cloud providers — /apimodel

Any of the six presets connects with one command; each remembers its own key:

/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 (no args) opens the platform picker; /apimodel <plataforma> reconnects with the saved key; /apimodel off disconnects. Any other OpenAI-compatible provider works via /models base + /models key + /models use.

Two cloud prefixes also remove all endpoint setup at the env level: deepseek/… and nvidia_build/… route to their provider APIs — set the key, nothing else. Per-role overrides (OIHK_ROOT_LLM, OIHK_RECON_LLM, …) route logical roles to different models.

Choosing a model

OIHK works best with a model that doesn't over-refuse: heavily safety-tuned assistants decline legitimate, authorized offensive steps and stall the agent mid-assessment. This doesn't lower OIHK's safety — the boundary was never the model's refusals; it's the engine's exact scope, fail-closed egress, governed tool surface, and evidence gate, which hold no matter what the model says.

Architecture

A root planner owns one revisioned ScanPlan and delegates steps to child agents. Every governed tool call clears four policy authorities — mode/role, exact scope, resource governor, sandbox egress — before executing, and its output becomes immutable evidence in the run ledger. Only a validation agent can turn that evidence into a finding; the root can't finish a run while critical work is open. Runs resume from artifacts (--resume <run-id>) and land under 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, the attack role, brings a declarative privilege-escalation vector catalog for Windows, Linux, and macOS behind an adaptive AIMD rate limiter — and the root controls the whole fleet in flight (list_children, send_message, stop_child, broadcast). Details in ARCHITECTURE.

AI agent evaluation

OIHK doubles as its own eval environment: the real engine runs against 24 bundled vulnerable scenarios — web, API, auth, source-code, configuration, and AutoPenBench-aligned privesc/crypto/CVE — and a programmatic verifier scores normalized 0–100 across finding correctness, evidence validity, tool usage, efficiency, and false-positive avoidance. No model grades itself.

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

The same harness ships as a verifiers environment on the Prime Intellect Hub (broskigx/oihk-security-agent):

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

Full scenario table, scoring formula, and benchmark mapping: EVALUATION.

Repository layout

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 your own model

scripts/build_lora_dataset.py generates a bilingual (Spanish/English) LoRA dataset — 536 samples each, 336 with real tool-calls — from the governed tool corpus and the 24 eval scenarios, including safety behaviors (scope discipline, docker gate, injection resistance). Train it against Qwen2.5-14B-Instruct, export a Q4_K_M GGUF, and serve it in Ollama or LM Studio: full pipeline in deploy/local-models.

Documentation

Legal

Authorized use only. OIHK actively tests the targets it's given. The operator is solely responsible for authorization, safe limits, target availability, data handling, and compliance with applicable law.

To report a security vulnerability in OIHK itself, see Reporting a vulnerability.

License

Released under the MIT License — free to use, modify, and distribute, including commercially, as long as the copyright notice and license text stay put.