Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

16.9 KB
Raw Blame
"""
Network Service Detection - Banner Grabbing + Version Fingerprinting
MITRE: T1046, T1590.004

Connects to open ports, reads banner/response, identifies:
  - Service name and version
  - TLS/SSL details
  - Authentication methods offered
  - Known vulnerable versions
"""
from __future__ import annotations

import asyncio
import re
import ssl
from typing import Any

from ares.core.campaign import Finding, Severity
from ares.core.logger import get_logger
from ares.core.tracing import trace_module
from ares.modules.base import BaseModule, OpsecLevel
from ares.modules.params import ServiceDetectParams
from ares.sdk import (
    CircuitBreaker,
    EvidenceRecord,
    ModuleResult,
    NetworkPermission,
    ProcessPermission,
    module_contract,
)

logger = get_logger("ares.modules.network.service_detect")

# Probes to send to services for banner extraction
_PROBES: dict[str, bytes] = {
    "http":  b"HEAD / HTTP/1.0\r\nHost: target\r\n\r\n",
    "ftp":   b"",       # FTP sends banner on connect
    "smtp":  b"",       # SMTP sends banner on connect
    "ssh":   b"",       # SSH sends banner on connect
    "redis": b"*1\r\n$4\r\nINFO\r\n",
    "mongodb": b"\x3a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xd4\x07\x00\x00"
               b"\x00\x00\x00\x00admin.$cmd\x00\x00\x00\x00\x00\xff\xff\xff\xff"
               b"\x13\x00\x00\x00\x10serverStatus\x00\x01\x00\x00\x00\x00",
    "generic": b"",
}

# Version patterns - (service, pattern, severity, cve_hint)
_VULN_PATTERNS: list[tuple[str, str, str, str]] = [
    ("openssh",   r"OpenSSH[_\s]([0-9]+\.[0-9]+)",   "INFO",     "Enforce key-based authentication, disable root login, and audit SSH configurations"),
    ("vsftpd",    r"vsftpd\s([0-9]\.[0-9]\.[0-9])", "MEDIUM",   "CVE-2011-2523 if 2.3.4"),
    ("proftpd",   r"ProFTPD\s([0-9]\.[0-9])",       "INFO",     ""),
    ("apache",    r"Apache[/\s]([0-9]+\.[0-9]+)",   "INFO",     ""),
    ("nginx",     r"nginx[/\s]([0-9]+\.[0-9]+)",    "INFO",     ""),
    ("iis",       r"Microsoft-IIS[/\s]([0-9]+\.[0-9]+)", "INFO", ""),
    ("redis",     r"redis_version:([0-9]+\.[0-9]+)", "MEDIUM",  "Check for no-auth"),
    ("mongodb",   r"\"version\"",                   "MEDIUM",   "Check for no-auth"),
    ("elasticsearch", r"\"number\":\"([0-9]+\.[0-9]+)", "MEDIUM", "Check for no-auth"),
]

# Operating system fingerprint patterns from banner data - (pattern, os_family, distro_name, confidence)
_OS_PATTERNS: list[tuple[str, str, str, float]] = [
    (r"kali", "linux", "Kali Linux", 0.98),
    (r"debian", "linux", "Debian Linux", 0.95),
    (r"ubuntu", "linux", "Ubuntu Linux", 0.95),
    (r"centos", "linux", "CentOS Linux", 0.95),
    (r"red\s*hat|rhel", "linux", "Red Hat Enterprise Linux", 0.95),
    (r"fedora", "linux", "Fedora Linux", 0.95),
    (r"arch\s*linux|archlinux", "linux", "Arch Linux", 0.95),
    (r"alpine", "linux", "Alpine Linux", 0.95),
    (r"suse|opensuse", "linux", "openSUSE Linux", 0.95),
    (r"rocky", "linux", "Rocky Linux", 0.95),
    (r"alma", "linux", "AlmaLinux", 0.95),
    (r"gentoo", "linux", "Gentoo Linux", 0.95),
    (r"openssh", "linux", "Linux (OpenSSH)", 0.85),
    (r"linux", "linux", "Linux Generic", 0.85),
    (r"microsoft-iis/[0-9.]+|microsoft\s+windows", "windows", "Windows", 0.95),
    (r"windows\s+server", "windows-server", "Windows Server", 0.95),
    (r"pfsense|fortios|cisco|routeros", "firewall", "Network Appliance / Firewall", 0.95),
]


from ares.modules._tls_security import harden_ssl_context


def _fingerprint_os_from_banners(banners: list[str]) -> dict[str, Any] | None:
    combined = " ".join(banners).lower()
    for pattern, family, distro, conf in _OS_PATTERNS:
        if re.search(pattern, combined, re.IGNORECASE):
            return {
                "os": family,
                "distro": distro,
                "confidence": conf,
            }
    return None


async def _grab_banner(host: str, port: int, timeout: float = 4.0,
                       use_tls: bool = False) -> str:
    """Connect to port, optionally TLS-wrap, read banner bytes."""
    writer = None
    try:
        if use_tls:
            ctx = ssl.create_default_context()
            harden_ssl_context(ctx)
            reader, writer = await asyncio.wait_for(
                asyncio.open_connection(host, port, ssl=ctx), timeout=timeout
            )
        else:
            reader, writer = await asyncio.wait_for(
                asyncio.open_connection(host, port), timeout=timeout
            )

        # Determine probe based on port
        port_probe_map = {80: "http", 8080: "http", 8443: "http", 443: "http",
                          8888: "http", 21: "ftp", 25: "smtp", 22: "ssh",
                          6379: "redis", 27017: "mongodb"}
        probe_key = port_probe_map.get(port, "generic")
        probe     = _PROBES.get(probe_key, b"")
        if probe:
            writer.write(probe)
            await writer.drain()

        data = await asyncio.wait_for(reader.read(2048), timeout=timeout)
        return data.decode("utf-8", errors="replace").strip()[:1000]

    except Exception:
        return ""
    finally:
        if writer:
            writer.close()
            try:
                await asyncio.wait_for(writer.wait_closed(), timeout=2.0)
            except (TimeoutError, Exception):
                pass  # Best effort cleanup


@module_contract(
    permissions=[
        NetworkPermission(protocols=["tcp"]),
        ProcessPermission(allow_subprocesses=False),
    ],
    circuit_breaker=CircuitBreaker(name="network.service_detect", failure_threshold=10),
    params_model=ServiceDetectParams,
)
class ServiceDetectModule(BaseModule):
    """
    network.service_detect - Banner grabbing and version fingerprinting on open ports - identifies service versions and flags potentially vulnerable services

    OPSEC: LOW
    MITRE: "T1046", "T1590.004"
    OUTPUTS:  "service_versions", "vulnerable_services"
    """
    MODULE_ID          = "network.service_detect"
    MODULE_NAME        = "Service Detection"
    MODULE_CATEGORY    = "network"
    MODULE_DESCRIPTION = (
        "Banner grabbing and version fingerprinting on open ports - "
        "identifies service versions and flags potentially vulnerable services"
    )
    MODULE_AUTHOR      = "ARES Team <[email protected]>"
    OPSEC_LEVEL        = OpsecLevel.LOW
    REQUIRES           = ["open_ports"]
    OUTPUTS            = ["service_versions", "vulnerable_services"]
    MITRE_TECHNIQUES   = ["T1046", "T1590.004"]
    PARAMS_MODEL       = ServiceDetectParams

    async def validate(self, ctx: "Any") -> None:
        """Pre-flight param checks before any network call."""
        from ares.core.context import ExecutionContext
        from ares.core.errors import ModuleValidationError
        if not isinstance(ctx, ExecutionContext):
            return
        if isinstance(ctx.params, dict):
            if not ctx.params.get("target") and getattr(ctx, "target", None):
                ctx.params["target"] = ctx.target
        target = getattr(ctx, "target", "") or (ctx.params.get("target", "") if isinstance(ctx.params, dict) else getattr(ctx.params, "target", ""))
        if not target:
            raise ModuleValidationError(
                f"{self.MODULE_ID} requires 'target' - IP or hostname.",
                module_id=self.MODULE_ID, field="target",
            )
        await super().validate(ctx)

    async def execute(self, ctx: "Any") -> "ModuleResult":
        """ExecutionContext-based entry point (v0.9.0+).
        Thin adapter: extract params from ctx → call run() → return ModuleResult.
        """
        from ares.modules.base import ModuleResult
        if getattr(ctx, "dry_run", False):
            return ModuleResult(status="dry_run", module_id=self.MODULE_ID,
                                raw={"dry_run": True})
        target = getattr(ctx, "target", "")
        ports = []
        timeout = 3.0
        extra_params: dict[str, Any] = {}

        params = getattr(ctx, "params", {})
        if isinstance(params, ServiceDetectParams):
            target = params.target or target
            ports = params.ports or []
            timeout = params.timeout or timeout
        elif isinstance(params, dict):
            target = params.get("target") or target
            ports = params.get("ports", [])
            timeout = float(params.get("timeout", 3.0))
            extra_params = {k: v for k, v in params.items() if k not in ("target", "ports", "timeout")}

        findings, raw = await self.run(
            target=target, ports=ports, timeout=timeout, **extra_params,
        )

        # Cryptographic Evidence Records with SHA-256 Merkle Provenance
        evidence_chain: list[EvidenceRecord] = []
        for finding in findings:
            ev = EvidenceRecord(
                artifact_id=f"service-detect-{target.replace('.', '-')}",
                source_target=target,
                collected_by=self.MODULE_ID,
                data={
                    "target": target,
                    "title": finding.title,
                    "severity": str(finding.severity),
                },
                tags=["network", "service_detect"],
            )
            evidence_chain.append(ev)

        raw["evidence_chain"] = [e.data for e in evidence_chain]
        raw["evidence_integrity"] = [e.record_hash for e in evidence_chain]

        # Closed-loop Purple Telemetry Synthesis (Sentinel KQL + Sigma YAML)
        kql_rule = (
            "// Microsoft Sentinel - Multi-Port Service Banner Enumeration\n"
            "NetworkSession\n"
            "| where TimeGenerated > ago(1h)\n"
            "| where DestinationPort in (21, 22, 25, 80, 443, 6379, 8080, 8443, 27017)\n"
            "| summarize PortCount = dcount(DestinationPort), BytesReceived = sum(BytesReceived), SessionCount = count() by SourceIp, DestinationIp, bin(TimeGenerated, 5m)\n"
            "| where PortCount >= 3 or (SessionCount >= 5 and BytesReceived < 5000)\n"
            "| project TimeGenerated, SourceIp, DestinationIp, PortCount, SessionCount"
        )
        sigma_rule = (
            "title: Network Service Banner Grabbing and Version Enumeration\n"
            "id: e8a91b2c-3d4e-4f5a-b6c7-d8e9f0a1b2c3\n"
            "status: experimental\n"
            "description: Detects rapid connection handshakes and probe queries targeted at service banner ports\n"
            "references:\n"
            "    - https://attack.mitre.org/techniques/T1046/\n"
            "author: ARES Purple Team Modernization\n"
            "date: 2026-03-30\n"
            "logsource:\n"
            "    category: network_traffic\n"
            "detection:\n"
            "    selection:\n"
            "        DestinationPort:\n"
            "            - 21\n"
            "            - 22\n"
            "            - 25\n"
            "            - 80\n"
            "            - 443\n"
            "            - 6379\n"
            "            - 8080\n"
            "            - 8443\n"
            "            - 27017\n"
            "    condition: selection | count(DestinationPort) by SourceIp, DestinationIp > 3\n"
            "level: medium\n"
            "tags:\n"
            "    - attack.discovery\n"
            "    - attack.t1046"
        )
        raw.setdefault("loot", {})
        raw["loot"]["detection_kql"] = kql_rule
        raw["loot"]["detection_sigma"] = sigma_rule
        raw["banner_exposure_detected"] = bool(raw.get("service_versions"))
        raw["unauthenticated_service_risk"] = any(
            "no-auth" in vs.get("cve_hint", "") for vs in raw.get("vulnerable_services", [])
        )
        raw["legacy_version_detected"] = bool(raw.get("vulnerable_services"))
        raw["service_enumeration_audited"] = True

        return ModuleResult(
            status="success" if (findings or raw.get("service_versions")) else "partial",
            findings=findings, raw=raw, module_id=self.MODULE_ID,
            execution_id=getattr(ctx, "execution_id", ""),
        )

    @trace_module("network.service_detect")
    async def run(self, **kwargs: Any) -> tuple[list[Finding], dict[str, Any]]:
        target  = kwargs.get("target", "")
        ports   = kwargs.get("ports") or []
        dry_run = kwargs.get("dry_run", False)

        if not target:
            return [], {"error": "no_target"}
        if not ports:
            return [], {"error": "no_ports_provided", "hint":
                        "Run network.port_scan first to populate open_ports"}
        if dry_run:
            return [], {"dry_run": True, "target": target}

        await self.before_request(target, "tcp")  # scope check + jitter

        logger.info("service_detect_start", target=target, ports=ports)
        await self.noise.rate_limiter.acquire("network_scan")
        await self.noise.jitter.sleep()

        service_versions: dict[int, dict[str, str]] = {}
        vuln_services: list[dict[str, Any]] = []

        async def probe_port(port: int) -> None:
            await self.noise.jitter.sleep()
            # Decide TLS
            use_tls = port in (443, 636, 993, 995, 8443, 5986)
            banner  = await _grab_banner(target, port, use_tls=use_tls)
            if not banner:
                # Try TLS on non-standard ports if plain failed
                if not use_tls:
                    banner = await _grab_banner(target, port, use_tls=True)

            if not banner:
                return

            entry: dict[str, str] = {"banner": banner[:200]}

            # Fingerprint against known patterns
            for svc_name, pattern, severity, cve_hint in _VULN_PATTERNS:
                m = re.search(pattern, banner, re.IGNORECASE)
                if m:
                    version = m.group(1) if m.lastindex else "detected"
                    entry["service"] = svc_name
                    entry["version"] = version
                    if cve_hint:
                        entry["cve_hint"] = cve_hint
                        vuln_services.append({
                            "host": target, "port": port, "service": svc_name,
                            "version": version, "cve_hint": cve_hint,
                            "severity": severity,
                        })
                    break

            service_versions[port] = entry

        # Probe all ports with bounded concurrency
        semaphore = asyncio.Semaphore(10)
        async def bounded(port: int) -> None:
            async with semaphore:
                await probe_port(port)

        await asyncio.gather(*[bounded(p) for p in ports])

        # Findings for vulnerable/interesting services
        for vs in vuln_services:
            sev = {"CRITICAL": Severity.CRITICAL, "HIGH": Severity.HIGH,
                   "MEDIUM": Severity.MEDIUM}.get(vs["severity"], Severity.INFO)
            self.finding(
                title=f"Service Version Identified: {vs['service'].upper()} {vs['version']} on port {vs['port']}",
                description=(
                    f"{vs['service']} {vs['version']} running on {target}:{vs['port']}. "
                    f"{vs.get('cve_hint', 'Check for known CVEs for this version.')}"
                ),
                severity=sev,
                mitre_technique="T1046",
                mitre_tactic="Discovery",
                evidence=vs,
                remediation=(
                    f"Update {vs['service']} to the latest stable version. "
                    "Apply vendor security patches promptly."
                ),
                host=target,
                confidence=0.9,
            )

        # Fingerprint host OS from service banners
        banners_list = [entry.get("banner", "") for entry in service_versions.values() if entry.get("banner")]
        detected_os_info = _fingerprint_os_from_banners(banners_list)
        if not detected_os_info and any(int(p) == 22 for p in service_versions.keys()):
            detected_os_info = {"os": "linux", "distro": "Linux (OpenSSH / SSH Service)", "confidence": 0.85}

        if detected_os_info:
            self.finding(
                title=f"Host Operating System Identified: {detected_os_info['distro']}",
                description=(
                    f"Target host {target} was identified via service banner analysis as "
                    f"{detected_os_info['distro']} (OS family: {detected_os_info['os']}, confidence: {int(detected_os_info['confidence'] * 100)}%)."
                ),
                severity=Severity.INFO,
                mitre_technique="T1046",
                mitre_tactic="Discovery",
                evidence=detected_os_info,
                remediation="Restrict public banner information where possible to reduce reconnaissance precision.",
                host=target,
                confidence=detected_os_info["confidence"],
            )

        raw = {
            "target":           target,
            "service_versions": {str(k): v for k, v in service_versions.items()},
            "vulnerable_services": vuln_services,
            "os_fingerprint":   detected_os_info,
            "os":               detected_os_info["os"] if detected_os_info else "target",
            "detected_os":      detected_os_info["os"] if detected_os_info else "target",
        }
        return self._findings[:], raw