OpenHunterAI

Your local AI red team.
Attacker-style reasoning for web, API, and LLM application security.

Quick start · Agent skill · Assessment model · Architecture · Docs · Star history

OpenHunterAI brings scope, scan activity, findings, and remediation into one local workspace. Start without an account, connect your model providers, and assess verified public applications you own or are authorized to test.

Capability	What you get
Local workspace	No signup; projects and scan records in your local database
Explicit scope	Domain verification, deterministic plans, human approval gates
Multiple signal sources	Browser inspection, recon, ZAP, and a Nuclei adapter
AI-assisted investigation	OpenHack/Strix adapter boundaries; bring your own runtimes
Evidence & remediation	Sanitized findings, coverage gaps, fix guidance, manual retest
Portable workflow	A skill for Codex, Claude Code, Gemini CLI, Grok Build, and OMP

Alpha. Integration coverage depends on configured runtimes. A healthy workspace or an empty report does not prove a target is secure.

Assessment model

OpenHunterAI keeps the useful core of the 48bf9036 technical requirements: assess externally observable behaviour from an attacker's perspective. Source code is not required. Every run stays constrained to a verified public target and an approved scope.

flowchart LR
  S["1. Lock scope"] --> M["2. Map surface"]
  M --> B["3. Establish baseline"]
  B --> H["4. Test bounded hypotheses"]
  H --> E["5. Gate evidence"]
  E --> R["6. Report and retest"]

Loading

Stage	Output	Control
Scope lock	Verified host, approved paths, scan plan	Authorization before work begins
Surface mapping	Browser and recon signals	Public, in-scope surface only
Baseline	Normal responses and coverage context	Bounded workers and adapter policies
Hypothesis testing	Candidate security signals	No destructive actions; sensitive validation needs approval
Evidence gate	Sanitized, reproducible finding	Separate observed signals from analyst judgement
Report and retest	Fix guidance, limitations, manual confirmation	A human owns impact decisions and closure

OpenAPI/Swagger descriptions, Postman examples, sanitized HTTP captures, and dedicated test accounts can help define the agreed test surface. Automated import or retention of raw sensitive traffic is not a promised capability.

Quick start

Requires Git, Node.js 22+, and Docker with Compose v2.

git clone https://github.com/LumosLab-Innovation/OpenHunterAI.git
cd OpenHunterAI
node ops/local.mjs start

Open localhost:3001. First startup builds the images, applies database migrations, and creates a private .env.local with generated secrets.

1. Set provider keys and model IDs in .env.local; run node ops/local.mjs restart.
2. Create a project and verify its public domain.
3. Authorize the scope, start a scan, and review its activity and coverage.

Command	Purpose
node ops/local.mjs status	Inspect services
node ops/local.mjs logs public-api	Diagnose API errors
node ops/local.mjs stop	Stop; keep database volumes

Included: browser inspection, ZAP, recon, and the Nuclei adapter. Bring separately: OpenHack and Strix runtimes. Optional interactive target-login capture: node ops/local.mjs start --with-browser.

Before scanning, resolve the Nuclei template-policy blocker. The adapter is packaged, but a reviewed template bundle is not yet supplied.

Local means the workspace runs on your machine, not permission to scan localhost/private networks. Keep its ports on loopback. Setup, model configuration, and troubleshooting →

Coding-agent skill

Run in the application repository you want your agent to assess:

npx --yes skills add LumosLab-Innovation/OpenHunterAI --skill openhunter --agent codex claude-code gemini-cli grok --yes

Reload your coding agent, then ask:

Use OpenHunter to check my workspace and prepare a scoped security assessment. Wait for my approval before starting a scan.

OMP discovers the shared .agents/skills installation through its Agents provider. The skill includes a read-only API helper; installation does not start a scan. Client compatibility →

Architecture

flowchart LR
  UI["Local workspace<br/>React + Vite"] --> API["Public API<br/>Scope + scan plan"]
  API --> BUS["NATS<br/>Orchestrator + workers"]
  BUS --> EVIDENCE["Internal API<br/>Findings + reporting"]
  EVIDENCE --> DB[("Postgres")]
  API <--> DB
  API -->|"Activity + reports"| UI

Loading

The public API builds the plan; Go workers execute it through bounded adapters. Signals pass through the findings policy before entering reports. Reporting is a backend service, not a separate scan worker.

Runtime & data flow · Worker mapping · Integration setup

Documentation

Start here	Go deeper
Local setup	Architecture & data model
Product overview	Product requirements
Agent workflow	LLM routing
Security guardrails	Acceptance & release gates

All documentation · Known limitations · Historical technical specification

Community & license

Report a bug, suggest an improvement, or help clarify the docs. Read contribution rules first; disclose vulnerabilities privately, without credentials or raw target data.

Source-available under PolyForm Noncommercial 1.0.0. Commercial licensing: LICENSING.md. Upstream tools and attribution retain their own notices.

Star history