From 93531d845e1c7d6c50d9cef19dc9d131db14e5e3 Mon Sep 17 00:00:00 2001 From: HungBil Date: Tue, 8 Sep 2026 00:50:28 +0700 Subject: [PATCH] docs: add public repository community profile --- .github/ISSUE_TEMPLATE/bug_report.yml | 34 ++ .github/ISSUE_TEMPLATE/config.yml | 5 + .github/ISSUE_TEMPLATE/feature_request.yml | 26 ++ .github/pull_request_template.md | 14 + CODE_OF_CONDUCT.md | 12 + CONTRIBUTING.md | 21 ++ README.md | 396 ++++++--------------- SECURITY.md | 21 ++ 8 files changed, 245 insertions(+), 284 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..52fcc9af --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,34 @@ +name: Bug report +description: Report a reproducible, non-sensitive defect in OpenHunterAI. +title: "[Bug]: " +labels: [needs-triage] +body: + - type: markdown + attributes: + value: | + Do not include target data, credentials, tokens, cookies, HAR, raw traffic, or exploit payloads. Use private security reporting for vulnerabilities. + - type: textarea + id: summary + attributes: + label: What happened? + description: Explain the observed behavior and the expected behavior. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Safe reproduction + description: List minimal, sanitized steps that reproduce the issue. + placeholder: "1. Start local stack\n2. ..." + validations: + required: true + - type: input + id: revision + attributes: + label: Revision + description: Commit SHA, release tag, or local branch. + - type: textarea + id: context + attributes: + label: Environment and sanitized logs + description: OS, browser, runtime versions, and sanitized errors only. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..5677dbd0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Private vulnerability report + url: https://github.com/LumosLab-Innovation/OpenHunterAI/security/advisories/new + about: Do not disclose vulnerabilities or sensitive evidence in public issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..8aa13de1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,26 @@ +name: Feature request +description: Propose an improvement consistent with the authorized-testing scope. +title: "[Feature]: " +labels: [needs-triage] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What user problem would this solve? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed behavior + description: Describe the smallest behavior that would solve the problem. + validations: + required: true + - type: checkboxes + id: scope + attributes: + label: Scope check + options: + - label: This does not require private-network scanning, unrestricted offensive behavior, destructive testing, or CI/CD-triggered retests. + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..2c6b665b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,14 @@ +## Summary + +Describe the smallest user-visible or technical change. + +## Verification + +- [ ] Targeted tests or checks were run. +- [ ] Documentation reflects behavior changes. +- [ ] No raw credentials, cookies, tokens, HAR, sensitive traffic, or target data were added. + +## Security and scope + +- [ ] This preserves verified scope, authorization, sanitization, timeout, and approval controls. +- [ ] This does not add private/internal scanning, destructive testing, credential stuffing, malware, persistence, or CI/CD-triggered retests. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..fc9aeb9d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,12 @@ +# Code of Conduct + +OpenHunterAI adopts the [Contributor Covenant Code of Conduct, version +2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). + +Participation must remain respectful, constructive, and free from harassment. +Maintainers may remove or reject conduct, content, or contributions that harm +the community or conflict with this standard. + +Report conduct concerns privately through the repository owner's GitHub profile: +. Reports will be handled respectfully and with +appropriate confidentiality. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c0ceef10 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing + +Issues for reproducible defects, documentation corrections, and product +feedback are welcome. Use the templates and remove all target data, +credentials, tokens, cookies, HAR, raw request/response content, and +vulnerability payloads before submitting. + +Source contributions are temporarily paused while HungBil finalizes the +contributor license agreement required for community contributions and future +commercial licensing. Please open an issue before preparing a pull request. + +This repository's security scope and product limits are mandatory: + +- Do not weaken verification, scope, evidence sanitization, or approval gates. +- Do not add private/internal scanning, destructive testing, credential + stuffing, malware, persistence, or CI/CD-triggered retests. +- Keep tests targeted and update the governing documentation when behavior + changes. + +See [SECURITY.md](SECURITY.md) for private vulnerability reporting and +[LICENSING.md](LICENSING.md) for license boundaries. diff --git a/README.md b/README.md index e0182a9e..f4947d06 100644 --- a/README.md +++ b/README.md @@ -1,310 +1,138 @@ -# OpenHunterAI — Technical Requirements +

+ + OpenHunterAI logo + +

-Technical requirements for OpenHunterAI's black-box pentest workflow and MVP architecture. +

OpenHunterAI

-> Release status: this document mixes implemented features with proposed tools. -> The running stack is React/Vite, Express/TypeScript, Go, Postgres and NATS; -> the technology catalogue below is not a ready-to-use capability guarantee. -> See [public release gates](docs/PUBLIC_RELEASE_READINESS.md), -> [current architecture](docs/ARCHITECTURE.md) and -> [mandatory security guardrails](docs/SECURITY_GUARDRAILS.md). -> Raw credentials, HAR and sensitive request/response data are not report artifacts. +

+ A governed workspace for authorized external web and application security testing. +

-## License - -OpenHunterAI is source-available under the [PolyForm Noncommercial License -1.0.0](LICENSE). Commercial use requires a separate written license from -HungBil. See [LICENSING.md](LICENSING.md). - -## 1. Technical Scope - -- **Model**: AI Agentic Workflow — AI orchestrates, analyzes context, and chooses actions; open-source tools handle recon, crawling, request sending, OAST, and known-vulnerability checks. -- **External black-box testing only.** Does not require: source code, database schema, internal architecture, internal data flow, internal permission matrix, or backend logs/access. -- **Valid inputs**: in-scope domain/subdomain/IP, test accounts, an authorized OpenAPI/Swagger spec, Postman Collection, HAR file, sample cURL, requests captured from a browser or Burp Suite. -- If URD, SRS, source code, or internal architecture docs are used, the project must be labeled `document-assisted black-box` or `grey-box` — it is no longer pure black-box. - -## 2. Black-box Pentest Workflow (9 Steps) - -### Step 1 — Project Initialization & Scope Lock -**Input**: domain/subdomain/IP, environment (Production/Staging/UAT), test accounts per role, allowed test window, request limits, exclusion list. -**Prohibited actions**: DoS/stress testing, deleting or modifying real data, uploading malware, creating real transactions, sending bulk email/SMS, accessing systems outside scope. -OpenHunterAI normalizes scope and validates scope before every request. - -| Activity | Tooling | -|---|---| -| Project/scope management | OpenHunterAI-native module | -| Allowlist URL check | Custom Scope Validator | -| Guardrail definition | Open Policy Agent (OPA) or JSON-based Policy Engine | -| Project config storage | PostgreSQL or SQLite (local MVP) | -| Secret management | HashiCorp Vault, SOPS, or encrypted local storage | -| Emergency stop | Custom Kill Switch | - -**Output**: `scope.json`, `exclusions.json`, rules of engagement, rate-limit policy, list of auth-support-only endpoints (not to be pentested). - -### Step 2 — Seed Data Ingestion & Normalization -**Input**: OpenAPI/Swagger, Postman Collection, HAR file, cURL, Burp Proxy history, test accounts, login/token-acquisition cURL, Interactsh/Burp Collaborator domain, seed URLs. -**Extracted**: endpoints, HTTP methods, query/path parameters, headers, cookies, request bodies, content types, authentication mechanism, valid request examples. -In black-box mode, role requirements, ownership, and business rules are only tagged `Observed`, `Inferred`, or `Unconfirmed` — never treated as an official spec. - -| Format | Tooling | -|---|---| -| OpenAPI/Swagger | Swagger Parser, openapi-spec-validator, Prance | -| Postman Collection | Postman Collection SDK | -| cURL | curlconverter or a custom cURL parser | -| HAR | Playwright HAR parser or haralyzer | -| Burp traffic | Burp XML parser or custom HTTP parser | -| JSON/YAML | PyYAML, Pydantic | -| Request normalization | Custom Request Normalizer | - -**Output**: `seed_requests.json`, `endpoints.json`, `parameters.json`, `auth_profiles.json`. - -### Step 3 — External Recon -Subdomain enumeration, DNS resolution, HTTP probing, port/service discovery, TLS inspection, technology fingerprinting, WAF/CDN detection, public JavaScript discovery, source map discovery, public API doc discovery, common file/endpoint discovery, exposed admin/debug interfaces, public secret/credential exposure. -Newly discovered assets are **not auto-added to scope** — tagged `Discovered – Pending Scope Approval`. - -| Activity | Tooling | -|---|---| -| Subdomain enumeration | Subfinder | -| DNS resolution | dnsx | -| HTTP probing | ProjectDiscovery httpx | -| Port discovery | Naabu | -| Service fingerprinting | Nmap | -| Public URL crawl | Katana | -| Historical URLs | gau, waybackurls | -| Technology detection | Wappalyzer, WhatWeb, ProjectDiscovery httpx | -| WAF detection | wafw00f | -| TLS inspection | testssl.sh or tlsx | -| Secrets in public JavaScript | TruffleHog, Gitleaks (public-file scope) | -| Known exposure templates | Nuclei | - -**Output**: `assets.json`, `services.json`, `technologies.json`, `discovered_out_of_scope.json`. - -### Step 4 — Browser Crawl & Application Mapping -A real browser simulates a user: login with test account, click links/menus/buttons, submit forms, follow redirects, record cookies/browser storage, capture network traffic, detect client-side routes, collect API calls, detect WebSocket/GraphQL, link page↔action↔API request, capture screenshots as evidence. -AI infers functionality: registration, login, password reset, profile, upload/download, payment, coupons, member invites, approvals, role management, state changes, export/import. - -| Activity | Tooling | -|---|---| -| Browser automation | Playwright | -| Browser network interception | Playwright CDP | -| HAR recording | Playwright HAR | -| Static crawling | Katana | -| JavaScript parsing | Tree-sitter, Babel Parser, or Esprima | -| Endpoint extraction from JS | LinkFinder or a custom JavaScript Analyzer | -| Screenshots | Playwright Screenshot API | -| DOM parsing | BeautifulSoup, lxml | -| Application graph | NetworkX or Neo4j | - -**Output**: `pages.json`, `browser_routes.json`, `network_requests.json`, `application_map.json`, `observed_workflows.json`, `screenshots/`. +

+ CI + PolyForm Noncommercial 1.0.0 + Latest release + GitHub stars +

-### Step 5 — Baseline & Test Plan Generation -Valid requests are sent to build a baseline: status code, response headers/body/length/time, redirect behavior, cookie changes, authentication state, error patterns. -AI then determines: which parameters to test, payloads appropriate to datatype/context, whether auth is required, likelihood the request mutates data, success/failure signals, risk level, and whether human approval is required. +> **Status: alpha.** This repository is public for inspection, noncommercial +> use, and feedback. It is not a claim of production readiness or a guarantee +> that any target has been scanned successfully. -**Test case classification**: `Safe` (auto-run) / `Controlled` (rate-limited, restricted payloads) / `Manual Approval` (requires user approval click) / `Manual Only` (guidance for the pentester only). +[Product guide](https://lumoslab-innovation.github.io/openhunterai-site/) · +[Documentation](docs/) · [Security policy](SECURITY.md) · +[Commercial licensing](LICENSING.md) -| Activity | Tooling | -|---|---| -| Baseline requests | Python HTTPX | -| JSON comparison | DeepDiff | -| HTML/text comparison | difflib, SimHash, or a custom normalized diff | -| Timing analysis | Python `statistics` module | -| Test plan generation | LLM Agent + Rule Engine | -| Risk classification | Custom Guardrail Engine | -| Workflow/state graph | NetworkX or Neo4j | +## What it is -**Output**: `baselines.json`, `test_plan.json`, `approval_queue.json`. +OpenHunterAI helps an authorized owner inspect a **verified public** web or +application target. It builds a deterministic plan before execution, records +sanitized activity as it runs, separates signals from validated findings, and +produces a report with coverage and limitations. -### Step 6 — Automated Test Execution +It is designed to make the decision trail inspectable: -**Core API testing**: the AI Agent mutates each request component — query, path, header, cookie, JSON body, form data, multipart field, GraphQL variable. AI may adapt strategy based on responses but may only use payloads within the approved risk level. - -| Activity | Tooling | -|---|---| -| Send HTTP requests | Python HTTPX | -| Async request execution | asyncio + HTTPX | -| Run sample cURL | cURL subprocess in a sandbox | -| Parameter mutation | Custom Mutation Engine | -| Payload library | PayloadsAllTheThings + in-house library | -| Encoding | Python urllib, base64, custom encoders | -| GraphQL | graphql-core or InQL | -| WebSocket | Python websockets | -| Replay browser requests | Playwright or HTTPX | - -**Known CVE / baseline scanning**: Nuclei covers known CVEs, common misconfigurations, exposed panels, default files, security headers, and technology-specific checks. Nuclei output is a signal source only — never auto-treated as a confirmed finding. - -**Blind / out-of-band testing**: SSRF, XXE, blind command injection, and blind template injection payloads carry a dedicated callback identifier (Interactsh self-hosted, Interactsh client, or a user-supplied Burp Collaborator domain). Every payload must carry a correlation ID linking the callback back to the originating request. - -### Step 7 — Authentication & Token Rotation -Per-account session management: cookie, access token, refresh token, CSRF token, login state, token expiry, observed role. -On HTTP 401: determine whether the request requires auth → run the configured cURL/login workflow → extract the new token → update headers/cookies → resend the request → log the rotation history. Repeated failure escalates to `manual intervention`. - -| Activity | Tooling | -|---|---| -| Browser-based login | Playwright | -| API-based login | Python HTTPX or cURL | -| JSON token extraction | JSONPath-ng, JMESPath, or jq | -| Regex token extraction | Python `re` | -| Cookie jar | HTTPX Cookies | -| JWT inspection | PyJWT | -| Secret storage | HashiCorp Vault or encrypted storage | -| Cross-role replay | Custom Auth Replay Engine | - -Auth endpoints may be tagged `support-only` — callable to maintain a session, but never fuzzed. - -### Step 8 — AI Analysis & Manual Approval -Mutated requests are compared against baseline: status code, response length/structure/timing, headers, cookies, redirects, data reflected in the response, OAST callbacks, browser rendering, state changes. - -**Result classification**: `Confirmed finding` / `Potential finding` / `Inconclusive` / `False positive` / `Test failed` / `Out of scope` / `Manual verification required`. -**A vulnerability must never be concluded solely because of**: HTTP 500, a longer/shorter response, a timeout, a WAF block, a status code change, or an error message containing SQL keywords. - -**Manual approval is mandatory for**: password change, email change, role change, accessing another user's data, payment/refund execution, bulk object creation, sending email/SMS, mass assignment into sensitive fields, race conditions with data-mutating potential, and account-takeover chains. -The dashboard displays: original request, planned request, payload, potential impact, rollback method, Approve/Reject buttons. - -| Activity | Tooling | -|---|---| -| Response comparison | DeepDiff + custom Semantic Diff | -| AI reasoning | LLM Agent | -| Finding dedupe | Embedding similarity + rule-based fingerprint | -| Confidence scoring | Custom scoring engine | -| OAST correlation | Interactsh correlation ID | -| Approval workflow | Custom Dashboard | -| Race-condition probing | asyncio + HTTPX or Turbo Intruder integration | -| IDOR/BOLA replay | Custom Identifier Mutation Engine | - -### Step 9 — Reporting, Retest & Remediation -**Generated**: raw request/response, payload, OAST evidence, screenshot, execution log, finding confidence, reproduction steps, limitations of the conclusion, manual verification guidance, remediation recommendation, retest request. +```text +verified scope + authorization + -> deterministic scan plan + -> Browser / R / Z / N / O / S stages + -> evidence-gated finding policy + -> sanitized report_v1 + manual retest +``` -| Activity | Tooling | -|---|---| -| Report template | Jinja2 | -| HTML report | Jinja2 + HTML/CSS | -| PDF report | WeasyPrint | -| Markdown report | Custom Markdown Generator | -| Raw JSON/JSONL | Python JSON serializer | -| CVSS | `cvss` Python package | -| CWE/OWASP mapping | Local mapping database | -| Retest | OpenHunterAI Execution Engine | -| Evidence storage | MinIO or local object storage | +The public labels above are compact workflow labels. Tool and upstream +attribution remains in the documentation and bundled notices. -**Remediation limits in black-box mode**: without source code, OpenHunterAI cannot guarantee a patch targets the right file/function/dependency, is directly mergeable, or preserves business logic. It only provides: root-cause hypothesis, remediation guidance, framework-specific code examples, validation patterns, and test cases for the developer to confirm the fix. Every code snippet must be labeled `Illustrative remediation example – requires developer review`. +## Why it is governed -## 3. Automation Matrix +- **No authorization, no scan.** Domains must be verified, scope must be + explicit, and redirects outside that scope are blocked. +- **A signal is not a vulnerability.** Passive observations and candidates do + not become findings without sanitized, evidence-backed validation. +- **Human control remains in the loop.** Sensitive or potentially mutating + actions require an approval decision; manual login and retest are not + bypassed. +- **Sensitive data is deliberately excluded.** Raw passwords, tokens, cookies, + browser storage, HAR, and sensitive request/response bodies must not enter + logs, prompts, reports, or exports. -| Level | Category | Primary Tooling | OpenHunterAI Handles | User Handles | -|---|---|---|---|---| -| Highly automated | Subdomain/asset discovery | Subfinder, dnsx, httpx | Collect and normalize assets | Confirm assets are in scope | -| Highly automated | Port/service discovery | Naabu, Nmap | Discover services within limits | Confirm testing is authorized | -| Highly automated | Static crawling | Katana | Collect URLs/endpoints | Provide seed URLs | -| Highly automated | Browser crawling | Playwright | Login, click, capture network traffic | Provide test account | -| Highly automated | API input mapping | OpenAPI parser, Postman SDK | Extract requests/parameters | Provide authorized documentation | -| Highly automated | Baseline comparison | HTTPX, DeepDiff | Compare responses | Review evidence | -| Highly automated | Security headers/CORS | HTTPX, Nuclei | Check configuration | Confirm business requirements | -| Highly automated | Known CVE/exposure | Nuclei | Run restricted templates | Verify critical findings | -| Highly automated | SSRF/OAST probing | Interactsh | Generate payloads, correlate callbacks | Confirm impact | -| Highly automated | Token rotation | Playwright, HTTPX, JSONPath | Refresh on 401 | Provide login workflow | -| Semi-automated | SQLi/NoSQLi/SSTI | HTTPX, custom mutation | Generate probes, analyze responses | Confirm exploitability | -| Semi-automated | IDOR/BOLA | Custom ID mutation | Swap IDs, replay across accounts, compare | Confirm ownership/impact | -| Semi-automated | Role authorization | Auth Replay Engine | Replay requests across accounts | Determine valid permissions | -| Semi-automated | Stored XSS | Playwright, Interactsh | Inject payload, re-crawl | Confirm render context | -| Semi-automated | File upload | HTTPX, Playwright | Test MIME/extension/access | Confirm exploit chain | -| Semi-automated | Race condition | asyncio/HTTPX, Turbo Intruder | Send bounded concurrent requests | Confirm state/impact | -| Semi-automated | Password reset | HTTPX, Playwright | Check replay/expiry | Confirm account takeover | -| Semi-automated | Business logic | AI Agent | Detect anomalies, propose tests | Design/confirm exploit | -| Manual | Payment/coupon/refund abuse | Evidence + workflow map | Prepare request/hypothesis | Approve and execute | -| Manual | Multi-step account takeover | AI Test Plan | Propose test chains | Pentester verifies | -| Manual | Final severity | CVSS helper | Propose initial technical rating | Decide business impact | +## What it does not do -Never claim "100% automated" for injection, authorization, or business-logic categories. Tooling can automate most of the mechanics, but a human must still confirm impact and intended behavior. +OpenHunterAI is not an unrestricted offensive tool, mass scanner, private +network scanner, malware or persistence framework, credential-stuffing tool, +or CI/CD auto-retest system. It does not test unverified targets or silently +turn an unavailable integration into a successful scan. -## 4. MVP Modules +Read the complete [security guardrails](docs/SECURITY_GUARDRAILS.md) before +running the project. -| # | Module | Function | Tooling | -|---|---|---|---| -| 1 | Project & Scope Manager | Scope, exclusions, environment, rate limits, guardrails, test window, kill switch | Custom web module, PostgreSQL/SQLite, Open Policy Agent, Pydantic/JSON Schema | -| 2 | Seed Input Engine | Parse OpenAPI/Postman/cURL/HAR, import Burp traffic, configure account/auth workflow | Swagger Parser, Prance, Postman Collection SDK, curlconverter, haralyzer, custom HTTP parser | -| 3 | Recon Engine | Subdomain, DNS, port, HTTP service, technology, public endpoint, JavaScript, source map | Subfinder, dnsx, ProjectDiscovery httpx, Naabu, Nmap, Katana, gau, Nuclei, wafw00f | -| 4 | Browser & Application Mapper | Render UI, login, click/submit, capture network requests, map page↔API, detect workflows | Playwright, Playwright CDP, NetworkX/Neo4j, Tree-sitter/Babel Parser | -| 5 | Request Normalizer | Normalize requests, identify parameters/authentication, link requests to account/page/workflow, strip dynamic data | Pydantic, Python urllib, custom HTTP parser, JSONPath-ng, custom normalization rules | -| 6 | AI Test Execution Engine | Generate payloads, mutate parameters, send requests, manage concurrency, enforce scope/rate limits, invoke Nuclei/Interactsh | LLM Function Calling, Python HTTPX, asyncio, Nuclei, Interactsh, PayloadsAllTheThings, Custom Mutation/Guardrail Engine | -| 7 | Auth Manager | Per-account sessions, cookie/token rotation, login workflow, CSRF token, cross-role replay | Playwright, HTTPX Cookie Jar, JSONPath-ng, PyJWT, HashiCorp Vault/encrypted storage | -| 8 | Evidence Vault & AI Analysis | Store request/response/screenshot/OAST callback, dedupe findings, compare against baseline, score confidence, generate manual verification steps | PostgreSQL, MinIO/local filesystem, DeepDiff, SimHash/embedding similarity, LLM Analysis Agent | -| 9 | Reporter & Remediation Advisor | Raw results, technical report, executive summary, CVSS/CWE/OWASP mapping, remediation guidance, retest | Jinja2, WeasyPrint, Python `cvss` package, local CWE/OWASP mapping, LLM Remediation Agent | +## Quick start -## 5. Proposed Technical Stack +Prerequisites: Docker Compose, Node.js with pnpm, Go, and Make. -| Component | Technology | -|---|---| -| Frontend Dashboard | Next.js | -| Backend API | FastAPI | -| Agent/Worker | Python | -| HTTP execution | HTTPX | -| Browser automation | Playwright | -| Task queue | Celery + Redis or Temporal | -| Database | PostgreSQL | -| Evidence storage | MinIO | -| Recon | Subfinder, dnsx, httpx, Katana | -| CVE/baseline scan | Nuclei | -| OAST | Interactsh self-hosted | -| Reporting | Jinja2, WeasyPrint | -| Local deployment | Docker Compose | -| Production isolation | Docker or Kubernetes sandbox | -| Secret management | Vault or encrypted database fields | +```bash +make install +make app +make db-generate +make db-migrate +make db-seed +``` -## 6. Project Output Structure +For a local frontend and public API development loop: -```text -project/ -├── scope.json -├── exclusions.json -├── assets.json -├── services.json -├── technologies.json -├── pages.json -├── endpoints.json -├── parameters.json -├── workflows.json -├── auth_profiles.json -├── baselines.json -├── test_plan.json -├── executions.jsonl -├── findings.json -├── raw_requests/ -├── raw_responses/ -├── browser_traces/ -├── screenshots/ -└── oast_interactions/ +```bash +make dev +# later +make dev-down ``` -## 7. OWASP WSTG v4.2 Cross-Reference & Optimal Tool Selection - -[OWASP Web Security Testing Guide v4.2](https://owasp.org/www-project-web-security-testing-guide/) is used as a professional reference to validate and narrow the tool choices in §2–§4 down to the single most optimal open-source pick per capability — it does not add scope beyond what §1–§6 already define. Where WSTG recommends a specialist tool that is not part of the current architecture (`docs/ARCHITECTURE.md` §4–§5: Browser/Playwright, ZAP, Nuclei, OpenHack, Strix), that gap is called out explicitly rather than silently folded in. +Use `make help` for the complete command list. Provider keys and runtime +configuration belong in ignored local configuration; never place them in the +repository. + +## Repository map + +| Path | Purpose | +| --- | --- | +| `frontend/` | React/Vite workspace and live scan UI | +| `gateway/` | Public API and internal worker callbacks | +| `backend/` | Control-plane, findings, reporting, and browser-session services | +| `workers/` | Go worker services | +| `integrations/` | Isolated integration adapters | +| `shared/` | Shared database, events, security, queue, and LLM gateway contracts | +| `contracts/` | OpenAPI, AsyncAPI, schema, and generated types | +| `infra/` | Compose and runtime configuration | +| `docs/` | Product contract, guardrails, architecture, and release gates | + +## Documentation + +- [Product requirements](docs/PRD.md) +- [Architecture](docs/ARCHITECTURE.md) +- [Security guardrails](docs/SECURITY_GUARDRAILS.md) +- [Acceptance criteria](docs/ACCEPTANCE_CRITERIA.md) +- [Worker contract](docs/WORKER_SPEC.md) +- [LLM gateway contract](docs/LLM_PROVIDER_SPEC.md) +- [Production readiness](docs/PRODUCTION_READINESS.md) +- [Public release readiness](docs/PUBLIC_RELEASE_READINESS.md) + +## Community + +Bug reports and product feedback are welcome through the issue templates. +Please do not post target data, credentials, tokens, raw traffic, exploit +payloads, or vulnerabilities in public issues. See [SECURITY.md](SECURITY.md) +for responsible disclosure and [CONTRIBUTING.md](CONTRIBUTING.md) for the +current contribution boundary. -| WSTG Category | Test IDs | Owning Module (§2/§4) | Optimal Tool (WSTG-validated) | Repo Status | -|---|---|---|---|---| -| Information Gathering | WSTG-INFO-01…10 | Recon Engine (Step 3) | Subfinder + dnsx + httpx + Katana (ProjectDiscovery suite — same vendor/ecosystem as the already-integrated Nuclei, chainable via stdout/stdin) | Implemented — `integrations/recon`, `workers/R` (dev/local only; staging/CI rollout pending, see `docs/ARCHITECTURE.md` §9) | -| Configuration & Deployment Management | WSTG-CONF-01…11 | Recon Engine + AI Test Execution Engine (Steps 3, 6) | Nuclei (`misconfiguration`/`exposed-panels`/`default-login` templates), ZAP passive scan | Implemented — `integrations/nuclei`, `integrations/zaproxy` | -| Identity Management | WSTG-IDNT-01…05 | Browser & Application Mapper (Step 4) | Playwright workflow observation, tagged `Observed`/`Inferred`/`Unconfirmed` | Implemented — `workers/browser-inspector` | -| Authentication | WSTG-ATHN-01…10 | Auth Manager (Step 7) | Playwright/HTTPX login replay + PyJWT for token inspection, Strix for bypass hypotheses | Implemented — Auth Manager + `integrations/strix` | -| Authorization | WSTG-ATHZ-01…04 | AI Analysis & Manual Approval (Step 8) | Custom Identifier Mutation Engine (IDOR/BOLA replay) + Strix `access_control_analysis` | Implemented — `integrations/strix` | -| Session Management | WSTG-SESS-01…09 | Auth Manager (Step 7) | HTTPX Cookie Jar, JSONPath-ng, PyJWT | Implemented — Auth Manager | -| Input Validation | WSTG-INPV-01…19 | AI Test Execution Engine (Step 6) | Nuclei templates + ZAP active rules + Custom Mutation Engine; Interactsh for blind/OOB classes (SSRF, XXE, blind SSTI/command injection) | Implemented — `integrations/nuclei`, `integrations/zaproxy`; WSTG's `sqlmap`-class deep SQLi validation is **not in v1** (Nuclei/ZAP signal only, escalated to Manual Approval) | -| Error Handling | WSTG-ERRH-01…02 | AI Analysis (Step 8) | ZAP passive + Nuclei response-pattern checks | Implemented | -| Weak Cryptography | WSTG-CRYP-01…04 | Recon Engine (Step 3) | WSTG's optimal standalone pick is `testssl.sh`/`tlsx` — **not in v1**; currently covered only indirectly via Nuclei `ssl`/`tls-config` templates | Partial — documented gap | -| Business Logic | WSTG-BUSL-01…09 | AI Analysis & Manual Approval (Step 8) | Strix adversarial reasoning + OpenHack scenario generation, always routed to Manual Approval — never auto-classified `Safe` | Implemented — `integrations/strix`, `integrations/openhack` | -| Client-side | WSTG-CLNT-01…13 | Browser & Application Mapper (Step 4) | Playwright rendering + ZAP passive DOM/XSS signals | Implemented | -| API Testing | WSTG-APIT-01 | Seed Input Engine (Step 2) | Swagger Parser, Prance, Postman Collection SDK, haralyzer | Implemented | +## License -**Selection rule applied**: for every WSTG category, prefer the tool already present in the v1 stack before introducing a new one. Two genuine gaps survived this filter — Recon Engine (Subfinder/dnsx/httpx/Katana) and standalone TLS depth (testssl.sh/tlsx). Recon Engine has since been implemented as a sixth worker/integration (`workers/R`, `integrations/recon`), approved and added to `docs/ARCHITECTURE.md` §4/§5/§9, `docs/WORKER_SPEC.md` §3/§4, and `docs/PRD.md` §7. Standalone TLS depth (testssl.sh/tlsx) remains an open gap, covered only indirectly via Nuclei's `ssl`/`tls-config` templates. +Copyright (c) 2026 HungBil. -## 8. Out of Technical Scope +OpenHunterAI is source-available under the [PolyForm Noncommercial License +1.0.0](LICENSE), not an OSI-approved open-source license. Personal, +educational, research, and other noncommercial use is covered by those terms. +Commercial use, hosting, resale, paid services, and inclusion in a paid product +require a separate written license from HungBil. See [LICENSING.md](LICENSING.md). -OpenHunterAI is **not**: -- A full replacement for a human pentester. -- A security certification tool. -- A source code scanner / SAST platform. -- An unrestricted automated exploitation tool. -- A mass Internet scanning tool. -- A tool for targets without authorization. -- A tool that guarantees detection of every vulnerability. -- A tool that auto-generates mergeable patches without review. +Third-party components retain their own license notices. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..5a44e0f8 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# Security Policy + +## Reporting a vulnerability + +Do not use public issues for a potential vulnerability, target details, raw +traffic, credentials, tokens, cookies, or proof material. + +Use [GitHub private vulnerability reporting](https://github.com/LumosLab-Innovation/OpenHunterAI/security/advisories/new) +instead. Include a minimal description, affected revision, safe reproduction +steps, and impact. Remove or mask sensitive values before submitting. + +## Scope + +This policy covers OpenHunterAI source and its public documentation. Reports +about third-party targets tested with OpenHunterAI must be sent to that target's +owner through its published disclosure channel. + +## Response + +HungBil will acknowledge reports, assess impact, and coordinate a remediation +or disclosure timeline where applicable. No bounty is promised by this policy.