tupaxpl 1.3.0__tar.gz

tupaxpl-1.3.0/LICENSE

@@ -0,0 +1,123 @@
+# XPL-Suite Security Research License (XSRL) v1.0
+
+Copyright (c) 2024-2026 Andre Henrike de Oliveira (@mrhenrike) / Uniao Geek
+All rights reserved.
+
+## 1. Definitions
+
+- "Software" means the source code, documentation, binaries, scripts, configuration
+  files, and any other materials included in this repository.
+- "Author" means the original copyright holder: Andre Henrike de Oliveira (@mrhenrike).
+- "Original Repository" means the source repository hosted at
+  https://github.com/mrhenrike/TupaXPL-Forge from which the Software originates.
+- "Upstream Credits" means the authors and licenses of third-party components,
+  libraries, or code referenced in the Software, as documented in source file headers,
+  CREDITS files, or README attribution sections.
+- "Authorized Security Testing" means penetration testing, vulnerability assessment,
+  red team exercises, purple team exercises, security auditing, or similar activities
+  conducted with explicit written permission from the owner of the target system(s).
+
+## 2. Grant of Rights
+
+Subject to the terms and conditions of this License, the Author grants you a
+non-exclusive, worldwide, royalty-free license to:
+
+a) **Use** the Software for educational purposes, academic research, security studies,
+   and Authorized Security Testing;
+b) **Copy and reproduce** the Software;
+c) **Modify** the Software and create derivative works;
+d) **Fork** the Software and maintain independent copies;
+e) **Distribute** the Software and derivative works, provided all conditions in
+   Section 3 are met.
+
+## 3. Conditions
+
+Any use, copy, modification, fork, or distribution of the Software must comply with
+ALL of the following conditions:
+
+### 3.1 Attribution
+
+a) You must retain the Author's original copyright notice and attribution in all
+   copies and derivative works.
+b) You must retain all Upstream Credits, including but not limited to: original author
+   names, license notices, and attribution statements of third-party code used as a
+   base or reference for the Software.
+c) Modified files must carry a prominent notice stating that you changed the files and
+   the date of any change.
+d) Derivative works must include a clear statement identifying the original Software
+   and its Author.
+e) Any copy, fork, or derivative work must include a visible reference to the Original
+   Repository URL (https://github.com/mrhenrike/TupaXPL-Forge) in the project's
+   README or equivalent documentation, so that users can trace the Software back to
+   its source.
+f) The Author's name and credits must not be removed, obscured, or replaced in any
+   copy, fork, or derivative work. The Author must remain credited as the original
+   creator in all circumstances.
+
+### 3.2 Same License
+
+a) Any distribution of the Software or derivative works must be under this same
+   License (XSRL v1.0).
+b) You may not apply any additional restrictions or alternative license terms to the
+   Software or derivative works.
+c) You may not sublicense the Software under different terms.
+
+### 3.3 Non-Commercial Use Only
+
+a) The Software may not be used, in whole or in part, for commercial purposes.
+b) "Commercial purposes" includes but is not limited to: selling the Software or
+   derivative works, incorporating the Software into commercial products or services,
+   using the Software to generate revenue directly or indirectly, and offering the
+   Software as part of a paid service.
+c) Use in non-profit organizations, academic institutions, and personal projects is
+   permitted, provided no commercial gain is derived.
+
+### 3.4 Ethical Use Only
+
+a) The Software may only be used for:
+   - Educational purposes and academic research;
+   - Security studies, training, and skill development;
+   - Authorized Security Testing (as defined in Section 1);
+   - Capture The Flag (CTF) competitions and security labs;
+   - Defensive security, incident response, and threat analysis.
+
+b) The Software may NOT be used for:
+   - Unauthorized access to systems, networks, or data;
+   - Any activity that violates applicable laws or regulations;
+   - Malicious purposes, including but not limited to: deploying malware against
+     unauthorized targets, conducting denial-of-service attacks, unauthorized
+     surveillance, data theft, or any form of cybercrime;
+   - Targeting individuals, organizations, or infrastructure without explicit
+     authorization;
+   - Any purpose that causes harm to individuals or organizations.
+
+## 4. No Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+## 5. Limitation of Liability
+
+The Author shall not be held responsible for any misuse of the Software. Users are
+solely responsible for ensuring their use of the Software complies with all applicable
+laws, regulations, and ethical standards.
+
+## 6. Termination
+
+This License and the rights granted hereunder will terminate automatically if you fail
+to comply with any of the terms and conditions of this License. Upon termination, you
+must cease all use and destroy all copies of the Software in your possession.
+
+## 7. Severability
+
+If any provision of this License is held to be unenforceable, such provision shall be
+reformed only to the extent necessary to make it enforceable, and the remaining
+provisions shall continue in full force and effect.
+
+---
+
+SPDX-License-Identifier: LicenseRef-XSRL-1.0

tupaxpl-1.3.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: tupaxpl
+Version: 1.3.0
+Summary: TupaXPL-Forge — Offensive Security Platform (LLM+LangGraph runtime)
+Author-email: Andre Henrike <safelabs.support@visioncybersecurity.com>
+License: XSRL-1.0
+Project-URL: Homepage, https://github.com/mrhenrike/TupaXPL-Forge
+Project-URL: Repository, https://github.com/mrhenrike/TupaXPL-Forge
+Project-URL: Documentation, https://github.com/mrhenrike/TupaXPL-Forge/wiki
+Project-URL: Bug Tracker, https://github.com/mrhenrike/TupaXPL-Forge/issues
+Project-URL: Changelog, https://github.com/mrhenrike/TupaXPL-Forge/releases
+Keywords: security,pentest,offensive,llm,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: rich>=14.1.0
+Requires-Dist: prompt_toolkit>=3.0.51
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: langgraph>=1.0.1
+Requires-Dist: langchain-core>=1.5.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pydantic-core>=2.46.4
+Requires-Dist: python-evtx>=0.8.1
+Requires-Dist: chromadb>=1.0.15
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: uvicorn>=0.35.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: xpl-core>=0.1.0
+Dynamic: license-file

tupaxpl-1.3.0/README.md

@@ -0,0 +1,129 @@
+<p align="center">
+  <img src="docs/img/tupaxpl-forge-banner_16x9.png" alt="TupaXPL-Forge Banner" width="100%"/>
+</p>
+
+![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square&logo=python)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-informational?style=flat-square)](README.md#compatibility)
+[![License](https://img.shields.io/badge/License-XSRL--1.0-blue?style=flat-square)](LICENSE)
+[![XPL Suite](https://img.shields.io/badge/XPL--Forge-Suite-red?style=flat-square)](https://github.com/mrhenrike)
+[![Issues](https://img.shields.io/github/issues/mrhenrike/TupaXPL-Forge?style=flat-square)](https://github.com/mrhenrike/TupaXPL-Forge/issues)
+[![Last Commit](https://img.shields.io/github/last-commit/mrhenrike/TupaXPL-Forge?style=flat-square)](https://github.com/mrhenrike/TupaXPL-Forge/commits)
+
+---
+
+> **Platform Note:** This framework is designed and tested primarily on **Linux** (Debian/Ubuntu/Kali). Most hardware-dependent modules (wireless adapters, USB devices, raw socket access, firmware tools) require Linux. Running on Windows or macOS may cause errors or limited functionality in many modules. Linux is strongly recommended for maximum compatibility.
+
+---
+
+# TupaXPL-Forge
+
+**Unified Offensive Security Platform** — LangGraph AI agent + EmbedXPL E2E execution + local unrestricted LLM + red team campaign orchestration.
+
+> Named after Tupã, the indigenous Brazilian god of thunder and lightning.
+> Part of the XPL-Forge ecosystem: EmbedXPL · FirewallXPL · IndustrialXPL · WirelessXPL · PrinterXPL.
+
+## Overview
+
+TupaXPL-Forge merges the `pentest-engine` LangGraph agent infrastructure with the `OffSecForge` campaign orchestrator into a single unified offensive security platform.
+
+```
+tupaxpl/
+  forge.py              # Unified CLI entrypoint
+  pentest_engine/       # LangGraph agent: tools, RAG, training, API
+    core/               # Ollama client, extraction, scoring
+    graph/              # StateGraph: authorize/recon/exploit/observe/report
+    tools/              # Ghidra, r2, binwalk, compiler, nuclei, atomic, gateway
+    knowledge/          # Chroma + BM25 RAG: ATT&CK, Sigma, Atomic, EmbedXPL
+    training/           # PEFT/LoRA fine-tuning pipeline
+    api/                # FastAPI at :8080
+  offsecforge/          # Campaign orchestrator
+    campaign.py         # Red team campaign management
+    ai/                 # LLM core (unrestricted), prompt library, code gen
+    builders/           # Exploit builder, payload builder, report builder, MITRE mapper
+    intel/              # EmbedXPL bridge (E2E), CVE feed
+    modules/            # recon, exploit, post, forensics
+  legacy/               # pentestgpt_arsenal
+```
+
+## Quick start
+
+```bash
+# Unrestricted mode (bypasses all policy gates)
+OFFSEC_MODE=unrestricted python forge.py chat
+
+# Generate exploit module for a CVE
+python forge.py generate exploit CVE-2024-53703
+
+# Generate offensive payload
+python forge.py generate payload "reverse shell linux x64"
+
+# Run full campaign
+python forge.py campaign new "Q3 Red Team" 192.168.1.0/24
+python forge.py campaign run <id>
+
+# Binary RE
+python forge.py analyze ./malware.bin --ghidra
+
+# Code security review
+python forge.py review ./target.py
+```
+
+## Requirements
+
+- Python 3.11+
+- Ollama (local LLM server): `ollama pull dolphin-llama3:8b-v2.9-q8_0`
+- EmbedXPL-Forge (set `EMBEDXPL_PATH`)
+
+## LLM models (via Ollama)
+
+| Model | Use | VRAM |
+|---|---|---|
+| `dolphin-llama3:8b-v2.9-q8_0` | Zero safety filters | 8 GB |
+| `qwen2.5-coder:14b-instruct-q4_K_M` | Best code quality | 8.5 GB |
+| `deepseek-coder-v2:16b-lite-instruct-q4_K_M` | Max quality | 10 GB |
+
+## Environment
+
+| Variable | Default | Description |
+|---|---|---|
+| `OFFSEC_MODE` | `standard` | Set to `unrestricted` to bypass PolicyGate |
+| `PE_SAFE` | `true` | Set to `false` to disable safe mode |
+| `PE_EXEC` | `false` | Set to `true` to enable execution |
+| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Ollama server |
+| `EMBEDXPL_PATH` | auto-detect | EmbedXPL-Forge root |
+
+## Author
+
+Andre Henrique (@mrhenrike) | Uniao Geek | https://uniaogeek.com.br/
+---
+
+## Contact
+
+**Support / general inquiries:** security.research@uniaogeek.com.br
+**Security issues:** [SECURITY.md](SECURITY.md)
+
+---
+
+### André Henrique
+
+| | |
+|---|---|
+| GitHub | [@mrhenrike](https://github.com/mrhenrike) |
+| X / Twitter | [@mrhenrike](https://x.com/mrhenrike) |
+| LinkedIn | [mrhenrike](https://www.linkedin.com/in/mrhenrike/) |
+
+### União Geek
+
+| | |
+|---|---|
+| Website | [uniaogeek.com.br](https://uniaogeek.com.br/) |
+| Blog | [uniaogeek.com.br/blog](https://uniaogeek.com.br/blog/) |
+| GitHub | [Uniao-Geek](https://github.com/Uniao-Geek) |
+| Instagram | [@uniaogeek](https://www.instagram.com/uniaogeek/) |
+
+---
+
+**License:** XSRL-1.0 - Copyright (c) 2024-2026 Andre Henrike de Oliveira / Uniao Geek
+**Created by:** André Henrique ([@mrhenrike](https://github.com/mrhenrike)) | [União Geek](https://uniaogeek.com.br/)
+
+[Leia em Português](README.pt-BR.md) - [Command coverage](docs/commands.md) - [Wiki](../../wiki)

tupaxpl-1.3.0/offsecforge/__init__.py

@@ -0,0 +1,5 @@
+"""OffSecForge — Offensive Security Test Campaign Constructor.
+
+Author: Andre Henrique (@mrhenrike) | Uniao Geek
+"""
+__version__ = "1.3.0"

tupaxpl-1.3.0/offsecforge/acquisition/__init__.py

@@ -0,0 +1,58 @@
+"""Acquisition layer __init__ - unified interface.
+
+Author: Andre Henrique (@mrhenrike) | Uniao Geek
+"""
+from offsecforge.acquisition.nvd_client import NvdClient, KevClient
+from offsecforge.acquisition.github_poc_finder import GitHubPocFinder
+from offsecforge.acquisition.exploit_db import ExploitDB, MalwareBazaar
+from offsecforge.acquisition.exploit_downloader import ExploitDownloader
+
+__all__ = [
+    "ExploitDB",
+    "ExploitDownloader",
+    "GitHubPocFinder",
+    "KevClient",
+    "MalwareBazaar",
+    "NvdClient",
+]
+
+
+def hunt(cve_id: str) -> dict:
+    """One-shot CVE intelligence: NVD + KEV + PoCs.
+
+    Returns a unified intel dict for a CVE.
+    """
+    nvd = NvdClient()
+    kev = KevClient()
+    gh = GitHubPocFinder()
+    edb = ExploitDB()
+
+    cve_data = nvd.get(cve_id) or {"id": cve_id, "description": "", "cvss_v3": 0, "severity": "UNKNOWN"}
+    kev_entry = kev.get(cve_id)
+    pocs = gh.find(cve_id)
+    edb_results = edb.search_cve(cve_id)
+
+    return {
+        "cve_id": cve_id,
+        "nvd": cve_data,
+        "is_kev": kev_entry is not None,
+        "kev": kev_entry,
+        "pocs": pocs,
+        "exploitdb": edb_results,
+        "poc_count": len(pocs),
+        "has_metasploit": any("metasploit" in (p.get("description") or "").lower() for p in pocs),
+        "recommendation": _recommend(cve_data, kev_entry is not None, len(pocs)),
+    }
+
+
+def _recommend(cve: dict, is_kev: bool, poc_count: int) -> str:
+    score = cve.get("cvss_v3", 0)
+    if is_kev and score >= 9.0:
+        return "CRITICAL - actively exploited, CVSS 9+, immediate priority"
+    elif is_kev:
+        return "HIGH - in CISA KEV, actively exploited in the wild"
+    elif score >= 9.0 and poc_count > 0:
+        return "HIGH - CVSS 9+, public PoC available"
+    elif score >= 7.0:
+        return "MEDIUM - high CVSS, investigate for exploitation path"
+    return "LOW - assess based on target context"

tupaxpl-1.3.0/offsecforge/acquisition/exploit_db.py

@@ -0,0 +1,89 @@
+"""ExploitDB / searchsploit bridge.
+
+Author: Andre Henrique (@mrhenrike) | Uniao Geek
+"""
+from __future__ import annotations
+import json
+import subprocess
+from typing import Optional
+
+
+class ExploitDB:
+    """Interface to ExploitDB via searchsploit (installed in WSL/Kali)."""
+
+    def search(self, query: str, limit: int = 10) -> list[dict]:
+        """Search ExploitDB for exploits matching query."""
+        return self._run_searchsploit(["--json", query])
+
+    def search_cve(self, cve_id: str) -> list[dict]:
+        """Search ExploitDB by CVE ID."""
+        return self._run_searchsploit(["--json", "--cve", cve_id])
+
+    def download(self, exploit_id: str, output_dir: str = "/tmp") -> Optional[str]:
+        """Download an exploit by its EDB ID."""
+        result = subprocess.run(
+            self._wsl_cmd(["searchsploit", "--mirror", exploit_id]),
+            capture_output=True, text=True, timeout=30, cwd=output_dir,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+
+    def _run_searchsploit(self, args: list[str]) -> list[dict]:
+        cmd = self._wsl_cmd(["searchsploit"] + args)
+        try:
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=20)
+            if result.returncode == 0:
+                data = json.loads(result.stdout)
+                return [self._parse(e) for e in data.get("RESULTS_EXPLOIT", [])]
+        except Exception:
+            pass
+        return []
+
+    def _parse(self, e: dict) -> dict:
+        return {
+            "id": e.get("EDB-ID", ""),
+            "title": e.get("Title", ""),
+            "date": e.get("Date", ""),
+            "author": e.get("Author", ""),
+            "type": e.get("Type", ""),
+            "platform": e.get("Platform", ""),
+            "path": e.get("Path", ""),
+            "codes": e.get("Codes", ""),
+        }
+
+    def _wsl_cmd(self, cmd: list[str]) -> list[str]:
+        """Wrap command for WSL execution on Windows."""
+        import sys
+        if sys.platform == "win32":
+            return ["wsl", "-d", "Ubuntu", "--"] + cmd
+        return cmd
+
+
+class MalwareBazaar:
+    """MalwareBazaar (abuse.ch) API client for malware samples."""
+
+    API = "https://mb-api.abuse.ch/api/v1/"
+
+    def search_tag(self, tag: str, limit: int = 10) -> list[dict]:
+        return self._query({"query": "get_taginfo", "tag": tag, "limit": limit})
+
+    def search_signature(self, sig: str) -> list[dict]:
+        return self._query({"query": "get_siginfo", "signature": sig, "limit": 10})
+
+    def get_hash(self, sha256: str) -> Optional[dict]:
+        results = self._query({"query": "get_info", "hash": sha256})
+        return results[0] if results else None
+
+    def _query(self, payload: dict) -> list[dict]:
+        import urllib.request
+        import urllib.parse
+        data = urllib.parse.urlencode(payload).encode()
+        try:
+            req = urllib.request.Request(self.API, data=data, method="POST")
+            req.add_header("User-Agent", "TupaXPL-Forge/2.0")
+            with urllib.request.urlopen(req, timeout=15) as r:
+                result = json.loads(r.read())
+                return result.get("data", [])
+        except Exception:
+            return []

tupaxpl-1.3.0/offsecforge/acquisition/exploit_downloader.py

@@ -0,0 +1,101 @@
+"""Exploit downloader - downloads and caches exploits locally.
+
+Never deletes cached exploits. Stores in .tmp/cache/exploits/<cve_id>/
+
+Author: Andre Henrique (@mrhenrike) | Uniao Geek
+"""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import ssl
+import subprocess
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+CACHE_DIR = Path(os.environ.get("TUPAXPL_CACHE", "")).resolve() or (
+    Path(__file__).resolve().parents[3] / ".tmp" / "cache" / "exploits"
+)
+_UA = "TupaXPL-Forge/2.0 Security Research"
+
+
+class ExploitDownloader:
+    """Downloads and caches exploit PoCs and scripts locally. Never deletes."""
+
+    def __init__(self, cache_dir: Optional[Path] = None) -> None:
+        self.cache = cache_dir or CACHE_DIR
+        self.cache.mkdir(parents=True, exist_ok=True)
+
+    def download_url(self, cve_id: str, url: str, filename: Optional[str] = None) -> dict:
+        """Download a PoC from URL into the CVE cache directory."""
+        cve_dir = self.cache / cve_id.upper()
+        cve_dir.mkdir(parents=True, exist_ok=True)
+        # Derive filename
+        if not filename:
+            filename = url.split("/")[-1].split("?")[0] or "poc.py"
+        dst = cve_dir / filename
+        if dst.exists():
+            return {"status": "cached", "path": str(dst), "size": dst.stat().st_size}
+        try:
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+            req = urllib.request.Request(url, headers={"User-Agent": _UA})
+            with urllib.request.urlopen(req, context=ctx, timeout=30) as r:
+                data = r.read()
+            dst.write_bytes(data)
+            # Write metadata
+            meta = {
+                "cve_id": cve_id,
+                "source_url": url,
+                "filename": filename,
+                "downloaded": datetime.now().isoformat(),
+                "size": len(data),
+                "sha256": hashlib.sha256(data).hexdigest(),
+            }
+            (cve_dir / "metadata.json").write_text(
+                json.dumps(meta, indent=2), encoding="utf-8"
+            )
+            return {"status": "downloaded", "path": str(dst), "size": len(data)}
+        except Exception as e:
+            return {"status": "error", "error": str(e), "url": url}
+
+    def clone_repo(self, cve_id: str, repo_url: str) -> dict:
+        """Clone a GitHub PoC repo into the CVE cache directory."""
+        cve_dir = self.cache / cve_id.upper()
+        repo_name = repo_url.rstrip("/").split("/")[-1].removesuffix(".git")
+        dst = cve_dir / repo_name
+        if dst.exists():
+            return {"status": "cached", "path": str(dst)}
+        cve_dir.mkdir(parents=True, exist_ok=True)
+        result = subprocess.run(
+            ["git", "clone", "--depth=1", repo_url, str(dst)],
+            capture_output=True, text=True, timeout=60,
+        )
+        if result.returncode == 0:
+            return {"status": "cloned", "path": str(dst)}
+        return {"status": "error", "error": result.stderr[:200]}
+
+    def list_cached(self, cve_id: str = "") -> list[dict]:
+        """List all cached exploits, optionally filtered by CVE."""
+        results = []
+        search = self.cache / cve_id.upper() if cve_id else self.cache
+        if not search.exists():
+            return []
+        pattern = "**/*.py" if not cve_id else "*.py"
+        for f in search.glob(pattern if cve_id else "**/*.py"):
+            meta_file = f.parent / "metadata.json"
+            meta = json.loads(meta_file.read_text()) if meta_file.exists() else {}
+            results.append({
+                "path": str(f),
+                "cve": f.parts[-2] if not cve_id else cve_id,
+                "size": f.stat().st_size,
+                **meta,
+            })
+        return results
+
+    def get_cache_path(self, cve_id: str) -> Path:
+        """Return the cache directory for a CVE."""
+        return self.cache / cve_id.upper()

tupaxpl-1.3.0/offsecforge/acquisition/github_poc_finder.py

@@ -0,0 +1,79 @@
+"""GitHub PoC finder - searches nomi-sec/PoC-in-GitHub and trickest/cve.
+
+Author: Andre Henrique (@mrhenrike) | Uniao Geek
+"""
+from __future__ import annotations
+import json
+import ssl
+import urllib.parse
+import urllib.request
+from typing import Any, Optional
+
+_UA = "TupaXPL-Forge/2.0 Security Research"
+_NOMI_BASE = "https://raw.githubusercontent.com/nomi-sec/PoC-in-GitHub/master"
+_GH_SEARCH = "https://api.github.com/search/repositories"
+
+
+def _get(url: str, timeout: float = 15.0) -> Any:
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    headers = {"User-Agent": _UA, "Accept": "application/vnd.github+json"}
+    req = urllib.request.Request(url, headers=headers)
+    with urllib.request.urlopen(req, context=ctx, timeout=timeout) as r:
+        return json.loads(r.read())
+
+
+class GitHubPocFinder:
+    """Multi-source PoC finder: nomi-sec, trickest/cve, GitHub Search."""
+
+    def find(self, cve_id: str) -> list[dict]:
+        """Find all PoC repos for a CVE ID."""
+        results = []
+        results.extend(self._nomi_sec(cve_id))
+        results.extend(self._github_search(cve_id))
+        # Deduplicate by URL
+        seen = set()
+        unique = []
+        for r in results:
+            url = r.get("url", "")
+            if url not in seen:
+                seen.add(url)
+                unique.append(r)
+        return sorted(unique, key=lambda x: x.get("stars", 0), reverse=True)
+
+    def _nomi_sec(self, cve_id: str) -> list[dict]:
+        """Query nomi-sec/PoC-in-GitHub index."""
+        try:
+            year = cve_id.split("-")[1]
+            url = f"{_NOMI_BASE}/{year}/{cve_id}.json"
+            data = _get(url)
+            return [{
+                "source": "nomi-sec",
+                "cve": cve_id,
+                "url": r.get("html_url", ""),
+                "description": r.get("description", ""),
+                "stars": r.get("stargazers_count", 0),
+                "language": r.get("language", ""),
+                "updated": r.get("updated_at", "")[:10],
+            } for r in (data if isinstance(data, list) else [])]
+        except Exception:
+            return []
+
+    def _github_search(self, cve_id: str, limit: int = 5) -> list[dict]:
+        """Search GitHub repositories by CVE ID."""
+        try:
+            query = urllib.parse.quote(f"{cve_id} exploit poc")
+            url = f"{_GH_SEARCH}?q={query}&sort=stars&per_page={limit}"
+            data = _get(url)
+            return [{
+                "source": "github-search",
+                "cve": cve_id,
+                "url": r.get("html_url", ""),
+                "description": (r.get("description") or "")[:200],
+                "stars": r.get("stargazers_count", 0),
+                "language": r.get("language", ""),
+                "updated": r.get("updated_at", "")[:10],
+            } for r in data.get("items", [])]
+        except Exception:
+            return []