Skip to content

gitstq/ReconGraph-CLI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
recongraph_cli
recongraph_cli
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
pyproject.toml
pyproject.toml
 
 

Repository files navigation

🔍 ReconGraph CLI

Lightweight Terminal OSINT Entity Relationship Graph Investigation Engine

Python 3.8+ License: MIT Zero Dependencies Cross Platform

English | 简体中文 | 繁體中文

English

🎉 About

ReconGraph CLI is a lightweight, zero-dependency terminal tool designed for security researchers, threat analysts, and investigators. It automatically discovers and maps relationships between OSINT entities (domains, IPs, emails, URLs, etc.) through intelligent enrichment, building an interactive entity relationship graph — all from your terminal.

Key Differentiators:

  • 🚀 Zero external dependencies — runs on Python 3.8+ stdlib only
  • 🕸️ Graph-based investigation — entities and relations stored in a local SQLite graph database
  • 🔌 10 built-in enrichers — DNS, WHOIS, geolocation, subdomain enum, port scanning, and more
  • 🎨 Beautiful terminal UI — colorful output with ASCII graph visualization
  • 📊 Multi-format export — JSON and Markdown report generation
  • 🧩 Plugin architecture — easily extend with custom enrichers

✨ Core Features

Feature Description
🌐 DNS Resolution Resolve domains to IPv4/IPv6 addresses via A/AAAA records
🔄 Reverse DNS Map IP addresses back to domain names
📍 IP Geolocation Country, city, ISP, and organization lookup for IP addresses
📋 WHOIS Lookup Registrar, creation date, nameservers, and registrant info
📁 Subdomain Enumeration Discover subdomains via certificate transparency logs (crt.sh)
🔧 HTTP Header Analysis Server technology detection and security header audit
🚪 Port Scanning Check 17 common TCP service ports
📧 Email Analysis Extract domain, detect disposable email providers
🔗 URL Parsing Extract components and related entities from URLs
🏢 ASN Lookup Autonomous System Number and organization information

🚀 Quick Start

Requirements: Python 3.8 or higher (no additional packages needed)

# Clone the repository
git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI

# Run directly (no installation needed)
python -m recongraph_cli scan example.com

# Or install as a CLI tool
pip install .
recongraph scan example.com

Basic Usage:

# Scan a single domain
recongraph scan example.com

# Scan an IP address with deeper enrichment
recongraph scan 8.8.8.8 --depth 2

# Scan multiple targets
recongraph scan example.com test.org 1.2.3.4

# Use specific enrichers only
recongraph scan example.com --enrichers dns-resolve whois subdomain-enum

# Export results to Markdown report
recongraph scan example.com --output report.md

# Export results to JSON
recongraph scan example.com --output report.json

📖 Detailed Guide

Available Commands:

Command Description
scan <targets> Scan targets for OSINT data
enrichers List all available enrichers
graph Display current graph state
export Export graph to file
stats Show graph statistics
clear Clear all graph data

Advanced Examples:

# Full investigation with report
recongraph scan target.com --depth 3 -o investigation_report.md

# Search within stored graph
recongraph graph --query "google"

# View graph statistics
recongraph stats

# Export accumulated data
recongraph export -o full_report.json

# Use custom database path
recongraph -d /path/to/custom.db scan example.com

Supported Entity Types (auto-detected):

  • 🌐 Domain names (example.com)
  • 📡 IP addresses (8.8.8.8)
  • 📧 Email addresses (user@example.com)
  • 🔗 URLs (https://example.com/path)
  • 🔒 CVE identifiers (CVE-2024-1234)
  • #️⃣ Hashes (MD5, SHA1, SHA256)

💡 Design Philosophy & Roadmap

Design Principles:

  • Simplicity First — Zero external dependencies, single-file install, works everywhere
  • Graph-Native — All data stored as entities and relations, enabling complex relationship queries
  • Extensible — Plugin architecture allows custom enrichers for specialized investigations
  • Privacy — All data stored locally in SQLite, no cloud services involved

Roadmap:

  • Shodan integration enricher
  • VirusTotal API enricher
  • Interactive TUI mode with keyboard navigation
  • Graph visualization export (DOT/Graphviz)
  • Batch scanning from file input
  • Timeline analysis for entity changes
  • Custom enricher template generator

📦 Installation & Deployment

Method 1: Direct Run (Recommended)

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
python -m recongraph_cli [command]

Method 2: pip Install

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pip install .
recongraph [command]

Method 3: pipx Install (Isolated)

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pipx install .
recongraph [command]

Compatible Environments:

  • ✅ Python 3.8, 3.9, 3.10, 3.11, 3.12
  • ✅ Windows 10/11, macOS 12+, Linux (all major distributions)
  • ✅ No admin/root privileges required

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Start:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-enricher)
  3. Commit your changes (git commit -m 'feat: add my custom enricher')
  4. Push to branch (git push origin feature/my-enricher)
  5. Create a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

简体中文

🎉 项目介绍

ReconGraph CLI 是一款轻量级、零外部依赖的终端OSINT实体关系图谱调查引擎，专为安全研究人员、威胁分析师和调查人员设计。它能通过智能富化自动发现并映射OSINT实体（域名、IP、邮箱、URL等）之间的关系，在终端中构建交互式实体关系图谱。

核心差异化亮点：

  • 🚀 零外部依赖 — 仅需 Python 3.8+ 标准库即可运行
  • 🕸️ 图谱化调查 — 实体和关系存储在本地SQLite图数据库中
  • 🔌 10个内置富化器 — DNS、WHOIS、地理位置、子域名枚举、端口扫描等
  • 🎨 精美终端UI — 彩色输出配合ASCII图谱可视化
  • 📊 多格式导出 — 支持JSON和Markdown报告生成
  • 🧩 插件化架构 — 轻松扩展自定义富化器

✨ 核心特性

特性 描述
🌐 DNS解析 通过A/AAAA记录将域名解析为IPv4/IPv6地址
🔄 反向DNS 将IP地址反向映射为域名
📍 IP地理位置 查询IP地址的国家、城市、ISP和组织信息
📋 WHOIS查询 注册商、创建日期、域名服务器和注册人信息
📁 子域名枚举 通过证书透明度日志(crt.sh)发现子域名
🔧 HTTP头分析 服务器技术检测和安全头审计
🚪 端口扫描 检测17个常见TCP服务端口
📧 邮箱分析 提取域名、检测一次性邮箱提供商
🔗 URL解析 从URL中提取组件和相关实体
🏢 ASN查询 自治系统编号和组织信息

🚀 快速开始

环境要求： Python 3.8 或更高版本（无需安装额外包）

# 克隆仓库
git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI

# 直接运行（无需安装）
python -m recongraph_cli scan example.com

# 或安装为CLI工具
pip install .
recongraph scan example.com

基础用法：

# 扫描单个域名
recongraph scan example.com

# 深度扫描IP地址
recongraph scan 8.8.8.8 --depth 2

# 扫描多个目标
recongraph scan example.com test.org 1.2.3.4

# 仅使用指定富化器
recongraph scan example.com --enrichers dns-resolve whois subdomain-enum

# 导出Markdown报告
recongraph scan example.com --output report.md

# 导出JSON数据
recongraph scan example.com --output report.json

📖 详细使用指南

可用命令：

命令 描述
scan <目标> 扫描目标的OSINT数据
enrichers 列出所有可用富化器
graph 显示当前图谱状态
export 导出图谱到文件
stats 显示图谱统计信息
clear 清除所有图谱数据

高级用法：

# 完整调查并生成报告
recongraph scan target.com --depth 3 -o investigation_report.md

# 在已存储的图谱中搜索
recongraph graph --query "google"

# 查看图谱统计
recongraph stats

# 导出累积数据
recongraph export -o full_report.json

# 使用自定义数据库路径
recongraph -d /path/to/custom.db scan example.com

支持的实体类型（自动识别）：

  • 🌐 域名 (example.com)
  • 📡 IP地址 (8.8.8.8)
  • 📧 邮箱地址 (user@example.com)
  • 🔗 URL (https://example.com/path)
  • 🔒 CVE编号 (CVE-2024-1234)
  • #️⃣ 哈希值 (MD5、SHA1、SHA256)

💡 设计思路与迭代规划

设计理念：

  • 简洁优先 — 零外部依赖，单文件安装，随处可用
  • 图谱原生 — 所有数据以实体和关系存储，支持复杂关系查询
  • 可扩展 — 插件架构支持自定义富化器，适配专业调查场景
  • 隐私至上 — 所有数据存储在本地SQLite中，不涉及任何云服务

后续迭代计划：

  • Shodan集成富化器
  • VirusTotal API富化器
  • 交互式TUI模式，支持键盘导航
  • 图谱可视化导出（DOT/Graphviz格式）
  • 从文件批量扫描
  • 实体变更时间线分析
  • 自定义富化器模板生成器

📦 安装与部署

方式一：直接运行（推荐）

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
python -m recongraph_cli [命令]

方式二：pip安装

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pip install .
recongraph [命令]

方式三：pipx隔离安装

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pipx install .
recongraph [命令]

兼容环境：

  • ✅ Python 3.8、3.9、3.10、3.11、3.12
  • ✅ Windows 10/11、macOS 12+、Linux（所有主流发行版）
  • ✅ 无需管理员/root权限

🤝 贡献指南

欢迎贡献代码！请参阅 CONTRIBUTING.md 了解详细指南。

快速开始：

  1. Fork 本仓库
  2. 创建功能分支 (git checkout -b feature/my-enricher)
  3. 提交更改 (git commit -m 'feat: add my custom enricher')
  4. 推送到分支 (git push origin feature/my-enricher)
  5. 创建 Pull Request

📄 开源协议

本项目基于 MIT 开源协议发布 — 详见 LICENSE 文件。

繁體中文

🎉 專案介紹

ReconGraph CLI 是一款輕量級、零外部依賴的終端OSINT實體關係圖譜調查引擎，專為安全研究人員、威脅分析師和調查人員設計。它能透過智慧富化自動發現並映射OSINT實體（網域名稱、IP、電子郵件、URL等）之間的關係，在終端中建構互動式實體關係圖譜。

核心差異化亮點：

  • 🚀 零外部依賴 — 僅需 Python 3.8+ 標準庫即可運行
  • 🕸️ 圖譜化調查 — 實體和關係儲存在本地SQLite圖資料庫中
  • 🔌 10個內建富化器 — DNS、WHOIS、地理位置、子網域枚舉、連接埠掃描等
  • 🎨 精美終端UI — 彩色輸出配合ASCII圖譜視覺化
  • 📊 多格式匯出 — 支援JSON和Markdown報告生成
  • 🧩 外掛化架構 — 輕鬆擴展自訂富化器

✨ 核心特性

特性 描述
🌐 DNS解析 透過A/AAAA記錄將網域解析為IPv4/IPv6位址
🔄 反向DNS 將IP位址反向映射為網域名稱
📍 IP地理位置 查詢IP位址的國家、城市、ISP和組織資訊
📋 WHOIS查詢 註冊商、建立日期、名稱伺服器和註冊人資訊
📁 子網域枚舉 透過憑證透明度日誌(crt.sh)發現子網域
🔧 HTTP標頭分析 伺服器技術偵測和安全標頭稽核
🚪 連接埠掃描 偵測17個常見TCP服務連接埠
📧 電子郵件分析 提取網域、偵測一次性電子郵件提供商
🔗 URL解析 從URL中提取元件和相關實體
🏢 ASN查詢 自治系統編號和組織資訊

🚀 快速開始

環境需求： Python 3.8 或更高版本（無需安裝額外套件）

# 克隆倉庫
git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI

# 直接運行（無需安裝）
python -m recongraph_cli scan example.com

# 或安裝為CLI工具
pip install .
recongraph scan example.com

基礎用法：

# 掃描單個網域
recongraph scan example.com

# 深度掃描IP位址
recongraph scan 8.8.8.8 --depth 2

# 掃描多個目標
recongraph scan example.com test.org 1.2.3.4

# 僅使用指定富化器
recongraph scan example.com --enrichers dns-resolve whois subdomain-enum

# 匯出Markdown報告
recongraph scan example.com --output report.md

# 匯出JSON資料
recongraph scan example.com --output report.json

📖 詳細使用指南

可用命令：

命令 描述
scan <目標> 掃描目標的OSINT資料
enrichers 列出所有可用富化器
graph 顯示當前圖譜狀態
export 匯出圖譜到檔案
stats 顯示圖譜統計資訊
clear 清除所有圖譜資料

進階用法：

# 完整調查並生成報告
recongraph scan target.com --depth 3 -o investigation_report.md

# 在已儲存的圖譜中搜尋
recongraph graph --query "google"

# 查看圖譜統計
recongraph stats

# 匯出累積資料
recongraph export -o full_report.json

# 使用自訂資料庫路徑
recongraph -d /path/to/custom.db scan example.com

支援的實體類型（自動識別）：

  • 🌐 網域名稱 (example.com)
  • 📡 IP位址 (8.8.8.8)
  • 📧 電子郵件 (user@example.com)
  • 🔗 URL (https://example.com/path)
  • 🔒 CVE編號 (CVE-2024-1234)
  • #️⃣ 雜湊值 (MD5、SHA1、SHA256)

💡 設計理念與迭代規劃

設計理念：

  • 簡潔優先 — 零外部依賴，單檔案安裝，隨處可用
  • 圖譜原生 — 所有資料以實體和關係儲存，支援複雜關係查詢
  • 可擴展 — 外掛架構支援自訂富化器，適配專業調查場景
  • 隱私至上 — 所有資料儲存在本地SQLite中，不涉及任何雲端服務

後續迭代計劃：

  • Shodan整合富化器
  • VirusTotal API富化器
  • 互動式TUI模式，支援鍵盤導航
  • 圖譜視覺化匯出（DOT/Graphviz格式）
  • 從檔案批次掃描
  • 實體變更時間線分析
  • 自訂富化器模板生成器

📦 安裝與部署

方式一：直接運行（推薦）

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
python -m recongraph_cli [命令]

方式二：pip安裝

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pip install .
recongraph [命令]

方式三：pipx隔離安裝

git clone https://github.com/gitstq/ReconGraph-CLI.git
cd ReconGraph-CLI
pipx install .
recongraph [命令]

相容環境：

  • ✅ Python 3.8、3.9、3.10、3.11、3.12
  • ✅ Windows 10/11、macOS 12+、Linux（所有主流發行版）
  • ✅ 無需管理員/root權限

🤝 貢獻指南

歡迎貢獻程式碼！請參閱 CONTRIBUTING.md 了解詳細指南。

快速開始：

  1. Fork 本倉庫
  2. 建立功能分支 (git checkout -b feature/my-enricher)
  3. 提交變更 (git commit -m 'feat: add my custom enricher')
  4. 推送到分支 (git push origin feature/my-enricher)
  5. 建立 Pull Request

📄 開源協議

本專案基於 MIT 開源協議發布 — 詳見 LICENSE 檔案。

Made with ❤️ by ReconGraph Team

About

🔍 Lightweight Terminal OSINT Entity Relationship Graph Investigation Engine - Zero dependencies, 10+ built-in enrichers, cross-platform

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages