How p1ngul1n0/blackbird works
Project type and purpose
• Blackbird is an open-source, Python-based CLI OSINT tool that performs fast username/email lookups across 600+ platforms (via WhatsMyName integration) and enriches results with AI-powered profiling.
• It has no persistent database; results are exported to disk (JSON, CSV, PDF). AI integration calls an external model.
File structure
• Top-level
• blackbird.py ← CLI entrypoint
• src/config.py ← configuration & API key management
• src/modules/ ← core logical layers
• Dockerfile, requirements.txt, tests/, docs/, .github/
• src/modules breakdown
• ai/ ← AI client & key manager
• core/ ← orchestrator for email/username workflows
• sites/ ← per-site lookup adapters (e.g. instagram.py)
• whatsmyname/ ← integration with community-driven site list
• export/ ← JSON/CSV/PDF/file utilities
• utils/ ← HTTP client, parsing, filtering, logging, input handling
• Tests mirror core and export functionality.
README for additional insights
• Describes CLI flags (--username, --email, --ai, --pdf)
• AI engine is free, only sends site names
• Integrates with external WhatsMyName project for 600+ sites
Main components
A. User & CLI Layer
• User invokes python blackbird.py with flags
• CLI Parser & Argument Handler
B. Orchestrator (core modules)
• UsernameSearch / EmailSearch controllers
• Pre-check & filter pipeline
C. Site Lookup Adapters
• modules/sites/*.py
• modules/whatsmyname for dynamic site list
D. AI Profiling
• modules/ai/client.py ← calls external AI service
• modules/ai/key_manager.py
E. Export Layer
• JSON, CSV, PDF generators (modules/export/*.py)
• file_operations for write/read
F. Utilities
• HTTP client, parsing, logging, hashing, user-agent rotation
G. External Services
• 600+ target websites
• AI engine (e.g., OpenAI or custom)
H. File System
• config file (~/.blackbird/config or env)
• output directory for exports
I. CI/CD & Documentation (side view)
• GitHub Actions (python-test, auto-close issues)
• Dockerfile for containerization
• GitBook docs
Relationships & data flows
1. CLI → Orchestrator
2. Orchestrator → Pre-check util → chooses EmailSearch or UsernameSearch
3. Search workflows → for each site adapter:
a. utils/http_client → send request → utils/parse → filter → result
4. (Optional) Orchestrator → AI client → external AI service → AI profile
5. Results + AI profile → Export layer → write JSON/CSV/PDF → File System
6. User retrieves files
Architectural patterns & design principles
• Layered architecture: CLI → service layer (core) → adapter layer (sites, AI) → I/O layer (export, fs)
• Plugin/adapter pattern for adding new site modules
• Utility modules for cross-cutting concerns (HTTP, logging, parsing)
• Separation of concerns: core logic vs. I/O vs. external integrations
Technologies & frameworks
• Python 3.x
• pip & requirements.txt
• Docker for containerization
• GitHub Actions for testing & workflows
• PDF generation library (e.g., ReportLab) in modules/export/pdf.py
• External AI API (e.g., OpenAI)
• WhatsMyName community library integration
Detail
• Config & key management as a separate component