exploitgraph 1.0.0__py3-none-any.whl

core/console.py

@@ -0,0 +1,469 @@
+"""ExploitGraph - msfconsole-style interactive shell with tab completion."""
+from __future__ import annotations
+import os, sys, cmd, readline
+from colorama import Fore, Style, init
+init(autoreset=True)
+
+from core.logger import log
+from core.module_loader import loader
+from core.session_manager import session_manager, Session
+from core.risk_engine import risk_engine
+from core.attack_graph import attack_graph
+
+
+def print_banner():
+    print(Fore.RED + r"""
+███████╗██╗  ██╗██████╗ ██╗      ██████╗ ██╗████████╗ ██████╗ ██████╗  █████╗ ██████╗ ██╗  ██╗
+██╔════╝╚██╗██╔╝██╔══██╗██║     ██╔═══██╗██║╚══██╔══╝██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║  ██║
+█████╗   ╚███╔╝ ██████╔╝██║     ██║   ██║██║   ██║   ██║  ███╗██████╔╝███████║██████╔╝███████║
+██╔══╝   ██╔██╗ ██╔═══╝ ██║     ██║   ██║██║   ██║   ██║   ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║
+███████╗██╔╝ ██╗██║     ███████╗╚██████╔╝██║   ██║   ╚██████╔╝██║  ██║██║  ██║██║     ██║  ██║
+╚══════╝╚═╝  ╚═╝╚═╝     ╚══════╝ ╚═════╝ ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+""" + Style.RESET_ALL)
+    print(f"  {Fore.WHITE}ExploitGraph  {Fore.YELLOW}v1.0.0{Style.RESET_ALL}")
+    print(f"  {Fore.CYAN}Automated Attack Path Discovery & Exploitation Framework{Style.RESET_ALL}")
+    print(f"  {Fore.RED}Misconfig → Exposure → Secrets → API Abuse → Compromise{Style.RESET_ALL}")
+    print(f"  {Fore.WHITE}github.com/prajwal-infosec/ExploitGraph  |  Authorized use only{Style.RESET_ALL}\n")
+
+
+class _Completer:
+    CMDS = ["help","use","set","unset","options","run","back","exit","quit",
+            "show","info","sessions","workspace","search","export","clear"]
+
+    def __init__(self, console):
+        self.console = console
+
+    def complete(self, text, state):
+        try:
+            buf   = readline.get_line_buffer().lstrip()
+            parts = buf.split()
+            first = parts[0] if parts else ""
+
+            if not parts or (len(parts)==1 and not buf.endswith(" ")):
+                matches = [c for c in self.CMDS if c.startswith(text)]
+            elif first == "use":
+                prefix = parts[1] if len(parts)>1 else ""
+                matches = [m for m in loader.list_names() if m.startswith(prefix if buf.endswith(" ") else text)]
+            elif first == "show":
+                subs = ["modules","options","findings","secrets","sessions","attack-path","exploits","summary"]
+                matches = [s for s in subs if s.startswith(text)]
+            elif first == "sessions":
+                matches = [s for s in ["-i","-k","-l"] if s.startswith(text)]
+            elif first == "workspace":
+                matches = [s for s in ["list","new","switch","delete"] if s.startswith(text)]
+            elif first == "export":
+                matches = [s for s in ["html","json","all"] if s.startswith(text)]
+            elif first == "set":
+                m = self.console._active_module
+                opts = list(m.OPTIONS.keys()) if m else ["TARGET","MODE"]
+                matches = [o for o in opts if o.startswith(text.upper())]
+            else:
+                matches = []
+
+            return matches[state] if state < len(matches) else None
+        except Exception:
+            return None
+
+
+class ExploitGraphConsole(cmd.Cmd):
+    intro  = ""
+    prompt = f"{Fore.RED}exploitgraph{Fore.WHITE}>{Style.RESET_ALL} "
+
+    def __init__(self):
+        super().__init__()
+        self._active_module      = None
+        self._active_module_path = ""
+        self._mode               = "offensive"
+
+        n = loader.discover()
+        for err in loader.load_errors():
+            log.warning(f"Module load error: {err}")
+
+        _c = _Completer(self)
+        readline.set_completer(_c.complete)
+        readline.parse_and_bind("tab: complete")
+        readline.set_completer_delims(" \t")
+
+        if not session_manager.active:
+            session_manager.new("http://127.0.0.1:5000", "default")
+
+        log.info(f"Loaded {n} modules | Session: {session_manager.active.session_id}")
+        log.info("Type 'help' for commands.  Type 'run auto' to start full attack chain.\n")
+
+    @property
+    def session(self) -> Session:
+        return session_manager.active
+
+    def _update_prompt(self):
+        if self._active_module_path:
+            self.prompt = (f"{Fore.RED}exploitgraph{Fore.WHITE}"
+                           f"({Fore.YELLOW}{self._active_module_path}{Fore.WHITE})"
+                           f">{Style.RESET_ALL} ")
+        else:
+            self.prompt = f"{Fore.RED}exploitgraph{Fore.WHITE}>{Style.RESET_ALL} "
+
+    # ── Commands ──────────────────────────────────────────────────────────────
+
+    def do_use(self, args):
+        """Select a module.  use discovery/http_enum"""
+        path = args.strip()
+        if not path: log.error("Usage: use <module_path>"); return
+        cls = loader.get(path)
+        if not cls: log.error(f"Not found: {path}  (try: show modules)"); return
+        self._active_module      = cls()
+        self._active_module_path = path
+        if "TARGET" in self._active_module.OPTIONS:
+            self._active_module.set_option("TARGET", self.session.target)
+        if "MODE" in self._active_module.OPTIONS:
+            self._active_module.set_option("MODE", self._mode)
+        self._update_prompt()
+        log.success(f"Using: {path}")
+        log.info(self._active_module.DESCRIPTION)
+        if self._active_module.MITRE:
+            log.info(f"MITRE: {', '.join(self._active_module.MITRE)}")
+        log.info("Type 'options' to configure.  Type 'run' to execute.")
+
+    def do_set(self, args):
+        """Set option or session variable.  set TARGET http://x.com"""
+        parts = args.strip().split(None, 1)
+        if len(parts) < 2: log.error("Usage: set OPTION value"); return
+        key, val = parts[0].upper(), parts[1]
+        if key == "TARGET":
+            self.session.target = val
+            log.success(f"TARGET => {val}")
+            if self._active_module and "TARGET" in self._active_module.OPTIONS:
+                self._active_module.set_option("TARGET", val)
+            return
+        if key == "MODE":
+            if val.lower() not in ("offensive","defensive"):
+                log.error("MODE must be offensive or defensive"); return
+            self._mode = val.lower()
+            log.success(f"MODE => {val.lower()}")
+            if self._active_module and "MODE" in self._active_module.OPTIONS:
+                self._active_module.set_option("MODE", val)
+            return
+        if not self._active_module: log.error("No module selected.  use <module>"); return
+        ok, msg = self._active_module.set_option(key, val)
+        (log.success if ok else log.error)(msg)
+
+    def do_unset(self, args):
+        """Reset an option to its default.  unset OPTION"""
+        key = args.strip().upper()
+        if self._active_module and key in self._active_module.OPTIONS:
+            self._active_module.set_option(key, self._active_module.OPTIONS[key].get("default",""))
+            log.success(f"{key} reset to default")
+        else:
+            log.error(f"No option: {key}")
+
+    def do_options(self, args):
+        """Show current module options."""
+        if not self._active_module:
+            log.kv("TARGET", self.session.target)
+            log.kv("MODE",   self._mode); return
+        rows = self._active_module.show_options()
+        log.table(["Option","Value","Required","Description"], rows,
+                  title=f"Options: {self._active_module_path}")
+
+    def do_run(self, args):
+        """Execute module or full chain.  run  |  run auto"""
+        if args.strip().lower() == "auto":
+            self._run_auto_chain(); return
+        if not self._active_module:
+            log.error("No module selected.  use <module>  OR  run auto"); return
+        ok, err = self._active_module.validate(self.session)
+        if not ok: log.error(f"Validation: {err}"); return
+        log.info(f"Running: {self._active_module_path}")
+        try:
+            result = self._active_module.run(self.session)
+            if result.success:
+                log.success("Module completed")
+                for k,v in result.data.items():
+                    if not isinstance(v,(list,dict)): log.result(f"{k}: {v}")
+            else:
+                log.error(f"Module failed: {result.error}")
+        except Exception as e:
+            log.error(f"Module error: {e}"); import traceback; traceback.print_exc()
+
+    def _run_auto_chain(self):
+        """Run the full attack chain — static discovery first, then context-driven."""
+        log.banner("AUTO ATTACK CHAIN")
+        log.info(f"Target:  {self.session.target}")
+        log.info(f"Mode:    {self._mode}")
+        log.info(f"Session: {self.session.session_id}\n")
+
+        from core.context_engine import context_engine
+
+        # Phase A: Static discovery chain (always runs)
+        static_chain = [
+            "discovery/http_enum",
+            "cloud/s3_enum",
+            "secrets/git_secrets",
+        ]
+
+        total_modules = len(static_chain)
+        for i, path in enumerate(static_chain, 1):
+            self._run_module_in_chain(path, i, total_modules)
+
+        # Phase B: Context-driven dynamic chain
+        log.newline()
+        log.info("Building dynamic chain based on discoveries...")
+        dynamic_chain = context_engine.build_dynamic_chain(self.session)
+        log.info(f"Context engine selected {len(dynamic_chain)} additional modules:")
+        for m in dynamic_chain:
+            log.step(m)
+        log.newline()
+
+        for i, path in enumerate(dynamic_chain, len(static_chain) + 1):
+            self._run_module_in_chain(path, i, len(static_chain) + len(dynamic_chain))
+
+        # Final summary
+        print()
+        log.banner("ATTACK CHAIN COMPLETE")
+        s = self.session.summary()
+        score, label = risk_engine.session_score(self.session)
+        log.kv("Session ID",    s["session_id"])
+        log.kv("Target",        s["target"])
+        log.kv("Risk Score",    f"{score}/10 [{label}]")
+        log.kv("Endpoints",     str(s["endpoints"]))
+        log.kv("Exposed Files", str(s["exposed_files"]))
+        log.kv("Secrets Found", str(s["secrets"]))
+        log.kv("Findings",      str(s["findings"]))
+        log.kv("CRITICAL",      str(s["severity"]["CRITICAL"]))
+        log.kv("HIGH",          str(s["severity"]["HIGH"]))
+        print()
+        log.info("View report: export html")
+
+    def _run_module_in_chain(self, path: str, step: int, total: int):
+        """Execute a single module within the auto chain."""
+        cls = loader.get(path)
+        if not cls:
+            log.warning(f"Skipping (not found): {path}")
+            return
+        log.phase(step, total, path)
+        mod = cls()
+        for opt, key in [("TARGET", self.session.target), ("MODE", self._mode)]:
+            if opt in mod.OPTIONS:
+                mod.set_option(opt, key)
+        ok, err = mod.validate(self.session)
+        if not ok:
+            log.error(f"Skip {path}: {err}")
+            return
+        try:
+            result = mod.run(self.session)
+            if result.success:
+                for k, v in result.data.items():
+                    if not isinstance(v, (list, dict)):
+                        log.result(f"{k}: {v}")
+        except Exception as e:
+            log.error(f"{path} error: {e}")
+
+    def do_show(self, args):
+        """show modules | findings | secrets | sessions | attack-path | exploits | summary | options"""
+        arg = args.strip().lower()
+        if arg in ("","help"):
+            for cmd, desc in [("show modules","List all modules"),("show options","Current options"),
+                              ("show findings","Security findings"),("show secrets","Extracted credentials"),
+                              ("show sessions","All sessions"),("show attack-path","ASCII kill chain"),
+                              ("show exploits","Exploitation results"),("show summary","Stats + risk score")]:
+                log.kv(f"  {cmd}", desc)
+            return
+
+        if arg == "modules":
+            for cat, mods in loader.all_modules().items():
+                if mods:
+                    print(f"\n  {Fore.YELLOW}{cat.upper()}{Style.RESET_ALL}")
+                    print(f"  {'─'*58}")
+                    for m in mods:
+                        sc = {"CRITICAL":Fore.RED,"HIGH":Fore.YELLOW,"MEDIUM":Fore.CYAN}.get(m["severity"],Fore.WHITE)
+                        print(f"  {Fore.CYAN}{m['path']:<38}{Style.RESET_ALL}"
+                              f"{sc}{m['severity']:<10}{Style.RESET_ALL}{m['description'][:40]}")
+            print(f"\n  Total: {loader.count()} modules | Tab-complete: use <Tab>")
+
+        elif arg == "options": self.do_options("")
+
+        elif arg == "findings":
+            if not self.session.findings: log.warning("No findings yet."); return
+            log.section(f"Findings ({len(self.session.findings)})")
+            for i,f in enumerate(self.session.findings,1):
+                print(f"  {log.severity_badge(f.get('severity','INFO'))} {i:>3}. {f['title']}")
+                if f.get("cvss_score"): log.step(f"CVSS: {f['cvss_score']} | {f.get('mitre_technique','')}")
+
+        elif arg == "secrets":
+            if not self.session.secrets: log.warning("No secrets yet."); return
+            log.section(f"Secrets ({len(self.session.secrets)})")
+            for s in self.session.secrets:
+                log.secret(s["secret_type"], s["value"][:60])
+                log.step(f"Source: {s['source']}")
+
+        elif arg == "sessions": self.do_sessions("")
+
+        elif arg == "attack-path":
+            if not self.session.graph_nodes: log.warning("No graph yet.  Run modules first."); return
+            attack_graph.build(self.session)
+            print(); print(attack_graph.print_ascii())
+            stats = attack_graph.stats()
+            print()
+            log.info(f"Nodes: {stats['nodes']} | Edges: {stats['edges']} | MITRE: {', '.join(stats['mitre_techniques'])}")
+
+        elif arg == "exploits":
+            if not self.session.exploit_results: log.warning("No exploits yet."); return
+            log.section(f"Exploit Results ({len(self.session.exploit_results)})")
+            for r in self.session.exploit_results:
+                st = f"{Fore.GREEN}[OK]{Style.RESET_ALL}" if r["success"] else f"{Fore.RED}[FAIL]{Style.RESET_ALL}"
+                print(f"  {st} {r['action']}")
+                log.step(r["detail"])
+
+        elif arg == "summary":
+            s = self.session.summary()
+            score, label = risk_engine.session_score(self.session)
+            log.banner("SESSION SUMMARY")
+            for k,v in s.items():
+                if isinstance(v,dict):
+                    for k2,v2 in v.items(): log.kv(f"  {k2}", str(v2))
+                else: log.kv(k, str(v))
+            log.kv("Risk Score", f"{score}/10 [{label}]")
+        else:
+            log.error(f"Unknown: show {arg}")
+
+    def do_sessions(self, args):
+        """sessions | sessions -i ID | sessions -k ID"""
+        arg = args.strip()
+        rows = session_manager.list_all()
+        if not arg or arg == "-l":
+            if not rows: log.warning("No sessions."); return
+            active_id = self.session.session_id if self.session else ""
+            for r in rows:
+                m = f"{Fore.GREEN}*{Style.RESET_ALL}" if r["session_id"]==active_id else " "
+                print(f"  {m} {Fore.CYAN}{r['session_id']}{Style.RESET_ALL} | "
+                      f"{r['name']:<15} | {r['target']:<35} | risk={r['risk_score']:.1f} | {r['status']}")
+            return
+        parts = arg.split()
+        if len(parts) >= 2:
+            flag, sid = parts[0], parts[1]
+            if flag == "-i":
+                s = session_manager.switch(sid)
+                log.success(f"Switched to: {sid}") if s else log.error(f"Not found: {sid}")
+                self._update_prompt()
+            elif flag == "-k":
+                log.success(f"Killed: {sid}") if session_manager.kill(sid) else log.error(f"Not found: {sid}")
+
+    def do_workspace(self, args):
+        """workspace list | workspace new <name> <url> | workspace switch <id>"""
+        parts = args.strip().split(None, 2)
+        if not parts: log.error("Usage: workspace [list|new|switch]"); return
+        sub = parts[0].lower()
+        if sub == "list": self.do_sessions("")
+        elif sub == "new":
+            if len(parts) < 3: log.error("Usage: workspace new <name> <url>"); return
+            t = parts[2] if parts[2].startswith(("http://","https://")) else "http://"+parts[2]
+            s = session_manager.new(t, parts[1], self._mode)
+            log.success(f"Workspace '{parts[1]}' created → {t} [{s.session_id}]")
+            self._update_prompt()
+        elif sub == "switch":
+            if len(parts) < 2: log.error("Usage: workspace switch <id>"); return
+            self.do_sessions(f"-i {parts[1]}")
+        else: log.error(f"Unknown: workspace {sub}")
+
+    def do_export(self, args):
+        """Export report.  export html | export json | export all"""
+        fmt = args.strip().lower() or "all"
+        fmts = ["html","json"] if fmt=="all" else [fmt]
+        for f in fmts:
+            mod = loader.instantiate(f"html_report" if f=="html" else "json_export")
+            if mod: mod.run(self.session)
+            else: log.error(f"Reporting module not found: {f}")
+
+    def do_info(self, args):
+        """Module details.  info discovery/http_enum"""
+        path = args.strip() or self._active_module_path
+        if not path: log.error("Usage: info <module>"); return
+        cls = loader.get(path)
+        if not cls: log.error(f"Not found: {path}"); return
+        log.banner(f"MODULE: {path.upper()}")
+        for k,v in [("Name",cls.NAME),("Description",cls.DESCRIPTION),("Author",cls.AUTHOR),
+                    ("Version",cls.VERSION),("Category",cls.CATEGORY),("Severity",cls.SEVERITY),
+                    ("MITRE",", ".join(cls.MITRE) or "N/A"),("AWS Parallel",cls.AWS_PARALLEL or "N/A")]:
+            log.kv(k, v)
+        if cls.OPTIONS:
+            log.table(["Option","Default","Required","Description"], cls().show_options())
+
+    def do_search(self, args):
+        """Search modules by keyword.  search jwt | search s3 | search cloud"""
+        kw = args.strip().lower()
+        if not kw: log.error("Usage: search <keyword>"); return
+        results = [m for mods in loader.all_modules().values() for m in mods
+                   if kw in m["name"] or kw in m["description"].lower()
+                   or kw in m.get("mitre","").lower()]
+        if not results: log.warning(f"No results for: {kw}"); return
+        print(f"\n  {Fore.YELLOW}Results for '{kw}':{Style.RESET_ALL}")
+        for m in results:
+            print(f"  {Fore.CYAN}{m['path']:<38}{Style.RESET_ALL}{m['description'][:48]}")
+
+    def do_back(self, args):
+        """Deselect current module."""
+        self._active_module = None; self._active_module_path = ""
+        self._update_prompt(); log.info("Returned to main console.")
+
+    def do_clear(self, args):
+        """Clear screen."""
+        os.system("clear"); print_banner()
+
+    def do_exit(self, args):
+        """Exit ExploitGraph."""
+        log.info("Exiting. Run 'export html' first if you haven't saved your report.")
+        if self.session: self.session.close()
+        return True
+
+    def do_quit(self, args): return self.do_exit(args)
+    def do_EOF(self, args):  print(); return self.do_exit(args)
+    def emptyline(self): pass
+    def default(self, line):
+        log.error(f"Unknown: {line.split()[0] if line.split() else line}  (type 'help')")
+
+    def do_help(self, args):
+        """Show all commands."""
+        if args: super().do_help(args); return
+        log.banner("EXPLOITGRAPH COMMANDS")
+        sections = [
+            ("SESSION", [
+                ("  workspace new <n> <url>",     "Create named workspace"),
+                ("  set TARGET <url>",             "Set scan target"),
+                ("  set MODE offensive|defensive", "Set scan mode"),
+            ]),
+            ("ATTACK", [
+                ("  run auto",                     "Full automatic attack chain"),
+                ("  use <module>",                 "Select a module (Tab to complete)"),
+                ("  run",                          "Execute selected module"),
+                ("  options",                      "Show module options"),
+                ("  set OPTION value",             "Configure option"),
+                ("  back",                         "Deselect module"),
+            ]),
+            ("INFORMATION", [
+                ("  show modules",                 "All modules by category"),
+                ("  show findings",                "Security findings"),
+                ("  show secrets",                 "Extracted credentials"),
+                ("  show attack-path",             "ASCII kill chain"),
+                ("  show summary",                 "Risk score + stats"),
+                ("  info <module>",                "Module details"),
+                ("  search <keyword>",             "Search modules"),
+            ]),
+            ("SESSIONS", [
+                ("  sessions",                     "List all sessions"),
+                ("  sessions -i <id>",             "Switch to session"),
+                ("  sessions -k <id>",             "Kill session"),
+            ]),
+            ("OUTPUT", [
+                ("  export html",                  "HTML report (D3.js graph)"),
+                ("  export json",                  "JSON for SIEM/ticketing"),
+                ("  export all",                   "All formats"),
+            ]),
+            ("MISC", [
+                ("  clear",                        "Clear screen"),
+                ("  exit / quit",                  "Exit framework"),
+            ]),
+        ]
+        for section, cmds in sections:
+            print(f"\n  {Fore.YELLOW}{section}{Style.RESET_ALL}")
+            for name, desc in cmds: log.kv(name, desc)
+        print()
+        log.info("Quick start: workspace new test http://target.com → run auto")

core/context_engine.py

@@ -0,0 +1,172 @@
+"""
+ExploitGraph - Context Engine
+Analyses what modules have found and decides dynamically which modules
+to run next. Replaces the static 6-step chain with intelligent sequencing.
+
+Logic:
+  Discovery → Cloud Enum → [if .gz found] CloudTrail Analysis
+                         → [if secrets found] Credential Validation
+                         → [if valid creds] IAM Enum + Priv-Esc
+                         → Reporting
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from core.session_manager import Session
+
+
+class ContextEngine:
+    """
+    Examines session state after each module and returns the next
+    module path(s) to execute.
+    """
+
+    # Static discovery chain — always runs in this order
+    DISCOVERY_CHAIN = [
+        "discovery/http_enum",
+        "cloud/s3_enum",
+        "secrets/git_secrets",
+    ]
+
+    # Always runs at the end
+    REPORTING_CHAIN = [
+        "reporting/html_report",
+        "reporting/json_export",
+    ]
+
+    def build_dynamic_chain(self, session: "Session") -> list[str]:
+        """
+        Build the full module execution chain based on what was discovered.
+        Call this AFTER the discovery chain has run.
+        """
+        chain = []
+
+        # ── Conditional: CloudTrail logs found ─────────────────────────────
+        if self._has_cloudtrail_logs(session):
+            chain.append("cloud/cloudtrail_analyzer")
+
+        # ── Conditional: Subdomains not yet checked ────────────────────────
+        if not self._already_ran("subdomain_enum", session):
+            chain.append("discovery/subdomain_enum")
+
+        # ── Conditional: Azure/GCP indicators in responses ─────────────────
+        body = self._all_response_text(session)
+        if "blob.core.windows.net" in body or "azurewebsites" in body:
+            chain.append("cloud/azure_enum")
+        if "storage.googleapis.com" in body or "appspot.com" in body:
+            chain.append("cloud/gcp_enum")
+
+        # ── Conditional: IMDS / metadata hints ─────────────────────────────
+        if "169.254.169.254" in body or "metadata" in body.lower():
+            chain.append("cloud/metadata_check")
+
+        # ── Always: scan for secrets in all discovered content ──────────────
+        chain.append("secrets/file_secrets")
+
+        # ── Conditional: AWS credentials found → validate them ──────────────
+        if self._has_aws_credentials(session):
+            chain.append("cloud/aws_credential_validator")
+            chain.append("cloud/iam_enum")
+            chain.append("cloud/iam_privilege_escalation")
+
+        # ── Conditional: Login/auth endpoints found → try exploitation ──────
+        if self._has_auth_endpoints(session):
+            chain.append("exploitation/api_exploit")
+            chain.append("exploitation/jwt_attack")
+
+        # ── Conditional: SSRF-prone parameters found ────────────────────────
+        if self._has_ssrf_params(session):
+            chain.append("exploitation/ssrf_scanner")
+
+        # ── Always: reporting at the end ────────────────────────────────────
+        chain.extend(self.REPORTING_CHAIN)
+
+        # Deduplicate while preserving order
+        seen = set()
+        return [x for x in chain if not (x in seen or seen.add(x))]
+
+    def next_modules(self, completed: str, session: "Session") -> list[str]:
+        """
+        After a specific module completes, return immediate follow-up modules.
+        Used for real-time chaining during execution.
+        """
+        follow_ups = []
+
+        if completed == "cloud/s3_enum":
+            if self._has_cloudtrail_logs(session):
+                follow_ups.append("cloud/cloudtrail_analyzer")
+            if session.exposed_files:
+                follow_ups.append("secrets/file_secrets")
+
+        elif completed in ("secrets/file_secrets", "cloud/cloudtrail_analyzer"):
+            if self._has_aws_credentials(session):
+                follow_ups.append("cloud/aws_credential_validator")
+
+        elif completed == "cloud/aws_credential_validator":
+            if self._has_valid_credentials(session):
+                follow_ups.extend(["cloud/iam_enum", "cloud/iam_privilege_escalation"])
+
+        return follow_ups
+
+    # ── Detection helpers ──────────────────────────────────────────────────
+
+    def _has_cloudtrail_logs(self, session: "Session") -> bool:
+        """Check if any downloaded files are CloudTrail .json.gz logs."""
+        for f in session.exposed_files:
+            path = f.get("path", "") or f.get("url", "")
+            if "CloudTrail" in path or (
+                path.endswith(".json.gz") and "AWSLogs" in path
+            ):
+                return True
+        return False
+
+    def _has_aws_credentials(self, session: "Session") -> bool:
+        """Check if any AWS access key + secret pair exists in secrets."""
+        types = {s["secret_type"] for s in session.secrets}
+        return "AWS_ACCESS_KEY" in types
+
+    def _has_valid_credentials(self, session: "Session") -> bool:
+        """Check if credential validator confirmed valid credentials."""
+        for r in session.exploit_results:
+            if "credential_validator" in r.get("module", "") and r.get("success"):
+                return True
+        return False
+
+    def _has_auth_endpoints(self, session: "Session") -> bool:
+        """Check if login/auth endpoints were discovered."""
+        for ep in session.endpoints:
+            p = ep.get("path", "").lower()
+            if any(kw in p for kw in ["login", "auth", "token", "signin"]):
+                return True
+        return False
+
+    def _has_ssrf_params(self, session: "Session") -> bool:
+        """Check if any discovered endpoints have SSRF-prone parameters."""
+        for ep in session.endpoints:
+            url = ep.get("url", "")
+            if any(p in url for p in ["url=", "redirect=", "proxy=", "fetch=", "dest="]):
+                return True
+        return False
+
+    def _already_ran(self, module_name: str, session: "Session") -> bool:
+        """Check if a module already produced results in this session."""
+        for r in session.exploit_results:
+            if module_name in r.get("module", ""):
+                return True
+        return False
+
+    def _all_response_text(self, session: "Session") -> str:
+        """Concatenate all downloaded file content for pattern matching."""
+        parts = []
+        for f in session.exposed_files:
+            content = f.get("content", "") or ""
+            if isinstance(content, str):
+                parts.append(content[:500])
+        for ep in session.endpoints:
+            parts.append(ep.get("url", ""))
+        return " ".join(parts)
+
+
+# Global singleton
+context_engine = ContextEngine()