Skip to content

README.md

Latest commit

 

History

History
125 lines (90 loc) · 3.79 KB

README.md

File metadata and controls

125 lines (90 loc) · 3.79 KB

Host Scan

Python Scope Bandit Pytest License GitHub Actions

Important

This project is for educational and ethical cybersecurity purposes only. Unauthorized scanning of systems is illegal and unethical. Use it only on networks and systems where you have explicit, written authorization.

🧠 Overview

Host Scan is a professional network reconnaissance tool developed in Python 3. It enables efficient analysis of open ports (TCP/UDP) on remote hosts using optimized concurrency with ThreadPoolExecutor.

The project is designed with a DevSecOps mindset, featuring automated linting, security analysis, and unit testing to ensure code quality and safety.

⚙️ Features

  • TCP/UDP Port Scanning — High-speed scanning using low-level socket connections.
  • Concurrent Execution — Optimized thread pool management for rapid results.
  • Service Identification — Basic mapping of open ports to standard services.
  • Modular Architecture — Clean separation between core logic and CLI interaction.
  • CI/CD Integrated — Automated validation via GitHub Actions.

🛠️ Tech Stack

Component Technology
Language Python 3.8+
Concurrency concurrent.futures.ThreadPoolExecutor
Sockets socket (Python stdlib)
SAST Bandit
Testing Pytest
Linting Flake8
CI/CD GitHub Actions

📦 Installation

Prerequisites

  • Python 3.8 or higher
  • Linux (Debian, Ubuntu, Arch) or Android (Termux) recommended

Setup

# 1. Clone the repository
git clone https://github.com/devsebastian44/Host-Scan.git
cd Host-Scan

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r configs/requirements.txt
pip install -r configs/requirements-dev.txt

▶️ Usage

Run the scanner from the terminal:

python3 src/scan.py

Running Tests & Quality Checks

# Run unit tests
pytest tests/

# Security analysis (SAST)
bandit -r src/

# Linting check
flake8 src/

📁 Project Structure

Host-Scan/
├── src/
│   └── scan.py           # Core scanner logic and CLI
├── tests/
│   └── test_scan.py      # Unit tests with socket mocking
├── configs/
│   ├── requirements.txt  # Production dependencies
│   └── requirements-dev.txt # Development dependencies
├── diagrams/             # Architecture diagrams
├── .github/workflows/    # CI/CD configuration
└── README.md             # Project documentation

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'feat: Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Commitment to Quality

  • Ensure all tests pass.
  • Follow PEP-8 guidelines.
  • Use Conventional Commits.

📄 License

Distributed under the Apache License 2.0. See LICENSE for more information.

👨‍💻 Author

Sebastian Zhunaula - @devsebastian44