pentester-mcp 0.3.0__py3-none-any.whl

pentest_agent/__init__.py

@@ -0,0 +1,3 @@
+"""pentest-mcp: authorization-gated penetration testing tools for agentic AI."""
+
+__version__ = "0.3.0"

pentest_agent/assets.py

@@ -0,0 +1,104 @@
+"""Asset inventory: what the assessment discovered, in one place.
+
+Every recon tool records hosts, services and technologies here so the final
+report can present an attack-surface view instead of isolated tool output.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class AssetStore:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else Path("evidence") / "assets.json"
+        self._lock = threading.Lock()
+        self._data: dict = {"hosts": {}, "services": {}, "technologies": {}, "updated_at": ""}
+        self._load()
+
+    def _load(self) -> None:
+        if self.path.is_file():
+            try:
+                self._data = json.loads(self.path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    def _save(self) -> None:
+        self._data["updated_at"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(self._data, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    def record_host(self, host: str, ips: list[str] | tuple[str, ...] = (), source: str = "") -> None:
+        host = (host or "").strip().lower().rstrip(".")
+        if not host:
+            return
+        with self._lock:
+            entry = self._data["hosts"].setdefault(host, {"ips": [], "sources": []})
+            for ip in ips:
+                if ip and ip not in entry["ips"]:
+                    entry["ips"].append(ip)
+            if source and source not in entry["sources"]:
+                entry["sources"].append(source)
+            self._save()
+
+    def record_service(self, host: str, port: int, proto: str = "tcp", banner: str = "", source: str = "") -> None:
+        host = (host or "").strip().lower().rstrip(".")
+        if not host:
+            return
+        with self._lock:
+            key = f"{host}:{port}/{proto}"
+            entry = self._data["services"].setdefault(
+                key, {"host": host, "port": port, "proto": proto, "banner": "", "source": source}
+            )
+            if banner and not entry["banner"]:
+                entry["banner"] = banner[:200]
+            host_entry = self._data["hosts"].setdefault(host, {"ips": [], "sources": []})
+            src = source or "service-scan"
+            if src not in host_entry["sources"]:
+                host_entry["sources"].append(src)
+            self._save()
+
+    def record_tech(self, url: str, technologies: list[str] | tuple[str, ...], source: str = "") -> None:
+        with self._lock:
+            entry = self._data["technologies"].setdefault(url, {"tech": [], "source": source})
+            for tech in technologies:
+                if tech and tech not in entry["tech"]:
+                    entry["tech"].append(tech)
+            self._save()
+
+    def inventory(self) -> dict:
+        with self._lock:
+            hosts = self._data.get("hosts", {})
+            services = self._data.get("services", {})
+            tech = self._data.get("technologies", {})
+            return {
+                "hosts": [
+                    {"host": h, **info,
+                     "services": sorted(
+                         (s for s in services if services[s]["host"] == h), key=_svc_key
+                     )}
+                    for h, info in sorted(hosts.items())
+                ],
+                "service_count": len(services),
+                "technologies": [{"url": u, **info} for u, info in sorted(tech.items())],
+                "updated_at": self._data.get("updated_at", ""),
+            }
+
+    def counts(self) -> dict:
+        with self._lock:
+            return {
+                "hosts": len(self._data.get("hosts", {})),
+                "services": len(self._data.get("services", {})),
+                "urls_with_tech": len(self._data.get("technologies", {})),
+            }
+
+
+def _svc_key(key: str) -> tuple:
+    try:
+        port = int(key.rsplit(":", 1)[1].split("/")[0])
+    except (ValueError, IndexError):
+        port = 0
+    return (port, key)

pentest_agent/audit.py

@@ -0,0 +1,62 @@
+"""Append-only audit trail. Every tool call is recorded before it runs."""
+
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+class AuditLog:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else Path.home() / ".pentest-mcp" / "audit.jsonl"
+        self._lock = threading.Lock()
+
+    def record(
+        self,
+        action: str,
+        target: str = "",
+        params: dict | None = None,
+        outcome: str = "started",
+        detail: str = "",
+    ) -> None:
+        entry = {
+            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
+            "action": action,
+            "target": target,
+            "params": _redact(params or {}),
+            "outcome": outcome,
+            "detail": detail[:2000],
+        }
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        line = json.dumps(entry, ensure_ascii=False)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+
+    def tail(self, n: int = 50) -> list[dict]:
+        if not self.path.is_file():
+            return []
+        with self._lock:
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+        out = []
+        for line in lines[-n:]:
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+        return out
+
+
+_SECRET_KEYS = {"password", "passwd", "secret", "token", "authorization", "api_key", "apikey"}
+
+
+def _redact(params: dict) -> dict:
+    clean = {}
+    for key, value in params.items():
+        if key.lower() in _SECRET_KEYS:
+            clean[key] = "[redacted]"
+        else:
+            clean[key] = value
+    return clean

pentest_agent/engagement.example.json

@@ -0,0 +1,32 @@
+{
+  "engagement_id": "ENG-2026-001",
+  "client": "PT Contoh Sejahtera",
+  "operator": "Nama Penguji",
+  "authorization": {
+    "statement": "Written authorisation obtained from CISO via RoA/2026/001 on 2026-01-05, covering external web application testing only.",
+    "reference": "RoA/2026/001",
+    "valid_from": "2026-01-05",
+    "valid_until": "2026-01-20"
+  },
+  "scope": {
+    "domains": ["example.com", "*.example.com"],
+    "cidrs": ["203.0.113.0/28"],
+    "ips": ["203.0.113.10"],
+    "urls": ["https://app.example.com"],
+    "excluded": ["pay.example.com", "203.0.113.13"]
+  },
+  "rules": {
+    "active_scanning": true,
+    "exploit_authorized": false,
+    "allow_payload_execution": false,
+    "credential_testing": false,
+    "rate_limit_rps": 2.0,
+    "no_dos": true,
+    "window": {
+      "start": "09:00",
+      "end": "18:00",
+      "timezone": "Asia/Jakarta"
+    }
+  },
+  "evidence_dir": "./evidence/ENG-2026-001"
+}

pentest_agent/engagement.py

@@ -0,0 +1,320 @@
+"""Engagement scope + authorization gate.
+
+Every network-touching tool in this package refuses to act on a target that is
+not inside the loaded engagement scope. The engagement file is written and
+signed off by the client before testing starts; it is the single source of
+truth for what may be tested, how hard, and when.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+from dataclasses import dataclass, field
+from datetime import date, datetime, time
+from pathlib import Path
+from urllib.parse import urlparse
+from zoneinfo import ZoneInfo
+
+
+class ScopeError(Exception):
+    """Raised when an action would fall outside the engagement scope."""
+
+
+@dataclass(frozen=True)
+class Authorization:
+    statement: str
+    reference: str = ""
+    valid_from: str = ""
+    valid_until: str = ""
+
+    def is_valid(self, today: date | None = None) -> bool:
+        today = today or date.today()
+        try:
+            if self.valid_from and today < date.fromisoformat(self.valid_from):
+                return False
+            if self.valid_until and today > date.fromisoformat(self.valid_until):
+                return False
+        except ValueError:
+            return False
+        return True
+
+
+@dataclass(frozen=True)
+class Window:
+    start: str = ""
+    end: str = ""
+    timezone: str = "UTC"
+
+    def allows(self, now: datetime | None = None) -> bool:
+        if not (self.start and self.end):
+            return True
+        try:
+            tz = ZoneInfo(self.timezone)
+            start = time.fromisoformat(self.start)
+            end = time.fromisoformat(self.end)
+        except (ValueError, KeyError):
+            return True
+        now = now or datetime.now(tz)
+        current = now.astimezone(tz).time()
+        if start <= end:
+            return start <= current <= end
+        return current >= start or current <= end
+
+
+@dataclass(frozen=True)
+class Rules:
+    active_scanning: bool = False
+    exploit_authorized: bool = False
+    allow_payload_execution: bool = False
+    credential_testing: bool = False
+    rate_limit_rps: float = 2.0
+    no_dos: bool = True
+    window: Window = field(default_factory=Window)
+
+
+@dataclass(frozen=True)
+class Engagement:
+    engagement_id: str
+    client: str
+    operator: str
+    authorization: Authorization
+    domains: tuple[str, ...] = ()
+    cidrs: tuple[str, ...] = ()
+    ips: tuple[str, ...] = ()
+    urls: tuple[str, ...] = ()
+    excluded: tuple[str, ...] = ()
+    rules: Rules = field(default_factory=Rules)
+    evidence_dir: str = ""
+
+    # ---------------------------------------------------------------- load
+    @classmethod
+    def from_file(cls, path: str | Path) -> "Engagement":
+        p = Path(path).expanduser().resolve()
+        if not p.is_file():
+            raise ScopeError(f"engagement file not found: {p}")
+        try:
+            raw = json.loads(p.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            raise ScopeError(f"engagement file is not valid JSON: {exc}") from exc
+
+        auth_raw = raw.get("authorization") or {}
+        auth = Authorization(
+            statement=str(auth_raw.get("statement", "")).strip(),
+            reference=str(auth_raw.get("reference", "")),
+            valid_from=str(auth_raw.get("valid_from", "")),
+            valid_until=str(auth_raw.get("valid_until", "")),
+        )
+        if not auth.statement:
+            raise ScopeError(
+                "authorization.statement is required: record who authorized this test and when"
+            )
+
+        rules_raw = raw.get("rules") or {}
+        window_raw = rules_raw.get("window") or {}
+        rules = Rules(
+            active_scanning=bool(rules_raw.get("active_scanning", False)),
+            exploit_authorized=bool(rules_raw.get("exploit_authorized", False)),
+            allow_payload_execution=bool(rules_raw.get("allow_payload_execution", False)),
+            credential_testing=bool(rules_raw.get("credential_testing", False)),
+            rate_limit_rps=float(rules_raw.get("rate_limit_rps", 2.0)),
+            no_dos=bool(rules_raw.get("no_dos", True)),
+            window=Window(
+                start=str(window_raw.get("start", "")),
+                end=str(window_raw.get("end", "")),
+                timezone=str(window_raw.get("timezone", "UTC")),
+            ),
+        )
+
+        scope_raw = raw.get("scope") or {}
+        eng = cls(
+            engagement_id=str(raw.get("engagement_id", "")).strip() or "ENG-UNSET",
+            client=str(raw.get("client", "")).strip(),
+            operator=str(raw.get("operator", "")).strip(),
+            authorization=auth,
+            domains=_tup(scope_raw.get("domains")),
+            cidrs=_tup(scope_raw.get("cidrs")),
+            ips=_tup(scope_raw.get("ips")),
+            urls=_tup(scope_raw.get("urls")),
+            excluded=_tup(scope_raw.get("excluded")),
+            rules=rules,
+            evidence_dir=str(raw.get("evidence_dir", "")),
+        )
+        if not (eng.domains or eng.cidrs or eng.ips or eng.urls):
+            raise ScopeError("scope is empty: nothing is authorised for testing")
+        return eng
+
+    # --------------------------------------------------------------- scope
+    def _norm_host(self, host: str) -> str:
+        return host.strip().lower().rstrip(".")
+
+    def _host_in(self, host: str, patterns: tuple[str, ...]) -> bool:
+        host = self._norm_host(host)
+        for pat in patterns:
+            pat = self._norm_host(pat)
+            if pat.startswith("*."):
+                suffix = pat[1:]  # ".example.com"
+                if host.endswith(suffix) and len(host) > len(suffix):
+                    return True
+            elif host == pat or host.endswith("." + pat):
+                return True
+        return False
+
+    def _ip_in(self, ip: str, patterns: tuple[str, ...]) -> bool:
+        try:
+            addr = ipaddress.ip_address(ip)
+        except ValueError:
+            return False
+        for pat in patterns:
+            try:
+                if addr in ipaddress.ip_network(pat, strict=False):
+                    return True
+            except ValueError:
+                continue
+        return False
+
+    def _parse_target(self, target: str) -> tuple[str, str]:
+        """Return (kind, value) where kind in {host, ip} and value is the host/IP."""
+        t = target.strip()
+        if "://" in t:
+            parsed = urlparse(t)
+            host = parsed.hostname or ""
+            return ("host" if host else "ip", self._norm_host(host))
+        if "/" in t and not t.startswith("/"):
+            # CIDR input: treat as network, checked separately.
+            return ("cidr", t.strip())
+        host = t.split("/")[0].split("@")[-1]
+        host = host.split(":")[0].strip()
+        if not host:
+            raise ScopeError(f"cannot parse target: {target!r}")
+        return ("host", self._norm_host(host))
+
+    def is_in_scope(self, target: str) -> tuple[bool, str]:
+        """Check a target against the scope. Returns (allowed, reason)."""
+        kind, value = self._parse_target(target)
+
+        if self._host_in(value, self.excluded) or self._ip_in(value, self.excluded):
+            return False, f"{value!r} is explicitly excluded from scope"
+        if kind == "cidr":
+            try:
+                net = ipaddress.ip_network(value, strict=False)
+            except ValueError:
+                return False, f"invalid CIDR: {value!r}"
+            for pat in self.cidrs:
+                other = ipaddress.ip_network(pat, strict=False)
+                if net.subnet_of(other):
+                    return True, f"CIDR {value} inside scope network {pat}"
+            return False, f"CIDR {value!r} is not inside a scoped network"
+
+        if kind == "ip" or _looks_like_ip(value):
+            if self._ip_in(value, self.cidrs) or self._ip_in(value, self.ips):
+                return True, f"IP {value} is in scope"
+            return False, f"IP {value!r} is not in scope (scope.ips / scope.cidrs)"
+
+        if self._host_in(value, self.domains):
+            return True, f"host {value} matches scoped domain"
+        for u in self.urls:
+            parsed = urlparse(u if "://" in u else "https://" + u)
+            if self._norm_host(parsed.hostname or "") == value:
+                return True, f"host {value} matches scoped URL {u}"
+        return False, f"host {value!r} is not in scope (scope.domains / scope.urls)"
+
+    # ---------------------------------------------------------------- gate
+    def assert_target(self, target: str) -> str:
+        """Raise ScopeError unless the target is authorised. Returns the target."""
+        if not self.authorization.is_valid():
+            raise ScopeError(
+                "engagement authorization is outside its validity window "
+                f"({self.authorization.valid_from} .. {self.authorization.valid_until})"
+            )
+        if not self.rules.window.allows():
+            raise ScopeError(
+                "outside the agreed testing window "
+                f"{self.rules.window.start}-{self.rules.window.end} {self.rules.window.timezone}"
+            )
+        ok, reason = self.is_in_scope(target)
+        if not ok:
+            raise ScopeError(f"refused: {reason}")
+        return target.strip()
+
+    def assert_active(self) -> None:
+        if not self.rules.active_scanning:
+            raise ScopeError(
+                "active scanning is not authorised in this engagement "
+                "(rules.active_scanning = false); passive/recon-only mode"
+            )
+
+    def assert_exploit(self, payload: bool = False) -> None:
+        if not self.rules.exploit_authorized:
+            raise ScopeError(
+                "exploitation is not authorised in this engagement "
+                "(rules.exploit_authorized = false)"
+            )
+        if payload and not self.rules.allow_payload_execution:
+            raise ScopeError(
+                "payload execution is not authorised (rules.allow_payload_execution = false); "
+                "verification/check mode only"
+            )
+
+    def assert_credentials(self) -> None:
+        if not self.rules.credential_testing:
+            raise ScopeError(
+                "credential testing is not authorised in this engagement "
+                "(rules.credential_testing = false)"
+            )
+
+    def summary(self) -> dict:
+        return {
+            "engagement_id": self.engagement_id,
+            "client": self.client,
+            "operator": self.operator,
+            "authorization": {
+                "reference": self.authorization.reference,
+                "valid_from": self.authorization.valid_from,
+                "valid_until": self.authorization.valid_until,
+                "valid_today": self.authorization.is_valid(),
+            },
+            "scope": {
+                "domains": list(self.domains),
+                "cidrs": list(self.cidrs),
+                "ips": list(self.ips),
+                "urls": list(self.urls),
+                "excluded": list(self.excluded),
+            },
+            "rules": {
+                "active_scanning": self.rules.active_scanning,
+                "exploit_authorized": self.rules.exploit_authorized,
+                "allow_payload_execution": self.rules.allow_payload_execution,
+                "credential_testing": self.rules.credential_testing,
+                "rate_limit_rps": self.rules.rate_limit_rps,
+                "no_dos": self.rules.no_dos,
+                "window": {
+                    "start": self.rules.window.start,
+                    "end": self.rules.window.end,
+                    "timezone": self.rules.window.timezone,
+                    "now_allowed": self.rules.window.allows(),
+                },
+            },
+            "evidence_dir": self.evidence_dir,
+        }
+
+    def evidence_path(self) -> Path:
+        base = Path(self.evidence_dir).expanduser() if self.evidence_dir else Path("evidence")
+        base.mkdir(parents=True, exist_ok=True)
+        return base
+
+
+def _tup(value) -> tuple[str, ...]:
+    if not value:
+        return ()
+    if isinstance(value, str):
+        return (value,)
+    return tuple(str(v) for v in value)
+
+
+def _looks_like_ip(value: str) -> bool:
+    try:
+        ipaddress.ip_address(value)
+        return True
+    except ValueError:
+        return False

pentest_agent/findings.py

@@ -0,0 +1,75 @@
+"""Finding model + JSONL store. Findings are the plugin's durable output."""
+
+from __future__ import annotations
+
+import json
+import threading
+import uuid
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+SEVERITIES = ("info", "low", "medium", "high", "critical")
+
+
+@dataclass
+class Finding:
+    title: str
+    severity: str
+    target: str
+    description: str = ""
+    evidence: str = ""
+    recommendation: str = ""
+    cvss: float | None = None
+    cve: str = ""
+    cwe: str = ""
+    tool: str = "manual"
+    status: str = "open"  # open | verified | false-positive
+    id: str = field(default_factory=lambda: f"F-{uuid.uuid4().hex[:8]}")
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat(timespec="seconds"))
+
+    def __post_init__(self):
+        if self.severity not in SEVERITIES:
+            raise ValueError(f"severity must be one of {SEVERITIES}, got {self.severity!r}")
+
+
+class FindingStore:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else Path("evidence") / "findings.jsonl"
+        self._lock = threading.Lock()
+
+    def add(self, finding: Finding) -> Finding:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(asdict(finding), ensure_ascii=False) + "\n")
+        return finding
+
+    def load(self) -> list[Finding]:
+        if not self.path.is_file():
+            return []
+        out: list[Finding] = []
+        with self._lock:
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                out.append(Finding(**json.loads(line)))
+            except (json.JSONDecodeError, TypeError, ValueError):
+                continue
+        return out
+
+    def list(self, severity: str | None = None, status: str | None = None) -> list[Finding]:
+        items = self.load()
+        if severity:
+            items = [f for f in items if f.severity == severity]
+        if status:
+            items = [f for f in items if f.status == status]
+        return items
+
+    def counts(self) -> dict[str, int]:
+        counts = {s: 0 for s in SEVERITIES}
+        for f in self.load():
+            counts[f.severity] += 1
+        return counts