The Problem

Finding a user’s accounts across dozens of social‑media sites is tedious and error‑prone. Analysts must manually craft URLs, handle site‑specific quirks, and sanitize input filenames. A repeatable, language‑aware scanner saves time and reduces false‑positives.

What This Does

Tookie‑OSINT reads a username (or list) and probes a curated set of sites (see sites/sites.json). Core logic lives in modules/modules.py, which defines the public helpers _safe_filename, load_sites, load_fields, and get_info. Language‑specific output strings are kept under lang/ (e.g., lang/en.py). The modules/webscraper.py driver wraps Selenium for sites that require JavaScript, while modules/fancy.py provides a simple banner (logo). Tests for filename sanitisation live in test_safe_filename.py.

How It Is Wired

  1. Entry point (implicit) – The repository does not ship a dedicated CLI script; typical usage imports modules.modules and calls get_info(username).
  2. get_info (modules/modules.py) – Called by the UI or a wrapper script; it loads site definitions (load_sites), field mappings (load_fields), then iterates over each site, delegating to scan_site (internal) which may invoke the Selenium driver in modules/webscraper.py.
  3. File I/O – _safe_filename (modules/modules.py) is the only routine that touches the filesystem (used by write_txt, write_csv, write_json). It is called from nine locations, making it the highest‑blast‑radius function for file writes.
  4. Network I/O – scan_site ultimately calls check_site (modules/webscraper.py) which performs HTTP requests or Selenium navigation; four functions across the repo make outbound calls.
  5. Call density – The internal call graph shows 33 resolved edges. logo (modules/fancy.py) is a leaf; modules/modules.py imports three other modules and is imported by two, giving it an instability of 0.25. No circular dependencies exist, simplifying future refactors.

Overall flow: user input → _safe_filename (sanitise) → load_sites/load_fields → get_info → per‑site scan_site → optional Selenium driver → result aggregation → optional file export.

How To Use It

# Clone the upstream repository
git clone https://github.com/moses-y/tookie-osint.git
cd toOKIE-osint

# Install Python dependencies (requires Python 3.12)
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration – Site metadata lives in sites/sites.json; no environment variables are required out of the box.

Running – From a Python interpreter:

from modules.modules import get_info

result = get_info("alice")
print(result)

If a Selenium‑based scan is needed, ensure a compatible driver is on the PATH; the driver is obtained via modules/webscraper.get_driver().

Real‑World Use

A red‑team script can import get_info to bulk‑check a list of candidate usernames and write the findings to CSV:

from modules.modules import get_info, write_csv

users = ["alice", "bob", "charlie"]
records = [get_info(u) for u in users]
write_csv("report.csv", records)

This integrates with existing reporting pipelines without additional wrappers.

Code Health & Issues

  • HIGH – No CI pipeline – 23 source files, no .github/workflows or other CI config. Fix: add a GitHub Actions workflow that runs pytest (or the existing test file) on push and pull_request.
  • MEDIUM – No Dependabot – Only requirements.txt is present; no lockfile or automated update bot. Fix: add .github/dependabot.yml for the pip ecosystem.
  • MEDIUM – Broad exception handling – modules/modules.py uses a bare except: that swallows errors. Fix: catch specific exceptions and re‑raise or log.
  • MEDIUM – Deep nesting (up to 6 levels) – In modules/webscraper.py, brib.py, and modules/fancy.py control flow is heavily nested, hurting readability. Fix: refactor with early returns or helper functions.
  • MEDIUM – Duplicated language blocks – Similar 6‑line snippets appear in multiple lang/*.py files. Fix: extract shared helpers into a common module.

No secrets were found, a license file exists, and a single test (test_safe_filename.py) provides basic coverage.

The Bottom Line

Tookie‑OSINT delivers a usable, language‑aware OSINT scanner with clear separation of site data, language strings, and scraping logic. It is functional but lacks a defined CLI entry point, automated testing, and robust error handling. Engineers comfortable with Python can adopt it quickly, but should add CI, tighten exception handling, and refactor deep nesting before using it in production pipelines.