🕵️♂️ (2-in-1) Email & Username OSINT suite featuring native MCP support for deep data extraction just from a single Email/Username. Analyzes 2720+ actively maintained scan vectors (210+ email / 2510+ username) for security research, investigations, and digital footprinting.
Python cybersecuritycybersecurity-toolsemail-osintethical-hackingethical-hacking-toolsidentificationinfosecosintosint-emailosint-toolosint-toolsosint-usernamepentestingpythonredteam-toolsredteamingthreat-intelligence
import concurrent.futures
import html
import io
import ipaddress
import json
import socket
import urllib.parse
from datetime import datetime
from typing import List, Any, Optional, Union
import httpx
from user_scanner.core.helpers import get_global_timeout, get_proxy
try:
from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, MofNCompleteColumn # type: ignore[import-untyped,import-not-found]
RICH_AVAILABLE = True
except ImportError:
RICH_AVAILABLE = False
try:
from reportlab.lib.pagesizes import A4 # type: ignore[import-untyped,import-not-found]
from reportlab.lib import colors # type: ignore[import-untyped,import-not-found]
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle # type: ignore[import-untyped,import-not-found]
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, Table, TableStyle, Image as RLImage, KeepTogether # type: ignore[import-untyped,import-not-found]
from reportlab.lib.units import inch # type: ignore[import-untyped,import-not-found]
REPORTLAB_AVAILABLE = True
except ImportError:
REPORTLAB_AVAILABLE = False
try:
from PIL import Image as PILImage # type: ignore[import-untyped,import-not-found]
PIL_AVAILABLE = True
except ImportError:
PIL_AVAILABLE = False
try:
from svglib.svglib import svg2rlg # type: ignore[import-untyped,import-not-found]
SVGLIB_AVAILABLE = True
except ImportError:
SVGLIB_AVAILABLE = False
IMAGE_HEURISTIC_KEYS = ["avatar", "image", "pfp", "profile_picture", "snapcode"]
def truncate(val: Any, max_length: int = 300) -> str:
if val is None:
return ""
if isinstance(val, (dict, list)):
try:
s = json.dumps(val)
except Exception:
s = str(val)
else:
s = str(val)
s = "".join([c for c in s if ord(c) < 128])
if len(s) > max_length:
return s[:max_length] + "..."
return s
def clean_metadata(extra: Any) -> List[tuple]:
if not extra or not isinstance(extra, dict):
return []
return [(k, v) for k, v in extra.items() if not any(x in k.lower() for x in IMAGE_HEURISTIC_KEYS)]
def is_safe_ip(ip: Union[ipaddress.IPv4Address, ipaddress.IPv6Address]) -> bool:
"""Check if an IP address is a safe, publicly-routable destination."""
if (
ip.is_loopback
or ip.is_private
or ip.is_link_local
or ip.is_reserved
or ip.is_multicast
or ip.is_unspecified
):
return False
if isinstance(ip, ipaddress.IPv6Address):
if ip.ipv4_mapped:
return is_safe_ip(ip.ipv4_mapped)
if ip.sixtofour:
return is_safe_ip(ip.sixtofour)
return True
def is_safe_media_url(url: str) -> bool:
"""Validate that a URL uses HTTP/HTTPS and resolves exclusively to safe public IPs."""
if not url or not isinstance(url, str):
return False
try:
parsed = urllib.parse.urlsplit(url)
if parsed.scheme.lower() not in ("http", "https"):
return False
hostname = parsed.hostname
if not hostname:
return False
hostname = hostname.strip("[]").lower()
if hostname == "localhost":
return False
# Try parsing directly as an IP address
try:
ip = ipaddress.ip_address(hostname)
return is_safe_ip(ip)
except ValueError:
pass
# Resolve hostname to all associated IPs via DNS
addrinfo = socket.getaddrinfo(hostname, None, proto=socket.IPPROTO_TCP)
if not addrinfo:
return False
for entry in addrinfo:
sockaddr = entry[4]
ip_str = sockaddr[0]
ip = ipaddress.ip_address(ip_str)
if not is_safe_ip(ip):
return False
return True
except Exception:
return False
def fetch_and_resize_image(url: str, max_size: tuple = (600, 600), timeout: float = 5.0) -> Optional[Any]:
if not PIL_AVAILABLE:
return None
global_timeout = get_global_timeout()
effective_timeout = global_timeout if global_timeout is not None else timeout
proxy = get_proxy()
max_redirects = 5
current_url = url
try:
headers = {
"User-Agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"
}
resp = None
for _ in range(max_redirects + 1):
if not is_safe_media_url(current_url):
return None
resp = httpx.get(
current_url,
headers=headers,
proxy=proxy,
timeout=effective_timeout,
follow_redirects=False,
)
if resp.is_redirect:
location = resp.headers.get("Location")
if not location:
return None
current_url = urllib.parse.urljoin(current_url, location)
continue
break
if resp is None or resp.status_code != 200:
return None
content_type = resp.headers.get("Content-Type", "")
if SVGLIB_AVAILABLE and ("svg" in content_type.lower() or current_url.lower().endswith(".svg")):
try:
drawing = svg2rlg(io.BytesIO(resp.content), resolve_entities=False)
if drawing and hasattr(drawing, "width") and hasattr(drawing, "height") and drawing.width > 0 and drawing.height > 0:
s = min(max_size[0] / drawing.width, max_size[1] / drawing.height)
if s < 1.0:
drawing.scale(s, s)
drawing.width = drawing.width * s
drawing.height = drawing.height * s
return drawing
except Exception:
pass
img_raw = PILImage.open(io.BytesIO(resp.content))
img = img_raw.convert("RGB")
# Crop to 1:1 square
min_dim = min(img.width, img.height)
left = (img.width - min_dim) / 2
top = (img.height - min_dim) / 2
right = (img.width + min_dim) / 2
bottom = (img.height + min_dim) / 2
cropped = img.crop((left, top, right, bottom))
# Scale down only if larger than max_size limit (600x600)
if cropped.width > max_size[0] or cropped.height > max_size[1]:
final_img = cropped.resize(max_size, PILImage.Resampling.LANCZOS)
else:
final_img = cropped
img_byte_arr = io.BytesIO()
final_img.save(img_byte_arr, format="JPEG", quality=90)
img_byte_arr.seek(0)
return img_byte_arr
except Exception:
pass
return None
def download_images_parallel(items: List[tuple]) -> dict:
downloaded_images: dict = {}
if not items:
return downloaded_images
max_workers = min(10, max(1, len(items)))
def _execute_downloads(progress_callback=None):
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
future_to_url = {
executor.submit(fetch_and_resize_image, url): url
for url, _ in items
}
for future in concurrent.futures.as_completed(future_to_url):
url = future_to_url[future]
try:
downloaded_images[url] = future.result()
except Exception:
downloaded_images[url] = None
if progress_callback:
progress_callback()
if RICH_AVAILABLE:
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
BarColumn(),
MofNCompleteColumn(),
TextColumn("[progress.percentage]{task.percentage:>3.0f}%"),
transient=True,
) as progress:
task_id = progress.add_task("[cyan]Downloading profile media...", total=len(items))
_execute_downloads(progress_callback=lambda: progress.advance(task_id))
else:
_execute_downloads()
return downloaded_images
def generate_pdf_report(
target: str,
scan_type: str,
results: List[Any],
total_modules: Optional[int] = None,
include_media: bool = True,
version: Optional[str] = None,
) -> bytes:
if not REPORTLAB_AVAILABLE:
raise ImportError(
"ReportLab is required for PDF generation. "
"Please install it using: pip install user-scanner[pdf] or pip install reportlab pillow svglib"
)
# Convert Result objects to dicts if needed
raw_results = []
for r in results:
if hasattr(r, "to_dict"):
raw_results.append(r.to_dict())
elif isinstance(r, dict):
raw_results.append(r)
if total_modules is None:
total_modules = len(raw_results)
buffer = io.BytesIO()
doc = SimpleDocTemplate(
buffer,
pagesize=A4,
rightMargin=30,
leftMargin=30,
topMargin=30,
bottomMargin=30,
)
styles = getSampleStyleSheet()
header_brand_style = ParagraphStyle(
"HeaderBrand",
parent=styles["Normal"],
fontSize=8,
leading=10,
textColor=colors.HexColor("#555555"),
fontName="Helvetica-Bold",
)
header_title_style = ParagraphStyle(
"HeaderTitle",
parent=styles["Normal"],
fontSize=18,
leading=22,
textColor=colors.black,
fontName="Helvetica-Bold",
)
header_subtitle_style = ParagraphStyle(
"HeaderSubtitle",
parent=styles["Normal"],
fontSize=8,
leading=10,
textColor=colors.HexColor("#555555"),
fontName="Helvetica",
)
date_right_style = ParagraphStyle(
"DateRight",
parent=styles["Normal"],
fontSize=7,
leading=9,
textColor=colors.HexColor("#666666"),
alignment=2, # Right align
)
section_title_style = ParagraphStyle(
"SectionTitle",
parent=styles["Heading2"],
fontSize=12,
leading=15,
textColor=colors.black,
spaceBefore=15,
spaceAfter=10,
fontName="Helvetica-Bold",
)
normal_style = styles["Normal"]
elements = []
date_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
version_str = f" v{version}" if version else ""
header_left = [
Paragraph(f"User Scanner{version_str.lower()}", header_brand_style),
Spacer(1, 2),
Paragraph("INTELLIGENCE DOSSIER", header_title_style),
Spacer(1, 2),
Paragraph("AUTOMATED OSINT EXTRACTION", header_subtitle_style),
]
header_right = [
Paragraph(
"<font size=9 color='#dc2626' name='Helvetica-Bold'>CONFIDENTIAL / INTERNAL</font><br/>"
+ date_str,
date_right_style,
)
]
# Header Table
header_data = [[header_left, header_right]]
header_table = Table(header_data, colWidths=[4.2 * inch, 2.8 * inch])
header_table.setStyle(
TableStyle(
[
("VALIGN", (0, 0), (-1, -1), "BOTTOM"),
("LINEBELOW", (0, 0), (-1, -1), 1, colors.HexColor("#222222")),
("BOTTOMPADDING", (0, 0), (-1, -1), 8),
]
)
)
elements.append(header_table)
elements.append(Spacer(1, 20))
hits = [
r
for r in raw_results
if str(r.get("status", "")).lower() in ["found", "registered", "taken"]
]
# Summary Box
summary_data = [
[
Paragraph(
f"<font size=7 color='#6b7280'>SUBJECT TARGET</font><br/><font size=10 name='Helvetica-Bold'>{html.escape(str(target))}</font>",
normal_style,
),
Paragraph(
f"<font size=7 color='#6b7280'>SCAN PARAMETER</font><br/><font size=10 name='Helvetica-Bold'>{html.escape(scan_type.upper())}</font>",
normal_style,
),
Paragraph(
f"<font size=7 color='#6b7280'>DATE OF REPORT</font><br/><font size=10 name='Helvetica-Bold'>{html.escape(date_str)}</font>",
normal_style,
),
Paragraph(
f"<font size=7 color='#6b7280'>TOTAL FINDINGS</font><br/><font size=10 name='Helvetica-Bold'>{len(hits)} Hits across {total_modules} vectors</font>",
normal_style,
),
]
]
summary_table = Table(summary_data, colWidths=[1.8 * inch] * 4)
summary_table.setStyle(
TableStyle(
[
("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#fafafa")),
("BOX", (0, 0), (-1, -1), 1, colors.HexColor("#e5e7eb")),
("PADDING", (0, 0), (-1, -1), 10),
("VALIGN", (0, 0), (-1, -1), "TOP"),
]
)
)
elements.append(summary_table)
# Profile Photos Grid
if include_media and PIL_AVAILABLE:
unique_photos = {}
for idx, hit in enumerate(hits):
media = hit.get("media", {})
extra = hit.get("extra", {})
urls: List[str] = []
if isinstance(media, dict) and media:
urls.extend(str(v) for v in media.values() if v)
elif isinstance(extra, dict) and extra:
for k, v in extra.items():
if v and isinstance(v, str):
k_lower = k.lower()
if any(x in k_lower for x in IMAGE_HEURISTIC_KEYS):
urls.append(v)
for url in urls:
if url and isinstance(url, str) and url.startswith("http") and url not in unique_photos:
unique_photos[url] = {
"site": hit.get("site_name", "Unknown"),
"slNo": idx + 1,
}
if unique_photos:
items = list(unique_photos.items())
downloaded_images = download_images_parallel(items)
photo_cells = []
for url, info in items:
img_io_or_drawing = downloaded_images.get(url)
if img_io_or_drawing:
if isinstance(img_io_or_drawing, io.BytesIO):
rl_img = RLImage(img_io_or_drawing, width=60, height=60)
else:
# For SVGs, we must scale the layout drawing itself to 60x60
drawing = img_io_or_drawing
if hasattr(drawing, "width") and hasattr(drawing, "height") and drawing.width > 0 and drawing.height > 0:
s = min(60.0 / drawing.width, 60.0 / drawing.height)
drawing.scale(s, s)
drawing.width = drawing.width * s
drawing.height = drawing.height * s
rl_img = drawing
caption = Paragraph(
f"<font size=6 color='#6b7280'>{info['slNo']}. {html.escape(str(info['site']))}</font>",
ParagraphStyle("c", alignment=1),
)
photo_cells.append([rl_img, caption])
if photo_cells:
elements.append(
Paragraph("IDENTIFIED PROFILE MEDIA", section_title_style)
)
row = []
grid_data = []
for cell in photo_cells:
cell_table = Table(
[[cell[0]], [cell[1]]], colWidths=[65], rowHeights=[65, 15]
)
cell_table.setStyle(
TableStyle(
[
("ALIGN", (0, 0), (-1, -1), "CENTER"),
("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
(
"BOX",
(0, 0),
(0, 0),
1,
colors.HexColor("#e5e7eb"),
),
(
"BACKGROUND",
(0, 0),
(0, 0),
colors.HexColor("#f3f4f6"),
),
]
)
)
row.append(cell_table)
if len(row) == 7:
grid_data.append(row)
row = []
if row:
while len(row) < 7:
row.append("")
grid_data.append(row)
grid_table = Table(grid_data)
grid_table.setStyle(
TableStyle(
[
("VALIGN", (0, 0), (-1, -1), "TOP"),
("ALIGN", (0, 0), (-1, -1), "CENTER"),
]
)
)
elements.append(grid_table)
elements.append(Spacer(1, 10))
# Footprint Table
elements.append(Paragraph("DIGITAL FOOTPRINT MAPPING", section_title_style))
is_cross_scan = "cross" in scan_type.lower()
if is_cross_scan:
table_data = [
[
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>SL</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>TARGET</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>PLATFORM</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>CATEGORY</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>STATUS</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>IDENTIFIED URL</font>",
normal_style,
),
]
]
else:
table_data = [
[
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>SL</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>PLATFORM</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>CATEGORY</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>STATUS</font>",
normal_style,
),
Paragraph(
"<font size=8 name='Helvetica-Bold' color='#374151'>IDENTIFIED URL</font>",
normal_style,
),
]
]
for idx, hit in enumerate(hits):
status = str(hit.get("status", "Unknown"))
status_color = (
"#16a34a"
if status.lower() in ["found", "registered", "taken"]
else "#111111"
)
url_text = truncate(hit.get("url", "N/A"), 100)
target_val = html.escape(str(hit.get("email") or hit.get("username") or ""))
if is_cross_scan:
table_data.append(
[
Paragraph(
f"<font size=8>{idx + 1}</font>",
ParagraphStyle("C", alignment=1),
),
Paragraph(
f"<font size=8>{target_val}</font>", normal_style
),
Paragraph(
f"<font size=8>{html.escape(str(hit.get('site_name', '')))}</font>", normal_style
),
Paragraph(
f"<font size=8>{html.escape(str(hit.get('category', '')))}</font>", normal_style
),
Paragraph(
f"<font size=8 color='{status_color}'>{html.escape(status)}</font>",
normal_style,
),
Paragraph(
f"<font size=7 color='#2563eb'>{html.escape(url_text)}</font>", normal_style
),
]
)
else:
table_data.append(
[
Paragraph(
f"<font size=8>{idx + 1}</font>",
ParagraphStyle("C", alignment=1),
),
Paragraph(
f"<font size=8>{html.escape(str(hit.get('site_name', '')))}</font>", normal_style
),
Paragraph(
f"<font size=8>{html.escape(str(hit.get('category', '')))}</font>", normal_style
),
Paragraph(
f"<font size=8 color='{status_color}'>{html.escape(status)}</font>",
normal_style,
),
Paragraph(
f"<font size=7 color='#2563eb'>{html.escape(url_text)}</font>", normal_style
),
]
)
if is_cross_scan:
data_table = Table(
table_data,
colWidths=[0.4 * inch, 1.5 * inch, 1.2 * inch, 0.9 * inch, 0.9 * inch, 2.4 * inch],
repeatRows=1,
)
else:
data_table = Table(
table_data,
colWidths=[0.5 * inch, 1.5 * inch, 1.2 * inch, 1.0 * inch, 3.1 * inch],
repeatRows=1,
)
data_table.setStyle(
TableStyle(
[
("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#f3f4f6")),
("BOX", (0, 0), (-1, -1), 1, colors.HexColor("#e5e7eb")),
("INNERGRID", (0, 0), (-1, -1), 1, colors.HexColor("#e5e7eb")),
("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
("BOTTOMPADDING", (0, 0), (-1, 0), 5),
("TOPPADDING", (0, 0), (-1, 0), 5),
]
)
)
elements.append(data_table)
# Deep Metadata Cards
hits_with_meta = []
for hit in hits:
meta = clean_metadata(hit.get("extra"))
media = hit.get("media")
if media and isinstance(media, dict):
for k, v in media.items():
if v:
meta.append((k, v))
if meta:
hits_with_meta.append((hit, meta))
if hits_with_meta:
elements.append(
Paragraph("EXTRACTED DEEP INTELLIGENCE", section_title_style)
)
for hit, meta in hits_with_meta:
site_title = html.escape(str(hit.get('site_name', '')))
target_val = html.escape(str(hit.get("email") or hit.get("username") or ""))
if is_cross_scan and target_val:
site_title += f" ({target_val})"
meta_elements = [
Paragraph(
f"<font size=10 name='Helvetica-Bold'>{site_title}</font>",
normal_style,
),
Spacer(1, 5),
]
meta_grid = []
row = []
for k, v in meta:
key_para = f"<font size=7 color='#6b7280'>{html.escape(str(k).replace('_', ' ').upper())}</font>"
val_para = (
f"<font size=8 color='#1f2937'>{html.escape(truncate(v, 200))}</font>"
)
cell = Paragraph(f"{key_para}<br/>{val_para}", normal_style)
row.append(cell)
if len(row) == 2:
meta_grid.append(row)
row = []
if row:
row.append("")
meta_grid.append(row)
if meta_grid:
m_table = Table(meta_grid, colWidths=[3.6 * inch, 3.6 * inch])
m_table.setStyle(
TableStyle(
[
("VALIGN", (0, 0), (-1, -1), "TOP"),
("BOTTOMPADDING", (0, 0), (-1, -1), 3),
("TOPPADDING", (0, 0), (-1, -1), 0),
]
)
)
meta_elements.append(m_table)
block_table = Table([[meta_elements]], colWidths=[7.2 * inch])
block_table.setStyle(
TableStyle(
[
("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#f9fafb")),
("BOX", (0, 0), (-1, -1), 1, colors.HexColor("#f3f4f6")),
("PADDING", (0, 0), (-1, -1), 8),
("BOTTOMPADDING", (0, 0), (-1, -1), 12),
]
)
)
elements.append(KeepTogether(block_table))
elements.append(Spacer(1, 10))
doc.build(elements)
buffer.seek(0)
return buffer.read()