AI powered OSINT engine to discover and map 840+ social media identities across the web
Python aiartificial-intelligencedebainhackhackerhackinghackingtoolsinformationinformation-gatheringlinuxlinux-desktoposintpythonpython-scriptpython3social-mediasocialmediahackingtermuxtermux-tool
import csv
import json
from datetime import datetime
from html import escape as _esc
from pathlib import Path
from typing import Any
from rich.panel import Panel
from rich.prompt import Prompt
from aliens_eye.utils.console import build_results_table, get_console
KNOWN_FORMATS = {
"json", "csv", "html", "md", "markdown",
"gexf", "maltego", "mermaid", "pdf", "all",
}
# Formats that need the correlation graph rather than the flat report.
GRAPH_FORMATS = {"gexf", "maltego", "mermaid"}
def _md_cell(value: Any) -> str:
"""Sanitize a value for use inside a Markdown table cell."""
return str(value or "").replace("|", "\\|").replace("\n", " ").replace("\r", " ").strip()
_REPORTED_STATUSES = {"Found", "Maybe"}
class ResultsExporter:
"""Save scan results in JSON, CSV, HTML, or Markdown formats."""
# With only_found, reports list just the Found and Maybe sites. The counts in
# them still cover every site scanned, so a short list isn't mistaken for a
# short scan.
only_found: bool = False
def __init__(self, output_dir: Path, only_found: bool = False) -> None:
self.only_found = only_found
self.output_dir = output_dir
self.output_dir.mkdir(parents=True, exist_ok=True)
self.console = get_console()
def save_results(
self,
base_username: str,
level: str,
all_results: dict[str, list[dict[str, Any]]],
formats: list[str],
correlation: dict[str, Any] | None = None,
domains: dict[str, Any] | None = None,
) -> list[Path]:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
results_data = self._build_results_data(
base_username, level, all_results, timestamp
)
if correlation is not None:
results_data["correlation"] = correlation
if domains is not None:
results_data["domains"] = domains
written: list[Path] = []
stem = f"{base_username}_{level}_{timestamp}"
if "json" in formats or "all" in formats:
json_path = self.output_dir / f"{stem}.json"
with json_path.open("w", encoding="utf-8") as handle:
json.dump(results_data, handle, indent=4)
written.append(json_path)
if "csv" in formats or "all" in formats:
csv_path = self.output_dir / f"{stem}.csv"
self._write_csv(csv_path, base_username, level, all_results)
written.append(csv_path)
if "html" in formats or "all" in formats:
html_path = self.output_dir / f"{stem}.html"
self._write_html(html_path, results_data)
written.append(html_path)
if "md" in formats or "markdown" in formats or "all" in formats:
md_path = self.output_dir / f"{stem}.md"
self._write_markdown(md_path, results_data)
written.append(md_path)
# Graph and PDF formats are opt-in only (not bundled into "all"), since
# they are analysis artifacts rather than the standard document report.
if "gexf" in formats:
p = self.output_dir / f"{stem}.gexf"
self._write_gexf(p, results_data)
written.append(p)
if "maltego" in formats:
p = self.output_dir / f"{stem}_maltego.csv"
self._write_maltego(p, results_data)
written.append(p)
if "mermaid" in formats:
p = self.output_dir / f"{stem}.mmd"
self._write_mermaid(p, results_data)
written.append(p)
if "pdf" in formats:
p = self.output_dir / f"{stem}.pdf"
if self._write_pdf(p, results_data):
written.append(p)
return written
def report_dict(
self,
base_username: str,
level: str,
all_results: dict[str, list[dict[str, Any]]],
) -> dict[str, Any]:
"""Public accessor for the structured report (used for --json-stdout)."""
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
return self._build_results_data(base_username, level, all_results, timestamp)
def _build_results_data(
self,
base_username: str,
level: str,
all_results: dict[str, list[dict[str, Any]]],
timestamp: str,
) -> dict[str, Any]:
variations_data: dict[str, Any] = {}
scan_summary = {
"base_username": base_username,
"scan_level": level,
"timestamp": timestamp,
"total_variations": len(all_results),
"total_sites_scanned": sum(len(results) for results in all_results.values()),
}
found_counts: dict[str, int] = {}
high_confidence_matches: dict[str, int] = {}
for username, results in all_results.items():
found_counts[username] = sum(1 for r in results if r["status"] == "Found")
high_confidence_matches[username] = sum(
1
for r in results
if r.get("confidence", 0) >= 85 and r["status"] == "Found"
)
variations_data[username] = {
"scan_info": {
"username": username,
"sites_scanned": len(results),
"found": found_counts[username],
"maybe": sum(1 for r in results if r["status"] == "Maybe"),
"not_found": sum(
1 for r in results if r["status"] == "Not Found"
),
"errors": sum(
1
for r in results
if r["status"] not in {"Found", "Not Found", "Maybe"}
),
"high_confidence_matches": high_confidence_matches[username],
},
"sites": {
r["site"]: {
"status": r["status"],
"code": r["code"],
"url": r["url"],
"final_url": r.get("final_url", ""),
"response_time": r["response_time"],
"confidence": r.get("confidence", 0),
"ai_analysis": r.get("ai_analysis", {}),
}
for r in results
if not self.only_found or r["status"] in _REPORTED_STATUSES
},
}
if self.only_found:
scan_summary["only_found"] = True
scan_summary["total_found"] = sum(found_counts.values())
scan_summary["total_high_confidence"] = sum(high_confidence_matches.values())
scan_summary["best_variations"] = sorted(
found_counts.items(), key=lambda x: x[1], reverse=True
)[:5]
return {"scan_summary": scan_summary, "variations": variations_data}
def _write_csv(
self,
path: Path,
base_username: str,
level: str,
all_results: dict[str, list[dict[str, Any]]],
) -> None:
fieldnames = [
"base_username",
"variation",
"site",
"status",
"confidence",
"http_code",
"url",
"final_url",
"response_time",
]
with path.open("w", newline="", encoding="utf-8") as handle:
writer = csv.DictWriter(handle, fieldnames=fieldnames)
writer.writeheader()
for variation, results in all_results.items():
for item in results:
if self.only_found and item["status"] not in _REPORTED_STATUSES:
continue
writer.writerow(
{
"base_username": base_username,
"variation": variation,
"site": item["site"],
"status": item["status"],
"confidence": item.get("confidence", 0),
"http_code": item.get("code", 0),
"url": item.get("url", ""),
"final_url": item.get("final_url", ""),
"response_time": item.get("response_time", 0),
}
)
def _write_html(self, path: Path, results_data: dict[str, Any]) -> None:
summary = results_data.get("scan_summary", {})
variations = results_data.get("variations", {})
rows = []
for variation, data in variations.items():
for site, info in data.get("sites", {}).items():
profile = info.get("ai_analysis", {}).get("signals", {}).get("profile", {})
is_hit = info.get("status") in {"Found", "Maybe"}
avatar_url = profile.get("avatar", "") if is_hit else ""
avatar_cell = (
f"<img src='{_esc(avatar_url, quote=True)}' alt='' style='height:40px;border-radius:4px'>"
if avatar_url
else ""
)
name = _esc(profile.get("name", "")) if is_hit else ""
bio = _esc(profile.get("bio", "")) if is_hit else ""
url = info.get("url", "")
rows.append(
f"<tr><td>{_esc(variation)}</td><td>{_esc(site)}</td>"
f"<td>{_esc(info.get('status',''))}</td>"
f"<td>{_esc(str(info.get('confidence',0)))}</td>"
f"<td>{_esc(str(info.get('code',0)))}</td>"
f"<td><a href='{_esc(url, quote=True)}'>{_esc(url)}</a></td>"
f"<td>{avatar_cell}</td><td>{name}</td><td>{bio}</td></tr>"
)
html = f"""
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Aliens Eye Report</title>
<style>
body {{ font-family: Arial, sans-serif; padding: 20px; }}
summary, table {{ margin-top: 20px; }}
table {{ border-collapse: collapse; width: 100%; }}
th, td {{ border: 1px solid #ddd; padding: 8px; font-size: 12px; }}
th {{ background-color: #f2f2f2; text-align: left; }}
</style>
</head>
<body>
<h1>Aliens Eye Report</h1>
<p><strong>Base Username:</strong> {_esc(str(summary.get('base_username','')))}</p>
<p><strong>Scan Level:</strong> {_esc(str(summary.get('scan_level','')))}</p>
<p><strong>Total Variations:</strong> {summary.get('total_variations',0)}</p>
<p><strong>Total Sites Scanned:</strong> {summary.get('total_sites_scanned',0)}</p>
<p><strong>Total Found:</strong> {summary.get('total_found',0)}</p>
<p><strong>Total High Confidence:</strong> {summary.get('total_high_confidence',0)}</p>
<table>
<thead>
<tr>
<th>Variation</th>
<th>Site</th>
<th>Status</th>
<th>Confidence</th>
<th>HTTP Code</th>
<th>URL</th>
<th>Avatar</th>
<th>Name</th>
<th>Bio</th>
</tr>
</thead>
<tbody>
{''.join(rows)}
</tbody>
</table>
</body>
</html>
"""
with path.open("w", encoding="utf-8") as handle:
handle.write(html)
def _write_markdown(self, path: Path, results_data: dict[str, Any]) -> None:
summary = results_data.get("scan_summary", {})
variations = results_data.get("variations", {})
lines = [
"# Aliens Eye Report",
"",
f"- **Base username:** `{summary.get('base_username', '')}`",
f"- **Scan level:** {summary.get('scan_level', '')}",
f"- **Timestamp:** {summary.get('timestamp', '')}",
f"- **Variations scanned:** {summary.get('total_variations', 0)}",
f"- **Sites scanned:** {summary.get('total_sites_scanned', 0)}",
f"- **Total found:** {summary.get('total_found', 0)}",
f"- **High confidence:** {summary.get('total_high_confidence', 0)}",
"",
]
for variation, data in variations.items():
info = data.get("scan_info", {})
lines.extend(
[
f"## `{variation}`",
"",
f"Found: {info.get('found', 0)} | Maybe: {info.get('maybe', 0)} | "
f"Not Found: {info.get('not_found', 0)} | Errors: {info.get('errors', 0)}",
"",
"| Site | Status | Confidence | HTTP | Name | Bio | URL |",
"| --- | --- | --- | --- | --- | --- | --- |",
]
)
sites = sorted(
data.get("sites", {}).items(),
key=lambda item: (
{"Found": 0, "Maybe": 1}.get(item[1].get("status", ""), 2),
-item[1].get("confidence", 0),
),
)
for site, site_info in sites:
status = site_info.get("status", "")
if status not in {"Found", "Maybe"}:
continue
profile = (
site_info.get("ai_analysis", {})
.get("signals", {})
.get("profile", {})
)
name = _md_cell(profile.get("name", ""))
bio = _md_cell(profile.get("bio", ""))
lines.append(
f"| {site} | {status} | {site_info.get('confidence', 0)}% | "
f"{site_info.get('code', 0)} | {name} | {bio} | {site_info.get('url', '')} |"
)
lines.append("")
path.write_text("\n".join(lines), encoding="utf-8")
# --- graph exports ----------------------------------------------------
@staticmethod
def _graph_model(results_data: dict[str, Any]) -> dict[str, Any]:
"""Build (nodes, edges) from Found/Maybe accounts + correlation clusters."""
nodes: dict[str, dict[str, Any]] = {}
edges: list[dict[str, str]] = []
variations = results_data.get("variations", {})
for variation, block in variations.items():
has_hit = False
for site, info in (block.get("sites", {}) or {}).items():
if info.get("status") not in {"Found", "Maybe"}:
continue
has_hit = True
acct = f"{variation}:{site}"
nodes[acct] = {"label": site, "type": "account", "url": info.get("url", "")}
edges.append({"source": variation, "target": acct, "label": "has-account"})
if has_hit:
nodes[variation] = {"label": variation, "type": "username", "url": ""}
for cluster in results_data.get("correlation", {}).get("clusters", []):
members = [m["variation"] + ":" + m["site"] for m in cluster.get("members", [])]
reason = ",".join(cluster.get("reasons", [])) or "same-person"
for i in range(len(members)):
for j in range(i + 1, len(members)):
if members[i] in nodes and members[j] in nodes:
edges.append({"source": members[i], "target": members[j], "label": reason})
return {"nodes": nodes, "edges": edges}
def _write_gexf(self, path: Path, results_data: dict[str, Any]) -> None:
model = self._graph_model(results_data)
ids = {name: str(i) for i, name in enumerate(model["nodes"])}
node_xml = "".join(
f'<node id="{ids[name]}" label="{_esc(data["label"], quote=True)}"/>'
for name, data in model["nodes"].items()
)
edge_xml = "".join(
f'<edge id="{i}" source="{ids[e["source"]]}" target="{ids[e["target"]]}" '
f'label="{_esc(e["label"], quote=True)}"/>'
for i, e in enumerate(model["edges"])
if e["source"] in ids and e["target"] in ids
)
xml = (
'<?xml version="1.0" encoding="UTF-8"?>\n'
'<gexf xmlns="http://gexf.net/1.3" version="1.3">\n'
'<graph defaultedgetype="undirected">\n'
f"<nodes>{node_xml}</nodes>\n<edges>{edge_xml}</edges>\n"
"</graph>\n</gexf>\n"
)
path.write_text(xml, encoding="utf-8")
def _write_maltego(self, path: Path, results_data: dict[str, Any]) -> None:
model = self._graph_model(results_data)
with path.open("w", newline="", encoding="utf-8") as handle:
writer = csv.writer(handle)
writer.writerow(["SourceEntity", "SourceType", "TargetEntity", "TargetType", "Relationship"])
for e in model["edges"]:
src = model["nodes"].get(e["source"], {})
tgt = model["nodes"].get(e["target"], {})
if not src or not tgt:
continue
writer.writerow([
e["source"], "maltego.Affiliation" if src.get("type") == "account" else "maltego.Alias",
e["target"], "maltego.Affiliation" if tgt.get("type") == "account" else "maltego.Alias",
e["label"],
])
def _write_mermaid(self, path: Path, results_data: dict[str, Any]) -> None:
model = self._graph_model(results_data)
ids = {name: f"n{i}" for i, name in enumerate(model["nodes"])}
lines = ["```mermaid", "graph TD"]
for name, data in model["nodes"].items():
label = data["label"].replace('"', "'")
shape = f'(["{label}"])' if data["type"] == "username" else f'["{label}"]'
lines.append(f" {ids[name]}{shape}")
for e in model["edges"]:
if e["source"] in ids and e["target"] in ids:
lines.append(f" {ids[e['source']]} -- {e['label']} --- {ids[e['target']]}")
lines.append("```")
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def _write_pdf(self, path: Path, results_data: dict[str, Any]) -> bool:
"""Investigator PDF report. Returns False (with a note) if reportlab is missing."""
try:
from aliens_eye.core.pdf_report import write_pdf
except ImportError:
self.console.print(
"[yellow]PDF export needs reportlab: pip install \"aliens-eye\\[pdf]\"[/yellow]"
)
return False
write_pdf(path, results_data)
return True
def display_results_from_file(self, file_path: str) -> None:
try:
with open(file_path, encoding="utf-8") as handle:
data = json.load(handle)
except FileNotFoundError:
self.console.print(f"[red]File not found: {file_path}[/red]")
return
except json.JSONDecodeError:
self.console.print(f"[red]Invalid JSON file: {file_path}[/red]")
return
if "scan_summary" not in data or "variations" not in data:
self.console.print(f"[red]Unrecognized results file: {file_path}[/red]")
return
summary = data["scan_summary"]
body = (
f"[blue]Base username:[/blue] [bold yellow]{summary.get('base_username', 'Unknown')}[/bold yellow]\n"
f"[blue]Scan level:[/blue] {summary.get('scan_level', 'Unknown')}\n"
f"[blue]Variations:[/blue] {summary.get('total_variations', 0)} "
f"[blue]Sites scanned:[/blue] {summary.get('total_sites_scanned', 0)}\n"
f"[bold green]Found: {summary.get('total_found', 0)}[/bold green] "
f"[green]High confidence: {summary.get('total_high_confidence', 0)}[/green]"
)
self.console.print(Panel(body, title="Scan Results", border_style="green"))
best = summary.get("best_variations", [])
if best:
self.console.print("[blue]Best variations:[/blue]")
for username, count in best:
self.console.print(f" [yellow]{username}[/yellow]: [green]{count} profiles found[/green]")
names = list(data["variations"].keys())
self.console.print("\n[blue]Available variations:[/blue]")
for i, username in enumerate(names, 1):
self.console.print(f" {i}. [yellow]{username}[/yellow]")
choice = Prompt.ask(
"\nEnter number for details ('all' for all, Enter to exit)",
default="",
console=self.console,
).strip()
if choice.lower() == "all":
for username, variation_data in data["variations"].items():
self._display_variation_results(username, variation_data)
elif choice.isdigit():
idx = int(choice) - 1
if 0 <= idx < len(names):
self._display_variation_results(names[idx], data["variations"][names[idx]])
def _display_variation_results(self, username: str, variation_data: dict[str, Any]) -> None:
scan_info = variation_data.get("scan_info", {})
body = (
f"[bold green]Found: {scan_info.get('found', 0)}[/bold green] "
f"[yellow]Maybe: {scan_info.get('maybe', 0)}[/yellow] "
f"[red]Not Found: {scan_info.get('not_found', 0)}[/red] "
f"[dim]Errors: {scan_info.get('errors', 0)}[/dim]"
)
self.console.print(Panel(body, title=f"Variation: {username}", border_style="blue"))
rows = [
{
"site": site,
"status": info.get("status", "Unknown"),
"confidence": info.get("confidence", 0),
"code": info.get("code", 0),
"url": info.get("url", ""),
"response_time": info.get("response_time", 0),
}
for site, info in variation_data.get("sites", {}).items()
]
rows.sort(
key=lambda r: (
{"Found": 0, "Maybe": 1, "Not Found": 2}.get(r["status"], 3),
-r["confidence"],
)
)
self.console.print(build_results_table(rows))