exploitgraph 1.0.0__py3-none-any.whl

core/session_manager.py

@@ -0,0 +1,254 @@
+"""ExploitGraph - SQLite-backed multi-session manager."""
+from __future__ import annotations
+import json, sqlite3, hashlib
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _now() -> str:
+    """Current UTC time as ISO string — Python 3.9+ compatible."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+SESSION_DIR = Path(__file__).parent.parent / "sessions"
+SESSION_DIR.mkdir(exist_ok=True)
+DB_PATH = SESSION_DIR / "exploitgraph.db"
+
+
+def _conn() -> sqlite3.Connection:
+    c = sqlite3.connect(DB_PATH)
+    c.row_factory = sqlite3.Row
+    c.execute("PRAGMA journal_mode=WAL")
+    return c
+
+
+def _init():
+    c = _conn()
+    c.executescript("""
+    CREATE TABLE IF NOT EXISTS sessions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT UNIQUE NOT NULL, name TEXT, target TEXT NOT NULL,
+        mode TEXT DEFAULT 'offensive', status TEXT DEFAULT 'active',
+        risk_score REAL DEFAULT 0.0, created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS findings (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL, module TEXT NOT NULL, title TEXT NOT NULL,
+        severity TEXT NOT NULL, cvss_score REAL DEFAULT 0.0,
+        description TEXT, evidence TEXT, recommendation TEXT,
+        aws_parallel TEXT, mitre_technique TEXT, created_at TEXT NOT NULL,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+    );
+    CREATE TABLE IF NOT EXISTS secrets (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL, secret_type TEXT NOT NULL, value TEXT NOT NULL,
+        source TEXT, severity TEXT DEFAULT 'HIGH', description TEXT,
+        aws_parallel TEXT, created_at TEXT NOT NULL,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+    );
+    CREATE TABLE IF NOT EXISTS graph_nodes (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL, node_id TEXT NOT NULL, label TEXT,
+        node_type TEXT, severity TEXT DEFAULT 'INFO', details TEXT,
+        UNIQUE(session_id, node_id),
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+    );
+    CREATE TABLE IF NOT EXISTS graph_edges (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT NOT NULL, source TEXT NOT NULL, target TEXT NOT NULL,
+        label TEXT, technique TEXT,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+    );
+    """)
+    c.commit(); c.close()
+
+_init()
+
+
+class Session:
+    def __init__(self, target: str, name: str = "", mode: str = "offensive"):
+        self.target     = target.rstrip("/")
+        self.name       = name or f"session_{datetime.now(timezone.utc).strftime('%H%M%S')}"
+        self.mode       = mode
+        self.session_id = "EG-" + hashlib.md5(
+            f"{target}{_now()}".encode()
+        ).hexdigest()[:8].upper()
+        self.created_at = _now()
+        self.risk_score = 0.0
+
+        self.endpoints:       list[dict] = []
+        self.exposed_files:   list[dict] = []
+        self.secrets:         list[dict] = []
+        self.findings:        list[dict] = []
+        self.valid_creds:     list[dict] = []
+        self.graph_nodes:     list[dict] = []
+        self.graph_edges:     list[dict] = []
+        self.exploit_results: list[dict] = []
+        self.notes:           list[str]  = []
+        self._scratch:        dict       = {}
+
+        self._save()
+
+    def _save(self):
+        c = _conn()
+        c.execute(
+            "INSERT OR REPLACE INTO sessions "
+            "(session_id,name,target,mode,status,risk_score,created_at,updated_at) "
+            "VALUES (?,?,?,?,?,?,?,?)",
+            (self.session_id, self.name, self.target, self.mode,
+             "active", self.risk_score, self.created_at, _now())
+        )
+        c.commit(); c.close()
+
+    def add_finding(self, *, title, severity, description, evidence, recommendation,
+                    module="unknown", cvss_score=0.0, aws_parallel="", mitre_technique=""):
+        row = dict(session_id=self.session_id, module=module, title=title,
+                   severity=severity, cvss_score=cvss_score, description=description,
+                   evidence=evidence, recommendation=recommendation,
+                   aws_parallel=aws_parallel, mitre_technique=mitre_technique,
+                   created_at=_now())
+        self.findings.append(row)
+        c = _conn()
+        c.execute(
+            "INSERT INTO findings "
+            "(session_id,module,title,severity,cvss_score,description,evidence,"
+            "recommendation,aws_parallel,mitre_technique,created_at) "
+            "VALUES (:session_id,:module,:title,:severity,:cvss_score,:description,"
+            ":evidence,:recommendation,:aws_parallel,:mitre_technique,:created_at)", row)
+        c.commit(); c.close()
+
+    def add_secret(self, *, secret_type, value, source, severity="HIGH",
+                   description="", aws_parallel=""):
+        if any(s["value"] == value for s in self.secrets):
+            return
+        row = dict(session_id=self.session_id, secret_type=secret_type, value=value,
+                   source=source, severity=severity, description=description,
+                   aws_parallel=aws_parallel, created_at=_now())
+        self.secrets.append(row)
+        c = _conn()
+        c.execute(
+            "INSERT INTO secrets "
+            "(session_id,secret_type,value,source,severity,description,aws_parallel,created_at) "
+            "VALUES (:session_id,:secret_type,:value,:source,:severity,"
+            ":description,:aws_parallel,:created_at)", row)
+        c.commit(); c.close()
+
+    def add_graph_node(self, node_id, label, node_type, severity="INFO", details=""):
+        if any(n["node_id"] == node_id for n in self.graph_nodes):
+            return
+        row = dict(session_id=self.session_id, node_id=node_id, label=label,
+                   node_type=node_type, severity=severity, details=details)
+        self.graph_nodes.append(row)
+        c = _conn()
+        c.execute(
+            "INSERT OR IGNORE INTO graph_nodes "
+            "(session_id,node_id,label,node_type,severity,details) "
+            "VALUES (:session_id,:node_id,:label,:node_type,:severity,:details)", row)
+        c.commit(); c.close()
+
+    def add_graph_edge(self, source, target, label="", technique=""):
+        row = dict(session_id=self.session_id, source=source, target=target,
+                   label=label, technique=technique)
+        self.graph_edges.append(row)
+        c = _conn()
+        c.execute(
+            "INSERT INTO graph_edges (session_id,source,target,label,technique) "
+            "VALUES (:session_id,:source,:target,:label,:technique)", row)
+        c.commit(); c.close()
+
+    def add_exploit_result(self, module, action, success, detail, data=None):
+        self.exploit_results.append(dict(
+            module=module, action=action, success=success,
+            detail=detail, data=data, timestamp=_now()))
+
+    def set_scratch(self, key: str, value: Any):   self._scratch[key] = value
+    def get_scratch(self, key: str, default=None): return self._scratch.get(key, default)
+
+    def update_risk(self, score: float):
+        self.risk_score = score
+        c = _conn()
+        c.execute("UPDATE sessions SET risk_score=?,updated_at=? WHERE session_id=?",
+                  (score, _now(), self.session_id))
+        c.commit(); c.close()
+
+    def close(self):
+        c = _conn()
+        c.execute("UPDATE sessions SET status='closed',updated_at=? WHERE session_id=?",
+                  (_now(), self.session_id))
+        c.commit(); c.close()
+
+    def summary(self) -> dict:
+        sev = {k: 0 for k in ("CRITICAL","HIGH","MEDIUM","LOW","INFO")}
+        for f in self.findings:
+            key = f.get("severity","INFO")
+            sev[key] = sev.get(key, 0) + 1
+        return dict(session_id=self.session_id, name=self.name, target=self.target,
+                    mode=self.mode, risk_score=self.risk_score,
+                    endpoints=len(self.endpoints), exposed_files=len(self.exposed_files),
+                    secrets=len(self.secrets), findings=len(self.findings),
+                    valid_creds=len(self.valid_creds), severity=sev)
+
+
+class SessionManager:
+    def __init__(self):
+        self._active: Optional[Session] = None
+
+    @property
+    def active(self) -> Optional[Session]: return self._active
+
+    def new(self, target: str, name: str = "", mode: str = "offensive") -> Session:
+        self._active = Session(target, name, mode)
+        return self._active
+
+    def switch(self, sid: str) -> Optional[Session]:
+        c = _conn()
+        row = c.execute("SELECT * FROM sessions WHERE session_id=?", (sid,)).fetchone()
+        c.close()
+        if not row: return None
+        s = Session.__new__(Session)
+        for k in ("session_id","name","target","mode","risk_score","created_at"):
+            setattr(s, k, row[k])
+        s._scratch = {}
+        c = _conn()
+        s.findings    = [dict(r) for r in c.execute("SELECT * FROM findings WHERE session_id=?",    (sid,)).fetchall()]
+        s.secrets     = [dict(r) for r in c.execute("SELECT * FROM secrets WHERE session_id=?",     (sid,)).fetchall()]
+        s.graph_nodes = [dict(r) for r in c.execute("SELECT * FROM graph_nodes WHERE session_id=?", (sid,)).fetchall()]
+        s.graph_edges = [dict(r) for r in c.execute("SELECT * FROM graph_edges WHERE session_id=?", (sid,)).fetchall()]
+        s.endpoints = []; s.exposed_files = []; s.valid_creds = []
+        s.exploit_results = []; s.notes = []
+        c.close()
+        self._active = s
+        return s
+
+    def list_all(self) -> list[dict]:
+        c = _conn()
+        rows = c.execute(
+            "SELECT session_id,name,target,mode,status,risk_score,created_at "
+            "FROM sessions ORDER BY created_at DESC").fetchall()
+        c.close()
+        return [dict(r) for r in rows]
+
+    def kill(self, sid: str) -> bool:
+        c = _conn()
+        n = c.execute("UPDATE sessions SET status='killed' WHERE session_id=?", (sid,)).rowcount
+        c.commit(); c.close()
+        if self._active and self._active.session_id == sid:
+            self._active = None
+        return n > 0
+
+    def get_findings(self, sid: str) -> list[dict]:
+        c = _conn()
+        rows = c.execute(
+            "SELECT * FROM findings WHERE session_id=? ORDER BY cvss_score DESC", (sid,)).fetchall()
+        c.close()
+        return [dict(r) for r in rows]
+
+    def get_secrets(self, sid: str) -> list[dict]:
+        c = _conn()
+        rows = c.execute("SELECT * FROM secrets WHERE session_id=?", (sid,)).fetchall()
+        c.close()
+        return [dict(r) for r in rows]
+
+
+session_manager = SessionManager()

exploitgraph-1.0.0.dist-info/METADATA

@@ -0,0 +1,429 @@
+Metadata-Version: 2.4
+Name: exploitgraph
+Version: 1.0.0
+Summary: Automated attack path discovery and exploitation framework for cloud-native applications
+Author-email: Prajwal Pawar <prajwal@exploitgraph.io>
+License: MIT
+Project-URL: Homepage, https://github.com/prajwalpawar/ExploitGraph
+Project-URL: Repository, https://github.com/prajwalpawar/ExploitGraph
+Project-URL: Bug Tracker, https://github.com/prajwalpawar/ExploitGraph/issues
+Project-URL: Documentation, https://github.com/prajwalpawar/ExploitGraph/wiki
+Keywords: security,pentesting,cloud,aws,attack-path,exploitation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: networkx>=3.2.0
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: aws
+Requires-Dist: boto3>=1.34.0; extra == "aws"
+Requires-Dist: botocore>=1.34.0; extra == "aws"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: exploitgraph[aws,dev]; extra == "all"
+Dynamic: license-file
+
+# ExploitGraph
+
+<div align="center">
+
+```
+███████╗██╗  ██╗██████╗ ██╗      ██████╗ ██╗████████╗ ██████╗ ██████╗  █████╗ ██████╗ ██╗  ██╗
+██╔════╝╚██╗██╔╝██╔══██╗██║     ██╔═══██╗██║╚══██╔══╝██╔════╝ ██╔══██╗██╔══██╗██╔══██╗██║  ██║
+█████╗   ╚███╔╝ ██████╔╝██║     ██║   ██║██║   ██║   ██║  ███╗██████╔╝███████║██████╔╝███████║
+██╔══╝   ██╔██╗ ██╔═══╝ ██║     ██║   ██║██║   ██║   ██║   ██║██╔══██╗██╔══██║██╔═══╝ ██╔══██║
+███████╗██╔╝ ██╗██║     ███████╗╚██████╔╝██║   ██║   ╚██████╔╝██║  ██║██║  ██║██║     ██║  ██║
+╚══════╝╚═╝  ╚═╝╚═╝     ╚══════╝ ╚═════╝ ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝
+```
+
+**Automated Attack Path Discovery & Exploitation Framework**
+
+[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?logo=python)](https://python.org)
+[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS-lightgrey)](https://github.com/prajwalpawar/ExploitGraph)
+[![Modules](https://img.shields.io/badge/Modules-8%2B-red)](modules/)
+[![AWS](https://img.shields.io/badge/AWS-Cloud%20Security-orange?logo=amazon-aws)](modules/cloud/)
+
+</div>
+
+---
+
+## What is ExploitGraph?
+
+ExploitGraph is a **modular, open-source attack path discovery framework** that automatically chains cloud misconfigurations, exposed secrets, and application vulnerabilities into a complete kill chain — starting from **zero prior knowledge**.
+
+Unlike tools that require credentials first (Pacu) or only audit configurations (Prowler/ScoutSuite), ExploitGraph **starts from nothing** and discovers everything it needs:
+
+```
+Cloud Misconfiguration → Data Exposure → Secret Leakage → API Abuse → Full Compromise
+```
+
+Every step is visualized as an interactive attack graph with MITRE ATT&CK mappings and AWS remediation commands.
+
+### How it differs from existing tools
+
+| Tool | Starting Point | Output | Attack Chain |
+|------|---------------|--------|--------------|
+| **Pacu** | Needs IAM credentials | Module results | No chaining |
+| **Prowler** | Needs AWS credentials | Audit findings | No chaining |
+| **ScoutSuite** | Needs AWS credentials | Config report | No chaining |
+| **TruffleHog** | Git repo / S3 bucket | Secret list | No chaining |
+| **ExploitGraph** | **Just a URL** | **Full kill chain + visual graph** | **Automated** |
+
+---
+
+## Features
+
+- **msfconsole-style interactive shell** with tab completion
+- **8+ modular attack modules** across discovery, cloud, secrets, exploitation, reporting
+- **Generic — works against any target** (not limited to fintech or specific apps)
+- **Wordlist-driven discovery** — no hardcoded paths
+- **20+ secret patterns** including AWS keys, JWT secrets, Stripe keys, GitHub tokens
+- **Optional boto3 AWS integration** — real S3 ACL checks, IAM enumeration, MFA detection
+- **JWT attack engine** — none-algorithm bypass, weak secret bruteforce
+- **Interactive D3.js attack graph** in HTML report
+- **CVSS scoring** per finding + session risk score (0-10)
+- **MITRE ATT&CK for Cloud** mapping
+- **Multi-session SQLite persistence** — resume scans across sessions
+- **Offensive and defensive modes**
+- **pip-installable** Python package
+
+---
+
+## Installation
+
+### Quick Start
+```bash
+git clone https://github.com/prajwalpawar/ExploitGraph.git
+cd ExploitGraph
+pip install -r requirements.txt
+python3 exploitgraph.py
+```
+
+### With AWS Support
+```bash
+pip install -r requirements.txt
+pip install boto3 botocore
+```
+
+### Requirements
+- Python 3.9+
+- Linux / macOS (Kali Linux recommended)
+- No AWS credentials required for HTTP-mode scanning
+
+---
+
+## Usage
+
+### Interactive Console
+```bash
+python3 exploitgraph.py
+```
+
+```
+exploitgraph> workspace new pentest http://target.com
+exploitgraph> run auto
+```
+
+### CLI Mode
+```bash
+# Full automated attack chain
+python3 exploitgraph.py -t http://target.com --auto
+
+# Single module
+python3 exploitgraph.py -t http://target.com -m cloud/s3_enum
+
+# Defensive audit mode (no exploitation)
+python3 exploitgraph.py -t http://target.com --mode defensive --auto
+
+# List all modules
+python3 exploitgraph.py --list-modules
+```
+
+### Console Commands
+```
+SESSION
+  workspace new <name> <url>    Create workspace
+  set TARGET http://target.com  Set target
+  set MODE offensive|defensive  Set mode
+
+MODULES
+  show modules                  List all modules by category
+  use discovery/http_enum       Select a module
+  options                       Show module options
+  set OPTION value              Configure option
+  run                           Execute module
+  run auto                      Full attack chain
+  back                          Deselect module
+
+INFORMATION
+  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
+
+OUTPUT
+  export html                   HTML report with D3.js graph
+  export json                   JSON for SIEM integration
+  export all                    All formats
+
+SESSION MANAGEMENT
+  sessions                      List sessions
+  sessions -i <id>              Switch session
+  sessions -k <id>              Kill session
+```
+
+---
+
+## Modules
+
+### Discovery
+| Module | Description | MITRE |
+|--------|-------------|-------|
+| `discovery/http_enum` | Wordlist-driven endpoint enumeration + tech fingerprinting | T1595.003 |
+
+### Cloud
+| Module | Description | MITRE |
+|--------|-------------|-------|
+| `cloud/s3_enum` | S3 bucket discovery, public ACL detection, file download + boto3 audit | T1530 |
+| `cloud/iam_enum` | IAM user/role enumeration, MFA checks, policy analysis (requires boto3) | T1580, T1078.004 |
+
+### Secrets
+| Module | Description | MITRE |
+|--------|-------------|-------|
+| `secrets/file_secrets` | 20+ pattern regex scanner + Shannon entropy detection | T1552.001 |
+
+### Exploitation
+| Module | Description | MITRE |
+|--------|-------------|-------|
+| `exploitation/api_exploit` | Generic credential testing, admin access, privilege escalation | T1078.004 |
+| `exploitation/jwt_attack` | None-algorithm bypass, weak secret bruteforce, algorithm confusion | T1078, T1550.001 |
+
+### Reporting
+| Module | Description |
+|--------|-------------|
+| `reporting/html_report` | Interactive HTML report with D3.js attack graph, CVSS scores, MITRE mapping |
+| `reporting/json_export` | Structured JSON for SIEM/ticketing integration |
+
+---
+
+## Secret Patterns (20+)
+
+ExploitGraph detects the following credential types:
+
+```
+AWS Access Key ID          AKIA[0-9A-Z]{16}
+AWS Secret Access Key      aws_secret_access_key = ...
+JWT Secret                 jwt_secret_key = ...
+Generic API Key            api_key = ...
+Stripe Live Key            sk_live_...
+GitHub Token               ghp_...
+Google API Key             AIza...
+SendGrid API Key           SG....
+Slack Token                xox[baprs]-...
+Database Password          db_password = ...
+Database URL               postgresql://user:pass@host
+Private Key                -----BEGIN RSA PRIVATE KEY-----
+Bearer Token               Authorization: Bearer ...
+Encryption Key             aes_key = [hex]
+Admin Credentials          admin password = ...
+Twilio SID                 AC[a-z0-9]{32}
+Webhook Secret             webhook_secret = ...
+High-Entropy Strings       Shannon entropy > 4.5
+```
+
+---
+
+## MITRE ATT&CK for Cloud Coverage
+
+| Technique | Name | Module |
+|-----------|------|--------|
+| T1595.003 | Wordlist Scanning | http_enum |
+| T1580 | Cloud Infrastructure Discovery | s3_enum, iam_enum |
+| T1530 | Data from Cloud Storage Object | s3_enum |
+| T1552.001 | Credentials in Files | file_secrets |
+| T1552.005 | Cloud Instance Metadata API | file_secrets |
+| T1078.004 | Valid Accounts: Cloud Accounts | api_exploit, iam_enum |
+| T1548 | Abuse Elevation Control Mechanism | api_exploit |
+| T1550.001 | Application Access Token | jwt_attack |
+
+---
+
+## Demo: Vulnerable Target (Viva/Lab Use)
+
+A deliberately vulnerable Flask fintech application is included for demonstration:
+
+```bash
+# Terminal 1 — Start target
+cd target && python3 app.py
+# Running at http://127.0.0.1:5000
+
+# Terminal 2 — Attack it
+python3 exploitgraph.py -t http://127.0.0.1:5000 --auto
+```
+
+The target simulates:
+- Public S3 bucket with backup archive
+- `.env` file with exposed AWS keys, API keys, JWT secrets
+- Weak admin credentials in deployment notes
+- Unauthenticated admin API endpoints
+- Debug endpoint leaking configuration
+
+> **The target app is for controlled lab environments only.**
+
+---
+
+## Writing Custom Modules
+
+Create a file in `modules/custom/my_module.py`:
+
+```python
+from modules.base import BaseModule, ModuleResult
+
+class MyModule(BaseModule):
+    NAME        = "my_module"
+    DESCRIPTION = "My custom scanner"
+    CATEGORY    = "discovery"
+    SEVERITY    = "HIGH"
+    MITRE       = ["T1595"]
+
+    OPTIONS = {
+        "TARGET": {"default": "", "required": True, "description": "Target URL"},
+    }
+
+    def run(self, session):
+        target = self.get_option("TARGET")
+        # ... your logic ...
+        session.add_finding(
+            module="my_module",
+            title="Finding Title",
+            severity="HIGH",
+            description="What was found",
+            evidence="Proof",
+            recommendation="How to fix",
+            cvss_score=7.5,
+        )
+        return ModuleResult(True, {"found": True})
+```
+
+ExploitGraph automatically discovers and loads it. No configuration needed.
+
+---
+
+## Report Output
+
+The HTML report includes:
+- Executive summary with severity breakdown
+- Interactive D3.js attack graph (drag, zoom, hover for details)
+- Expandable findings with CVSS scores
+- Evidence + proof-of-concept per finding
+- AWS CLI remediation commands
+- MITRE ATT&CK technique mapping
+- Full secrets table
+- Exploitation evidence log
+- Session risk score (0-10)
+
+---
+
+## AWS Integration
+
+With boto3 installed and credentials configured:
+
+```bash
+# Using AWS CLI profile
+exploitgraph> use cloud/s3_enum
+exploitgraph> set AWS_PROFILE my-profile
+exploitgraph> run
+
+# Using discovered credentials (auto-populated from file_secrets)
+exploitgraph> use cloud/iam_enum
+exploitgraph> run   # Picks up AWS keys found by file_secrets automatically
+```
+
+**All AWS operations are READ-ONLY** — no modifications to your AWS environment.
+
+---
+
+## Architecture
+
+```
+ExploitGraph/
+├── exploitgraph.py          Entry point (CLI + console launcher)
+├── core/
+│   ├── console.py           msfconsole-style interactive shell
+│   ├── module_loader.py     Dynamic plugin discovery & loading
+│   ├── session_manager.py   SQLite-backed multi-session tracking
+│   ├── attack_graph.py      networkx attack graph engine
+│   ├── risk_engine.py       CVSS-style risk scoring
+│   ├── logger.py            Structured colored logger
+│   └── config.py            YAML configuration loader
+├── modules/
+│   ├── base.py              BaseModule abstract class
+│   ├── discovery/           HTTP enumeration modules
+│   ├── cloud/               AWS/cloud security modules
+│   ├── secrets/             Credential extraction modules
+│   ├── exploitation/        Attack execution modules
+│   ├── reporting/           Report generation modules
+│   └── custom/              Drop your own modules here
+├── data/wordlists/          Attack wordlists
+├── sessions/                SQLite session database
+├── reports/                 Generated reports
+└── target/                  Demo vulnerable application
+```
+
+---
+
+## Legal Disclaimer
+
+ExploitGraph is developed for **authorized security testing and educational purposes only**.
+
+- Only use against systems you own or have explicit written permission to test
+- The demo target application is for isolated lab environments only
+- Unauthorized use against third-party systems is illegal
+
+The author assumes no liability for misuse of this tool.
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE)
+
+---
+
+## Author
+
+**Prajwal Pawar**
+B.Sc. Cyber Security — Final Year Project
+School of Computer Application
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+The easiest contribution: write a new module in `modules/custom/` following the `BaseModule` pattern and submit a PR.