Martian Proxy

Martian Proxy é um proxy HTTP programável projetado para ser usado em testes.

Martian é uma ótima ferramenta para usar se você quiser:

• Verificar se todas (ou um subconjunto) das requisições são seguras
• Simular (mock) serviços externos na camada de rede
• Injetar cabeçalhos, modificar cookies ou realizar outras mutações em requisições e respostas HTTP
• Verificar se os pingbacks ocorrem quando você espera que ocorram
• Desembrulhar tráfego criptografado (requer instalação do certificado CA no navegador)

Aproveitando a compilação cruzada do Go, o Martian pode ser implantado em qualquer lugar que o Go possa segmentar.

Última Versão

v3.0.0

Requisitos

Go 1.11

Suporte a Go Modules

O Martian Proxy adicionou suporte a Go Modules desde a v3.0.0. Se você usa uma versão do Go que não suporta módulos, isso vai quebrar. A última versão sem suporte a Go Modules foi a v2.1.0.

Primeiros Passos

Instalação

O Martian Proxy pode ser instalado usando go install

go get github.com/google/martian/ && \
go install github.com/google/martian/cmd/proxy

Iniciar o Proxy

Supondo que você tenha instalado o Martian, executar o proxy é tão simples quanto

$GOPATH/bin/proxy

Se você quiser ver logs do sistema enquanto o Martian está em execução, passe a flag de verbosidade:

$GOPATH/bin/proxy -v=2

Por padrão, o Martian será executado na porta 8080, e a API do Martian será executada na 8181. A porta pode ser especificada via flags:

$GOPATH/bin/proxy -addr=:9999 -api-addr=:9898

Registro (Logging)

Para registro de requisições e respostas, um modifier de logging está disponível ou logs HAR estão disponíveis se a flag -har for usada.

Registro HAR

Para habilitar o registro HAR no Martian, chame o binário com a flag -har:

$GOPATH/bin/proxy -har

Se a flag -har foi habilitada, dois endpoints relacionados a HAR estarão disponíveis:

GET http://martian.proxy/logs

Irá recuperar o log HAR de todas as requisições e respostas vistas pelo proxy desde o último reset.

DELETE http://martian.proxy/logs/reset

Irá redefinir o log HAR em memória. Observe que o log crescerá indefinidamente a menos que seja reiniciado periodicamente.

Configurar

Uma vez que o Martian está em execução, você precisa configurar seu comportamento. Sem configuração, o Martian apenas faz proxy sem fazer nada nas requisições ou respostas. Se habilitado, o registro ocorrerá sem configuração adicional.

O Martian é configurado por mensagens JSON enviadas via HTTP que assumem a forma geral de:

{
  "header.Modifier": {
    "scope": ["response"],
    "name": "Test-Header",
    "value": "true"
  }
}

A configuração acima diz ao Martian para injetar um cabeçalho com o nome "Test-Header" e o valor "true" em todas as respostas.

Vamos detalhar as partes desta mensagem.

• [package.Type]: O package.Type do modificador que você deseja usar. Neste caso, é "header.Modifier", que é o nome do modificador que define cabeçalhos (para saber mais sobre o header.Modifier, consulte a referência de modificadores).
• [package.Type].scope: Indica se deve aplicar o modificador a requisições, respostas ou ambos. Pode ser um array contendo "request", "response" ou ambos.
• [package.Type].[key]: Dados específicos do modificador. No caso do modificador de cabeçalho, precisamos do name e value do cabeçalho.

Esta é uma configuração simples, para configurações mais complexas, modificadores são combinados com grupos e filtros para compor o comportamento desejado.

Para configurar o Martian, faça um POST do JSON para http://martian.proxy/modifiers. Você vai querer usar o mecanismo que sua linguagem de escolha fornece para fazer requisições HTTP, mas para fins de demonstração, curl funciona (assumindo que sua configuração está em um arquivo chamado modifier.json).

    curl -x localhost:8080 \
         -X POST \
         -H "Content-Type: application/json" \
         -d @modifier.json \
            "http://martian.proxy/configure"

Interceptando Requisições e Respostas HTTPS

O Martian suporta modificar requisições e respostas HTTPS se configurado para isso.

Para que o Martian intercepte tráfego HTTPS, um certificado CA personalizado deve ser instalado no navegador para que avisos de conexão não sejam exibidos.

A maneira mais fácil de instalar o certificado CA é iniciar o proxy com as flags necessárias para usar um certificado CA personalizado e chave privada usando as flags -cert e -key, ou fazer o proxy gerar um usando a flag -generate-ca-cert.

Após o proxy ter iniciado, visite http://martian.proxy/authority.cer no navegador configurado para usar o proxy e um prompt será exibido para instalar o certificado.

Várias flags estão disponíveis em examples/main.go para ajudar a configurar a funcionalidade MITM:

-key=""
  Arquivo de chave privada codificada em PEM do certificado CA fornecido em -cert; usado
  para assinar certificados que são gerados dinamicamente
-cert=""
  Arquivo de certificado CA codificado em PEM usado para gerar certificados
-generate-ca-cert=false
  Gera um certificado CA e chave privada para usar em man-in-the-middle;
  a maioria dos usuários que escolherem esta opção visitará imediatamente
  http://martian.proxy/authority.cer no navegador cujo tráfego será interceptado
  para instalar o certificado CA recém-gerado
-organization="Martian Proxy"
  Nome da organização definido nos certificados gerados dinamicamente durante
  o man-in-the-middle
-validity="1h"
  Janela de tempo ao redor do momento da requisição em que o certificado gerado
  dinamicamente é válido; a duração é definida de forma que o período total válido
  seja o dobro do valor de validade (1h antes & 1h depois)

Verificar Verificadores

Vamos supor que você configurou o Martian para verificar a presença de um cabeçalho específico em respostas para uma URL específica.

Aqui está uma configuração para verificar se todas as requisições para example.com retornam respostas com 200 OK.

      {
        "url.Filter": {
          "scope": ["request", "response"],
          "host" : "example.com",
          "modifier" : {
            "status.Verifier": {
              "scope" : ["response"],
              "statusCode": 200
            }
          }
        }
      }

Uma vez que o Martian está em execução, configurado e as requisições e respostas resultantes que você deseja verificar ocorreram, você pode verificar sua expectativa de que recebeu apenas respostas 200 OK.

Para verificar as verificações, execute

GET http://martian.proxy/verify

As expectativas falhas são rastreadas como erros, e a lista de erros é recuperada fazendo uma requisição GET para host:port/martian/verify, que retornará uma lista de erros:

  {
      "errors" : [
          {
              "message": "response(http://example.com) status code verify failure: got 500, want 200"
          },
          {
              "message": "response(http://example.com/foo) status code verify failure: got 500, want 200"
          }
      ]
  }

Os erros de verificação são mantidos em memória até que sejam explicitamente limpos por

POST http://martian.proxy/verify/reset

Martian como Biblioteca

O Martian também pode ser incluído em qualquer programa Go e usado como biblioteca.