CONTRIBUTING.md

Contributing to ExploitGraph

Thank you for your interest in contributing to ExploitGraph!

Adding a New Module

The easiest way to contribute is to write a new attack or detection module.

Step 1: Create the file

Place your module in the appropriate category directory:

modules/
  discovery/   — endpoint enumeration, fingerprinting
  cloud/       — AWS/GCP/Azure checks
  secrets/     — credential extraction and analysis
  exploitation/— attack execution
  reporting/   — output and visualization
  custom/      — your personal modules (not tracked by git)

Step 2: Inherit BaseModule

from modules.base import BaseModule, ModuleResult

class MyScanner(BaseModule):
    NAME        = "my_scanner"          # Unique snake_case name
    DESCRIPTION = "What this does"
    AUTHOR      = "Your Name"
    VERSION     = "1.0.0"
    CATEGORY    = "discovery"           # category folder name
    SEVERITY    = "HIGH"                # INFO | LOW | MEDIUM | HIGH | CRITICAL
    MITRE       = ["T1595"]             # MITRE ATT&CK technique IDs
    AWS_PARALLEL = "aws equivalent"     # Real AWS command this maps to

    OPTIONS = {
        "TARGET": {
            "default": "",
            "required": True,
            "description": "Target URL"
        },
        "MY_OPTION": {
            "default": "default_value",
            "required": False,
            "description": "What this option does"
        },
    }

    def run(self, session) -> ModuleResult:
        target = self.get_option("TARGET") or session.target
        # ... your scanning logic ...

        # Write findings to session
        session.add_finding(
            module          = self.NAME,
            title           = "Finding title",
            severity        = "HIGH",
            description     = "What was found and why it matters",
            evidence        = "Proof of the finding",
            recommendation  = "How to fix it",
            cvss_score      = 7.5,
            aws_parallel    = "Real AWS misconfiguration this maps to",
            mitre_technique = "T1595",
        )

        # Write secrets to session
        session.add_secret(
            secret_type  = "API_KEY",
            value        = "sk_live_...",
            source       = target,
            severity     = "CRITICAL",
            description  = "API key found",
            aws_parallel = "API Gateway key exposed",
        )

        return ModuleResult(True, {"items_found": 42})

Step 3: Test it

python3 exploitgraph.py
exploitgraph> use discovery/my_scanner
exploitgraph> set TARGET http://testsite.com
exploitgraph> run

Step 4: Submit a PR

• One module per PR
• Include a brief description of what the module detects
• All modules must be READ-ONLY safe by default (no destructive operations without explicit user consent)

Code Style

• Type hints on all function signatures
• Docstrings on class and run() method
• Use self.info(), self.ok(), self.warn() for output (not print())
• Catch all exceptions — modules must never crash the framework

Bug Reports

Open a GitHub issue with:

1. ExploitGraph version
2. Python version
3. Command that caused the issue
4. Full error output