netexec-mcp 1.0.0__py3-none-any.whl

netexec_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""netexec-mcp: an MCP server that drives NetExec (nxc) for authorized security testing."""
+
+__version__ = "0.1.0"

netexec_mcp/auth.py

@@ -0,0 +1,156 @@
+"""Shared authentication model -> nxc flags.
+
+Every protocol module accepts the same credential parameters; this module turns
+them into the argv flags nxc expects, with light validation of nonsensical
+combinations. It builds *only* the auth-related flags -- targets and per-tool
+action flags (e.g. ``--shares``) are added by the caller.
+
+Mapping (per PLAN.md "Shared auth model -> flags"):
+  username      -> -u
+  password      -> -p
+  ntlm_hash     -> -H   (pass-the-hash)
+  domain        -> -d
+  local_auth    -> --local-auth
+  kerberos      -> -k
+  use_kcache    -> --use-kcache  (implies kerberos)
+  cred_id       -> -id  (use a credential already stored in nxc's DB)
+"""
+
+from __future__ import annotations
+
+
+class AuthError(ValueError):
+    """Raised for contradictory credential parameters (nothing runs)."""
+
+
+def _as_list(value) -> list[str]:
+    """Normalise a str | list[str] | None credential field to a list of tokens."""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value]
+    return [str(v) for v in value]
+
+
+# The blank/empty-LM hash. nxc's DB stores a pass-the-hash secret as `<LM>:<NT>`, and for a
+# modern account the LM half is this constant. Passing the full `<blankLM>:<NT>` can fail
+# auth (observed live: NTDS dump -> STATUS_LOGON_FAILURE on a DC that refuses LM) while the
+# bare NT hash succeeds -- so reduce a blank-LM pair to just the NT half.
+_BLANK_LM = "aad3b435b51404eeaad3b435b51404ee"
+
+
+def _nt_only(h: str) -> str:
+    """Reduce a `LM:NT` hash whose LM half is the blank-LM value (or empty) to the bare NT
+    hash. A real (non-blank) LM half, a plain NT hash, and a non-hash token (e.g. a wordlist
+    path) are returned unchanged -- only an exact blank-LM prefix is stripped."""
+    lm, sep, nt = h.partition(":")
+    if sep and nt and (lm.lower() == _BLANK_LM or lm == ""):
+        return nt
+    return h
+
+
+def build_auth_flags(
+    username: "str | list[str] | None" = None,
+    password: "str | list[str] | None" = None,
+    ntlm_hash: "str | list[str] | None" = None,
+    domain: str | None = None,
+    local_auth: bool = False,
+    kerberos: bool = False,
+    use_kcache: bool = False,
+    cred_id: int | None = None,
+    laps: str | None = None,
+    kdc_host: str | None = None,
+    aes_key: str | None = None,
+    ccache: str | None = None,
+    pfx_cert: str | None = None,
+    pfx_base64: str | None = None,
+    pfx_pass: str | None = None,
+    pem_cert: str | None = None,
+    pem_key: str | None = None,
+) -> list[str]:
+    """Translate credential parameters into an nxc auth flag list.
+
+    username/password/ntlm_hash accept either a single value or a list (for
+    password spraying); each list entry may be a literal value or a path to a
+    wordlist file that nxc reads. `laps` enables LAPS auth (`--laps <account>`):
+    nxc reads the target's LAPS-managed local-admin password from AD using the
+    supplied creds, then authenticates with it -- pass the account name (use
+    "administrator" for the nxc default). Raises AuthError on contradictory
+    combinations so a bad call is rejected before any command is built.
+    """
+    usernames = _as_list(username)
+    passwords = _as_list(password)
+    hashes = _as_list(ntlm_hash)
+    cert_auth = bool(pfx_cert or pfx_base64 or pem_cert)
+
+    if passwords and hashes:
+        raise AuthError("provide either password(s) or NTLM hash(es), not both.")
+    if local_auth and domain:
+        raise AuthError("--local-auth authenticates locally; do not also set a domain.")
+    if cred_id is not None and (usernames or passwords or hashes or domain or local_auth):
+        raise AuthError(
+            "cred_id uses a credential stored in nxc's DB; do not also pass "
+            "username/password/hash/domain/local_auth."
+        )
+    if cert_auth and not usernames:
+        raise AuthError("certificate authentication requires a username.")
+    if bool(pem_cert) != bool(pem_key):
+        raise AuthError("PEM certificate auth needs both pem_cert and pem_key.")
+
+    flags: list[str] = []
+
+    if cred_id is not None:
+        flags += ["-id", str(cred_id)]
+    else:
+        if domain:
+            flags += ["-d", domain]
+        for user in usernames:
+            flags += ["-u", user]
+        for pw in passwords:
+            flags += ["-p", pw]
+        if usernames and not passwords and not hashes and not (kerberos or use_kcache or aes_key or ccache or cert_auth):
+            # Username(s) with no secret = empty-password (guest/null) bind. nxc
+            # needs an explicit `-p ''`; emitting it here makes guest auth reliable
+            # without an agent having to serialise an empty string (which MCP
+            # clients routinely mangle). `-u guest` -> `-u guest -p ''`.
+            flags += ["-p", ""]
+        for h in hashes:
+            flags += ["-H", _nt_only(h)]
+        if local_auth:
+            flags.append("--local-auth")
+
+    # Certificate authentication (PKINIT / ADCS) -- a distinct method (requires a
+    # username, checked above). Provide a pfx (file or base64, optional --pfx-pass)
+    # OR a PEM cert+key pair.
+    if pfx_cert:
+        flags += ["--pfx-cert", pfx_cert]
+    if pfx_base64:
+        flags += ["--pfx-base64", pfx_base64]
+    if pfx_pass:
+        flags += ["--pfx-pass", pfx_pass]
+    if pem_cert:
+        flags += ["--pem-cert", pem_cert]
+    if pem_key:
+        flags += ["--pem-key", pem_key]
+
+    if laps:
+        flags += ["--laps", laps]
+
+    # Kerberos options. `--aesKey` is itself a Kerberos secret (overpass-the-key;
+    # pairs with the aes256/aes128 keys recovered by smb_lsa/smb_ntds) -- nxc treats
+    # its presence as enabling Kerberos, so no separate -k is needed. `--kdcHost`
+    # names the KDC and is often required for `-k` to resolve the DC.
+    if aes_key:
+        flags += ["--aesKey", aes_key]
+    if kdc_host:
+        flags += ["--kdcHost", kdc_host]
+
+    # Kerberos can layer on top of either path (e.g. -k with a username, or
+    # --use-kcache with a stored ticket). A `ccache` path implies --use-kcache
+    # (the executor points KRB5CCNAME at it; nxc has no ccache flag).
+    if use_kcache or ccache:
+        flags.append("--use-kcache")
+    elif kerberos:
+        flags.append("-k")
+
+    return flags

netexec_mcp/config.py

@@ -0,0 +1,219 @@
+"""Environment resolution and NetExec base-command detection.
+
+The base command is how this server invokes nxc. Resolution order (per PLAN.md):
+  1. NXC_COMMAND env (shlex-parsed) if set -- covers uv/poetry/pipx/docker installs.
+  2. else auto-detect `nxc` / `netexec` on PATH.
+  3. else fail fast with setup help.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+import shlex
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+# All protocol-modules nxc supports that we expose as tool groups. Enabled subset
+# is controlled by NXC_PROTOCOLS; default is all of them.
+DEFAULT_PROTOCOLS = [
+    "smb", "ldap", "winrm", "ssh", "mssql", "wmi", "rdp", "ftp", "nfs", "vnc",
+]
+
+# The single operating-mode control (NXC_MODE), with four escalating levels:
+#   suggest -- return the resolved command, never execute (the auditor runs it).
+#              Scope is still enforced; offensive commands *can* be previewed.
+#   recon   -- execute read-only enumeration; everything beyond it is blocked. (default)
+#   loot    -- also permit read-only *credential-dumping* (sam/lsa/ntds/gpp/roasting):
+#              no state change on the target, but it harvests credential material.
+#   full    -- execute everything, including state-changing / privilege-escalation
+#              actions (exec, write, spray, coercion-with-listener, exploits).
+# The recon<loot<full split mirrors nxc's own module taxonomy (ENUMERATION <
+# CREDENTIAL_DUMPING < PRIVILEGE_ESCALATION).
+VALID_MODES = ("suggest", "recon", "loot", "full")
+
+# How the tool surface is presented (NXC_TOOL_MODE), independent of the operating
+# mode above:
+#   dynamic -- (DEFAULT) expose only a few meta-tools (catalog/find/describe/call);
+#              the real tools stay registered + callable but are hidden from tools/list.
+#              Keeps the ~46k-token tool surface out of the model's context window --
+#              what makes the server usable on small-context models (and ~8x cheaper on
+#              big ones, same quality). See dynamic.py. Benchmark: dynamic is net-positive
+#              or neutral for 4/5 models tested and the ONLY viable mode for <=8B/32k.
+#   static  -- register every enabled tool as a first-class MCP tool (opt-out). Best for
+#              a decisive one-shot model, or to avoid discovery round-trips on a
+#              big-context model. On a small context the ~46k surface overflows -> a
+#              startup warning is emitted.
+VALID_TOOL_MODES = ("static", "dynamic")
+
+
+class ConfigError(RuntimeError):
+    """Raised when the server cannot determine a valid configuration."""
+
+
+def nxc_home() -> Path:
+    """nxc's home dir, mirroring ``nxc/paths.py``: ``$NXC_PATH`` if set, else
+    ``~/.nxc``. Identical on Linux/macOS/Windows -- nxc uses ``expanduser`` (no
+    ``%APPDATA%``/appdirs), so ``~`` resolves to ``C:\\Users\\<user>`` on Windows.
+    Honoring nxc's own env var keeps our reads aligned with wherever nxc writes.
+    """
+    override = os.environ.get("NXC_PATH")
+    if override and override.strip():
+        return Path(os.path.expanduser(override.strip()))
+    return Path(os.path.expanduser("~/.nxc"))
+
+
+def nxc_config_path() -> Path:
+    """Path to ``nxc.conf`` under the resolved nxc home."""
+    return nxc_home() / "nxc.conf"
+
+
+def nxc_workspace_dir() -> Path:
+    """The ``workspaces/`` dir (per-protocol ``.db`` files) under the nxc home."""
+    return nxc_home() / "workspaces"
+
+
+# nxc's own fallbacks when nxc.conf is absent or a key is unset.
+_NXC_CONF_DEFAULTS = {"pwn3d_label": "Pwn3d!", "workspace": "default"}
+
+
+def read_nxc_conf() -> dict:
+    """Read the operator-configurable ``[nxc]`` ``pwn3d_label`` and ``workspace``.
+
+    Both live in ``nxc.conf`` and can be changed by the operator, so we read them
+    from that single source of truth instead of hardcoding. Falls back to nxc's
+    own defaults when the file is missing/unreadable. ``pwn3d_label`` is preserved
+    verbatim when the key exists (even if blank); a blank ``workspace`` collapses
+    to ``default``.
+    """
+    parser = configparser.ConfigParser(interpolation=None)  # values may contain %
+    try:
+        with open(nxc_config_path(), encoding="utf-8") as fh:
+            parser.read_file(fh)
+    except (OSError, configparser.Error):
+        return dict(_NXC_CONF_DEFAULTS)
+    if not parser.has_section("nxc"):
+        return dict(_NXC_CONF_DEFAULTS)
+    section = parser["nxc"]
+    label = section.get("pwn3d_label", _NXC_CONF_DEFAULTS["pwn3d_label"])
+    workspace = (section.get("workspace") or "").strip() or _NXC_CONF_DEFAULTS["workspace"]
+    return {"pwn3d_label": label, "workspace": workspace}
+
+
+def _env_list(name: str) -> list[str]:
+    """Parse a comma/newline-separated env var into a clean list of tokens."""
+    raw = os.environ.get(name, "")
+    return [p.strip() for p in raw.replace("\n", ",").split(",") if p.strip()]
+
+
+def resolve_base_command() -> list[str]:
+    """Resolve the nxc base command as an argv list (never via a shell).
+
+    Tokens are user-expanded so values like
+    `uv run --directory ~/NetExec netexec` work as written.
+    """
+    explicit = os.environ.get("NXC_COMMAND")
+    if explicit and explicit.strip():
+        argv = [os.path.expanduser(tok) for tok in shlex.split(explicit)]
+        if not argv:
+            raise ConfigError("NXC_COMMAND is set but empty after parsing.")
+        return argv
+
+    for candidate in ("nxc", "netexec"):
+        found = shutil.which(candidate)
+        if found:
+            return [found]
+
+    raise ConfigError(
+        "Could not find NetExec. Set NXC_COMMAND (e.g. "
+        "\"uv run --directory ~/NetExec netexec\") or put 'nxc'/'netexec' on PATH."
+    )
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise ConfigError(f"{name} must be an integer.") from exc
+    if value <= 0:
+        raise ConfigError(f"{name} must be a positive integer.")
+    return value
+
+
+def _resolve_mode() -> tuple[str, bool, bool]:
+    """Resolve the operating mode -> (mode, dry_run, allow_offensive).
+
+    `NXC_MODE` (suggest|recon|full) is the canonical control; the `dry_run` and
+    `allow_offensive` booleans are derived from it. Defaults to `recon` when unset.
+    """
+    raw = os.environ.get("NXC_MODE")
+    mode = raw.strip().lower() if raw and raw.strip() else "recon"
+    if mode not in VALID_MODES:
+        raise ConfigError(
+            f"NXC_MODE must be one of {', '.join(VALID_MODES)}; got {raw!r}."
+        )
+    return mode, mode == "suggest", mode == "full"
+
+
+def _resolve_tool_mode() -> str:
+    """Resolve NXC_TOOL_MODE (static|dynamic); defaults to dynamic (progressive disclosure
+    -- usable on small-context models, cheaper on large ones; set static to opt out)."""
+    raw = (os.environ.get("NXC_TOOL_MODE") or "dynamic").strip().lower()
+    if raw not in VALID_TOOL_MODES:
+        raise ConfigError(
+            f"NXC_TOOL_MODE must be one of {', '.join(VALID_TOOL_MODES)}; got {raw!r}."
+        )
+    return raw
+
+
+@dataclass(frozen=True)
+class Config:
+    base_command: list[str]
+    protocols: list[str]
+    scope: list[str]
+    allow_offensive: bool
+    dry_run: bool
+    timeout: int
+    max_targets: int
+    audit_log: str | None
+    workspace: str | None
+    mode: str = "recon"
+    # loot mode permits credential-dumping (offensive but read-only) on top of recon;
+    # full implies loot. Derived from `mode` in from_env(); see check_offensive().
+    allow_loot: bool = False
+    # Tool-surface presentation (NXC_TOOL_MODE), orthogonal to `mode`. Default "dynamic"
+    # hides the full tool surface behind meta-tools so small-context models can use the
+    # server (see dynamic.py); "static" opts out to listing every tool.
+    tool_mode: str = "dynamic"
+    # From nxc.conf's `[nxc] pwn3d_label` (operator-configurable). Surfaced to the
+    # agent via the auth guide; the MCP itself keys auth on the `[+]` marker, which
+    # nxc does not make configurable.
+    pwn3d_label: str = "Pwn3d!"
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        mode, dry_run, allow_offensive = _resolve_mode()
+        conf = read_nxc_conf()
+        return cls(
+            base_command=resolve_base_command(),
+            protocols=_env_list("NXC_PROTOCOLS") or list(DEFAULT_PROTOCOLS),
+            scope=_env_list("NXC_SCOPE"),
+            allow_offensive=allow_offensive,
+            # loot and full both permit credential-dumping; full additionally permits
+            # state-changing/offensive actions (allow_offensive).
+            allow_loot=mode in ("loot", "full"),
+            dry_run=dry_run,
+            timeout=_env_int("NXC_TIMEOUT", 300),
+            max_targets=_env_int("NXC_MAX_TARGETS", 256),
+            audit_log=os.environ.get("NXC_AUDIT_LOG"),
+            # NXC_WORKSPACE wins; else default to whatever nxc.conf writes to, so
+            # our reads track nxc's writes without extra configuration.
+            workspace=os.environ.get("NXC_WORKSPACE") or conf["workspace"],
+            mode=mode,
+            tool_mode=_resolve_tool_mode(),
+            pwn3d_label=conf["pwn3d_label"],
+        )