security-pentest-planner 1.0.2__py3-none-any.whl

security_pentest_planner/__init__.py

@@ -0,0 +1,48 @@
+"""security_pentest_planner package.
+
+Gera Planos de Ação de Pentest a partir de especificações OpenAPI/Swagger.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .contract_analyzer import ContractAnalyzer
+from .errors import Error, InputError, ParseError
+from .models import Category, Endpoint, Parameter, RedFlag, Vector
+from .openapi_parser import OpenAPIParser
+from .plan_renderer import PlanRenderer
+from .planner import Planner
+from .vector_catalog import VectorCatalog
+from .version import __version__
+
+
+def generate(input_path: str, **options: Any) -> str:
+    """Generate a pentest action plan from an OpenAPI specification file."""
+    return Planner(input_path=input_path, **options).call()
+
+
+def generate_from_spec(spec: dict[str, Any], **options: Any) -> str:
+    """Generate a pentest action plan from an in-memory OpenAPI specification dict."""
+    return Planner(spec=spec, **options).call()
+
+
+__all__ = [
+    "__version__",
+    "generate",
+    "generate_from_spec",
+    "Planner",
+    "OpenAPIParser",
+    "ContractAnalyzer",
+    "VectorCatalog",
+    "PlanRenderer",
+    "Endpoint",
+    "Parameter",
+    "RedFlag",
+    "Vector",
+    "Category",
+    "Error",
+    "ParseError",
+    "InputError",
+]
+

security_pentest_planner/__main__.py

@@ -0,0 +1,8 @@
+"""Main entry point when invoked as python -m security_pentest_planner."""
+
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())
+

security_pentest_planner/cli.py

@@ -0,0 +1,65 @@
+"""CLI entry point for security-pentest-planner."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .errors import Error
+from .planner import Planner
+from .version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds the argument parser for the CLI."""
+    parser = argparse.ArgumentParser(
+        prog="security-pentest-planner",
+        description="Gera um Plano de Ação de Pentest a partir de especificação OpenAPI.",
+    )
+    parser.add_argument("input", nargs="?", help="Caminho do arquivo OpenAPI (.yaml, .yml, .json)")
+    parser.add_argument("-t", "--team", help="Nome do time no título do documento")
+    parser.add_argument("-s", "--scope", help="Limitar escopo a um path (ex: /api/v1/metrics)")
+    parser.add_argument("-d", "--datalake", action="store_true", help="Incluir vetores de Data Lake no plano")
+    parser.add_argument("--api-layer", default="API", help="Nome da camada de API no documento (default: API)")
+    parser.add_argument("--data-layer", default="Data Lake", help="Nome da camada de Data Lake no documento (default: Data Lake)")
+    parser.add_argument("-o", "--output", help="Salvar plano em arquivo (default: stdout)")
+    parser.add_argument("-v", "--version", action="version", version=f"security_pentest_planner {__version__}")
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main CLI execution method."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.input:
+        parser.print_help(sys.stderr)
+        return 1
+
+    try:
+        planner = Planner(
+            input_path=args.input,
+            team=args.team,
+            scope=args.scope,
+            include_datalake=args.datalake,
+            api_layer=args.api_layer,
+            data_layer=args.data_layer,
+        )
+        plan = planner.call()
+
+        if args.output:
+            Path(args.output).write_text(plan, encoding="utf-8")
+            print(f"Plano de Ação gerado em {args.output}", file=sys.stderr)
+        else:
+            print(plan)
+        return 0
+    except Error as e:
+        print(f"Erro: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

security_pentest_planner/contract_analyzer.py

@@ -0,0 +1,219 @@
+"""Contract analyzer for detecting security signals and red flags."""
+
+from __future__ import annotations
+
+import re
+from typing import Sequence
+
+from .models import Endpoint, Parameter, RedFlag
+from .openapi_parser import OpenAPIParser
+
+ANALYTICS_PATH_PATTERN = re.compile(r"metric|analytic|report|channel|insight|dashboard|aggregate", re.IGNORECASE)
+ANALYTICS_SUMMARY_PATTERN = re.compile(r"metric|analytic|report|aggregate", re.IGNORECASE)
+
+
+class ContractAnalyzer:
+    """Analyzes an OpenAPI specification for pentest triggers and security red flags."""
+
+    def __init__(
+        self,
+        parser: OpenAPIParser,
+        scope_paths: str | Sequence[str] | None = None,
+        include_datalake: bool = False,
+    ) -> None:
+        self.parser: OpenAPIParser = parser
+        if isinstance(scope_paths, str):
+            self.scope_paths: list[str] = [scope_paths]
+        elif scope_paths is not None:
+            self.scope_paths = list(scope_paths)
+        else:
+            self.scope_paths = []
+        self.include_datalake: bool = include_datalake
+
+    @property
+    def scoped_endpoints(self) -> list[Endpoint]:
+        """Endpoints matching the configured scope paths (or all if scope is empty)."""
+        endpoints = self.parser.endpoints
+        if not self.scope_paths:
+            return endpoints
+
+        return [
+            ep
+            for ep in endpoints
+            if any(ep.path == p or ep.path.startswith(p) for p in self.scope_paths)
+        ]
+
+    def parameters_for(self, endpoint: Endpoint) -> list[Parameter]:
+        """Returns parameters for a given endpoint."""
+        return self.parser.parameters_for(endpoint)
+
+    @property
+    def tenant_headers(self) -> list[Parameter]:
+        """Unique tenant headers detected across scoped endpoints."""
+        seen: set[str] = set()
+        result: list[Parameter] = []
+        for ep in self.scoped_endpoints:
+            for p in self.parameters_for(ep):
+                if p.is_tenant_header and p.name not in seen:
+                    seen.add(p.name)
+                    result.append(p)
+        return result
+
+    @property
+    def date_params(self) -> list[Parameter]:
+        """Unique date/time parameters detected across scoped endpoints."""
+        seen: set[str] = set()
+        result: list[Parameter] = []
+        for ep in self.scoped_endpoints:
+            for p in self.parameters_for(ep):
+                if p.is_date_param and p.name not in seen:
+                    seen.add(p.name)
+                    result.append(p)
+        return result
+
+    @property
+    def enum_params(self) -> list[Parameter]:
+        """Unique enum parameters detected across scoped endpoints."""
+        seen: set[str] = set()
+        result: list[Parameter] = []
+        for ep in self.scoped_endpoints:
+            for p in self.parameters_for(ep):
+                if p.is_enum_param and p.name not in seen:
+                    seen.add(p.name)
+                    result.append(p)
+        return result
+
+    @property
+    def timezone_headers(self) -> list[Parameter]:
+        """Unique timezone headers detected across scoped endpoints."""
+        seen: set[str] = set()
+        result: list[Parameter] = []
+        for ep in self.scoped_endpoints:
+            for p in self.parameters_for(ep):
+                if p.is_timezone_header and p.name not in seen:
+                    seen.add(p.name)
+                    result.append(p)
+        return result
+
+    @property
+    def has_tenant_scoping(self) -> bool:
+        """True if tenant headers are present."""
+        return bool(self.tenant_headers)
+
+    @property
+    def has_date_range(self) -> bool:
+        """True if date query parameters are present."""
+        return bool(self.date_params)
+
+    @property
+    def has_enum_params(self) -> bool:
+        """True if enum parameters are present."""
+        return bool(self.enum_params)
+
+    @property
+    def has_free_text_headers(self) -> bool:
+        """True if timezone header or free-form tenant headers are present."""
+        return bool(self.timezone_headers) or any(not h.enum_values for h in self.tenant_headers)
+
+    @property
+    def is_analytics_endpoint(self) -> bool:
+        """True if any scoped endpoint matches analytical patterns."""
+        for ep in self.scoped_endpoints:
+            if ANALYTICS_PATH_PATTERN.search(ep.path):
+                return True
+            if ep.summary and ANALYTICS_SUMMARY_PATTERN.search(ep.summary):
+                return True
+        return False
+
+    @property
+    def red_flags(self) -> list[RedFlag]:
+        """Generates list of identified contract security red flags."""
+        flags: list[RedFlag] = []
+
+        if not self.parser.security_schemes and self.scoped_endpoints:
+            flags.append(
+                RedFlag(
+                    message="Ausência de `securitySchemes` documentado no contrato OpenAPI",
+                    severity="high",
+                )
+            )
+
+        for header in self.tenant_headers:
+            if not header.required:
+                flags.append(
+                    RedFlag(
+                        message=f"Header `{header.name}` documentado como opcional (`required: false`)",
+                        severity="high",
+                    )
+                )
+
+        tenant_names = {h.name for h in self.tenant_headers}
+        if len(tenant_names) > 1:
+            joined = " vs ".join(sorted(tenant_names))
+            flags.append(
+                RedFlag(
+                    message=f"Divergência de nomes de header de tenant: {joined}",
+                    severity="medium",
+                )
+            )
+
+        for tz in self.timezone_headers:
+            if not tz.enum_values:
+                flags.append(
+                    RedFlag(
+                        message=f"Header `{tz.name}` como string livre (sem enum/whitelist IANA)",
+                        severity="medium",
+                    )
+                )
+
+        if self.is_analytics_endpoint:
+            flags.append(
+                RedFlag(
+                    message="Nenhum rate limiting documentado em endpoint analítico",
+                    severity="medium",
+                )
+            )
+
+        return flags
+
+    @property
+    def signals(self) -> dict[str, bool]:
+        """Dictionary of detected architectural security signals."""
+        return {
+            "tenant_scoping": self.has_tenant_scoping,
+            "date_range": self.has_date_range,
+            "enum_params": self.has_enum_params,
+            "free_text_headers": self.has_free_text_headers,
+            "analytics": self.is_analytics_endpoint,
+            "datalake": self.include_datalake,
+        }
+
+    @property
+    def primary_endpoint(self) -> Endpoint | None:
+        """First scoped endpoint or None."""
+        endpoints = self.scoped_endpoints
+        return endpoints[0] if endpoints else None
+
+    @property
+    def host(self) -> str:
+        """Target API host or default."""
+        servers = self.parser.servers
+        return servers[0] if servers else "api.example.com"
+
+    @property
+    def tenant_header_name(self) -> str:
+        """First detected tenant header name or default."""
+        headers = self.tenant_headers
+        return headers[0].name if headers else "X-Tenant-ID"
+
+    @property
+    def date_param_names(self) -> list[str]:
+        """List of detected date parameter names."""
+        return [p.name for p in self.date_params]
+
+    @property
+    def enum_param(self) -> Parameter | None:
+        """First detected enum parameter or None."""
+        params = self.enum_params
+        return params[0] if params else None
+

security_pentest_planner/errors.py

@@ -0,0 +1,14 @@
+"""Exceptions for security_pentest_planner."""
+
+
+class Error(Exception):
+    """Base exception for security_pentest_planner."""
+
+
+class ParseError(Error):
+    """Raised when an OpenAPI document cannot be parsed."""
+
+
+class InputError(Error):
+    """Raised when input parameters or scope paths are invalid."""
+

security_pentest_planner/models.py

@@ -0,0 +1,111 @@
+"""Data models for security_pentest_planner."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+TENANT_HEADER_PATTERN = re.compile(r"tenant", re.IGNORECASE)
+DATE_PARAM_PATTERN = re.compile(r"date|start|end|from|to|period|range", re.IGNORECASE)
+TIMEZONE_HEADER_PATTERN = re.compile(r"timezone|time_zone|tz", re.IGNORECASE)
+
+
+@dataclass
+class Parameter:
+    """Represents an OpenAPI operation parameter."""
+
+    name: str
+    location: str
+    required: bool = False
+    schema: dict[str, Any] = field(default_factory=dict)
+    description: str | None = None
+
+    @property
+    def enum_values(self) -> list[Any]:
+        """Returns enum values from the schema or its items."""
+        if not isinstance(self.schema, dict):
+            return []
+        enum = self.schema.get("enum")
+        if enum:
+            return list(enum)
+        items = self.schema.get("items")
+        if isinstance(items, dict) and items.get("enum"):
+            return list(items["enum"])
+        return []
+
+    @property
+    def type(self) -> str | None:
+        """Returns the schema type if defined."""
+        if isinstance(self.schema, dict):
+            return self.schema.get("type")
+        return None
+
+    @property
+    def is_tenant_header(self) -> bool:
+        """Checks if parameter is a tenant header."""
+        return self.location == "header" and bool(TENANT_HEADER_PATTERN.search(self.name))
+
+    @property
+    def is_date_param(self) -> bool:
+        """Checks if parameter is a date/time range query parameter."""
+        return self.location == "query" and bool(DATE_PARAM_PATTERN.search(self.name))
+
+    @property
+    def is_timezone_header(self) -> bool:
+        """Checks if parameter is a timezone header."""
+        return self.location == "header" and bool(TIMEZONE_HEADER_PATTERN.search(self.name))
+
+    @property
+    def is_enum_param(self) -> bool:
+        """Checks if parameter restricts values using an enum."""
+        return bool(self.enum_values)
+
+
+@dataclass
+class Endpoint:
+    """Represents an API endpoint operation."""
+
+    path: str
+    method: str
+    operation_id: str | None = None
+    summary: str | None = None
+    parameters: list[Parameter] = field(default_factory=list)
+    security: list[Any] | None = None
+
+
+@dataclass
+class RedFlag:
+    """Represents a security design smell or missing control in the OpenAPI contract."""
+
+    message: str
+    severity: str  # "high", "medium", "low"
+
+
+@dataclass
+class Category:
+    """Represents a pentest category."""
+
+    slug: str
+    title: str
+    layer: str  # "api" or "datalake"
+
+
+@dataclass
+class Vector:
+    """Represents a specific offensive security test vector."""
+
+    id: str
+    name: str
+    category_slug: str
+    category_title: str
+    layer: str  # "api" or "datalake"
+    triggers: list[str]
+    objective: str
+    procedure: list[str]
+    payload: str
+    payload_type: str
+    expected_validation: str
+    failure_criteria: str
+    risk: str
+

security_pentest_planner/openapi_parser.py

@@ -0,0 +1,203 @@
+"""OpenAPI contract parser."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .errors import ParseError
+from .models import Endpoint, Parameter
+
+VALID_HTTP_METHODS = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
+
+
+class OpenAPIParser:
+    """Parses OpenAPI 3.x specifications in YAML or JSON."""
+
+    def __init__(self, content: dict[str, Any], source_path: str | None = None) -> None:
+        self.raw: dict[str, Any] = content or {}
+        self.source_path: str | None = source_path
+        self._endpoints: list[Endpoint] | None = None
+
+    @classmethod
+    def parse_file(cls, path_str: str) -> OpenAPIParser:
+        """Parses an OpenAPI spec from a file path."""
+        path = Path(path_str)
+        if not path.is_file():
+            raise ParseError(f"Arquivo não encontrado: {path_str}")
+
+        content = path.read_text(encoding="utf-8")
+        ext = path.suffix.lower()
+
+        try:
+            if ext in {".yaml", ".yml"}:
+                parsed = yaml.safe_load(content)
+            elif ext == ".json":
+                parsed = json.loads(content)
+            else:
+                raise ParseError(f"Unsupported file extension: {path_str}. Use .yaml, .yml or .json")
+        except Exception as exc:
+            if isinstance(exc, ParseError):
+                raise
+            raise ParseError(f"Erro ao processar contrato OpenAPI em {path_str}: {exc}") from exc
+
+        if not isinstance(parsed, dict):
+            raise ParseError(f"Conteúdo OpenAPI inválido em {path_str} (esperado objeto/dicionário).")
+
+        return cls(parsed, source_path=path_str)
+
+    @property
+    def info(self) -> dict[str, Any]:
+        """Returns the info section of the OpenAPI spec."""
+        info_data = self.raw.get("info")
+        return info_data if isinstance(info_data, dict) else {}
+
+    @property
+    def title(self) -> str | None:
+        """API Title."""
+        return self.info.get("title")
+
+    @property
+    def version(self) -> str | None:
+        """API Version."""
+        return self.info.get("version")
+
+    @property
+    def servers(self) -> list[str]:
+        """List of server URLs."""
+        servers_data = self.raw.get("servers")
+        if not isinstance(servers_data, list):
+            return []
+        urls = []
+        for s in servers_data:
+            if isinstance(s, dict) and "url" in s and s["url"]:
+                urls.append(s["url"])
+        return urls
+
+    @property
+    def security_schemes(self) -> dict[str, Any]:
+        """Returns security schemes defined in components."""
+        components = self.raw.get("components")
+        if isinstance(components, dict):
+            schemes = components.get("securitySchemes")
+            if isinstance(schemes, dict):
+                return schemes
+        return {}
+
+    @property
+    def endpoints(self) -> list[Endpoint]:
+        """Returns all parsed endpoints/operations."""
+        if self._endpoints is None:
+            self._endpoints = self._build_endpoints()
+        return self._endpoints
+
+    def parameters_for(self, endpoint: Endpoint) -> list[Parameter]:
+        """Merges global path-level parameters with endpoint-level parameters."""
+        paths = self.raw.get("paths")
+        global_params: list[Any] = []
+        if isinstance(paths, dict):
+            path_item = paths.get(endpoint.path)
+            if isinstance(path_item, dict):
+                gp = path_item.get("parameters")
+                if isinstance(gp, list):
+                    global_params = gp
+
+        all_params = global_params + list(endpoint.parameters)
+        return self._merge_parameters(all_params)
+
+    def _build_endpoints(self) -> list[Endpoint]:
+        paths = self.raw.get("paths")
+        if not isinstance(paths, dict):
+            return []
+
+        endpoints: list[Endpoint] = []
+        for path_str, methods in paths.items():
+            if not isinstance(methods, dict):
+                continue
+            for method, operation in methods.items():
+                if method.lower() not in VALID_HTTP_METHODS or not isinstance(operation, dict):
+                    continue
+
+                raw_params = operation.get("parameters")
+                param_objs: list[Parameter] = []
+                if isinstance(raw_params, list):
+                    for p in raw_params:
+                        built = self._build_parameter(p)
+                        if built:
+                            param_objs.append(built)
+
+                summary = operation.get("summary") or operation.get("description")
+                endpoints.append(
+                    Endpoint(
+                        path=path_str,
+                        method=method.upper(),
+                        operation_id=operation.get("operationId"),
+                        summary=summary,
+                        parameters=param_objs,
+                        security=operation.get("security"),
+                    )
+                )
+
+        return endpoints
+
+    def _build_parameter(self, param: Any) -> Parameter | None:
+        if isinstance(param, Parameter):
+            return param
+        resolved = self._resolve_ref(param)
+        if not isinstance(resolved, dict) or "name" not in resolved:
+            return None
+
+        schema = resolved.get("schema")
+        if not isinstance(schema, dict):
+            schema = {}
+
+        return Parameter(
+            name=resolved["name"],
+            location=resolved.get("in", ""),
+            required=resolved.get("required") is True,
+            schema=schema,
+            description=resolved.get("description"),
+        )
+
+    def _resolve_ref(self, obj: Any) -> Any:
+        if not isinstance(obj, dict) or "$ref" not in obj:
+            return obj
+
+        ref = obj["$ref"]
+        if not isinstance(ref, str):
+            return obj
+
+        if ref.startswith("#/"):
+            clean_ref = ref[2:]
+        elif ref.startswith("#"):
+            clean_ref = ref[1:]
+        else:
+            clean_ref = ref
+
+        parts = [p.replace("~1", "/").replace("~0", "~") for p in clean_ref.split("/") if p]
+        node: Any = self.raw
+        for part in parts:
+            if isinstance(node, dict) and part in node:
+                node = node[part]
+            else:
+                return obj
+        return node
+
+    def _merge_parameters(self, params: list[Any]) -> list[Parameter]:
+        merged: list[Parameter] = []
+        seen: set[tuple[str, str]] = set()
+
+        for p in params:
+            built = self._build_parameter(p)
+            if not built:
+                continue
+            key = (built.location, built.name)
+            if key not in seen:
+                seen.add(key)
+                merged.append(built)
+
+        return merged
+