AI-powered Facebook SOCMINT platform — 100% local, zero cloud dependency. For lite version check this repo click here
Installation · Troubleshooting · Disclaimer . Contributing
- 🔍 Profile collection — Automated data gathering of posts, photos, reels, about data also comments, commentors profile link and name
- 🧠 Interaction intelligence — AI sentiment, stance, emotion, and language analysis per interaction
- 📊 Actor scoring — Weighted composite score with 5-tier classification system
- 🌍 Country detection — LLM identifies country of origin from profile signals
- 👤 Face intelligence — Face detection, 128D encoding, and identity clustering across all images. It uses HOG model.
- 🕸️ Network graphs — Interactive HTML graphs including force-directed and co-interactors relationship matrix
- 📄 PDF reports — Professional intelligence report with limited ammount of charts
- 🤖 Local AI — Ollama powered, gemma3:4b/12b/27b and other models(mention in web panel), runs on GPU or CPU
- 🐳 Docker ready — One command deployment on Linux and Windows
Full usage guides for both investigation modes are available on the project website:
BIRDY-EDWARDS is developed strictly for authorized intelligence, law enforcement, and academic research purposes only.
Scope of data access:
- This tool operates exclusively using a valid Facebook session authenticated by the operator
- It only accesses publicly visible profile data, posts, photos, reels, and comments
- It does not access private messages, locked profiles, restricted content, or any data not visible to a logged-in user
- It does not use bots, fake accounts, or automated account creation — the operator supplies their own authenticated session
Legal responsibility:
- This tool must only be used on profiles and content where you have explicit legal authorization to collect and analyze data
- Use without authorization may violate Facebook's Terms of Service, applicable privacy laws (GDPR, IT Act, DPDP Act), and local regulations
- The developer assumes no liability for misuse, unauthorized data collection, or any harm caused by improper use
- All investigations are the sole responsibility of the operator
By using BIRDY-EDWARDS, you confirm that your use is lawful, authorized, and compliant with all applicable laws in your jurisdiction.
| Component | Minimum | Recommended |
|---|---|---|
| OS | Ubuntu 24.04 LTS / Windows 10+ | Ubuntu 24.04 LTS |
| RAM | 8 GB | 16 GB |
| Storage | 20 GB free | 40 GB free |
| Docker | Docker Desktop / Engine | Latest stable |
| Ollama | Latest | Latest |
Step 1 — Install Docker
- Linux: https://docs.docker.com/engine/install/ubuntu/
- Windows: https://docs.docker.com/desktop/install/windows-install/
Step 2 — Install Ollama
- Linux:
curl -fsSL https://ollama.com/install.sh | sh- Windows: Download installer from https://ollama.com/download
Step 3 — Start Ollama bound to all interfaces
- Linux:
OLLAMA_HOST=0.0.0.0:11434 ollama serveTo make this permanent:
sudo systemctl edit ollamaAdd:
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"sudo systemctl daemon-reload && sudo systemctl restart ollama- Windows: Ollama listens on all interfaces by default — no extra configuration needed. If no then,
$env:OLLAMA_HOST="0.0.0.0"
ollama serveStep 1 — Clone the repository
git clone https://github.com/jeet-ganguly/birdy-edwards.git
cd birdy-edwardsStep 2 — Create required files and directories
- Linux:
mkdir -p app/reports app/face_data app/post_screenshots app/status
touch app/fb_cookies.pkl app/socmint.db app/socmint_manual.db app/.ollama_model- Windows (PowerShell):
New-Item -ItemType Directory app/reports, app/face_data, app/post_screenshots, app/status
New-Item -ItemType File app/fb_cookies.pkl, app/socmint.db, app/socmint_manual.db, app/.ollama_modelStep 3 — Build the Docker image
⚠️ First build takes 15–25 minutes — dlib compiles from source. Subsequent builds are fast (layers cached).
docker compose buildStep 4 — Start the container
docker compose up -d
docker compose logs -fStep 5 — Open the web UI
http://localhost:5000
Step6 - Import session cookies
http://localhost:5000/tools/import-cookies
Pull a model on your host machine:
ollama pull gemma3:4bOr use the AI Model panel in the web UI — select a model and click Apply & Pull.
| RAM | Recommended Model |
|---|---|
| 8 GB | gemma3:4b |
| 16 GB | gemma3:12b |
| 32 GB | gemma3:27b |
BIRDY-EDWARDS requires a valid Facebook session. Use the Cookie-Editor browser extension — works on all platforms, no Selenium required.
🔒 Operational Security: It is strongly recommended to use a dedicated burner account for investigations rather than your personal Facebook account. This protects your identity and prevents your primary account from being flagged or restricted.
- Install Cookie-Editor → Chrome · Firefox
- Log into your dedicated investigation account on Facebook
- Click Cookie-Editor while on facebook.com
- Click Export → Export as JSON
- Go to
http://localhost:5000/tools/import-cookiesand paste
If you find BIRDY-EDWARDS useful or interesting, here are a few ways you can support the project:
- ⭐ Star the repository — it helps others discover the tool
- 🐛 Report bugs — open an Issue if something isn't working
- 🔧 Contribute — check the Contributing section to get started
- 📢 Share it — post it in OSINT communities, forums, X or with colleagues who might find it useful
- 💬 Give feedback — suggestions for new features or improvements are always welcome
Every contribution, big or small, helps build better tools for the OSINT and threat intelligence community.
Ollama not reachable from Docker
docker exec -it birdy-edwards curl http://host.docker.internal:11434/api/tagsIf it fails, restart Ollama with OLLAMA_HOST=0.0.0.0:11434 ollama serve
DB error: no such table or other DB related error
Start a new investigation — schema is created automatically on first use. If you stop process/program during analysis delete that investigation and then start new investigation.
Cookies expired
Go to http://localhost:5000/tools/import-cookies and re-import fresh cookies.
Port 5000 already in use
Change in docker-compose.yml: "5001:5000" then access at http://localhost:5001
Out of memory during build
Increase Docker Desktop memory to 8 GB+ via Settings → Resources → Memory
Contributions are welcome. Please follow these guidelines to keep the project clean and consistent.
Reporting bugs
- Open an Issue describing the bug, steps to reproduce, and your environment (OS, RAM, Docker version)
- Attach relevant logs from
docker compose logs
Feature requests
- Open an Issue with a clear description of the feature and its use case
- Discuss before opening a Pull Request for large changes
Submitting a Pull Request
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature-name - Commit your changes:
git commit -m "Add: short description" - Push to your branch:
git push origin feature/your-feature-name - Open a Pull Request against
main
Code guidelines
- Follow existing code style — Python 3.12, Flask conventions
- Test your changes locally via Docker before submitting
- Do not commit
fb_cookies.pkl, databases, or any scraped data - Keep scraper changes minimal — Facebook DOM changes frequently
What we welcome
- Bug fixes and stability improvements
- New Ollama model support
- UI improvements
- Documentation improvements
- Additional language support for OCR and comment analysis
What we do not accept
- Features that bypass platform security controls
- Changes that introduce cloud dependencies
- Code that stores or transmits investigation data externally
- Inspired by Sherlock
- Inspired by the OSINT and threat intelligence research community
- SeleniumBase — Undetected Chrome automation
- Ollama — Local LLM inference engine
- face_recognition — Face detection and encoding library
- pyvis — Interactive network graph visualization
- reportlab — PDF generation
- pytesseract — OCR engine wrapper
BIRDY-EDWARDS · Infiltrate & Expose ·