Como resolver CAPTCHA do AWS WAF em Go com o SDK oficial

TL;DR

• O SDK oficial do Go pode submeter uma AntiAwsWafTask documentada e retornar um resultado de CAPTCHA do AWS WAF.
• Esta tarefa usa uma URL de página proprietária e um proxy; os campos de desafio opcionais devem seguir a documentação atual da tarefa.
• Defina o host da API do SDK como HTTPS explicitamente na versão usada aqui e aplique um tempo limite de solicitação HTTP.
• Leia o resultado por meio de result.Solution.Cookie após verificar erros, prontidão e uma solução não vazia.
• Testes de fixture HTTP local verificaram o comportamento de solicitação e resposta do exemplo; uma solução e aceitação de aplicação do AWS WAF em tempo real não foram testadas.

Uma integração de CAPTCHA do AWS WAF em Go tem duas responsabilidades separadas: solicitar ao solucionador o resultado documentado e usá-lo corretamente na aplicação sendo testada. O SDK oficial lida com a troca de API, mas não pode decidir se sua aplicação aceitou a tentativa concluída.

Este tutorial usa o CapSolver para uma página de teste do AWS WAF proprietária. Ele se concentra na instalação do módulo Go, na construção da tarefa, no tratamento do cookie retornado e na compreensão do comportamento de transporte do SDK. O percurso não pressupõe que um token aceito em um domínio se aplique a outro.

O que o SDK do Go lida?

O SDK do Go encapsula a criação da tarefa e a recuperação do resultado atrás do método Solve. Uma biblioteca de API empacota essas chamadas em métodos de nível de linguagem, mas você ainda precisa dos parâmetros corretos da tarefa e da lógica da aplicação.

A documentação oficial da tarefa do AWS WAF descreve AntiAwsWafTask e seu resultado solution.cookie. O SDK do Go expõe a resposta como um CapSolverResponse contendo um ponteiro Solution. Essa distinção importa: Solve não retorna diretamente a string do cookie.

Para este tutorial, a sequência desejada é:

1. Abra uma página de teste proprietária e identifique o contexto do desafio do AWS WAF.
2. Forneça essa URL da página, o proxy necessário e uma chave de API de resolução.
3. Chame o SDK e verifique a resposta retornada.
4. Passe o valor do cookie para o mesmo teste de aplicação autorizado.
5. Afirme o resultado real da aplicação.

A AWS descreve seus tokens como parte de mitigação de ameaças inteligentes do AWS WAF. Trate o resultado como um valor associado a uma tentativa específica, não como uma permissão permanente para acessar uma aplicação.

Etapa 1: Instalar o módulo oficial do Go

Crie um pequeno módulo do Go e fixe a versão do SDK usada para este exemplo. O pacote é publicado no repositório oficial do CapSolver do Go.

mkdir capsolver-aws-waf-example
cd capsolver-aws-waf-example
go mod init capsolver-aws-waf-example
go get github.com/capsolver/capsolver-go@v0.0.0-20251204081438-e4e07af23eae

O exemplo foi compilado e seus testes locais executados com o Go 1.27.1. A versão longa é uma pseudo-versão do Go identificando um commit específico. Fixá-la torna a fonte do SDK reproduzível; não é uma recomendação para ignorar correções futuras.

Mantenha os arquivos go.mod e go.sum gerados com o exemplo. A documentação padrão de gerenciamento de dependências do Go explica esses arquivos e a seleção de versão. Ao atualizar o SDK, execute novamente os testes que cobrem os campos de solicitação e o tratamento da resposta.

Esta instalação prepara a biblioteca do cliente. Não provisiona uma página de teste do AWS WAF, compra crédito do solucionador ou configura um proxy. Esses são pré-requisitos separados para uma solução real.

Etapa 2: Preparar as três configurações necessárias

O exemplo lê uma URL de página proprietária, uma string de proxy e uma chave de API de resolução de variáveis de ambiente.

Esses nomes de variáveis pertencem ao exemplo; não são campos adicionais da tarefa da API. O código do Go os mapeia para websiteURL, proxy e ApiKey do cliente do SDK.

Use seu gerenciador de segredos normal ou ambiente de desenvolvimento para fornecer credenciais. Não cole uma chave real em código comprometido e não substitua uma credencial de gerenciamento de conteúdo pela chave de resolução. As credenciais do proxy devem receber a mesma atenção.

Escolha a URL específica que produz o desafio. Uma homepage genérica pode não fornecer o contexto necessário para um teste de rota diferente. Mantenha a sessão da aplicação e a configuração de rede consistente com o design do teste em vez de tratar o resultado do solucionador como desconectado da solicitação que o necessita.

Etapa 3: Definir HTTPS e enviar a tarefa

Salve o seguinte código como main.go. Seu mapa de tarefa e chamada Solve seguem o SDK oficial e exemplos de tarefa. As verificações de ambiente, atribuição explícita do host HTTPS, timeout e verificações de cookie pronto são adições para este pequeno programa. As fixtures HTTP locais exerceram o SDK; uma solução em tempo real requer sua chave de resolução, proxy e página proprietária e não foi realizada.

package main

import (
    "errors"
    "fmt"
    "log"
    "net/http"
    "os"
    "time"

    capsolver_go "github.com/capsolver/capsolver-go"
)

func solveAWS(pageURL, proxy, key string) (*capsolver_go.CapSolverResponse, error) {
    if pageURL == "" || proxy == "" || key == "" {
        return nil, errors.New("defina OWNED_WAF_URL, CAPSOLVER_PROXY e CAPSOLVER_API_KEY")
    }
    client := capsolver_go.CapSolver{ApiKey: key}
    result, err := client.Solve(map[string]any{
        "type": "AntiAwsWafTask",
        "websiteURL": pageURL,
        "proxy": proxy,
    })
    if err != nil {
        return nil, err
    }
    if result == nil || result.Status != "ready" ||
        result.Solution == nil || result.Solution.Cookie == "" {
        return nil, errors.New("nenhum resultado de cookie AWS WAF pronto")
    }
    return result, nil
}

func main() {
    capsolver_go.ApiHost = "https://api.capsolver.com"
    http.DefaultClient.Timeout = 20 * time.Second
    result, err := solveAWS(
        os.Getenv("OWNED_WAF_URL"),
        os.Getenv("CAPSOLVER_PROXY"),
        os.Getenv("CAPSOLVER_API_KEY"),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Status do resultado AWS WAF:", result.Status)
    // result.Solution.Cookie pertence a esta tentativa de teste autorizada.
}

No código do SDK fixado, o host padrão volta para uma URL HTTP. A atribuição explícita para capsolver_go.ApiHost seleciona https://api.capsolver.com antes que a solicitação envie sua credencial de resolução.

O SDK usa o cliente HTTP padrão do Go. Definir http.DefaultClient.Timeout aplica um tempo limite de solicitação para este exemplo autônomo. Também altera esse cliente process-wide: se você integrar o SDK em um aplicativo maior, revise o efeito em outros usuários do cliente padrão.

O valor de 20 segundos é uma configuração de exemplo, não uma garantia de conclusão do serviço ou um prazo para toda a tarefa. O SDK pode fazer várias solicitações HTTP enquanto recupera um resultado. Cada solicitação com um tempo limite não torna a chamada completa Solve uma operação de 20 segundos.

A documentação do Go net/http descreve o comportamento de tempo limite do cliente. O wrapper não expõe um parâmetro baseado em contexto porque o método do SDK mostrado aqui não aceita um.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Etapa 4: Executar o programa e inspecionar o resultado

Execute o programa após fornecer as três configurações de ambiente. Este comando em tempo real ainda precisa de validação com sua página proprietária; os testes registrados usaram uma fixture HTTP local:

go run .

Quando o SDK retorna uma resposta pronta com um cookie não vazio, o programa imprime o status da resposta. Ele não imprime intencionalmente o cookie em si. O valor está disponível em result.Solution.Cookie para a parte do seu teste proprietário que continua o fluxo da aplicação.

Há três verificações distintas em solveAWS. Um erro do Go falha a chamada. Uma resposta ausente ou não pronta falha na verificação de prontidão do wrapper. Um solução nula ou cookie vazio falha na verificação do conteúdo da resposta. Isso evita que o código chamador continue apenas porque um ponteiro foi retornado.

Uma impressão de status não é uma afirmação de sucesso da aplicação. Adicione a verificação final no seu executor de testes após usá-lo na sessão apropriada. Se a página ainda apresentar um desafio, mantenha a fase observada e as informações de erro do provedor relevante em vez de tratar o status impresso como prova de que a página aceitou a tentativa.

O exemplo não implementa um jar de cookies HTTP ou uma camada de automação de navegador. Esses dependem de como sua aplicação cria e mantém sua sessão de teste. Evite adicionar um domínio de cookie adivinhado ou um cabeçalho global que aplique o valor a solicitações não relacionadas.

Quando os campos opcionais do AWS WAF são necessários?

Campos opcionais são relevantes quando o contexto do desafio real e a documentação da tarefa atual os exigem. O guia da tarefa do AWS WAF inclui campos como awsKey, awsIv, awsContext e awsChallengeJS para situações documentadas.

Comece com a solicitação que corresponda à sua página e ao tipo de tarefa suportado. Se o serviço relatar que o contexto necessário está faltando, inspecione o desafio atual na página proprietária e siga a documentação correspondente. Não insira valores de substituição em todos os campos opcionais apenas para que o JSON pareça completo.

Os dados do desafio devem pertencer à tentativa atual. Misturar uma URL de página de um teste com parâmetros de desafio salvos de outra página ou tempo torna a solicitação mais difícil de compreender. Uma solicitação pode ser sintaticamente válida enquanto seus inputs descrevem contextos incompatíveis.

O guia mais amplo sobre CAPTCHA do AWS WAF explica a família de tarefas. Este exemplo do Go adiciona o tratamento específico da linguagem da envelope de resposta e comportamento HTTP; não muda as informações de desafio necessárias.

Como a aplicação deve usar o cookie retornado?

A aplicação deve usar o resultado apenas no contexto de teste autorizado para o qual foi obtido. A AWS documenta domínios de token e listas de domínios, que influenciam onde um token pode ser aceito.

Para um teste de integração proprietário, registre o host de destino e a tentativa associada ao resultado. Deixe o cliente ou camada de navegador específico da aplicação gerenciar seu escopo de cookie pretendido. Não assuma que a string retornada deve ser copiada para todos os hosts que um crawler ou agente visita.

Uma verificação de aceitação útil responde a duas perguntas: o provedor retornou a forma esperada do resultado e a aplicação aceitou a operação subsequente? Mantenha ambos os resultados. Se o primeiro for bem-sucedido e o segundo falhar, investigue domínio, sessão, tempo e a resposta da aplicação em vez de rotular cada rejeição como falha de transporte do SDK.

O SDK não implementa políticas de acesso do AWS ou altera seu ACL da web. Sua configuração do WAF ainda controla o tratamento das solicitações.

O que os testes locais verificaram?

O exemplo foi executado contra uma fixture HTTP local usando o SDK real fixado. Os testes verificaram o mapa de tarefa de saída, uma resposta pronta direta, uma resposta de criação e verificação, erros do provedor, JSON malformado, cookies ausentes e configurações ausentes.

Essa superfície de testes é mais estreita que uma solução em tempo real. A fixture forneceu seu próprio valor de cookie, e nenhuma página real do AWS WAF aceitou. Os testes estabelecem que o wrapper do Go interage com o SDK instalado e trata essas formas de resposta. Eles não estabelecem compatibilidade com o serviço em tempo real ou taxa de sucesso de solução.

Um detalhe de origem merece atenção ao estender o cliente: o SDK fixado serializa sua credencial usando ClientKey, enquanto os exemplos REST mostram clientKey. A fixture local registra o que o SDK realmente envia; não prova qual formatação um endpoint em tempo real aceita. Mantenha essa distinção visível ao diagnosticar uma solicitação real e consulte o suporte upstream antes de alterar internos do SDK.

Para uma primeira verificação em tempo real, use uma única página proprietária representativa, uma chave de resolução válida e a configuração de proxy documentada. Verifique o cookie retornado e o resultado final da aplicação. Tente o CapSolver para essa verificação específica antes de expandir a integração para páginas adicionais.

Perguntas frequentes

Q: Qual é o caminho de importação correto do Go?

Use github.com/capsolver/capsolver-go. Este exemplo o atribui ao alias local capsolver_go e fixa a versão da dependência mostrada no comando de instalação.

Q: O Solve retorna diretamente o cookie do AWS WAF?

Não. Ele retorna um envelope de resposta. Após verificar o erro, o status da resposta e a solução, acesse o cookie por meio de result.Solution.Cookie.

Q: Por que definir o host da API explicitamente?

O código do SDK fixado tem um host de fallback HTTP. O exemplo seleciona o endpoint da API HTTPS antes de enviar as credenciais. Verifique esse comportamento novamente ao alterar as versões da dependência.

Q: O timeout HTTP é um prazo para a solução completa?

Não. O SDK pode emitir várias solicitações enquanto recupera o resultado. Um timeout por solicitação não impõe o mesmo limite na operação inteira ou estabelece cancelamento remoto.

Q: Foi testado contra uma página real do AWS WAF?

Não. O código Go foi executado contra fixtures HTTP locais com o SDK real. Uma chave de resolução em tempo real e uma página de teste do AWS WAF proprietária ainda são necessárias para validar o comportamento do serviço e a aceitação da aplicação.