obsidian

<div align="center">

```
  ██████╗ ██████╗ ███████╗██╗██████╗ ██╗ █████╗ ███╗   ██╗
 ██╔═══██╗██╔══██╗██╔════╝██║██╔══██╗██║██╔══██╗████╗  ██║
 ██║   ██║██████╔╝███████╗██║██║  ██║██║███████║██╔██╗ ██║
 ██║   ██║██╔══██╗╚════██║██║██║  ██║██║██╔══██║██║╚██╗██║
 ╚██████╔╝██████╔╝███████║██║██████╔╝██║██║  ██║██║ ╚████║
  ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝
```

**Autonomous VAPT platform. Give it a target — FQDN, IP, or CIDR range. It hunts, it reports.**

> *"The Obsidian Order has files on everyone."*
> — Garak, Star Trek: Deep Space Nine

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-3776AB.svg?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![Shell](https://img.shields.io/badge/Shell-bash-4EAA25.svg?style=flat-square&logo=gnubash&logoColor=white)](https://www.gnu.org/software/bash/)
[![AI Powered](https://img.shields.io/badge/AI-Ollama%20%7C%20MLX%20%7C%20Claude%20%7C%20GPT--4o%20%7C%20Grok-blueviolet.svg?style=flat-square)](#multi-provider-ai)

[Quick Start](#quick-start) · [Architecture](#architecture) · [Vulnerability Coverage](#vulnerability-coverage) · [Reports](#reports) · [Installation](#installation) · [API Keys](#api-keys-setup) · [Contributing](#contributing)

---

**Recon → Tech fingerprinting → CVE mapping → Vulnerability scanning → AI analysis → Professional report**

</div>

---

## The Obsidian Order

In *Star Trek: Deep Space Nine*, the **Obsidian Order** was the most feared intelligence organisation in the quadrant. Nothing escaped their notice. No secret stayed buried.

OBSIDIAN operates the same way. Give it a target. Walk away. Come back to a full VAPT report.

It was inspired by and evolved from [**claude-bug-bounty**](https://github.com/shuvonsec/claude-bug-bounty) — the original AI-assisted bug bounty automation platform that laid the recon pipeline, ReAct agent architecture, and AI analysis engine that powers this tool today.

---

## What It Does

OBSIDIAN is an autonomous VAPT tool built for professional security consultants. You give it a target — a domain, a single IP, or an entire subnet. It runs the full assessment pipeline and produces a submission-ready report.

| Stage | What happens |
|:------|:-------------|
| 🔭 **Recon** | Subdomain enumeration, DNS resolution, live host discovery, URL crawling, JS analysis, secret extraction |
| 🔬 **Fingerprint** | Tech stack detection (httpx), CVE risk scoring, priority host ranking |
| 🔍 **Scan** | SQLi, XSS, SSTI, RCE, file upload, CORS, JWT, cloud misconfigs, framework exposure |
| 💥 **Exploit** | CMS exploit chains (Drupal, WordPress), Spring actuators, exposed admin panels |
| 🧠 **Analyze** | AI-powered triage — finds chains, ranks by impact, kills noise |
| 📋 **Report** | Burp Suite-style HTML report: executive summary, CVSS scores, PoC evidence, remediation |

---

## Quick Start

```bash
git clone https://github.com/venkatas/obsidian.git
cd obsidian
chmod +x setup.sh && ./setup.sh      # installs all required tools

# Run a full assessment
python3 hunt.py --target example.com

# Single IP address
python3 hunt.py --target 192.168.1.100

# Subnet (discovers live hosts first via nmap ping sweep)
python3 hunt.py --target 10.0.0.0/24

# Faster scan (fewer checks)
python3 hunt.py --target example.com --quick

# Autonomous mode — AI drives all decisions
python3 hunt.py --target example.com --autonomous
```

---

## Architecture

```
Target (FQDN / IP / CIDR)
        │
        ▼
   hunt.py  ◄── brain.py (AI analysis + multi-provider LLM)
        │         └── agent.py (autonomous ReAct loop)
        │
   ┌────┴────────────────────────────────────┐
   │                                         │
   ▼                                         ▼
recon.sh                               scanner.sh
  │                                       │
  ├── subfinder / assetfinder             ├── SQLi (sqlmap + verifier)
  ├── amass / dnsx                        ├── XSS (dalfox)
  ├── httpx (tech detect)                 ├── SSTI (math-canary probes)
  ├── katana / waybackurls / gau          ├── RCE (Log4Shell, Tomcat, JBoss)
  ├── nuclei (CVE templates)              ├── File upload bypass
  ├── nmap / naabu (port scan)            ├── Cloud exposure (Firebase, K8s, Docker)
  ├── subzy (takeover check)              ├── Framework exposure (Spring, GraphQL)
  └── trufflehog / gitleaks (JS secrets)  └── Race conditions (xargs -P 20)
        │
        ▼
  prioritize.py (CVE risk scoring)
        │
        ▼
   brain.py (AI triage)
        │
        ▼
   reporter.py
     ├── vapt_report.html  (Burp Suite-style, self-contained)
     └── vapt_report.md    (Markdown summary)
```

---

## Vulnerability Coverage

| Category | Checks |
|:---------|:-------|
| **Injection** | SQLi (error/blind/time-based), SSTI (Jinja2/Freemarker/Thymeleaf/ERB), XXE, LDAP injection |
| **XSS** | Reflected, stored, DOM — via dalfox pipeline |
| **RCE** | Log4Shell OOB, Tomcat PUT (CVE-2017-12615), JBoss deserialization, Spring4Shell |
| **Auth** | JWT (alg=none, RS256→HS256, weak secret), OAuth misconfig, session fixation |
| **IDOR** | Object-level, field-level, GraphQL node() IDOR, UUID enumeration |
| **File Upload** | Extension bypass, MIME confusion, polyglots, SVG XSS |
| **Cloud** | Firebase open read/write, K8s API unauthenticated, Docker socket exposure, S3 bucket enum |
| **Framework** | Spring actuators (env/heapdump), H2 console, GraphQL introspection, Swagger UI |
| **CMS** | Drupalgeddon2 (CVE-2018-7600), WordPress user enum + xmlrpc, Joomla/Magento |
| **Infrastructure** | Subdomain takeover (subzy), CORS misconfiguration, open redirect, HTTP smuggling |
| **Secrets** | JS bundle secrets (trufflehog/gitleaks), .env exposure, .git/config leak |
| **Race Conditions** | Concurrent probes on OTP, coupon, payment endpoints |

---

## Reports

The report output matches professional pentest engagement standards — suitable for client submission.

**HTML report** (`vapt_report.html`) — single self-contained file:
- Dark navy cover page with client name, consultant, date, and classification
- Executive summary with risk breakdown bar
- Vulnerability summary table (ID, name, severity, CVSS, host)
- Per-finding detail: description, impact, PoC evidence, remediation, CWE/OWASP reference
- Appendix: tools used, methodology, assessment timeline

```bash
# Generate report from a completed scan session
python3 reporter.py recon/example.com/sessions/20260325_120000_abc1/findings/ \
    --client "Acme Corp" \
    --consultant "Your Name" \
    --title "Web Application Penetration Test"
```

Output: `reports/example.com/vapt_report.html` + `vapt_report.md`

---

## Autonomous Agent Mode

The `--autonomous` flag activates the ReAct agent (`agent.py`) which drives the entire assessment without manual intervention — planning, choosing tools, analysing results, and pivoting to the next attack surface on its own.

```bash
# Autonomous hunt with a 4-hour budget
python3 hunt.py --target example.com --autonomous --time 4

# Watch live decisions as they happen
tail -f recon/example.com/sessions/<session_id>/agent_trace.jsonl

# Inject operator guidance mid-run without stopping the agent
python3 agent.py --bump recon/example.com/sessions/<session_id>/ \
    "Focus on /api/v2/ endpoints — de-prioritize static assets"
```

The agent operates in a tight loop: **Observe → Think (LLM) → Act (tool) → Observe**. Every decision is logged to `agent_trace.jsonl` for post-engagement review.

---

## Multi-Provider AI

`brain.py` supports five LLM backends. Set `BRAIN_PROVIDER` to force one, or let OBSIDIAN auto-detect in priority order: **Ollama → MLX → Claude → OpenAI → Grok**.

| Provider | Env var required | Example models | Notes |
|:---------|:----------------|:---------------|:------|
| **Ollama** (local, default) | — | `qwen2.5:14b`, `qwen3-coder:32b` | CPU/GPU, all platforms |
| **MLX**

[truncated…]