Hist-Recon

Hist-Recon is a lightweight browser history analyzer for cyber-forensics style workflows. It focuses on fast, local parsing of browser history SQLite databases (starting with Chromium-based browsers) and producing investigator-friendly exports (JSON or CSV).

Features

• Extract visit records from Chromium/Chrome/Edge history databases.
• Normalized data model with timestamps, titles, URLs, visit counts, and profile labels.
• Safe parsing: copies locked databases to a temp file before reading.
• Export to JSON or CSV for downstream timelines or reports.
• CLI with clear subcommands and flags for quick use.

Project layout

• src/histrecon/cli.py — entrypoint for the CLI.
• src/histrecon/chromium.py — Chromium/Chrome/Edge history parser.
• src/histrecon/reporters.py — JSON/CSV exporters.
• src/histrecon/models.py — shared data structures.
• src/histrecon/utils.py — utilities (e.g., safe SQLite copying).
• tests/ — small sanity tests.

Quick start

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m src.histrecon.cli --help

Run manual (step-by-step)

1. Close Chrome/Chromium to avoid DB locks.
2. (Recommended) Copy the DB to a temp location so the original stays untouched:

   cp ~/.config/google-chrome/Default/History /tmp/histrecon_history
   # or for Chromium:
   # cp ~/.config/chromium/Default/History /tmp/histrecon_history

3. JSON export:

   python -m src.histrecon.cli \
     --browser chromium \
     --db /tmp/histrecon_history \
     --profile "Default" \
     --out visits.json \
     --format json

4. CSV export:

   python -m src.histrecon.cli \
     --browser chromium \
     --db /tmp/histrecon_history \
     --profile "Default" \
     --out visits.csv \
     --format csv

5. Inspect output:

   head -n 5 visits.json
   head -n 5 visits.csv

Notes and limitations

• Only Chromium-style history is implemented currently; Firefox/SQLite schema support can be added later.
• The tool reads from a temp copy of the DB; original files are untouched.
• Timestamps are normalized to UTC ISO-8601.

Contributing / next steps

• Add Firefox support by parsing places.sqlite.
• Enrich records with visit source (typed, link, reload) when available.
• Add HTML reporting with simple timelines.