mcp-api-pentest 0.2.0__py3-none-any.whl

mcp_api_logic_pentest/adapters/cli.py

@@ -0,0 +1,65 @@
+"""CLI entry point for mcp-api-logic-pentest."""
+import argparse
+import sys
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcp-api-pentest",
+        description="MCP server for autonomous API logic penetration testing",
+    )
+    parser.add_argument(
+        "--swagger", "-s",
+        help="Path to OpenAPI/Swagger spec file (JSON or YAML)",
+    )
+    parser.add_argument(
+        "--target", "-t",
+        help="Base URL of the API to audit",
+    )
+    parser.add_argument(
+        "--output", "-o",
+        default="REPORTE_PENTEST.md",
+        help="Output report path (default: REPORTE_PENTEST.md)",
+    )
+    parser.add_argument(
+        "--delay",
+        type=float,
+        default=0.5,
+        help="Delay in seconds between requests (default: 0.5)",
+    )
+    parser.add_argument(
+        "--token-admin",
+        help="Admin-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--token-victim",
+        help="Victim-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--token-attacker",
+        help="Attacker-level authentication token for multi-session audits",
+    )
+    parser.add_argument(
+        "--config",
+        help="Path to YAML configuration file",
+    )
+    parser.add_argument(
+        "--mock",
+        action="store_true",
+        help="Launch the mock API sandbox instead of the MCP server",
+    )
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+
+    if args.mock:
+        print("Starting mock API sandbox...")
+        import subprocess
+        subprocess.run([sys.executable, "mock_api.py"])
+        return
+
+    print("Starting MCP API Logic Pentest server...")
+    from mcp_api_logic_pentest.adapters.mcp_server import mcp
+    mcp.run()

mcp_api_logic_pentest/adapters/mcp_server.py

@@ -0,0 +1,50 @@
+from fastmcp import FastMCP
+
+from mcp_api_logic_pentest.audit_context.attack_context import (
+    capture_context,
+    clear_context,
+    extract_json_value,
+    get_context,
+    list_context,
+)
+from mcp_api_logic_pentest.http_client.http_client import execute_security_request
+from mcp_api_logic_pentest.idor_detector.access_analyzer import analyze_access_control
+from mcp_api_logic_pentest.report_generator.reporter import (
+    export_report_json,
+    generate_report,
+    save_security_finding,
+)
+from mcp_api_logic_pentest.spec_analyzer.spec_parser import parse_api_spec
+
+mcp = FastMCP("mcp-api-logic-pentest")
+
+# ---------------------------------------------------------------------------
+# Fase 1 + 4: HTTP client and spec parsing
+# ---------------------------------------------------------------------------
+
+mcp.tool()(parse_api_spec)
+mcp.tool()(execute_security_request)
+
+# ---------------------------------------------------------------------------
+# Fase 2: Multi-session IDOR detection
+# ---------------------------------------------------------------------------
+
+mcp.tool()(analyze_access_control)
+
+# ---------------------------------------------------------------------------
+# Fase 3: State management for chained attacks
+# ---------------------------------------------------------------------------
+
+mcp.tool()(capture_context)
+mcp.tool()(get_context)
+mcp.tool()(list_context)
+mcp.tool()(clear_context)
+mcp.tool()(extract_json_value)
+
+# ---------------------------------------------------------------------------
+# Fase 5b: Report generation
+# ---------------------------------------------------------------------------
+
+mcp.tool()(save_security_finding)
+mcp.tool()(generate_report)
+mcp.tool()(export_report_json)

mcp_api_logic_pentest/adapters/tests/test_cli.py

@@ -0,0 +1,122 @@
+"""
+Tests for CLI argument parsing — verify all flags and defaults work correctly.
+"""
+
+from mcp_api_logic_pentest.adapters.cli import build_parser
+
+
+class TestCLIDefaults:
+    def test_default_delay(self):
+        parser = build_parser()
+        args = parser.parse_args([])
+        assert args.delay == 0.5
+        assert args.mock is False
+        assert args.output == "REPORTE_PENTEST.md"
+
+    def test_default_tokens_none(self):
+        parser = build_parser()
+        args = parser.parse_args([])
+        assert args.token_admin is None
+        assert args.token_victim is None
+        assert args.token_attacker is None
+
+    def test_default_config_none(self):
+        parser = build_parser()
+        args = parser.parse_args([])
+        assert args.config is None
+
+
+class TestCLIFlags:
+    def test_swagger_short_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["-s", "spec.json"])
+        assert args.swagger == "spec.json"
+
+    def test_target_short_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["-t", "https://api.example.com"])
+        assert args.target == "https://api.example.com"
+
+    def test_output_long_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--output", "custom_report.md"])
+        assert args.output == "custom_report.md"
+
+    def test_output_short_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["-o", "short_report.md"])
+        assert args.output == "short_report.md"
+
+    def test_delay_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--delay", "1.5"])
+        assert args.delay == 1.5
+
+    def test_mock_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--mock"])
+        assert args.mock is True
+
+
+class TestTokenFlags:
+    def test_admin_token_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--token-admin", "admin_secret_2026"])
+        assert args.token_admin == "admin_secret_2026"
+
+    def test_victim_token_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--token-victim", "victim_token"])
+        assert args.token_victim == "victim_token"
+
+    def test_attacker_token_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--token-attacker", "attacker_token"])
+        assert args.token_attacker == "attacker_token"
+
+    def test_all_tokens_together(self):
+        parser = build_parser()
+        args = parser.parse_args([
+            "--token-admin", "admin",
+            "--token-victim", "victim",
+            "--token-attacker", "attacker",
+        ])
+        assert args.token_admin == "admin"
+        assert args.token_victim == "victim"
+        assert args.token_attacker == "attacker"
+
+
+class TestConfigFlag:
+    def test_config_flag(self):
+        parser = build_parser()
+        args = parser.parse_args(["--config", "config.yaml"])
+        assert args.config == "config.yaml"
+
+
+class TestCombinedFlags:
+    def test_full_pentest_command(self):
+        parser = build_parser()
+        args = parser.parse_args([
+            "--swagger", "spec.json",
+            "--target", "https://api.example.com",
+            "--output", "report.md",
+            "--delay", "1.0",
+            "--token-admin", "admin123",
+            "--token-victim", "victim456",
+            "--token-attacker", "attacker789",
+            "--config", "settings.yaml",
+        ])
+        assert args.swagger == "spec.json"
+        assert args.target == "https://api.example.com"
+        assert args.output == "report.md"
+        assert args.delay == 1.0
+        assert args.token_admin == "admin123"
+        assert args.token_victim == "victim456"
+        assert args.token_attacker == "attacker789"
+        assert args.config == "settings.yaml"
+
+    def test_mock_with_custom_delay(self):
+        parser = build_parser()
+        args = parser.parse_args(["--mock", "--delay", "2.0"])
+        assert args.mock is True
+        assert args.delay == 2.0

mcp_api_logic_pentest/audit_context/attack_context.py

@@ -0,0 +1,101 @@
+import json
+from typing import Dict
+
+ATTACK_CONTEXT: Dict[str, str] = {}
+
+
+def capture_context(key: str, value: str) -> str:
+    """Stores a dynamic value in the session cache. Use after POST/PUT responses to save
+    resource IDs for later use in DELETE/GET requests with a different auth token."""
+    ATTACK_CONTEXT[key] = value
+    return json.dumps({
+        "status": "stored",
+        "key": key,
+        "value": value,
+        "total_keys": len(ATTACK_CONTEXT),
+    })
+
+
+def get_context(key: str) -> str:
+    """Retrieves a previously stored value from the session cache. Returns not_found
+    if the key does not exist. Use to inject dynamic IDs into attack URLs."""
+    value = ATTACK_CONTEXT.get(key)
+    if value is None:
+        return json.dumps({
+            "status": "not_found",
+            "key": key,
+            "available_keys": list(ATTACK_CONTEXT.keys()),
+        })
+    return json.dumps({
+        "status": "found",
+        "key": key,
+        "value": value,
+    })
+
+
+def list_context() -> str:
+    """Returns all key-value pairs stored in the session cache. Useful for the LLM
+    to see what dynamic IDs are available for chained attack flows."""
+    return json.dumps({
+        "total_keys": len(ATTACK_CONTEXT),
+        "entries": dict(ATTACK_CONTEXT),
+    }, indent=2)
+
+
+def clear_context() -> str:
+    """Clears all stored values from the session cache. Use at the start of a new audit
+    cycle to avoid stale data contamination."""
+    count = len(ATTACK_CONTEXT)
+    ATTACK_CONTEXT.clear()
+    return json.dumps({
+        "status": "cleared",
+        "keys_removed": count,
+    })
+
+
+def extract_json_value(response_json: str, json_path: str) -> str:
+    """Extracts a specific value from a JSON response using dot-notation path.
+    Essential for chained attacks where the LLM needs to grab a dynamically
+    created resource ID from a POST response (e.g. 'data.id' → 42)."""
+    try:
+        data = json.loads(response_json) if isinstance(response_json, str) else response_json
+    except json.JSONDecodeError:
+        return json.dumps({
+            "error": "Invalid JSON input",
+            "input_preview": response_json[:200],
+        })
+
+    parts = json_path.split(".")
+    current = data
+    traversed = []
+
+    for part in parts:
+        traversed.append(part)
+        if isinstance(current, dict):
+            if part not in current:
+                return json.dumps({
+                    "error": f"Key '{part}' not found at path '{'.'.join(traversed)}'",
+                    "available_keys": list(current.keys()) if isinstance(current, dict) else None,
+                })
+            current = current[part]
+        elif isinstance(current, list):
+            try:
+                idx = int(part)
+                current = current[idx]
+            except (ValueError, IndexError):
+                return json.dumps({
+                    "error": f"Invalid list index '{part}' at path '{'.'.join(traversed)}'",
+                    "list_length": len(current),
+                })
+        else:
+            return json.dumps({
+                "error": f"Cannot traverse into scalar value at path '{'.'.join(traversed[:-1])}'",
+                "scalar_value": str(current),
+            })
+
+    return json.dumps({
+        "status": "extracted",
+        "path": json_path,
+        "value": current,
+        "type": type(current).__name__,
+    }, default=str)

mcp_api_logic_pentest/audit_context/tests/__init__.py

@@ -0,0 +1 @@
+# Test package

mcp_api_logic_pentest/audit_context/tests/test_attack_context.py

@@ -0,0 +1,134 @@
+"""
+Tests for audit_context.attack_context module.
+Uses autouse fixture to isolate ATTACK_CONTEXT state between tests.
+"""
+import json
+
+import pytest
+
+from mcp_api_logic_pentest.audit_context.attack_context import (
+    ATTACK_CONTEXT,
+    capture_context,
+    clear_context,
+    extract_json_value,
+    get_context,
+    list_context,
+)
+
+
+@pytest.fixture(autouse=True)
+def _clear_state():
+    ATTACK_CONTEXT.clear()
+    yield
+    ATTACK_CONTEXT.clear()
+
+
+class TestCaptureContext:
+    def test_returns_stored_status(self):
+        result = json.loads(capture_context("user_id", "42"))
+        assert result["status"] == "stored"
+        assert result["key"] == "user_id"
+        assert result["value"] == "42"
+
+    def test_increments_total_keys(self):
+        capture_context("a", "1")
+        result = json.loads(capture_context("b", "2"))
+        assert result["total_keys"] == 2
+
+    def test_overwrites_existing_key(self):
+        capture_context("key", "old")
+        capture_context("key", "new")
+        assert ATTACK_CONTEXT["key"] == "new"
+        assert len(ATTACK_CONTEXT) == 1
+
+
+class TestGetContext:
+    def test_returns_value_for_existing_key(self):
+        capture_context("invoice_id", "1004")
+        result = json.loads(get_context("invoice_id"))
+        assert result["status"] == "found"
+        assert result["key"] == "invoice_id"
+        assert result["value"] == "1004"
+
+    def test_returns_not_found_for_missing_key(self):
+        result = json.loads(get_context("nonexistent"))
+        assert result["status"] == "not_found"
+        assert result["available_keys"] == []
+
+    def test_lists_available_keys_when_not_found(self):
+        capture_context("a", "1")
+        capture_context("b", "2")
+        result = json.loads(get_context("c"))
+        assert result["status"] == "not_found"
+        assert set(result["available_keys"]) == {"a", "b"}
+
+
+class TestListContext:
+    def test_returns_empty_when_no_keys(self):
+        result = json.loads(list_context())
+        assert result["total_keys"] == 0
+        assert result["entries"] == {}
+
+    def test_returns_all_stored_pairs(self):
+        capture_context("id", "42")
+        capture_context("token", "abc")
+        result = json.loads(list_context())
+        assert result["total_keys"] == 2
+        assert result["entries"]["id"] == "42"
+        assert result["entries"]["token"] == "abc"
+
+
+class TestClearContext:
+    def test_clears_all_entries(self):
+        capture_context("a", "1")
+        capture_context("b", "2")
+        result = json.loads(clear_context())
+        assert result["status"] == "cleared"
+        assert result["keys_removed"] == 2
+        assert len(ATTACK_CONTEXT) == 0
+
+    def test_returns_zero_when_already_empty(self):
+        result = json.loads(clear_context())
+        assert result["status"] == "cleared"
+        assert result["keys_removed"] == 0
+
+
+class TestExtractJsonValue:
+    def test_extracts_simple_key(self):
+        result = json.loads(extract_json_value('{"data": {"id": 42}}', "data.id"))
+        assert result["status"] == "extracted"
+        assert result["value"] == 42
+        assert result["type"] == "int"
+
+    def test_extracts_from_list_index(self):
+        result = json.loads(extract_json_value('{"items": [10, 20, 30]}', "items.1"))
+        assert result["status"] == "extracted"
+        assert result["value"] == 20
+
+    def test_extracts_nested_dict_path(self):
+        result = json.loads(extract_json_value(
+            '{"results": [{"name": "first"}, {"name": "second"}]}',
+            "results.0.name"
+        ))
+        assert result["value"] == "first"
+
+    def test_returns_error_for_invalid_json(self):
+        result = json.loads(extract_json_value("not valid json", "key"))
+        assert "error" in result
+        assert "Invalid JSON" in result["error"]
+
+    def test_returns_error_for_missing_key(self):
+        result = json.loads(extract_json_value('{"a": 1}', "b"))
+        assert "error" in result
+        assert "not found" in result["error"]
+        assert result["available_keys"] == ["a"]
+
+    def test_returns_error_for_invalid_list_index(self):
+        result = json.loads(extract_json_value('{"items": [1, 2]}', "items.5"))
+        assert "error" in result
+        assert "Invalid list index" in result["error"]
+
+    def test_returns_error_for_traverse_into_scalar(self):
+        result = json.loads(extract_json_value('{"value": 42}', "value.nested"))
+        assert "error" in result
+        assert "scalar" in result["error"]

mcp_api_logic_pentest/config/settings.py

@@ -0,0 +1,13 @@
+import logging
+
+MAX_RESPONSE_SIZE_BYTES = 4096
+DEFAULT_DELAY_SECONDS = 0.5
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+USER_AGENT = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "mcp-api-logic-pentest/1.0"
+)
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger("mcp-api-logic-pentest")

mcp_api_logic_pentest/http_client/auth/bearer_auth.py

@@ -0,0 +1,18 @@
+from typing import Dict
+
+
+def apply_bearer_auth(headers: Dict[str, str], token: str) -> Dict[str, str]:
+    headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def apply_api_key_header(headers: Dict[str, str], key_name: str, key_value: str) -> Dict[str, str]:
+    headers[key_name] = key_value
+    return headers
+
+
+def apply_basic_auth(headers: Dict[str, str], username: str, password: str) -> Dict[str, str]:
+    import base64
+    credentials = base64.b64encode(f"{username}:{password}".encode()).decode()
+    headers["Authorization"] = f"Basic {credentials}"
+    return headers

mcp_api_logic_pentest/http_client/http_client.py

@@ -0,0 +1,84 @@
+import json
+import time
+from typing import Optional
+
+import httpx
+
+from mcp_api_logic_pentest.config.settings import (
+    DEFAULT_DELAY_SECONDS,
+    DEFAULT_TIMEOUT_SECONDS,
+    MAX_RESPONSE_SIZE_BYTES,
+    USER_AGENT,
+    logger,
+)
+from mcp_api_logic_pentest.shared.json_truncator import truncate_json_intelligently
+
+
+async def execute_security_request(
+    url: str,
+    method: str,
+    auth_token: Optional[str] = None,
+    body_json: Optional[str] = None,
+    delay_seconds: float = DEFAULT_DELAY_SECONDS,
+) -> str:
+    """
+    Async resilient HTTP client with anti-blocking (WAF) protection and passive rate limiting.
+    Sends LLM-directed requests and returns a structured, token-optimized traffic report.
+    """
+    if delay_seconds > 0:
+        time.sleep(delay_seconds)
+
+    method = method.upper()
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+
+    if auth_token:
+        headers["Authorization"] = f"Bearer {auth_token}"
+    if body_json:
+        headers["Content-Type"] = "application/json"
+
+    payload = None
+    if body_json:
+        try:
+            payload = json.loads(body_json)
+        except json.JSONDecodeError:
+            return "Error: The 'body_json' parameter supplied is not valid JSON."
+
+    async with httpx.AsyncClient(timeout=DEFAULT_TIMEOUT_SECONDS) as client:
+        try:
+            logger.info(f"Executing audit request: {method} {url}")
+            response = await client.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=payload,
+            )
+
+            report = {
+                "status_code": response.status_code,
+                "response_headers": dict(response.headers),
+                "raw_size_bytes": len(response.text),
+                "response_body": None,
+            }
+
+            if "application/json" in response.headers.get("content-type", "").lower():
+                try:
+                    json_data = response.json()
+                    if len(response.text) > MAX_RESPONSE_SIZE_BYTES:
+                        report["response_body"] = truncate_json_intelligently(json_data)
+                    else:
+                        report["response_body"] = json_data
+                except Exception:
+                    report["response_body"] = response.text[:500] + " ... [Unparseable JSON truncated]"
+            else:
+                report["response_body"] = response.text[:1000] + "\n... [Non-JSON text truncated by MCP server]"
+
+            return json.dumps(report, indent=2, ensure_ascii=False)
+
+        except httpx.RequestError as exc:
+            return json.dumps({
+                "error": "Network connection failure to target",
+                "details": f"Could not connect to the web server: {str(exc)}",
+            })