security_pentest_planner 1.0.1

data/lib/security_pentest_planner/plan_renderer.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+module SecurityPentestPlanner
+  class PlanRenderer
+    SUMMARY_CATEGORIES = {
+      "Acesso" => %w[tenant-traversal header-injection privilege-escalation sa-overprivilege metadata-leak],
+      "Entrada" => %w[sqli-basic enum-injection timezone-manipulation bypass-tenant union-exploitation type-juggling],
+      "Disponibilidade" => %w[data-range-exhaustion rate-limit-absence cartesian-product full-scan],
+      "Informação" => %w[verbosity-check metadata-leak]
+    }.freeze
+
+    def initialize(analyzer:, vectors:, team: nil, api_layer: "API", data_layer: "Data Lake")
+      @analyzer = analyzer
+      @vectors = vectors
+      @team = team || "TIME"
+      @api_layer = api_layer
+      @data_layer = data_layer
+    end
+
+    def render
+      sections = [
+        header,
+        introduction,
+        api_section,
+        datalake_section,
+        summary_table,
+        recommendations,
+        datalake_sql_reference,
+        assumptions
+      ]
+
+      sections.compact.join("\n\n")
+    end
+
+    private
+
+    attr_reader :analyzer, :vectors, :team, :api_layer, :data_layer
+
+    def header
+      "# #{team} — Plano de Ação de Pentest"
+    end
+
+    def introduction
+      endpoint = analyzer.primary_endpoint
+      scope_table = analyzer.scoped_endpoints.map do |ep|
+        tenant = analyzer.tenant_headers.find { |h| analyzer.parser.parameters_for(ep).include?(h) }
+        required = tenant&.required ? "true" : "**false**"
+        "| #{ep.method} | `#{ep.path}` | `#{tenant&.name || '—'}` (required: #{required}) |"
+      end
+
+      red_flags = analyzer.red_flags.map { |f| "- #{f.message}" }.join("\n")
+
+      <<~MD.strip
+        ## Introdução do Projeto
+
+        #{intro_text}
+
+        **Camadas em escopo:**
+
+        - **#{api_layer}:** Endpoints REST mapeados no contrato OpenAPI
+        #{datalake_in_scope? ? "- **#{data_layer}:** Queries analíticas, IAM e persistência downstream" : ""}
+
+        **Fonte analisada:** `#{analyzer.parser.source_path || "OpenAPI spec"}`
+
+        **Endpoint(s) / componente(s):**
+
+        | Método | Path | Header de tenant |
+        |--------|------|------------------|
+        #{scope_table.join("\n")}
+
+        **Red flags do contrato:**
+        #{red_flags.empty? ? "- Nenhum red flag automático detectado — revisão manual recomendada." : red_flags}
+      MD
+    end
+
+    def intro_text
+      title = analyzer.parser.title || "API"
+      has_tenant = analyzer.has_tenant_scoping?
+
+      text = "API **#{title}**"
+      text += " com escopo multi-tenant via header HTTP" if has_tenant
+      text += ", com filtragem por período e agregação analítica" if analyzer.has_date_range?
+      text += "."
+
+      text + "\n\nModelo **Defense in Depth** relevante porque parâmetros e headers são manipuláveis pelo cliente" \
+        + (analyzer.analytics_endpoint? ? " e endpoints disparam agregações pesadas downstream." : ".")
+    end
+
+    def api_section
+      api_vectors = vectors.select { |v| v.layer == :api }
+      return nil if api_vectors.empty?
+
+      grouped = api_vectors.group_by(&:category_title)
+      categories = grouped.map.with_index(1) do |(title, items), index|
+        "### #{index}. #{title}\n\n#{render_vectors(items)}"
+      end
+
+      "## PENTEST — #{api_layer}\n\n> Incluir apenas categorias aplicáveis ao input.\n\n#{categories.join("\n\n---\n\n")}"
+    end
+
+    def datalake_section
+      return nil unless datalake_in_scope?
+
+      dl_vectors = vectors.select { |v| v.layer == :datalake }
+      return nil if dl_vectors.empty?
+
+      grouped = dl_vectors.group_by(&:category_title)
+      categories = grouped.map.with_index(1) do |(title, items), index|
+        "### #{index}. #{title}\n\n#{render_vectors(items)}"
+      end
+
+      "## PENTEST — #{data_layer}\n\n> Incluir somente quando queries, IAM ou persistência estiverem no escopo.\n\n#{categories.join("\n\n---\n\n")}"
+    end
+
+    def render_vectors(items)
+      items.map do |vector|
+        procedure = vector.procedure.map.with_index(1) { |step, i| "#{i}. #{step}" }.join("\n")
+        <<~VECTOR.strip
+          #### #{vector.name}
+
+          - **Objetivo:** #{vector.objective}
+          - **Procedimento:**
+            #{procedure.gsub(/^/, "  ")}
+          - **Payload / exemplo:**
+            ```#{vector.payload_type}
+            #{vector.payload}
+            ```
+          - **Validação esperada:** #{vector.expected_validation}
+          - **Critério de falha:** #{vector.failure_criteria}
+          - **Risco:** #{vector.risk}
+        VECTOR
+      end.join("\n\n")
+    end
+
+    def summary_table
+      rows = SUMMARY_CATEGORIES.filter_map do |category, vector_ids|
+        match = vectors.find { |v| vector_ids.include?(v.id) }
+        next unless match
+
+        "| #{category} | #{match.name} | #{truncate(match.objective, 80)} |"
+      end
+
+      return nil if rows.empty?
+
+      <<~MD.strip
+        ## Tabela de Resumo para o Time
+
+        | Categoria | Vetor de Teste | Objetivo |
+        |-----------|----------------|----------|
+        #{rows.join("\n")}
+      MD
+    end
+
+    def recommendations
+      api_recs = []
+      dl_recs = []
+
+      if analyzer.tenant_headers.any? { |header| !header.required }
+        api_recs << "Tornar `#{analyzer.tenant_header_name}` obrigatório no OpenAPI (`required: true`) e aplicar early return na Controller."
+      end
+
+      if analyzer.timezone_headers.any?
+        api_recs << "Implementar whitelist IANA para header `#{analyzer.timezone_headers.first.name}`."
+      end
+
+      if analyzer.analytics_endpoint?
+        api_recs << "Implementar rate limiting (`rack-attack` ou equivalente) em endpoints analíticos."
+      end
+
+      if analyzer.has_date_range?
+        api_recs << "Limitar intervalo máximo de consulta (ex: 90 dias) para prevenir DoS lógico."
+      end
+
+      if analyzer.parser.security_schemes.empty?
+        api_recs << "Documentar `securitySchemes` no contrato OpenAPI e alinhar com autenticação em produção."
+      end
+
+      if datalake_in_scope?
+        dl_recs << 'Banir interpolação `#{variable}` em heredocs SQL; usar parametrização nativa GCP (`@tenant_id`).'
+        dl_recs << "Aplicar IAM mínimo — revogar acesso a `INFORMATION_SCHEMA` quando não necessário."
+        dl_recs << "Segregar Service Accounts por finalidade (API read-only vs. pipelines de escrita)."
+      end
+
+      return nil if api_recs.empty? && dl_recs.empty?
+
+      sections = ["## Recomendações Imediatas"]
+
+      unless api_recs.empty?
+        sections << "### #{api_layer}\n\n#{api_recs.map.with_index(1) { |r, i| "#{i}. #{r}" }.join("\n")}"
+      end
+
+      unless dl_recs.empty?
+        sections << "### #{data_layer}\n\n#{dl_recs.map.with_index(1) { |r, i| "#{i}. #{r}" }.join("\n")}"
+      end
+
+      sections.join("\n\n")
+    end
+
+    def datalake_sql_reference
+      return nil unless datalake_in_scope?
+
+      <<~MD.strip
+        ## Referência SQL
+
+        | Tipo de Teste | Exemplo | Objetivo |
+        |---------------|---------|----------|
+        | Exploração de Esquema | `SELECT * FROM information_schema.columns WHERE table_name = '...'` | Mapear metadados |
+        | Bypass de Tenant | `SELECT count(*) FROM ... WHERE tenant_id = 'X' OR '1'='1'` | Cross-tenant leak |
+        | Verificar Usuário | `SELECT current_user()` | Privilégios da SA |
+        | Ataque de Custo | `SELECT a.*, b.* FROM big_table a CROSS JOIN big_table b` | DoS financeiro |
+      MD
+    end
+
+    def assumptions
+      <<~MD.strip
+        ## Suposições
+
+        - Plano gerado automaticamente a partir do contrato OpenAPI; revisão humana de AppSec é obrigatória antes da execução.
+        - Payloads usam nomes extraídos do contrato; ajustar host, credenciais e IDs de tenant conforme ambiente de teste.
+        - Este documento **não** inclui scripts executáveis, resultados de teste nem RFCs de implementação.
+
+        ## Fora do escopo
+
+        - Execução dos testes e coleta de evidências
+        - Scripts Faraday/Ruby/SQL runnable
+        - RFCs de remediação pós-execução
+      MD
+    end
+
+    def datalake_in_scope?
+      analyzer.include_datalake || vectors.any? { |v| v.layer == :datalake }
+    end
+
+    def truncate(text, max_length, omission: "...")
+      return text if text.length <= max_length
+
+      "#{text[0, max_length - omission.length]}#{omission}"
+    end
+  end
+end

data/lib/security_pentest_planner/planner.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SecurityPentestPlanner
+  class Planner
+    DEFAULT_OPTIONS = {
+      team: nil,
+      scope: nil,
+      include_datalake: false,
+      api_layer: "API",
+      data_layer: "Data Lake"
+    }.freeze
+
+    def initialize(input_path: nil, spec: nil, **options)
+      @input_path = input_path
+      @spec = spec
+      @options = DEFAULT_OPTIONS.merge(options)
+    end
+
+    def call
+      parser = build_parser
+      analyzer = ContractAnalyzer.new(
+        parser,
+        scope_paths: options[:scope],
+        include_datalake: options[:include_datalake]
+      )
+
+      raise InputError, "Nenhum endpoint encontrado no escopo informado." if analyzer.scoped_endpoints.empty?
+
+      vectors = VectorCatalog.vectors_for(analyzer)
+      raise InputError, "Nenhum vetor aplicável encontrado para os sinais detectados." if vectors.empty?
+
+      PlanRenderer.new(
+        analyzer: analyzer,
+        vectors: vectors,
+        team: options[:team],
+        api_layer: options[:api_layer],
+        data_layer: options[:data_layer]
+      ).render
+    end
+
+    private
+
+    attr_reader :input_path, :spec, :options
+
+    def build_parser
+      return OpenAPIParser.new(spec, source_path: input_path) if spec
+
+      raise InputError, "input_path é obrigatório quando spec não é informado." unless input_path
+      raise InputError, "Arquivo não encontrado: #{input_path}" unless File.exist?(input_path)
+
+      OpenAPIParser.parse_file(input_path)
+    end
+  end
+end