exploitgraph 1.0.0__py3-none-any.whl

core/attack_graph.py

@@ -0,0 +1,83 @@
+"""ExploitGraph - Attack path graph engine (networkx)."""
+from __future__ import annotations
+import json
+from typing import TYPE_CHECKING
+import networkx as nx
+if TYPE_CHECKING:
+    from core.session_manager import Session
+
+SEVERITY_COLOR = {"CRITICAL":"#dc2626","HIGH":"#ea580c","MEDIUM":"#d97706",
+                  "LOW":"#16a34a","INFO":"#2563eb"}
+MITRE_REF = {
+    "T1595":"Active Scanning", "T1595.003":"Wordlist Scanning",
+    "T1580":"Cloud Infrastructure Discovery", "T1530":"Data from Cloud Storage",
+    "T1552.001":"Credentials in Files", "T1552.004":"Private Keys",
+    "T1552.005":"Cloud Instance Metadata API", "T1078":"Valid Accounts",
+    "T1078.004":"Valid Accounts: Cloud Accounts", "T1548":"Abuse Elevation Control",
+    "T1550.001":"Application Access Token", "T1069.003":"Cloud Groups",
+    "T1110.001":"Password Guessing",
+}
+
+
+class AttackGraph:
+    def __init__(self): self.G: nx.DiGraph = nx.DiGraph()
+
+    def build(self, session: "Session"):
+        self.G.clear()
+        for n in session.graph_nodes:
+            self.G.add_node(n["node_id"], label=n.get("label",""),
+                            type=n.get("node_type","asset"),
+                            severity=n.get("severity","INFO"),
+                            details=n.get("details",""),
+                            color=SEVERITY_COLOR.get(n.get("severity","INFO"),"#6b7280"))
+        for e in session.graph_edges:
+            if e["source"] in self.G and e["target"] in self.G:
+                self.G.add_edge(e["source"], e["target"],
+                                label=e.get("label",""), technique=e.get("technique",""))
+
+    def find_paths(self, src="attacker", tgt="compromise") -> list[list[str]]:
+        try:
+            nodes = list(self.G.nodes())
+            src = next((n for n in nodes if src in n), src)
+            tgt = next((n for n in nodes if tgt in n.lower()), tgt)
+            return list(nx.all_simple_paths(self.G, src, tgt))
+        except Exception:
+            return []
+
+    def stats(self) -> dict:
+        techs = set()
+        for _,_,d in self.G.edges(data=True):
+            if d.get("technique"): techs.add(d["technique"])
+        critical = [n for n,d in self.G.nodes(data=True) if d.get("severity") in ("CRITICAL","HIGH")]
+        return dict(nodes=self.G.number_of_nodes(), edges=self.G.number_of_edges(),
+                    critical_nodes=len(critical), mitre_techniques=sorted(techs),
+                    is_connected=nx.is_weakly_connected(self.G) if self.G.nodes() else False)
+
+    def to_json(self) -> dict:
+        nodes = [dict(id=nid, label=d.get("label",nid), type=d.get("type","asset"),
+                      severity=d.get("severity","INFO"), details=d.get("details",""),
+                      color=d.get("color","#6b7280"))
+                 for nid,d in self.G.nodes(data=True)]
+        edges = [dict(source=s, target=t, label=d.get("label",""), technique=d.get("technique",""))
+                 for s,t,d in self.G.edges(data=True)]
+        return dict(nodes=nodes, edges=edges, stats=self.stats(), attack_paths=self.find_paths())
+
+    def print_ascii(self) -> str:
+        paths = self.find_paths()
+        if not paths: return "No complete attack path found."
+        path = max(paths, key=len)
+        lines = []
+        colors = {"CRITICAL":"\033[91m","HIGH":"\033[93m","MEDIUM":"\033[96m","INFO":"\033[97m"}
+        for i, nid in enumerate(path):
+            d = self.G.nodes.get(nid, {})
+            label = d.get("label", nid).split("\n")[0]
+            sev   = d.get("severity","INFO")
+            if i > 0:
+                ed = self.G.edges.get((path[i-1], nid), {})
+                tech = ed.get("technique","")
+                lines.append(f"       ↓  {tech}")
+            lines.append(f"{colors.get(sev,'')}  [{sev}] {label}\033[0m")
+        return "\n".join(lines)
+
+
+attack_graph = AttackGraph()

core/aws_client.py

@@ -0,0 +1,284 @@
+"""
+ExploitGraph - AWS Client Factory
+Production-grade boto3 session management with:
+  - Automatic retry with exponential backoff
+  - Region fallback (us-east-1 → us-west-2 → eu-west-1)
+  - Credential injection from session secrets
+  - Standardised response parsing
+  - GuardDuty detection-awareness tagging
+
+All modules call get_client() — no per-module boto3 setup needed.
+"""
+from __future__ import annotations
+import time
+import functools
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from core.session_manager import Session
+
+try:
+    import boto3
+    import botocore.config
+    import botocore.exceptions
+    HAS_BOTO3 = True
+except ImportError:
+    HAS_BOTO3 = False
+
+DEFAULT_REGION   = "us-east-1"
+FALLBACK_REGIONS = ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"]
+
+# Retry config: 3 attempts, exponential backoff
+_RETRY_CONFIG = None
+if HAS_BOTO3:
+    _RETRY_CONFIG = botocore.config.Config(
+        retries={"max_attempts": 3, "mode": "adaptive"},
+        connect_timeout=10,
+        read_timeout=20,
+    )
+
+# GuardDuty-awareness: these API calls are known to trigger alerts
+GUARDDUTY_NOISY_APIS = {
+    "GetCallerIdentity":              "HIGH",    # Recon — always logged
+    "GetAccountAuthorizationDetails": "CRITICAL", # Full IAM dump — very noisy
+    "ListUsers":                      "MEDIUM",
+    "ListRoles":                      "MEDIUM",
+    "CreateAccessKey":                "HIGH",    # Backdoor credential
+    "DeleteTrail":                    "CRITICAL", # Covering tracks
+    "StopLogging":                    "CRITICAL",
+    "PutBucketLogging":               "HIGH",
+    "DescribeInstances":              "LOW",     # Normal ops but logged
+}
+
+GUARDDUTY_STEALTHY_APIS = {
+    "ListBuckets":                    "no-sign-request avoids auth logs",
+    "GetObject":                      "anonymous S3 access not in CloudTrail",
+    "GetBucketAcl":                   "no-sign-request avoids auth logs",
+}
+
+
+def get_client(service: str,
+               session: "Optional[Session]" = None,
+               region:  str = DEFAULT_REGION,
+               profile: str = "",
+               access_key:    str = "",
+               secret_key:    str = "",
+               session_token: str = "") -> Any:
+    """
+    Return a boto3 client. Credential resolution order:
+      1. Explicit access_key/secret_key args
+      2. Session secrets (injected by file_secrets / cloudtrail_analyzer)
+      3. AWS CLI profile
+      4. Default boto3 chain (env vars → ~/.aws → IMDS)
+
+    Includes automatic retry + exponential backoff.
+    Returns None if boto3 unavailable or all credential sources fail.
+    """
+    if not HAS_BOTO3:
+        return None
+
+    if session and not access_key:
+        access_key, secret_key, session_token = _creds_from_session(session)
+
+    return _build_client(service, region, profile,
+                          access_key, secret_key, session_token)
+
+
+def _build_client(service: str, region: str, profile: str,
+                   access_key: str, secret_key: str,
+                   session_token: str) -> Any:
+    """Build boto3 client with retry config and region fallback."""
+    regions_to_try = [region] if region else FALLBACK_REGIONS
+
+    for reg in regions_to_try:
+        try:
+            if access_key and secret_key:
+                client = boto3.client(
+                    service,
+                    region_name=reg,
+                    aws_access_key_id=access_key,
+                    aws_secret_access_key=secret_key,
+                    aws_session_token=session_token or None,
+                    config=_RETRY_CONFIG,
+                )
+            elif profile:
+                boto_session = boto3.Session(profile_name=profile, region_name=reg)
+                client = boto_session.client(service, config=_RETRY_CONFIG)
+            else:
+                client = boto3.client(service, region_name=reg, config=_RETRY_CONFIG)
+            return client
+        except Exception:
+            continue
+
+    return None
+
+
+def get_session(session: "Optional[Session]" = None,
+                region:  str = DEFAULT_REGION,
+                profile: str = "") -> Any:
+    """Return a boto3 Session for multi-service use."""
+    if not HAS_BOTO3:
+        return None
+
+    access_key, secret_key, session_token = "", "", ""
+    if session:
+        access_key, secret_key, session_token = _creds_from_session(session)
+
+    try:
+        if access_key and secret_key:
+            return boto3.Session(
+                region_name=region,
+                aws_access_key_id=access_key,
+                aws_secret_access_key=secret_key,
+                aws_session_token=session_token or None,
+            )
+        elif profile:
+            return boto3.Session(profile_name=profile, region_name=region)
+        else:
+            return boto3.Session(region_name=region)
+    except Exception:
+        return None
+
+
+def safe_call(client: Any, method: str, **kwargs) -> tuple[bool, Any, str]:
+    """
+    Safely call a boto3 client method with retry + error handling.
+
+    Returns: (success, response_or_None, error_message)
+
+    Usage:
+        ok, resp, err = safe_call(iam, 'list_users', MaxItems=5)
+        if ok:
+            users = resp['Users']
+    """
+    if client is None:
+        return False, None, "boto3 client is None"
+
+    max_attempts = 3
+    for attempt in range(max_attempts):
+        try:
+            fn = getattr(client, method)
+            response = fn(**kwargs)
+            return True, response, ""
+        except botocore.exceptions.ClientError as e:
+            code = e.response["Error"]["Code"]
+            msg  = e.response["Error"]["Message"]
+            # Don't retry auth errors
+            if code in ("InvalidClientTokenId", "AuthFailure",
+                        "UnauthorizedAccess", "AccessDenied",
+                        "ExpiredTokenException"):
+                return False, None, f"{code}: {msg}"
+            # Retry throttle errors
+            if code in ("Throttling", "RequestLimitExceeded",
+                        "TooManyRequestsException"):
+                if attempt < max_attempts - 1:
+                    time.sleep(2 ** attempt)
+                    continue
+            return False, None, f"{code}: {msg}"
+        except Exception as e:
+            if attempt < max_attempts - 1:
+                time.sleep(1)
+                continue
+            return False, None, str(e)
+
+    return False, None, "Max retry attempts exceeded"
+
+
+def verify_credentials(access_key: str, secret_key: str,
+                        session_token: str = "",
+                        region: str = DEFAULT_REGION) -> dict:
+    """
+    Verify AWS credentials via STS:GetCallerIdentity.
+    Returns structured result — never raises.
+
+    NOTE: GetCallerIdentity IS logged in CloudTrail and flagged by GuardDuty.
+    Severity: HIGH (known recon indicator).
+    """
+    if not HAS_BOTO3:
+        return {"valid": False, "error": "boto3 not installed",
+                "guardduty_risk": "N/A"}
+
+    result = {
+        "valid":         False,
+        "arn":           "",
+        "account":       "",
+        "user_id":       "",
+        "username":      "",
+        "error":         "",
+        "guardduty_risk": GUARDDUTY_NOISY_APIS.get("GetCallerIdentity", "HIGH"),
+        "guardduty_note": "GetCallerIdentity is always logged and a known recon indicator",
+    }
+
+    client = _build_client("sts", region, "", access_key, secret_key, session_token)
+    if not client:
+        result["error"] = "Could not create STS client"
+        return result
+
+    ok, resp, err = safe_call(client, "get_caller_identity")
+    if ok:
+        result["valid"]    = True
+        result["arn"]      = resp.get("Arn", "")
+        result["account"]  = resp.get("Account", "")
+        result["user_id"]  = resp.get("UserId", "")
+        # Extract username from ARN
+        arn = result["arn"]
+        if "/" in arn:
+            result["username"] = arn.split("/")[-1]
+    else:
+        result["error"] = err
+
+    return result
+
+
+def detect_region(access_key: str, secret_key: str,
+                   session_token: str = "") -> str:
+    """
+    Detect the primary region for these credentials.
+    Falls back to us-east-1 if detection fails.
+    """
+    if not HAS_BOTO3:
+        return DEFAULT_REGION
+
+    for region in FALLBACK_REGIONS:
+        client = _build_client("sts", region, "", access_key, secret_key, session_token)
+        ok, resp, _ = safe_call(client, "get_caller_identity")
+        if ok:
+            return region
+
+    return DEFAULT_REGION
+
+
+def _creds_from_session(session: "Session") -> tuple[str, str, str]:
+    """Extract best available AWS credentials from session secrets."""
+    access_key = secret_key = session_token = ""
+    for s in session.secrets:
+        t = s.get("secret_type", "")
+        v = s.get("value", "")
+        if t == "AWS_ACCESS_KEY" and not access_key:
+            access_key = v
+        elif t == "AWS_SECRET_KEY" and not secret_key:
+            secret_key = v
+        elif t == "AWS_SESSION_TOKEN" and not session_token:
+            session_token = v
+    return access_key, secret_key, session_token
+
+
+def guardduty_risk(api_name: str) -> tuple[str, str]:
+    """
+    Return (risk_level, explanation) for a given API call.
+    Used by modules to annotate findings with detection awareness.
+    """
+    if api_name in GUARDDUTY_NOISY_APIS:
+        return GUARDDUTY_NOISY_APIS[api_name], "GuardDuty: known high-signal event"
+    if api_name in GUARDDUTY_STEALTHY_APIS:
+        return "LOW", GUARDDUTY_STEALTHY_APIS[api_name]
+    return "LOW", "Not a known GuardDuty trigger"
+
+
+def is_available() -> bool:
+    return HAS_BOTO3
+
+
+def has_credentials(session: "Session") -> bool:
+    ak, sk, _ = _creds_from_session(session)
+    return bool(ak and sk)

core/config.py

@@ -0,0 +1,83 @@
+"""ExploitGraph - YAML configuration loader."""
+from __future__ import annotations
+import os
+from pathlib import Path
+from typing import Any
+
+BASE_DIR    = Path(__file__).parent.parent
+CONFIG_FILE = BASE_DIR / "config.yaml"
+
+DEFAULTS = {
+    "framework": {"version":"1.0.0","max_threads":10,"timeout":8,"retry":2,
+                  "user_agent":"ExploitGraph/1.0 (Security Research)",
+                  "output_dir":"reports","log_level":"INFO","verify_ssl":False},
+    "wordlists": {"http_paths":"data/wordlists/common_paths.txt",
+                  "s3_buckets":"data/wordlists/s3_buckets.txt",
+                  "backup_files":"data/wordlists/backup_files.txt",
+                  "subdomains":"data/wordlists/subdomains.txt"},
+    "aws":       {"profile":None,"region":"us-east-1","enabled":False},
+    "reporting": {"formats":["html","json"],"cvss_minimum":0.0,"open_browser":False},
+}
+
+
+class Config:
+    def __init__(self):
+        import copy; self._data = copy.deepcopy(DEFAULTS)
+        self._load()
+
+    def _load(self):
+        try:
+            import yaml
+            if CONFIG_FILE.exists():
+                with open(CONFIG_FILE) as f:
+                    self._merge(self._data, yaml.safe_load(f) or {})
+        except ImportError:
+            pass
+        for k, v in os.environ.items():
+            if k.startswith("EG_"):
+                parts = k[3:].lower().split("_", 1)
+                if len(parts) == 2 and parts[0] in self._data:
+                    if isinstance(self._data[parts[0]], dict):
+                        self._data[parts[0]][parts[1]] = v
+
+    def _merge(self, base, override):
+        for k, v in override.items():
+            if k in base and isinstance(base[k], dict) and isinstance(v, dict):
+                self._merge(base[k], v)
+            else:
+                base[k] = v
+
+    def __getitem__(self, k): return self._data[k]
+
+    def get(self, dotpath: str, default: Any = None) -> Any:
+        node = self._data
+        for p in dotpath.split("."):
+            if not isinstance(node, dict) or p not in node: return default
+            node = node[p]
+        return node
+
+    def set(self, dotpath: str, value: Any):
+        parts = dotpath.split(".")
+        node  = self._data
+        for p in parts[:-1]: node = node.setdefault(p, {})
+        node[parts[-1]] = value
+
+    def wordlist_path(self, name: str) -> Path:
+        rel = self.get(f"wordlists.{name}", "")
+        return BASE_DIR / rel if rel else BASE_DIR / "data" / "wordlists" / f"{name}.txt"
+
+    @property
+    def timeout(self) -> int:      return int(self.get("framework.timeout", 8))
+    @property
+    def max_threads(self) -> int:  return int(self.get("framework.max_threads", 10))
+    @property
+    def user_agent(self) -> str:   return self.get("framework.user_agent","ExploitGraph/1.0")
+    @property
+    def verify_ssl(self) -> bool:  return bool(self.get("framework.verify_ssl", False))
+    @property
+    def aws_enabled(self) -> bool:
+        try: import boto3; return bool(self.get("aws.enabled", False))
+        except ImportError: return False
+
+
+cfg = Config()