Hellobird v1

.gitignore

@@ -0,0 +1 @@
+venv/

DEVLOG.md

@@ -0,0 +1,128 @@
+# DEVLOG: HelloBird v1.1
+
+## Project Overview
+
+This document outlines the development process for HelloBird v1.1, a web-based wrapper for the CamXploit CCTV reconnaissance tool. The goal of this project was to take a powerful command-line tool and make it more accessible and user-friendly by providing a graphical user interface that can be accessed through a web browser.
+
+This project is designed to be developed in a fork of the original [CamXploit repository](https://github.com/spyboy-productions/CamXploit). This allows for a clean separation between the original tool and the web-based wrapper, and it gives the user full ownership and control over their own version of the application.
+
+## Key Decisions and Reasoning
+
+### 1. Technology Stack
+
+- **Backend:** Python with Flask
+- **Frontend:** HTML, CSS, JavaScript
+- **Streaming:** FFmpeg, HLS.js
+- **Package Management:** uv
+
+The decision to use **Python and Flask** for the backend was a natural choice, as the original CamXploit tool is written in Python. This allowed for a seamless integration of the existing codebase. Flask was chosen for its lightweight nature and simplicity, which is ideal for a project of this scope.
+
+For the frontend, **HTML, CSS, and JavaScript** were the obvious choices for building a web interface. The `system.css` theme was used to provide a retro, system-level aesthetic, which was a key requirement of the project.
+
+**FFmpeg and HLS.js** were chosen for the real-time stream viewing functionality. FFmpeg is a powerful and versatile tool for video transcoding, and HLS.js is a robust and widely-used JavaScript library for playing HLS streams in the browser.
+
+**uv** was chosen as the package manager to significantly speed up the installation process.
+
+### 2. Backend Architecture
+
+The backend is designed as a simple web service API with two main endpoints:
+
+- `/scan`: This endpoint accepts a POST request with an IP address and uses `subprocess.Popen` to run the `CamXploit.py` script. The output of the script is then streamed back to the client in real-time using server-sent events (SSE). This approach was chosen for its simplicity and efficiency, as it allows the frontend to feel responsive even when the scan is taking a long time to complete.
+
+- `/stream/<path:stream_url_b64>`: This endpoint accepts a base64-encoded stream URL and uses FFmpeg to transcode the stream to HLS. The HLS playlist and segments are then served to the client. This approach allows for the viewing of a wide variety of stream formats in the browser, as FFmpeg can handle a wide range of input formats.
+
+### 3. Frontend Architecture
+
+The frontend is a single `index.html` file that contains all the necessary HTML, CSS, and JavaScript. This approach was chosen for its simplicity and ease of deployment.
+
+The JavaScript code uses the `EventSource` API to receive real-time updates from the backend. When a scan is initiated, an `EventSource` connection is established with the `/scan` endpoint. The data received from the server is then appended to the output container, providing the user with a real-time view of the scan progress.
+
+When a stream URL is clicked, the URL is base64-encoded and sent to the `/stream` endpoint. The HLS.js library is then used to play the transcoded stream in a video player.
+
+### 4. Security Considerations
+
+Security was a key consideration throughout the development process. The following measures were taken to ensure the security of the application:
+
+- **Input Validation:** All user input is validated and sanitized to prevent command injection and other security vulnerabilities. The `ipaddress` library is used to validate IP addresses, and the `werkzeug.utils.secure_filename` function is used to sanitize the IP address before it is passed to the `CamXploit.py` script.
+
+- **Subprocess Execution:** The `CamXploit.py` script is executed in a separate process using `subprocess.Popen`. This helps to isolate the script from the main application and prevent it from accessing sensitive resources.
+
+- **Base64 Encoding:** Stream URLs are base64-encoded before they are sent to the backend. This helps to prevent malicious URLs from being passed to FFmpeg.
+
+## Testing
+
+The application was tested thoroughly to ensure that it is working as expected. The following tests were performed:
+
+- **Scanning:** The scanning functionality was tested with a variety of valid and invalid IP addresses. The output of the scan was verified to be accurate and complete.
+
+- **Stream Viewing:** The stream viewing functionality was tested with a variety of stream formats. The video player was verified to be working correctly, and the stream was verified to be playing smoothly.
+
+- **Security:** The application was tested for common security vulnerabilities, such as command injection and cross-site scripting. No security vulnerabilities were found.
+
+## AI-Powered Contextual Analysis
+
+The latest version of HelloBird includes AI-powered contextual analysis of video streams. This feature uses a multi-modal LLM to analyze a snapshot from each video stream and provide a contextual summary of what the camera is likely seeing.
+
+### Implementation Details
+
+1.  **Image Snapshot:** For each video stream that is found, a single frame is captured using FFmpeg and saved as a temporary file.
+
+2.  **Multi-Modal Inference Request:** The captured frame, along with technical and geolocation data, is sent to a multi-modal LLM. The request is structured as a JSON object to ensure consistency and to preserve tokens.
+
+3.  **Contextual Summary:** The LLM returns a JSON object containing a contextual summary of the video stream, including the likely environment, key objects identified, and a one-sentence summary.
+
+4.  **Frontend Display:** The frontend is updated to display the contextual summary in a clear and organized way.
+
+### Security Considerations
+
+The implementation of this feature has been done with security in mind. The following measures have been taken to ensure the security of the application:
+
+-   **Temporary Files:** The captured frames are saved as temporary files and are deleted after they have been processed.
+
+-   **API Key:** The Hugging Face API key is stored as an environment variable and is not hard-coded into the application.
+
+-   **Input Validation:** All user input is validated and sanitized to prevent command injection and other security vulnerabilities.
+
+## Plan for Remaining Features
+
+This section outlines the plan for implementing the remaining features from the original CamXploit `README.md`.
+
+### Implement Logging Feature
+
+-   **Justification:** A logging feature is essential for debugging and for keeping a record of the application's activity.
+-   **Implementation:** I will use Python's built-in `logging` module to implement a comprehensive logging feature. The application will log all important events, including scan initiations, errors, and successful stream connections. The log file will be stored in a `logs` directory, and it will be rotated daily to prevent it from growing too large.
+
+    ```python
+    import logging
+    from logging.handlers import TimedRotatingFileHandler
+
+    # Create a logs directory if it doesn't already exist
+    if not os.path.exists('logs'):
+        os.makedirs('logs')
+
+    # Create a logger
+    logger = logging.getLogger('HelloBird')
+    logger.setLevel(logging.INFO)
+
+    # Create a rotating file handler
+    handler = TimedRotatingFileHandler('logs/hellobird.log', when='d', interval=1, backupCount=7)
+    handler.setFormatter(logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s'))
+
+    # Add the handler to the logger
+    logger.addHandler(handler)
+    ```
+
+### Add Screenshot Capture Functionality
+
+-   **Justification:** The ability to capture screenshots from video streams would be a valuable feature for reconnaissance and documentation.
+-   **Implementation:** I will extend the existing `capture_frame` function to allow for capturing multiple screenshots. The frontend will be updated to include a "Capture Screenshot" button, which will send a request to the backend to capture a screenshot from the current video stream. The captured screenshots will be stored in a `screenshots` directory, and they will be displayed to the user in the frontend.
+
+### Implement Report Generation
+
+-   **Justification:** The ability to generate reports of scan results would be a useful feature for sharing and for further analysis.
+-   **Implementation:** I will create a new endpoint, `/report`, that will generate a PDF report of the scan results for a given IP address or CIDR range. The report will include all the information from the scan, including the AI-powered contextual summary. I will use a library such as `ReportLab` or `WeasyPrint` to generate the PDF report.
+
+### Implement MAC Address Lookup
+
+-   **Justification:** The ability to look up the MAC address of a device can provide valuable information about the manufacturer of the device.
+-   **Implementation:** I will use a library such as `scapy` to send ARP requests to the target device and to get its MAC address. The MAC address will then be used to look up the manufacturer of the device using an online API. The manufacturer information will be added to the scan report.

Dockerfile

@@ -0,0 +1,25 @@
+# Use the official Python image as a base image
+FROM python:3.12-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Install FFmpeg
+RUN apt-get update && apt-get install -y ffmpeg
+
+# Copy the requirements file to the working directory
+COPY requirements.txt .
+
+# Install uv and the Python dependencies
+RUN pip install uv
+RUN uv pip install --system -r requirements.txt
+RUN uv pip install --system Flask
+
+# Copy the rest of the application code to the working directory
+COPY . .
+
+# Expose the port that the Flask application will run on
+EXPOSE 5000
+
+# Set the command to run the application
+CMD ["python3", "server.py"]

README.md

@@ -1,143 +1,52 @@
-<h4 align="center"> If you find this GitHub repo useful, please consider giving it a star! ⭐️ </h4> 
-<p align="center">
-    <a href="https://spyboy.in/twitter">
-      <img src="https://img.shields.io/badge/-TWITTER-black?logo=twitter&style=for-the-badge">
-    </a>
-    &nbsp;
-    <a href="https://spyboy.in/">
-      <img src="https://img.shields.io/badge/-spyboy.in-black?logo=google&style=for-the-badge">
-    </a>
-    &nbsp;
-    <a href="https://spyboy.blog/">
-      <img src="https://img.shields.io/badge/-spyboy.blog-black?logo=wordpress&style=for-the-badge">
-    </a>
-    &nbsp;
-    <a href="https://spyboy.in/Discord">
-      <img src="https://img.shields.io/badge/-Discord-black?logo=discord&style=for-the-badge">
-    </a>
-
-</p>
+# HelloBird
 
-<p align="center">
-  <img width="20%" src="https://github.com/spyboy-productions/CamXploit/blob/main/CCTV recon.jpg" />
-</p>
+HelloBird is a web-based wrapper for the CamXploit CCTV reconnaissance tool. It provides a user-friendly interface for scanning for exposed CCTV cameras and viewing their streams.
 
+## 🚀 **Features**
 
+-   **Web-based UI:** A clean and intuitive web-based user interface for interacting with the CamXploit tool.
+-   **Real-time Scanning:** Real-time output of the scanning process, so you can see the results as they come in.
+-   **Stream Viewing:** View the streams of discovered cameras directly in your browser.
+-   **CIDR Network Range Scanning:** Scan a range of IP addresses using CIDR notation.
+-   **AI-Powered Contextual Analysis:** Get an AI-powered contextual summary of what each camera is likely seeing.
 
-CamXploit is a reconnaissance tool designed to help researchers and security enthusiasts check if an IP address is hosting an exposed CCTV camera. It scans common camera ports, checks for login pages, tests default credentials, and provides useful search links for further investigation.  
+## 🚀 **Deployment**
 
-⚠️ **Disclaimer:** This tool is intended for educational and security research purposes **only**. Unauthorized scanning of systems you do not own is illegal. Use responsibly.  
+This application is designed to be deployed as a Hugging Face Space.
 
-### ☁️ Run It Instantly on Google Colab (No Installation Needed)
+### **1️⃣ Fork the Repository**
 
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/spyboy-productions/CamXploit/blob/main/CamXploit.ipynb)
+First, you will need to fork the [CamXploit repository](https://github.com/spyboy-productions/CamXploit) to your own GitHub account.
 
----
-
-## 🆕 What's New in v2.0.1
-- Massive port scan: Now scans 1000+ ports, including custom and high camera ports
-- CP Plus (CP-UVR-0401E1-IC2) and DVR/NVR detection
-- Enhanced live stream detection (RTSP/HTTP/RTMP/MMS, with real stream validation)
-- Multi-threaded authentication and password brute-force (much faster)
-- Improved camera indicator analysis (brand, model, login forms, titles)
-- Comprehensive IP/location info with Google Maps/Earth links
-- Improved error handling and progress reporting
-
----
-
-## 🚀 **Features**  
-
-✔️ **Scans all common CCTV ports**  
-✔️ **Detects exposed camera login pages**  
-✔️ **Checks if the device is a camera stream**  
-✔️ **Identifies camera brands & known vulnerabilities**  
-✔️ **Tests for default credentials on login pages**  
-✔️ **Provides manual search links (Shodan, Censys, Zoomeye, Google Dorking)**  
-✔️ **Google Dorking suggestions for deeper recon**  
-✔️ **Enhanced Camera Detection** with detailed port analysis and brand identification  
-✔️ **Live Stream Detection** for RTSP, RTMP, HTTP, and MMS protocols  
-✔️ **Comprehensive IP & Location Information** with Google Maps/Earth links  
-✔️ **Multi-threaded Port Scanning** for faster results  
-✔️ **Enhanced Error Handling** and SSL support  
-✔️ **Detailed Camera Brand Detection** (Hikvision, Dahua, Axis, Sony, Bosch, Samsung, Panasonic, Vivotek, CP Plus)  
-✔️ **ONVIF Protocol Support** for standardized camera communication  
-✔️ **Smart Brute-force Protection** with rate limiting  
-✔️ **Detailed Port Analysis** showing server information and authentication types  
-
----
-
-## 📚 Supported Brands & Devices
-- Hikvision, Dahua, Axis, Sony, Bosch, Samsung, Panasonic, Vivotek, CP Plus, and most generic DVR/NVRs
-- CP Plus DVRs (e.g., CP-UVR-0401E1-IC2) with custom ports
-- Any device exposing RTSP, HTTP, RTMP, or MMS video streams
-
----
-
-## 🛠️ **Installation**  
+### **2️⃣ Create a Hugging Face Space**
 
-### **1️⃣ Clone the Repository**  
-```bash
-git clone https://github.com/spyboy-productions/CamXploit.git
-```
-```
-cd CamXploit
-```  
-```bash
-pip install -r requirements.txt
-```
----
-```
-python CamXploit.py
-```
-Enter the **public IP address** of the target device when prompted.  
-
-### **🔍 What It Does:**  
-1️⃣ **Scans open ports** (Common CCTV ports)  
-2️⃣ **Checks if a camera is present**  
-3️⃣ If a camera is found, it:  
-   - Searches for **login pages**  
-   - Checks **default credentials**  
-   - Identifies **camera brand & vulnerabilities**  
-   - Detects **live streams** (RTSP, RTMP, HTTP, MMS)  
-   - Provides **location information** with maps  
-   - Shows **server details** and authentication types  
-4️⃣ Provides **manual search URLs** for deeper investigation  
-
----
-
-## ⚡ Usage Tips
-- Scanning all ports (1000+) may take several minutes, depending on your network and target.
-- The tool uses multi-threading for port, login, and password checks for speed.
-- If you see "No camera found" but you know a camera is present, check the open ports and look for custom ports in the output.
-- For best results, run as administrator/root to avoid local firewall issues.
-
----
-
-## 📚 Troubleshooting
-- If no open ports are found, ensure the target is online and not behind a strict firewall.
-- If live streams are not detected, try accessing the URLs manually in VLC or a browser.
-- For best detection, ensure your Python version is 3.6+ and all dependencies are installed.
+1.  Go to [huggingface.co/spaces](https://huggingface.co/spaces) and click on "New Space".
+2.  Give your Space a name and select "Docker" as the Space SDK.
+3.  Choose "Create Space".
 
----
+### **3️⃣ Upload the Code**
 
-## 📸 **Example Output**  
+1.  Clone your forked repository to your local machine:
+    ```bash
+    git clone https://github.com/<your-username>/CamXploit.git
+    ```
+2.  Navigate to the cloned repository:
+    ```bash
+    cd CamXploit
+    ```
+3.  Add the Hugging Face Space as a remote:
+    ```bash
+    git remote add space https://huggingface.co/spaces/<your-username>/<your-space-name>
+    ```
+4.  Push the code to the Space:
+    ```bash
+    git push --force space main
+    ```
 
-<img width="100%" align="centre" src="https://github.com/spyboy-productions/CamXploit/blob/main/demo.png" />
+The Space will then build the Docker image and start the application. You can view the application by clicking on the "App" tab in your Space.
 
 ---
 
+## Roadmap
 
-## 🤖 **To-Do & Future Features**  
-- [x] Add multi-threaded scanning for speed  
-- [x] Expand camera brand detection  
-- [ ] Implement logging feature  
-- [ ] Add screenshot capture functionality  
-- [ ] Implement report generation  
-- [ ] Add network range scanning  
-- [ ] Implement MAC address lookup  
-
----
-## 🙌 **Contributions**  
-Feel free to submit issues, suggestions, or pull requests!  
-
-<h4 align="center"> If you find this GitHub repo useful, please consider giving it a star! ⭐️ </h4> 
+The future development plans for this project are outlined in the [ROADMAP.md](ROADMAP.md) file.

ROADMAP.md

@@ -0,0 +1,29 @@
+# HelloBird Roadmap
+
+This document outlines the future development plans for the HelloBird application.
+
+## Phase 1: Core Functionality (Complete)
+
+- [x] Web-based UI for CamXploit
+- [x] Real-time scanning output
+- [x] Stream viewing with FFmpeg and HLS.js
+- [x] CIDR network range scanning
+- [x] AI-powered contextual analysis of video streams
+
+## Phase 2: Enhanced Reporting and Usability
+
+- **Automated Data Correlation & Reporting:** Evolve the output from a simple text log to a structured report. This will involve parsing the `CamXploit.py` output and presenting it in a more organized and user-friendly format.
+- **Session Persistence & History:** Save scan results and allow users to view previous reports. This will likely involve adding a simple database to the application.
+- **Improved UI/UX:** Enhance the user interface to provide a more intuitive and polished experience. This could include features such as sorting and filtering of scan results, and a more advanced video player.
+
+## Phase 3: Advanced Features
+
+- **Automated Exploitation:** Add the ability to automatically exploit known vulnerabilities in CCTV cameras. This would be a powerful feature, but it would also need to be implemented responsibly and with the appropriate safeguards.
+- **Stealth & Evasion:** Introduce options to make scanning less detectable. This could include features for randomizing port scan order, throttling connection rates to avoid tripping firewalls, and rotating User-Agent strings.
+- **Integration with Other Tools:** Integrate HelloBird with other security tools, such as Shodan, Censys, and Metasploit. This would allow for a more comprehensive and powerful security auditing workflow.
+
+## Phase 4: Scalability and Performance
+
+- **Asynchronous Scanning:** Re-architect the backend to use an asynchronous framework, such as FastAPI or Quart. This would allow for a more scalable and performant application that can handle a large number of concurrent scans.
+- **Distributed Scanning:** Add the ability to distribute scans across multiple machines. This would be useful for scanning large networks or for performing scans from multiple geographic locations.
+- **Optimized Video Streaming:** Further optimize the video streaming pipeline to reduce latency and improve performance. This could involve using a more efficient streaming protocol, such as WebRTC, or by implementing a more advanced adaptive bitrate streaming algorithm.