A Python script to analyze Brave browser history for workplace investigations. Generates an interactive HTML report with charts and tables categorizing browsing behavior, detecting inappropriate content, and highlighting work vs. non-work activity.
- Features
- Prerequisites
- Installation
- Data Acquisition
- Usage
- Examples
- Configuration & Customization
- Output
- Contributing
- License
- Parses Brave
HistorySQLite database and extracts URLs with timestamps - Categorizes visits into work, social media, streaming, shopping, gaming, news, adult, and more
- Flags potentially inappropriate content based on keyword matching
- Marks visits occurring within specified work days/hours
- Generates an interactive HTML report with:
- Executive summary
- Pie charts & bar plots
- Tables of flagged URLs
- Sub-tabs for non-work activity during work hours
- Supports user-defined custom categories and work-keywords
- Python 3.8+
- A Brave
HistorySQLite file (typically located in your profile directory) - Access to the
urlstable in theHistorydatabase
-
Clone the repository
git clone https://github.com/clearnetlabs/octorecon.git cd octorecon -
Create a virtual environment (optional but recommended)
python3 -m venv venv source venv/bin/activate -
Install dependencies
pip install -r requirements.txt
requirements.txt should include:
pandas matplotlib seaborn pytz
-
Navigate to your Brave profile directory. Common paths:
- macOS/Linux:
~/.config/BraveSoftware/Brave-Browser/Default/History - Windows:
%USERPROFILE%\AppData\Local\BraveSoftware\Brave-Browser\User Data\Default\History
- macOS/Linux:
-
Copy or link the
Historyfile and rename it (e.g.,History-BRAVE). -
Export the
urlstable to CSV:sqlite3 -header -csv History-BRAVE "SELECT * FROM urls;" > urls.csv
If you’re conducting a pentest and need to pull the History file over SMB:
smbclient \\\\10.10.10.1\\C$ -U 'contorso.com/username'Once connected:
cd "Users/TargetUser/AppData/Local/BraveSoftware/Brave-Browser/User Data/Default"
get History-BRAVE
exitThen export to CSV as above:
sqlite3 -header -csv History-BRAVE " SELECT * FROM urls;" > urls.csv./octorecon.py urls.csv \
--starttime 09:00 \
--endtime 17:00 \
--days M,T,W,Th,F \
--work-keywords "mycorp.com,jira,salesforce" \
--custom-categories "internalapp(work),companycars(auto)" \
--output browser_history_report.html-
csv_file
Path to the CSV file exported from the Braveurlstable. -
--starttime(default:09:00)
Workday start time ("9am","09:00","13", etc.). -
--endtime(default:17:00)
Workday end time ("5pm","17:00","17", etc.). -
--days(default:M,T,W,Th,F)
Comma-separated work days (M,T,W,Th,F,Sa,Su). -
--work-keywords
Comma-separated domains/keywords to force into the “work” category. -
--custom-categories
User-defined categories in the format
keyword1(categoryA),keyword two(categoryB) -
--output(default:browser_history_report.html)
Name of the generated HTML report. -
--diagnose
Print diagnostic info for the first few rows and exit.
-
Basic run with defaults
./octorecon.py urls.csv
-
Custom work hours and days
./octorecon.py urls.csv \ --starttime 08:30 \ --endtime 18:00 \ --days M,T,W,Th,F,Sa
-
Adding work keywords & custom categories
./octorecon.py urls.csv \ --work-keywords "vpn.mycorp.com,docs.mycorp.com" \ --custom-categories "internaltool(work),leasing(auto)"
- Whitelist Domains: Adjust
COMMON_LEGIT_DOMAINS_WHITELISTin the script. - Category Patterns: Modify the
self.patternsdictionary for additional domains/patterns. - Inappropriate Keywords: Edit the
self.inappropriate_keywordsset to tune sensitivity. - Charts & Styling: Tweak
matplotlib/seabornsettings ingenerate_report().
- HTML Report: Interactive file showing summary, visuals, and tables.
- Charts PNG: Saved as
browser_analysis_charts.pngalongside the report.
- Fork the repo.
- Create a branch:
git checkout -b feature/<your-feature>
- Make your changes & add tests.
- Submit a Pull Request describing your enhancements.
Please follow the existing code style and include documentation for any new features.
This project is licensed under the Apache2.0 License. See LICENSE for details.