feat: Add CIDR notation support for target specification

- Add expand_cidr() and is_cidr() functions to helpers.py
- Update normalize_targets() to expand CIDR ranges to individual IPs
- Consolidate duplicate IP check functions (remove _is_ip_address, use is_ipv4)
- Supports mixed input: CIDRs, IPs, hostnames in CLI and targets file
- Add comprehensive tests for CIDR expansion

Author: r0BIT

taskhound/engine/online.py

@@ -26,13 +26,13 @@
 from ..parsers.task_xml import parse_task_xml
 from ..smb.connection import (
     _dns_ptr_lookup,
-    _is_ip_address,
     get_server_fqdn,
     get_server_sid,
     smb_connect,
     smb_login,
     smb_negotiate,
 )
+from ..utils.helpers import is_ipv4
 from ..smb.credguard import check_credential_guard
 from ..smb.task_rpc import CredentialStatus, TaskRunInfo, TaskSchedulerRPC
 from ..smb.tasks import crawl_tasks, smb_listdir
@@ -196,7 +196,7 @@ def process_target(
             if not discovered_hostname:
                 # SMBv3 doesn't populate server name during negotiate
                 # Try DNS reverse lookup as fallback
-                if _is_ip_address(target):
+                if is_ipv4(target):
                     # Try DC first, then system DNS
                     if dc_ip:
                         discovered_hostname = _dns_ptr_lookup(target, nameserver=dc_ip, use_tcp=dns_tcp)

taskhound/smb/connection.py

@@ -11,6 +11,8 @@
 
 from impacket.smbconnection import SMBConnection
 
+from ..utils.helpers import is_ipv4
+
 
 def _parse_hashes(password: str):
     # Parse a provided password or NTLM hash string.
@@ -379,7 +381,7 @@ def get_server_fqdn(smb: SMBConnection, target_ip: Optional[str] = None, dc_ip:
         FQDN string (e.g., "DC.badsuccessor.lab") or "UNKNOWN_HOST"
     """
     # Method 0: If target already looks like an FQDN (has dots and isn't an IP), use it
-    if target_ip and "." in target_ip and not _is_ip_address(target_ip):
+    if target_ip and "." in target_ip and not is_ipv4(target_ip):
         return target_ip
 
     try:
@@ -404,7 +406,7 @@ def get_server_fqdn(smb: SMBConnection, target_ip: Optional[str] = None, dc_ip:
         server_name = None
 
     # Method 3 & 4: DNS fallback - try to resolve via PTR record
-    if target_ip and _is_ip_address(target_ip):
+    if target_ip and is_ipv4(target_ip):
         # Method 3: Try using DC as DNS server (if provided)
         if dc_ip:
             fqdn = _dns_ptr_lookup(target_ip, nameserver=dc_ip, use_tcp=dns_tcp)
@@ -423,17 +425,6 @@ def get_server_fqdn(smb: SMBConnection, target_ip: Optional[str] = None, dc_ip:
     return "UNKNOWN_HOST"
 
 
-def _is_ip_address(hostname: str) -> bool:
-    """Check if a string is an IPv4 address."""
-    parts = hostname.split(".")
-    if len(parts) == 4:
-        try:
-            return all(0 <= int(p) <= 255 for p in parts)
-        except (ValueError, TypeError):
-            return False
-    return False
-
-
 def _dns_ptr_lookup(ip: str, nameserver: Optional[str] = None, use_tcp: bool = False) -> Optional[str]:
     """
     Perform DNS PTR lookup to resolve IP to hostname.

taskhound/utils/helpers.py

@@ -3,6 +3,7 @@
 # This module contains simple utilities for classifying RunAs values,
 # normalizing target hostnames, and the ASCII banner used by the CLI.
 
+import ipaddress
 import re
 import uuid
 from typing import List, Tuple
@@ -41,17 +42,67 @@ def parse_ntlm_hashes(hashes: str) -> Tuple[str, str]:
         return "", hashes
 
 
+def expand_cidr(cidr: str) -> List[str]:
+    """Expand a CIDR notation to a list of IP addresses.
+    
+    Args:
+        cidr: CIDR notation string (e.g., '192.168.1.0/24')
+        
+    Returns:
+        List of IP address strings (excludes network and broadcast for /31+)
+        
+    Raises:
+        ValueError: If the CIDR notation is invalid
+    """
+    try:
+        network = ipaddress.ip_network(cidr, strict=False)
+        # For /31 and /32, return all addresses (point-to-point or single host)
+        # For larger networks, exclude network and broadcast addresses
+        if network.prefixlen >= 31:
+            return [str(ip) for ip in network.hosts()] or [str(network.network_address)]
+        return [str(ip) for ip in network.hosts()]
+    except ValueError as e:
+        raise ValueError(f"Invalid CIDR notation '{cidr}': {e}")
+
+
+def is_cidr(target: str) -> bool:
+    """Check if a string is CIDR notation (e.g., '192.168.1.0/24')."""
+    if "/" not in target:
+        return False
+    try:
+        ipaddress.ip_network(target, strict=False)
+        return True
+    except ValueError:
+        return False
+
+
 def normalize_targets(targets: List[str], domain: str) -> List[str]:
-    # Normalize a list of targets: keep IPs, append domain for short hostnames.
-    #
-    # Empty lines are ignored. This mirrors the behavior expected by the CLI
-    # where users may pass bare hostnames that need to be FQDN-ified.
+    """Normalize a list of targets: expand CIDRs, keep IPs, append domain for short hostnames.
+    
+    Args:
+        targets: List of target strings (IPs, hostnames, FQDNs, or CIDR notation)
+        domain: Domain to append to short hostnames
+        
+    Returns:
+        Normalized list of targets with CIDRs expanded to individual IPs
+        
+    Empty lines are ignored. This mirrors the behavior expected by the CLI
+    where users may pass bare hostnames that need to be FQDN-ified.
+    """
     out = []
     for t in targets:
         t = t.strip()
         if not t:
             continue
-        if is_ipv4(t):
+        # Check for CIDR notation first
+        if is_cidr(t):
+            try:
+                expanded = expand_cidr(t)
+                out.extend(expanded)
+            except ValueError:
+                # Invalid CIDR, treat as hostname
+                out.append(t)
+        elif is_ipv4(t):
             out.append(t)
         else:
             # append domain if it's a short host (no dot)

tests/test_helpers_extended.py

@@ -4,14 +4,18 @@
 Tests cover:
 - is_ipv4 function
 - parse_ntlm_hashes function
-- normalize_targets function
+- normalize_targets function (including CIDR expansion)
+- expand_cidr function
+- is_cidr function
 - sanitize_json_string function
 """
 
 import pytest
 
 from taskhound.utils.helpers import (
     is_ipv4,
+    is_cidr,
+    expand_cidr,
     parse_ntlm_hashes,
     normalize_targets,
     sanitize_json_string,
@@ -161,6 +165,109 @@ def test_empty_list(self):
 
         assert result == []
 
+    def test_cidr_expansion(self):
+        """Should expand CIDR notation to individual IPs"""
+        targets = ["192.168.1.0/30"]
+        
+        result = normalize_targets(targets, "example.com")
+        
+        # /30 has 4 IPs, but .hosts() excludes network (.0) and broadcast (.3)
+        assert result == ["192.168.1.1", "192.168.1.2"]
+
+    def test_cidr_with_mixed_targets(self):
+        """Should handle CIDR mixed with other target types"""
+        targets = ["10.0.0.0/30", "DC01", "192.168.1.100"]
+        
+        result = normalize_targets(targets, "example.com")
+        
+        assert result == ["10.0.0.1", "10.0.0.2", "DC01.example.com", "192.168.1.100"]
+
+    def test_cidr_single_host(self):
+        """Should handle /32 single host CIDR"""
+        targets = ["192.168.1.50/32"]
+        
+        result = normalize_targets(targets, "example.com")
+        
+        assert result == ["192.168.1.50"]
+
+
+# ============================================================================
+# Test: expand_cidr
+# ============================================================================
+
+
+class TestExpandCidr:
+    """Tests for expand_cidr function"""
+
+    def test_slash_24(self):
+        """Should expand /24 to 254 hosts"""
+        result = expand_cidr("192.168.1.0/24")
+        
+        assert len(result) == 254
+        assert result[0] == "192.168.1.1"
+        assert result[-1] == "192.168.1.254"
+
+    def test_slash_30(self):
+        """Should expand /30 to 2 hosts"""
+        result = expand_cidr("10.0.0.0/30")
+        
+        assert result == ["10.0.0.1", "10.0.0.2"]
+
+    def test_slash_31(self):
+        """Should expand /31 point-to-point"""
+        result = expand_cidr("10.0.0.0/31")
+        
+        assert result == ["10.0.0.0", "10.0.0.1"]
+
+    def test_slash_32(self):
+        """Should expand /32 single host"""
+        result = expand_cidr("192.168.1.100/32")
+        
+        assert result == ["192.168.1.100"]
+
+    def test_invalid_cidr_raises(self):
+        """Should raise ValueError for invalid CIDR"""
+        with pytest.raises(ValueError):
+            expand_cidr("not-a-cidr")
+
+    def test_invalid_prefix_raises(self):
+        """Should raise ValueError for invalid prefix"""
+        with pytest.raises(ValueError):
+            expand_cidr("192.168.1.0/33")
+
+
+# ============================================================================
+# Test: is_cidr
+# ============================================================================
+
+
+class TestIsCidr:
+    """Tests for is_cidr function"""
+
+    def test_valid_cidr(self):
+        """Should return True for valid CIDR notation"""
+        assert is_cidr("192.168.1.0/24") is True
+        assert is_cidr("10.0.0.0/8") is True
+        assert is_cidr("172.16.0.0/16") is True
+
+    def test_single_host_cidr(self):
+        """Should return True for /32 single host"""
+        assert is_cidr("192.168.1.1/32") is True
+
+    def test_plain_ip_not_cidr(self):
+        """Should return False for plain IP address"""
+        assert is_cidr("192.168.1.1") is False
+
+    def test_hostname_not_cidr(self):
+        """Should return False for hostname"""
+        assert is_cidr("DC01.example.com") is False
+        assert is_cidr("DC01") is False
+
+    def test_invalid_cidr(self):
+        """Should return False for invalid CIDR notation"""
+        assert is_cidr("192.168.1.0/33") is False
+        assert is_cidr("not/valid") is False
+
 
 # ============================================================================
 # Test: sanitize_json_string