1  # Crow - Blackbird GUI Frontend
  2  
  3  A PyQt6-based graphical user interface for the Blackbird OSINT tool, providing an intuitive way to conduct username and email investigations across multiple platforms.
  4  
  5  ## Features
  6  
  7  - **User-Friendly Interface**: Easy-to-use GUI for Blackbird OSINT operations
  8  - **Multiple Input Methods**: Support for direct username/email input and file-based inputs
  9  - **Advanced Search Options**: Permutation, filtering, and AI-powered analysis
 10  - **Flexible Output Formats**: CSV, PDF, JSON, verbose logs, and HTML dumps
 11  - **Session Management**: Save and load search configurations
 12  - **Real-time Output**: Live monitoring of search progress and results
 13  - **Instagram Integration**: Enhanced metadata extraction with session ID
 14  - **AI Analysis**: Automated profile analysis and risk assessment
 15  
 16  ## Installation
 17  
 18  ### Prerequisites
 19  
 20  1. Python 3 or higher
 21  2. Blackbird OSINT tool (must be in the same directory)
 22  3. Required Python packages:
 23  
 24  ```
 25  pip install -r requirements_GUI.txt
 26  ```
 27  
 28  ## Python
 29  
 30  ### Arch users
 31  
 32  ### Python 311
 33  
 34  ```
 35  yay -S python311
 36  ```
 37  
 38  ### Python 312
 39  
 40  ```
 41  yay -S python312
 42  ```
 43  
 44  ### Installs:
 45  
 46  In one command:
 47  
 48      git clone https://github.com/p1ngul1n0/blackbird.git && git clone https://github.com/airborne-commando/crow.git && mv crow/*.txt ./blackbird/ && mv crow/*.py ./blackbird/ && cd ./blackbird/ && python3 -m venv venv && source venv/bin/activate && pip3 install -r requirements.txt && pip3 install -r requirements_GUI.txt
 49  
 50  
 51  ### python311
 52  
 53      git clone https://github.com/p1ngul1n0/blackbird.git && git clone https://github.com/airborne-commando/crow.git && mv crow/*.txt ./blackbird/ && mv crow/*.py ./blackbird/ && cd ./blackbird/ && python3.11 -m venv venv && source venv/bin/activate && pip3 install -r requirements.txt && pip3 install -r requirements_GUI.txt
 54  
 55  ### python312
 56  
 57      git clone https://github.com/p1ngul1n0/blackbird.git && git clone https://github.com/airborne-commando/crow.git && mv crow/*.txt ./blackbird/ && mv crow/*.py ./blackbird/ && cd ./blackbird/ && python3.12 -m venv venv && source venv/bin/activate && pip3 install -r requirements.txt && pip3 install -r requirements_GUI.txt
 58  
 59  
 60  ### For the dev-tor:
 61  
 62        git clone https://github.com/p1ngul1n0/blackbird.git && git clone --branch dev-tor --single-branch https://github.com/airborne-commando/crow.git && mv crow/*.txt ./blackbird/ && mv crow/*.py ./blackbird/ && cd ./blackbird/ && python3 -m venv venv && source venv/bin/activate && pip3 install -r requirements.txt && pip3 install -r requirements_GUI.txt
 63  
 64  ### File Structure
 65  
 66  Ensure the following files are in your working directory:
 67  
 68  ```
 69  project/
 70  ├── crow.py                 # Main GUI application
 71  ├── build_blackbird_command.py  # Command builder utility
 72  ├── save_settings.py        # Settings save functionality
 73  ├── load_settings.py        # Settings load functionality
 74  ├── requirements_GUI.txt # GUI requirements
 75  ├── tor_api_setup.py # Tor functions
 76  ├── tor_hook.py
 77  ├── tor_spoofing.py
 78  └── blackbird.py           # Blackbird OSINT tool (required)
 79  ```
 80  
 81  ### Tor Usage:
 82  
 83  Can Bypass daily limits on AI summary, but the password is hard coded, you'll need to edit this value inside tor_spoofing.py:
 84  
 85  ## Edit these values
 86  
 87          class TORSpoofer:
 88              def __init__(self, gui_instance=None):
 89                  self.gui_instance = gui_instance
 90                  self.tor_enabled = False
 91                  self.tor_session = None
 92                  self.tor_port = 9050  # Default TOR port
 93                  self.control_port = 9051  # Default control port
 94                  self.tor_password = "hashbrownyummy"  # ← SET YOUR PASSWORD HERE
 95  
 96  you'll need to also install tor inside your system and do the following.
 97  
 98  ### Password gen example
 99  
100        tor --hash-password hashbrownyummy
101  
102  New value of hashbrownyummy
103  
104        16:173F2CE915F54E88606A84E39D3750633B34E57F384910306004433BE9
105  
106  Then edit, uncomment HashedControlPassword and ControlPort:
107  
108  **sudo nano /etc/tor/torrc**
109  
110        #ControlPort 9051
111        ## If you enable the controlport, be sure to enable one of these
112        ## authentication methods, to prevent attackers from accessing it.
113        #HashedControlPassword 16:173F2CE915F54E88606A84E39D3750633B34E57F384910306004433BE9
114        #CookieAuthentication 1
115  
116  Restart the tor service with **sudo systemctl restart tor**
117  
118  Be sure to enable and start
119  
120  ## Usage
121  
122  ### Basic Operation
123  
124  1. **Launch the Application**:
125     ```
126     python crow.py
127     ```
128  
129  2. **Input Targets**:
130     - Enter usernames in the "Username(s)" field (comma-separated for multiple)
131     - Enter emails in the "Email(s)" field (comma-separated for multiple)
132     - Or select files containing lists of usernames/emails
133  
134  3. **Configure Options**:
135     - **Permutation**: Generate username variations (requires single username)
136     - **AI Analysis**: Enable AI-powered metadata extraction (requires API key setup)
137     - **Output Formats**: Select desired output formats (CSV, PDF, JSON, etc.)
138     - **Filters**: Apply custom search filters
139     - **Proxy**: Configure proxy settings for requests
140     - **Timeout**: Set request timeout in seconds
141  
142  4. **Execute Search**:
143     - Click "Run Blackbird" to start the investigation
144     - Monitor real-time progress in the output area
145     - Use "Stop Blackbird" to cancel ongoing searches
146  
147  ### Advanced Features
148  
149  #### AI Analysis Setup
150  
151  1. Click "Setup API Key" to configure AI analysis
152  2. Follow the automated setup process
153  3. API key is automatically saved and loaded for future sessions
154  
155  #### Instagram Enhanced Metadata
156  
157  1. Obtain Instagram Session ID:
158     - Log into Instagram in your browser
159     - Open Developer Tools (F12)
160     - Go to Application > Cookies
161     - Copy the "sessionid" cookie value
162  2. Paste the Session ID in the dedicated field
163  3. Enhanced metadata will be extracted during searches
164  
165  #### Custom Filters
166  
167  Create advanced search filters using properties and operators:
168  
169  **Properties**: `name`, `cat`, `uri_check`, `e_code`, `e_string`, `m_string`, `m_code`
170  
171  **Operators**: `=`, `~`, `>`, `<`, `>=`, `<=`, `!=`
172  
173  **Examples**:
174  - `name~Mastodon` - Sites containing "Mastodon" in name
175  - `e_code>200` - Sites with error codes greater than 200
176  - `cat=social and uri_check~101010` - Social sites with specific URI patterns
177  
178  #### Permutation Options
179  
180  - **Permute Username**: Generates common variations of a single username
181  - **Permute All**: Creates broader permutations including sub-components
182  
183  ## Configuration
184  
185  ### Settings Management
186  
187  - **Save Settings**: Store current configuration to JSON file
188  - **Load Settings**: Restore previous configuration from JSON file
189  
190  Saved settings include:
191  - Input fields (usernames, emails, filters)
192  - Checkbox states (options, output formats)
193  - API keys and session IDs
194  - Proxy and timeout configurations
195  
196  ### Environment Variables
197  
198  The application automatically manages:
199  - `INSTAGRAM_SESSION_ID`: For enhanced Instagram metadata
200  - `BLACKBIRD_AI_API_KEY`: For AI analysis functionality
201  
202  ## Output Handling
203  
204  ### Real-time Monitoring
205  
206  - Live output display with formatted AI results
207  - Automatic scrolling to latest content
208  - Color-coded and emoji-enhanced status messages
209  
210  ### Auto-save Features
211  
212  - AI analysis results automatically saved to timestamped files
213  - Files named: `blackbird_ai_{target}_{timestamp}.txt`
214  - Includes comprehensive analysis reports with timestamps
215  
216  ### File Outputs
217  
218  Based on selected options, generates:
219  - **CSV**: Structured results data
220  - **PDF**: Formatted reports
221  - **JSON**: Machine-readable results
222  - **HTML Dumps**: Raw page content
223  - **Verbose Logs**: Detailed process information
224  
225  ## Troubleshooting
226  
227  ### Common Issues
228  
229  1. **Blackbird Not Found**: Ensure `blackbird.py` is in the same directory
230  2. **AI Analysis Fails**: Verify API key setup and internet connectivity
231  3. **Instagram Metadata Issues**: Check session ID validity and login status
232  4. **Permission Errors**: Ensure write permissions for output files
233  
234  ### Help System
235  
236  Comprehensive help buttons (`?`) provide detailed information about:
237  - AI analysis capabilities and limitations
238  - Permutation examples and patterns
239  - Filter syntax and examples
240  - Instagram session ID acquisition
241  
242  ## Word filter gen for blackbird.
243  
244  A bare bones GUI for word filtering, should make it easier, comes with an analysis to see which json file (user) is affected by which site and category.
245  
246  ## An example:
247  
248  > "cat!=health and cat!=video and cat!=political and cat!=shopping and cat!=business and cat!=coding and cat!=blog and cat!=misc and cat!=hobby and cat!=gaming and cat!=tech and cat!=art ..."
249  
250  You get the idea..
251  
252  It can also generate, order, exclude and include filters and also include custom filters.
253  
254  ## Will not work with sites with spaces that are multiple. Will error out on blackbirds end, sort out manually.
255  
256  >"cat!=health and cat!=video and cat!=political and cat!=shopping and name!='Twitter archived tweets' and name!='Parler archived posts'"
257  
258  Use the analysis tool to figure out which site is affecting which user, do a few runs; also manually edit the json files if you must.
259  
260  ## Procedure:
261  
262  What I usually do is do a dry run and filter stuff out that way, it takes time but it's a bit more accurate with results. I also use a username file.
263  
264  you can use the CLI version of blackbird or the GUI, whichever works.
265  
266  Copy to clipboard WILL not copy the generated filter, you'll need to select the generated filters and do ctrl+c. copy to clipboard simply copies the current filters that are excluded or included. There is no automatic ordering, do so manually.
267  
268  ## Dependencies (not for word filter)
269  
270  - PyQt6 >= 6.0.0
271  - requests >= 2.25.0
272  - Blackbird OSINT tool
273  
274  ## License
275  
276  This project is designed as a frontend for the [Blackbird OSINT tool](https://github.com/p1ngul1n0/blackbird/tree/main). Please ensure compliance with Blackbird's license terms and applicable laws when conducting investigations.
277  
278  ## Contributing
279  
280  This is a GUI wrapper for the Blackbird tool. For issues related to the core OSINT functionality, refer to the main [Blackbird repository](https://github.com/p1ngul1n0/blackbird/tree/main).
281  
282  ---
283  
284  **Note**: Always use OSINT tools responsibly and in compliance with applicable laws, terms of service, and ethical guidelines.