security_pentest_planner 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bcc45ece1c0bd69559144e7fe445ccf7d6b5ebef75ead44a5c154a466bdc9a96
+  data.tar.gz: 2e697b751eba0431ed172b985700e1d38289f5755212dbc4db240536cf4a805a
+SHA512:
+  metadata.gz: 9508039a75d5287b49f5c9f9c73d2136e848d8e03d2b3cb41fb698c43474eecc67ff796dc901be0695291346f949ad209dd41b67e79eec3e19434c144dc09dda
+  data.tar.gz: 7dfadfcb457ce8177642f56bf48222b6d3f92f9ff859ce0f2d7f5c1735747e7afa87564b8cca2f390588a603b8a00646149717aec45ef83e9e37c0997dcc1e5e

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## [1.0.1] - 2026-07-07
+
+### Fixed
+
+- YAML parser no longer references unresolved `Date`/`Time` constants inside `OpenAPIParser`, fixing CI on Ruby 3.1–3.3
+
+## [1.0.0] - 2026-06-26
+
+### Added
+
+- Parser OpenAPI 3.x (YAML/JSON)
+- Analisador de contrato com detecção de red flags
+- Catálogo de vetores OWASP API Security e Data Lake
+- Renderizador de Plano de Ação em Markdown
+- CLI `security-pentest-planner`
+- API programática `SecurityPentestPlanner.generate`
+
+## [Unreleased]
+
+### Changed
+
+- Repositório movido para projeto pessoal open source
+- Removidas referências corporativas e exemplos específicos de produto interno
+- Defaults genéricos para camadas API (`API` em vez de nome de produto)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saulo Filho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,121 @@
+# security_pentest_planner
+
+[![Gem Version](https://badge.fury.io/rb/security_pentest_planner.svg)](https://badge.fury.io/rb/security_pentest_planner)
+
+**Site:** [saulofilho.github.io/security-pentest-planner](https://saulofilho.github.io/security-pentest-planner/)
+
+Gera **Planos de Ação de Pentest** a partir de especificações OpenAPI/Swagger.
+
+Ferramenta open source para times de engenharia e AppSec que precisam estruturar testes ofensivos **antes** da execução — com vetores OWASP, procedimentos, payloads e critérios de validação.
+
+## O que ela faz
+
+- Analisa contratos **OpenAPI 3.x** (YAML ou JSON)
+- Detecta sinais de risco: tenant headers, parâmetros de data, enums, timezone livre
+- Seleciona vetores OWASP API Security aplicáveis via taxonomia
+- Gera um **design doc** em Markdown com:
+  - Procedimentos passo a passo por vetor
+  - Payloads e exemplos HTTP/SQL
+  - Tabela resumo (Acesso · Entrada · Disponibilidade · Informação)
+  - Recomendações imediatas de remediação
+  - Red flags do contrato
+
+## O que ela NÃO faz
+
+- Scripts executáveis (Faraday, Ruby, SQL runnable)
+- Resultados de teste (APROVADO/REPROVADO)
+- RFCs de implementação
+
+Esses artefatos pertencem à **fase de execução** do pentest.
+
+## Instalação
+
+```bash
+gem install security_pentest_planner
+```
+
+Ou no `Gemfile`:
+
+```ruby
+gem "security_pentest_planner"
+```
+
+## Uso via CLI
+
+```bash
+# Gerar plano no stdout
+security-pentest-planner swagger/v2/swagger.json
+
+# Salvar em arquivo
+security-pentest-planner openapi.yaml -o plano-de-acao-pentest.md
+
+# Com escopo e Data Lake
+security-pentest-planner openapi.yaml \
+  --team "Platform Team" \
+  --scope /api/v1/metrics \
+  --datalake \
+  -o plano.md
+```
+
+### Opções
+
+| Flag | Descrição |
+|------|-----------|
+| `-t, --team TEAM` | Nome do time no título |
+| `-s, --scope PATH` | Limitar a um endpoint |
+| `-d, --datalake` | Incluir vetores de Data Lake |
+| `--api-layer NAME` | Nome da camada API (default: API) |
+| `--data-layer NAME` | Nome da camada Data Lake (default: Data Lake) |
+| `-o, --output FILE` | Salvar em arquivo |
+
+## Uso programático
+
+```ruby
+require "security_pentest_planner"
+
+plan = SecurityPentestPlanner.generate(
+  input_path: "openapi.yaml",
+  team: "Platform Team",
+  scope: "/api/v1/metrics",
+  include_datalake: true
+)
+
+File.write("plano-de-acao-pentest.md", plan)
+```
+
+## Publicar no RubyGems.org
+
+```bash
+bundle install
+bundle exec rspec
+gem build security_pentest_planner.gemspec
+gem push security_pentest_planner-1.0.0.gem
+```
+
+> Requer conta no [RubyGems.org](https://rubygems.org) e MFA habilitado.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/saulofilho/security-pentest-planner.git
+cd security-pentest-planner
+bundle install
+bundle exec rspec
+bundle exec rake
+```
+
+## Fluxo recomendado
+
+```
+OpenAPI spec  →  security_pentest_planner  →  Plano de Ação (Markdown)
+                                                      ↓
+                                              Execução manual / CI
+                                                      ↓
+                                              Resultados + RFCs
+```
+
+A gem cobre a fase de **planejamento** de forma determinística — ideal para CI/CD, pipelines e integração em projetos Ruby/Rails.
+
+## Licença
+
+MIT — veja [LICENSE.txt](LICENSE.txt).

data/exe/security-pentest-planner

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "security_pentest_planner/cli"
+
+SecurityPentestPlanner::CLI.run

data/lib/security_pentest_planner/cli.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../security_pentest_planner"
+
+module SecurityPentestPlanner
+  class CLI
+    def self.run(argv = ARGV)
+      new.run(argv)
+    end
+
+    def run(argv)
+      options = default_options
+      parser = build_option_parser(options)
+      parser.parse!(argv)
+
+      input = argv.first
+      abort parser.help if input.nil?
+
+      plan = SecurityPentestPlanner.generate(
+        input_path: input,
+        **options
+      )
+
+      if options[:output]
+        File.write(options[:output], plan)
+        warn "Plano de Ação gerado em #{options[:output]}"
+      else
+        puts plan
+      end
+    rescue Error => e
+      warn "Erro: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def default_options
+      {
+        team: nil,
+        scope: nil,
+        include_datalake: false,
+        api_layer: "API",
+        data_layer: "Data Lake",
+        output: nil
+      }
+    end
+
+    def build_option_parser(options)
+      OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          Usage: security-pentest-planner [options] <openapi.yaml>
+
+          Gera um Plano de Ação de Pentest a partir de especificação OpenAPI.
+
+        BANNER
+
+        opts.on("-t", "--team TEAM", "Nome do time no título do documento") do |team|
+          options[:team] = team
+        end
+
+        opts.on("-s", "--scope PATH", "Limitar escopo a um path (ex: /api/v1/metrics)") do |scope|
+          options[:scope] = scope
+        end
+
+        opts.on("-d", "--datalake", "Incluir vetores de Data Lake no plano") do
+          options[:include_datalake] = true
+        end
+
+        opts.on("--api-layer NAME", "Nome da camada de API no documento") do |name|
+          options[:api_layer] = name
+        end
+
+        opts.on("--data-layer NAME", "Nome da camada de Data Lake no documento") do |name|
+          options[:data_layer] = name
+        end
+
+        opts.on("-o", "--output FILE", "Salvar plano em arquivo (default: stdout)") do |file|
+          options[:output] = file
+        end
+
+        opts.on("-v", "--version", "Exibe a versão") do
+          puts "security_pentest_planner #{SecurityPentestPlanner::VERSION}"
+          exit
+        end
+
+        opts.on("-h", "--help", "Exibe esta ajuda") do
+          puts opts
+          exit
+        end
+      end
+    end
+  end
+end
+
+SecurityPentestPlanner::CLI.run if $PROGRAM_NAME == __FILE__

data/lib/security_pentest_planner/contract_analyzer.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SecurityPentestPlanner
+  class ContractAnalyzer
+    RedFlag = Struct.new(:message, :severity, keyword_init: true)
+
+    attr_reader :parser, :scope_paths, :include_datalake
+
+    def initialize(parser, scope_paths: nil, include_datalake: false)
+      @parser = parser
+      @scope_paths = scope_paths
+      @include_datalake = include_datalake
+    end
+
+    def scoped_endpoints
+      endpoints = parser.endpoints
+      return endpoints if scope_paths.nil? || scope_paths.empty?
+
+      paths = Array(scope_paths)
+      endpoints.select { |ep| paths.any? { |p| ep.path == p || ep.path.start_with?(p) } }
+    end
+
+    def tenant_headers
+      scoped_endpoints.flat_map { |ep| parameters_for(ep).select(&:tenant_header?) }
+                      .uniq { |p| p.name }
+    end
+
+    def date_params
+      scoped_endpoints.flat_map { |ep| parameters_for(ep).select(&:date_param?) }
+                      .uniq { |p| p.name }
+    end
+
+    def enum_params
+      scoped_endpoints.flat_map { |ep| parameters_for(ep).select(&:enum_param?) }
+                      .uniq { |p| p.name }
+    end
+
+    def timezone_headers
+      scoped_endpoints.flat_map { |ep| parameters_for(ep).select(&:timezone_header?) }
+                      .uniq { |p| p.name }
+    end
+
+    def has_tenant_scoping?
+      tenant_headers.any?
+    end
+
+    def has_date_range?
+      date_params.any?
+    end
+
+    def has_enum_params?
+      enum_params.any?
+    end
+
+    def has_free_text_headers?
+      timezone_headers.any? || tenant_headers.any? { |h| !h.enum_values.any? }
+    end
+
+    def analytics_endpoint?
+      scoped_endpoints.any? do |ep|
+        ep.path.match?(/metric|analytic|report|channel|insight|dashboard|aggregate/i) ||
+          ep.summary.to_s.match?(/metric|analytic|report|aggregate/i)
+      end
+    end
+
+    def red_flags
+      flags = []
+
+      if parser.security_schemes.empty? && scoped_endpoints.any?
+        flags << RedFlag.new(
+          message: "Ausência de `securitySchemes` documentado no contrato OpenAPI",
+          severity: :high
+        )
+      end
+
+      tenant_headers.each do |header|
+        next if header.required
+
+        flags << RedFlag.new(
+          message: "Header `#{header.name}` documentado como opcional (`required: false`)",
+          severity: :high
+        )
+      end
+
+      if tenant_headers.map(&:name).uniq.size > 1
+        flags << RedFlag.new(
+          message: "Divergência de nomes de header de tenant: #{tenant_headers.map(&:name).uniq.join(' vs ')}",
+          severity: :medium
+        )
+      end
+
+      timezone_headers.each do |header|
+        next if header.enum_values.any?
+
+        flags << RedFlag.new(
+          message: "Header `#{header.name}` como string livre (sem enum/whitelist IANA)",
+          severity: :medium
+        )
+      end
+
+      if analytics_endpoint?
+        flags << RedFlag.new(
+          message: "Nenhum rate limiting documentado em endpoint analítico",
+          severity: :medium
+        )
+      end
+
+      flags
+    end
+
+    def signals
+      {
+        tenant_scoping: has_tenant_scoping?,
+        date_range: has_date_range?,
+        enum_params: has_enum_params?,
+        free_text_headers: has_free_text_headers?,
+        analytics: analytics_endpoint?,
+        datalake: include_datalake
+      }
+    end
+
+    def primary_endpoint
+      scoped_endpoints.first
+    end
+
+    def host
+      parser.servers.first || "api.example.com"
+    end
+
+    def tenant_header_name
+      tenant_headers.first&.name || "X-Tenant-ID"
+    end
+
+    def date_param_names
+      date_params.map(&:name)
+    end
+
+    def enum_param
+      enum_params.first
+    end
+
+    private
+
+    def parameters_for(endpoint)
+      parser.parameters_for(endpoint)
+    end
+  end
+end

data/lib/security_pentest_planner/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SecurityPentestPlanner
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class InputError < Error; end
+end

data/lib/security_pentest_planner/openapi_parser.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module SecurityPentestPlanner
+  class OpenAPIParser
+    TENANT_HEADER_PATTERN = /tenant/i
+    DATE_PARAM_PATTERN = /date|start|end|from|to|period|range/i
+    TIMEZONE_HEADER_PATTERN = /timezone|time_zone|tz/i
+
+    Endpoint = Struct.new(
+      :path,
+      :method,
+      :operation_id,
+      :summary,
+      :parameters,
+      :security,
+      keyword_init: true
+    )
+
+    Parameter = Struct.new(
+      :name,
+      :location,
+      :required,
+      :schema,
+      :description,
+      keyword_init: true
+    ) do
+      def enum_values
+        schema&.dig("enum") || schema&.dig("items", "enum") || []
+      end
+
+      def type
+        schema&.dig("type")
+      end
+
+      def tenant_header?
+        location == "header" && name.match?(TENANT_HEADER_PATTERN)
+      end
+
+      def date_param?
+        location == "query" && name.match?(DATE_PARAM_PATTERN)
+      end
+
+      def timezone_header?
+        location == "header" && name.match?(TIMEZONE_HEADER_PATTERN)
+      end
+
+      def enum_param?
+        enum_values.any? || schema&.dig("items", "enum")&.any?
+      end
+    end
+
+    attr_reader :raw, :source_path
+
+    def initialize(content, source_path: nil)
+      @raw = content
+      @source_path = source_path
+    end
+
+    def self.parse_file(path)
+      content = File.read(path)
+      parsed = case File.extname(path).downcase
+               when ".yaml", ".yml" then YAML.safe_load(content, aliases: true)
+               when ".json" then JSON.parse(content)
+               else
+                 raise ParseError, "Unsupported file extension: #{path}. Use .yaml, .yml or .json"
+               end
+      new(parsed, source_path: path)
+    end
+
+    def title
+      info["title"]
+    end
+
+    def version
+      info["version"]
+    end
+
+    def servers
+      Array(raw["servers"]).map { |s| s["url"] }.compact
+    end
+
+    def security_schemes
+      raw.dig("components", "securitySchemes") || {}
+    end
+
+    def endpoints
+      @endpoints ||= build_endpoints
+    end
+
+    def parameters_for(endpoint)
+      global = Array(raw.dig("paths", endpoint.path, "parameters"))
+      local = Array(endpoint.parameters)
+      merge_parameters(global + local)
+    end
+
+    private
+
+    def info
+      raw["info"] || {}
+    end
+
+    def build_endpoints
+      paths = raw["paths"] || {}
+      paths.flat_map do |path, methods|
+        methods.filter_map do |method, operation|
+          next unless operation.is_a?(Hash)
+          next unless %w[get post put patch delete head options].include?(method)
+
+          Endpoint.new(
+            path: path,
+            method: method.upcase,
+            operation_id: operation["operationId"],
+            summary: operation["summary"] || operation["description"],
+            parameters: Array(operation["parameters"]).map { |p| build_parameter(p) },
+            security: operation["security"]
+          )
+        end
+      end
+    end
+
+    def build_parameter(param)
+      resolved = resolve_ref(param)
+      Parameter.new(
+        name: resolved["name"],
+        location: resolved["in"],
+        required: resolved["required"] == true,
+        schema: resolved["schema"] || {},
+        description: resolved["description"]
+      )
+    end
+
+    def resolve_ref(obj)
+      return obj unless obj.is_a?(Hash) && obj["$ref"]
+
+      ref = obj["$ref"]
+      parts = ref.split("/")
+      parts.reduce(raw) { |node, key| node[key] }
+    end
+
+    def merge_parameters(params)
+      params
+        .map { |p| p.is_a?(Parameter) ? p : build_parameter(p) }
+        .uniq { |p| [p.location, p.name] }
+    end
+  end
+end