{"id":22164398,"url":"https://github.com/sergio11/nethawk_analyzer","last_synced_at":"2025-10-06T09:30:26.412Z","repository":{"id":90143680,"uuid":"71126854","full_name":"sergio11/nethawk_analyzer","owner":"sergio11","description":"NetHawk 🦅: An AI-powered tool for ethical hacking and network vulnerability assessment 🔍💻, simplifying deep scans and security audits for professionals 🛡️🌐.","archived":false,"fork":false,"pushed_at":"2025-01-16T18:50:55.000Z","size":5653,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-20T21:11:28.294Z","etag":null,"topics":["ai","automation","cybersecurity","ethical-hacking","ethical-hacking-tools","generative-ai","groq-ai","langchain","langchain-groq","llama3","network-scanner","network-security","nmap","penetration-testing","scapy","security-audit","vulnerability-assessment"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/NetHawkAnalyzer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sergio11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-17T10:31:10.000Z","updated_at":"2025-01-16T18:50:57.000Z","dependencies_parsed_at":"2024-12-15T12:24:30.577Z","dependency_job_id":"ae01f957-dc1c-49dd-ac49-56a1a7b0d3bf","html_url":"https://github.com/sergio11/nethawk_analyzer","commit_stats":null,"previous_names":["sergio11/nethawk_analyzer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergio11%2Fnethawk_analyzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergio11%2Fnethawk_analyzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergio11%2Fnethawk_analyzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergio11%2Fnethawk_analyzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sergio11","download_url":"https://codeload.github.com/sergio11/nethawk_analyzer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235515428,"owners_count":19002481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cybersecurity","ethical-hacking","ethical-hacking-tools","generative-ai","groq-ai","langchain","langchain-groq","llama3","network-scanner","network-security","nmap","penetration-testing","scapy","security-audit","vulnerability-assessment"],"created_at":"2024-12-02T05:07:33.706Z","updated_at":"2025-10-06T09:30:26.406Z","avatar_url":"https://github.com/sergio11.png","language":"Python","funding_links":[],"categories":["2. [↑](#-content) Pentesting"],"sub_categories":["2.6 [↑](#-content) Network"],"readme":"# NetHawk 🦅: AI-Powered Ethical Hacking \u0026 Network Vulnerability Assessment 🔍💻🛡️🌐\n\n[![GitHub](https://img.shields.io/badge/GitHub-View%20on%20GitHub-blue?style=flat-square)](https://github.com/sergio11/nethawk_analyzer)  \n[![License](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://github.com/sergio11/nethawk_analyzer/blob/main/LICENSE)\n\n**NetHawk** is a personal project developed as part of a **Cybersecurity and Ethical Hacking course**. It was created with educational purposes in mind, allowing me to put into practice core concepts in ethical hacking, network analysis, and the use of AI in security automation.\n\nNetHawk utilizes powerful tools like **Scapy** and **Nmap** to perform deep scans, analyze network security, and uncover potential vulnerabilities in target systems. Through AI-driven automation, it also streamlines port scanning, vulnerability detection, and report generation — making learning more interactive and hands-on.\n\n\u003e ⚠️ **Disclaimer:** NetHawk is intended solely for learning and ethical use. It should never be used for malicious purposes.\n\n🙏 **Special thanks to** [Santiago Hernández](https://www.udemy.com/user/shramos/), a leading expert in Cybersecurity and Artificial Intelligence. His outstanding Udemy course on **Cybersecurity and Ethical Hacking** was instrumental in the creation of this project. The knowledge and techniques shared there were essential for building NetHawk. Thank you for your guidance and inspiration!\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/langchain-1C3C3C?style=for-the-badge\u0026logo=langchain\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Kali_Linux-557C94?style=for-the-badge\u0026logo=kali-linux\u0026logoColor=white\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-FFD43B?style=for-the-badge\u0026logo=python\u0026logoColor=blue\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_1.PNG\" /\u003e\n\u003c/p\u003e\n\n## ⚠️ Disclaimer  \n\n**NetHawk** has been developed exclusively for educational and research purposes as part of my learning journey in **Ethical Hacking**. This project serves as a practical application of the skills acquired during cybersecurity training, allowing me to experiment in a **controlled lab environment** and include this tool in my **cybersecurity portfolio**.  \n\nThis tool is intended **only for authorized testing environments** where explicit permission has been granted. **Unauthorized use on external systems is strictly prohibited** and may violate laws.\nI disclaim any responsibility for misuse of this tool. **Always obtain proper authorization** before conducting security assessments.  \n\n## 🌟 Key Features of NetHawk:\n\n- 🔧 **Multi-Tool Scanning**: Combines the capabilities of Scapy and Nmap to offer thorough network scans, giving users a broad view of potential vulnerabilities.\n- 🚪 **Advanced Port Scanning**: Supports TCP, UDP, and Xmas scans to detect open, closed, and filtered ports — ideal for learning how attackers discover network entry points.\n- 📊 **Result Consolidation**: Merges results from different tools into a single report, teaching good practices in data organization and analysis.\n- ⚡ **High Concurrency**: Demonstrates how to optimize scans for performance using threading and parallel execution — useful for real-world scalability.\n- ⏱️ **Customizable Parameters**: Allows users to tweak settings like timeouts and port ranges, encouraging experimentation and deeper understanding of scanning behavior.\n- 🤖 **AI-Powered Analysis**: Offers a practical introduction to applying AI logic for automated decision-making in cybersecurity tools.\n\n## 🎯 Educational Use Cases:\n\n- 🔓 **Penetration Testing Practice**: Helps ethical hacking learners simulate attacks in safe environments and recognize potential weaknesses before they’re exploited.\n- 🔍 **Network Security Audits**: Supports IT students and professionals in conducting internal scans to identify misconfigurations and learn how to interpret scan data effectively.\n\n## 🔍 Host and Port Scanning Strategy (How It Works):\n\nNetHawk implements a layered scanning approach to teach how different scanning techniques complement each other for comprehensive vulnerability detection.\n\n### 1. **Host Discovery Using Scapy**:\n- **ICMP Ping**: Sends echo requests to identify live hosts.\n- **TCP SYN and ACK Scans**: Used when ICMP is blocked, to detect hosts through common service ports.\n- **Fallback to Socket Scans**: Direct connection attempts are made when both ICMP and TCP probes are inconclusive — simulating real-world firewall evasion tactics.\n\n### 2. **Port Scanning Using Scapy and Nmap**:\n- **Scapy**: Performs detailed scans using:\n  - **TCP SYN** (Stealth scan)\n  - **UDP Scan** (For stateless services)\n  - **Xmas Scan** (For analyzing unusual TCP flags responses)\n- **Nmap**: Adds service detection, OS guessing, and extended port coverage.\n\nResults are then **merged**, avoiding duplicates and giving a clearer view of open services and attack surfaces.\n\n### 3. **Results Aggregation and Analysis**:\n- By combining Scapy and Nmap outputs, NetHawk produces an educational, high-fidelity vulnerability map — allowing learners to understand how attackers and defenders might see a network differently.\n\n## 🌐 Learning with the NetHawk API\n\nAs part of the educational design of NetHawk, the tool includes a simplified yet powerful **Python API** to practice concepts such as **network scanning**, **service enumeration**, and **automation in cybersecurity**.\n\nThis API abstracts many complexities of lower-level tools like Scapy and Nmap, providing a great opportunity to understand how these tools can be integrated and automated for ethical hacking purposes.\n\n### 1. 🚀 **Initialization (`__init__`)**\n\nThe core component is the `NetHawkAnalyzer` class. When initializing it, you provide basic configuration parameters such as:\n\n- `**network_range**`: The target IP range (e.g., `192.168.1.0/24`) — a key part of any scan.\n- `**timeout**`: Scan timeout (in seconds), helping manage performance.\n- `**groq_api_key**` and `**model_id**` (optional): For integrating with AI models, great for experimenting with automated decision-making.\n\n\u003e 🧠 **Learning Tip:** Initializing scanning tools with flexible parameters is key to adapting them for different environments.\n\n### 2. 🔍 **Host Scanning (`scan_hosts`)**\n\nThis method detects live devices on the network. It introduces two scanning strategies:\n\n- `**arp**`: Uses ARP packets — ideal for local networks and very fast.\n- `**scapy**`: Performs more robust host discovery, useful for filtered or protected networks.\n\n\u003e 💡 Great for learning how attackers map networks and how to detect hosts even when firewalls are present.\n\n### 3. 🚪 **Port Scanning (`scan_ports` and `scan_all_ports`)**\n\nUnderstanding how to scan for open ports is fundamental in network security. These methods allow exploration of:\n\n- **TCP SYN Scan**: Classic \"stealth\" technique used in many real-world assessments.\n- **UDP Scan**: Useful for stateless services that don't use TCP.\n- **Xmas Scan**: Sends unusual TCP flag combinations — great for exploring how firewalls react.\n\n`scan_all_ports` runs all techniques at once, providing a complete picture of the host’s exposed services.\n\n\u003e 🔍 **Hands-on Learning:** Try each scan type separately to compare how different firewalls and configurations respond!\n\n### 4. 🛠️ **Service Detection (`scan_services`)**\n\nOnce open ports are discovered, this method attempts to identify the services running behind them and gather **banner information**.\n\n\u003e 📚 This is essential for learning **vulnerability assessment**, as knowing the version of a service can help identify known security flaws.\n\n### 5. 📁 **SMB Share Scanning (`scan_smb_shares`)**\n\nUse this method to find **publicly accessible SMB shares**, which can represent serious misconfigurations in real environments.\n\n\u003e 🧪 **Experiment Tip:** Test this in a virtual lab to understand how file sharing services can be exposed without proper restrictions.\n\n### 6. 📝 **Full Network Scan (`run_full_scan`)**\n\nThis method puts it all together — a one-stop scan that:\n\n- Detects hosts\n- Scans ports\n- Identifies services\n- Finds SMB shares\n\nThe results can be exported to **PDF** and **JSON**, which is excellent for **report writing practice** — a vital skill for ethical hackers and security analysts.\n\n### ⚠️ **Error Handling**\n\nNetHawk includes error management to simulate real-world challenges:\n\n- Raises `ValueError` for invalid scan types or misconfigurations.\n- Guides the user with meaningful feedback.\n\n\u003e 🛠️ **Why this matters:** Learning to write and handle clear error messages is essential for building tools that others can use effectively.\n\n## 🖼️ Tool Screenshots\n\nTo help visualize how NetHawk works in practice, this section includes real screenshots of the tool in action.\n\nThese images show:\n\n- The scanning process\n- Results from network analysis\n- How findings are organized and presented\n\nThis makes it easier to understand the **workflow of a network assessment** and how data is interpreted.\n\n\u003e 🧭 **Explore and Analyze:** Use the screenshots to get familiar with the kinds of outputs NetHawk generates, and reflect on how they can be used to make informed security decisions.\n\n\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_1.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_2.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_3.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_4.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_5.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_6.PNG\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"doc/screenshots/picture_7.PNG\" /\u003e\n\u003c/p\u003e\n\n## 📦 Required Dependencies\n\n| Dependency              | Version    | Description                                                                                   |\n|-------------------------|------------|-----------------------------------------------------------------------------------------------|\n| **scapy**               | `2.6.0`   | A powerful Python library used for network packet manipulation and analysis.                 |\n| **tqdm**                | `4.65.0`   | A fast, extensible progress bar for loops and file processing.                               |\n| **rich**                | `13.9.2`  | A library for rich text and beautiful formatting in the terminal.                             |\n| **pysmb**               | `1.2.10`  | A Python implementation of the SMB/CIFS protocol for network file sharing.                    |\n| **python3-nmap**       | `1.9.1`   | A Python library that allows you to interact with Nmap from your Python scripts.            |\n| **langchain**           | `0.2.16`  | A framework for building applications with language models and AI capabilities.               |\n| **langchain-groq**      | `0.1.10`  | An extension for Langchain that enables integration with Groq-based systems.                  |\n| **fpdf2**               | `2.8.1`   | A library for generating PDF documents using Python.                                         |\n\n\n## Getting Started with NetHawkAnalyzer 🦅\n\nTo run the example provided below, follow these steps:\n\n### Prerequisites\n\n1. **Install NetHawkAnalyzer**:\n   Ensure you have the package installed. If you haven't done this yet, you can install it using pip:\n\n   ```bash\n   pip install -r examples/requirements.txt\n   ```\n2. **Set Up Environment Variables**: You need to set up two environment variables: **GROQ_API_KEY** and **MODEL_ID**. You can do this by creating a .env file in your project directory and adding your keys there.\n\nExample .env file:\n\n```bash\nGROQ_API_KEY=your_groq_api_key_here\nMODEL_ID=your_model_id_here\n ```\n\n**Running the Example**\n\nHere's a sample script that demonstrates how to use NetHawkAnalyzer for network analysis. This script will load your environment variables, initialize the analyzer with a specified network range, and run a full scan.\n\n```python\nimport os \nfrom NetHawkAnalyzer.analyzer import NetHawkAnalyzer\nfrom dotenv import load_dotenv\n\ndef main():\n    # Load environment variables from .env file\n    load_dotenv()\n\n    # Retrieve your API key and model ID from environment variables\n    groq_api_key = os.getenv(\"GROQ_API_KEY\")\n    model_id = os.getenv(\"MODEL_ID\")\n \n    # Initialize the NetHawkAnalyzer with your network range\n    analyzer = NetHawkAnalyzer(\n        network_range=\"192.168.11.0/24\", \n        groq_api_key=groq_api_key, \n        model_id=model_id\n    )\n    \n    # Run a full scan\n    results = analyzer.run_full_scan()\n    \n    # Optionally, process or save the results\n    print(\"Full scan completed!\")\n    print(results)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n### Explanation\n\n- **Loading Environment Variables**: The script uses the `dotenv` library to load environment variables from a `.env` file. This allows you to keep sensitive information secure.\n\n- **Network Analyzer Initialization**: The `NetHawkAnalyzer` is initialized with the specified network range and your API credentials.\n\n- **Running a Scan**: The `run_full_scan()` method is called to perform a comprehensive network analysis.\n\n- **Displaying Results**: Finally, the results of the scan are printed to the console.\n\n### Important Notes\n\n- Make sure to replace `your_groq_api_key_here` and `your_model_id_here` in your `.env` file with your actual API key and model ID.\n- Ensure that the specified network range is appropriate for your network setup.\n\nBy following these steps, you can successfully run the example script and begin analyzing your network using `NetHawkAnalyzer`! 🔍💻\n\n## ⚠️ Disclaimer  \n\n**NetHawk** has been developed exclusively for educational and research purposes as part of my learning journey in **Ethical Hacking**. This project serves as a practical application of the skills acquired during cybersecurity training, allowing me to experiment in a **controlled lab environment** and include this tool in my **cybersecurity portfolio**.  \n\nThis tool is intended **only for authorized testing environments** where explicit permission has been granted. **Unauthorized use on external systems is strictly prohibited** and may violate laws.\nI disclaim any responsibility for misuse of this tool. **Always obtain proper authorization** before conducting security assessments.  \n\n## Acknowledgements 🙏\n\n🙏 I would like to express my sincere gratitude to [Santiago Hernández, a leading expert in Cybersecurity and Artificial Intelligence](https://www.udemy.com/user/shramos/). His outstanding course on **Cybersecurity and Ethical Hacking**, available on Udemy, was instrumental in the development of this project. The insights and techniques I gained from his course were invaluable in guiding my approach to cybersecurity practices. Thank you for sharing your knowledge and expertise!\n\nSpecial thanks to the open-source community and the contributors who have made this project possible.\n\n## License ⚖️\n\nThis project is licensed under the MIT License, an open-source software license that allows developers to freely use, copy, modify, and distribute the software. 🛠️ This includes use in both personal and commercial projects, with the only requirement being that the original copyright notice is retained. 📄\n\nPlease note the following limitations:\n\n- The software is provided \"as is\", without any warranties, express or implied. 🚫🛡️\n- If you distribute the software, whether in original or modified form, you must include the original copyright notice and license. 📑\n- The license allows for commercial use, but you cannot claim ownership over the software itself. 🏷️\n\nThe goal of this license is to maximize freedom for developers while maintaining recognition for the original creators.\n\n```\nMIT License\n\nCopyright (c) 2024 Dream software - Sergio Sánchez \n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n```\n\n## Visitors Count\n\n\u003cimg width=\"auto\" src=\"https://profile-counter.glitch.me/nethawk_analyzer/count.svg\" /\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergio11%2Fnethawk_analyzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergio11%2Fnethawk_analyzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergio11%2Fnethawk_analyzer/lists"}