chore: add project infrastructure and testing setup

Author: TheOnlyChou

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e ".[dev]"
+
+    - name: Run tests with pytest
+      run: |
+        pytest -v --tb=short
+
+    - name: Test CLI installation
+      run: |
+        netsleuth --help
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install package
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .
+
+    - name: Check package imports
+      run: |
+        python -c "from NetSleuth import resolve_host, scan_ports, parse_ports; print('Imports OK')"

NetSleuth/__init__.py

@@ -4,13 +4,14 @@
 This package provides tools for network port scanning and host discovery.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 from .models import ScanResult
 from .scanner import resolve_host, scan_port, scan_ports
 from .ports import parse_ports
 from .banner import grab_banner
 from .reporter import results_to_dict, write_json, write_ndjson
+from .utils import is_valid_port, format_duration, calculate_scan_estimate
 
 __all__ = [
     "ScanResult",
@@ -22,4 +23,7 @@
     "results_to_dict",
     "write_json",
     "write_ndjson",
+    "is_valid_port",
+    "format_duration",
+    "calculate_scan_estimate",
 ]

NetSleuth/reporter.py

@@ -19,7 +19,7 @@ def results_to_dict(target_host: str, target_ip: str, timeout: float, workers: i
     """
     return {
         "tool": "NetSleuth",
-        "version": "0.1.0",
+        "version": "0.2.0",
         "timestamp": datetime.now(timezone.utc).isoformat(),
         "target": {
             "host": target_host,

NetSleuth/utils.py

@@ -0,0 +1,54 @@
+def is_valid_port(port: int) -> bool:
+    """
+    Check if a port number is within the valid range (1-65535).
+    
+    Args:
+        port: Port number to validate.
+    
+    Returns:
+        True if the port is valid, False otherwise.
+    """
+    return 1 <= port <= 65535
+
+
+def format_duration(seconds: float) -> str:
+    """
+    Format a duration in seconds to a human-readable string.
+    
+    Args:
+        seconds: Duration in seconds.
+    
+    Returns:
+        Formatted string (e.g., "1.5s", "2m 30s", "1h 5m").
+    """
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    elif seconds < 3600:
+        minutes = int(seconds // 60)
+        secs = int(seconds % 60)
+        return f"{minutes}m {secs}s"
+    else:
+        hours = int(seconds // 3600)
+        minutes = int((seconds % 3600) // 60)
+        return f"{hours}h {minutes}m"
+
+
+def calculate_scan_estimate(num_ports: int, timeout: float, workers: int) -> float:
+    """
+    Estimate the total scan time based on parameters.
+    
+    Args:
+        num_ports: Number of ports to scan.
+        timeout: Timeout per connection in seconds.
+        workers: Number of concurrent workers.
+    
+    Returns:
+        Estimated scan time in seconds.
+    """
+    if workers <= 0:
+        workers = 1
+    
+    # Rough estimate: time per batch * number of batches
+    # Add small overhead for threading
+    batches = (num_ports + workers - 1) // workers
+    return batches * timeout * 1.1  # 10% overhead