Metadata-Version: 2.4
Name: reconx-py
Version: 0.1.0
Summary: AI-powered OSINT and security reconnaissance toolkit for Python: subdomain finder, WAF detector, JWT analyzer, breach and SPF/DMARC checker, GitHub secret scanner, and a natural-language AI agent.
Project-URL: Homepage, https://github.com/Muhammad-Adil-code/Reconx-py
Project-URL: Repository, https://github.com/Muhammad-Adil-code/Reconx-py
Project-URL: Issues, https://github.com/Muhammad-Adil-code/Reconx-py/issues
Author-email: Muhammad Adil <adil.mern.ai@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,bug-bounty,cybersecurity,infosec,jwt,llm,osint,pentest,pentesting,recon,reconnaissance,security,security-tools,subdomain-enumeration,waf-detection
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: dnspython>=2.3
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: whois
Requires-Dist: python-whois>=0.9; extra == 'whois'
Description-Content-Type: text/markdown

<div align="center">

# reconx-py

**AI-powered OSINT and security reconnaissance toolkit for Python.**

A Python security reconnaissance library, command-line tool, and optional AI agent. It bundles a subdomain finder, WAF detector, JWT analyzer, email breach and SPF/DMARC checker, GitHub secret scanner, and website security audit into one package built for bug bounty, penetration testing, and OSINT workflows.

![Python](https://img.shields.io/badge/Python-3.9+-3776AB?style=for-the-badge&logo=python&logoColor=white)
![httpx](https://img.shields.io/badge/httpx-async-2A6DB2?style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)
![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)

</div>

## Overview

`reconx-py` provides penetration testers, bug bounty hunters, and security researchers with nine focused reconnaissance tools, exposed both as clean asynchronous Python functions and as a `reconx` command-line interface. Each tool works standalone with no configuration. An optional AI agent adds a natural-language layer that maps plain-English requests to the correct tool, runs it, and returns an explanation. The agent works with any OpenAI-compatible API, including OpenAI, DeepSeek, OpenRouter, and Groq.

## Installation

```bash
pip install reconx-py
```

Optional WHOIS enrichment for the `osint` command:

```bash
pip install "reconx-py[whois]"
```

## Library usage

```python
import asyncio
from reconx import scan_website, find_subdomains, check_breach

print(asyncio.run(scan_website("example.com")))
print(asyncio.run(find_subdomains("github.com")))
```

Every tool returns a plain `dict`.

| Function | Description |
|----------|-------------|
| `scan_website(domain)` | Website security scanner. HTTP security-header audit with a graded score. |
| `scan_github(username)` | GitHub secret scanner. Flags leaked API keys and credentials in public repositories. |
| `osint_recon(domain)` | OSINT reconnaissance. DNS, WHOIS, and IP intelligence. |
| `find_subdomains(domain)` | Subdomain finder and enumeration via Certificate Transparency logs (crt.sh). |
| `check_breach(email)` | Email breach checker. Have I Been Pwned style lookup. |
| `analyze_jwt(token)` | JWT analyzer and decoder with an offline security audit. |
| `email_security(domain)` | SPF and DMARC checker for email spoofing protection. |
| `waf_detect(domain)` | WAF and CDN detector using response fingerprinting. |
| `brand_monitor(domain)` | Typosquatting and domain-impersonation finder. |

All functions are asynchronous except `analyze_jwt`, which runs fully offline.

## Command-line usage

```bash
reconx scan example.com
reconx subdomains github.com --json
reconx jwt "eyJhbGci..."
reconx email-sec github.com
reconx waf cloudflare.com
```

Add `--json` to any command for raw JSON output.

## AI agent (optional)

Bring any OpenAI-compatible API key.

```python
import asyncio
from reconx.agent import ask

asyncio.run(ask("scan example.com and explain the risks", api_key="sk-..."))
```

```bash
export OPENAI_API_KEY=sk-...
# For a non-OpenAI provider, also set:
# export OPENAI_BASE_URL=https://openrouter.ai/api/v1
# export OPENAI_MODEL=openai/gpt-4o-mini
reconx ask "does cloudflare.com have a WAF?"
```

The agent selects the correct tool, executes it, and explains the findings in plain English. Requests go only to the provider you configure.

## Design notes

* Light dependencies: `httpx` and `dnspython` only.
* Data sources such as crt.sh and LeakCheck are free public services and can be rate-limited or briefly unavailable. Tools degrade gracefully and return a note rather than raising.
* Set `GITHUB_TOKEN` to raise the GitHub API rate limit for `scan_github`.
* Authorized testing only. Scan targets you own or have written permission to test.

## Who it is for

Bug bounty hunters, penetration testers, red teams, and security researchers who want a scriptable Python reconnaissance toolkit, plus anyone who prefers to query an AI security assistant in plain English instead of memorizing commands.

## Keywords

Python security tools, OSINT library, reconnaissance toolkit, subdomain enumeration, WAF detection, JWT decoder, email breach lookup, SPF and DMARC checker, GitHub secret scanning, typosquatting detection, bug bounty, penetration testing, AI security agent, LLM tool calling.

## License

MIT. Copyright (c) 2025 Muhammad Adil.

<div align="center">

Built by [Muhammad Adil](https://github.com/Muhammad-Adil-code)

</div>
