Ladder

Ladder é um proxy web HTTP.

简体中文

O Ladder é uma ferramenta de desenvolvimento para testar e analisar implementações de paywall e o comportamento de entrega de conteúdo em sites modernos.

Ele permite que desenvolvedores, pesquisadores e editores simulem diferentes ambientes de cliente (como navegadores e rastreadores) e observem como o conteúdo é servido em condições variadas. Isso o torna útil para depurar configurações de paywall, verificar controles de acesso, cabeçalhos HTTP e garantir um comportamento consistente entre diferentes user agents.

O Ladder destina-se exclusivamente a fins legítimos de teste, pesquisa e garantia de qualidade. Ele deve ser usado apenas em conformidade com as leis aplicáveis e os termos de serviço do site alvo.

Como funciona

sequenceDiagram
    client->>+ladder: GET
    ladder-->>ladder: apply RequestModifications
    ladder->>+website: GET
    website->>-ladder: 200 OK
    ladder-->>ladder: apply ResultModifications
    ladder->>-client: 200 OK

Recursos

• Remove/modifica cabeçalhos CORS de respostas, assets e imagens ...
• Remove/modifica outros cabeçalhos (ex.: Content-Security-Policy)
• Remove/injeta código personalizado (HTML, CSS, JavaScript) na página
• Aplica ruleset/código baseado em domínio para modificar a resposta ou a URL solicitada
• Mantém o site navegável
• API
• Buscar HTML cru (RAW)
• User Agent personalizado
• IP X-Forwarded-For personalizado
• Contêiner Docker (amd64, arm64)
• Binário Linux
• Binário Mac OS
• Binário Windows (não testado)
• Basic Auth
• Registros de acesso

Limitações

Alguns sites entregam conteúdos diferentes (Cloaking) dependendo do tipo de cliente que os acessa (por exemplo, rastreadores de mecanismos de busca versus navegadores web padrão). O Ladder pode ser configurado para emular diferentes tipos de cliente, a fim de recuperar conteúdo publicamente acessível para fins de teste, automação ou pesquisa.

No entanto, muitos sites implementam mecanismos avançados para restringir o acesso automatizado, como fingerprinting, limitação de taxa (rate limiting) ou análise comportamental. O Ladder não contorna essas proteções e pode não funcionar corretamente em serviços que restringem ou controlam ativamente o acesso.

Ferramentas de terceiros, como o FlareSolverr, existem e podem ser usadas de forma independente para renderizar páginas web em um ambiente de navegador headless. Essas ferramentas não fazem parte do Ladder, e seu uso pode estar sujeito a restrições legais e contratuais. Os usuários são os únicos responsáveis por garantir que seu uso esteja em conformidade com todos os regulamentos aplicáveis.

Instalação

Aviso: Se a sua instância for acessível publicamente, certifique-se de ativar o Basic Auth. Isso impedirá que usuários não autorizados usem o seu proxy. Se você não ativar o Basic Auth, qualquer pessoa poderá usar o seu proxy para navegar em conteúdo impróprio/ilegal. E você será considerado responsável por isso.

Binário

1. Baixe o binário aqui
2. Descompacte e execute o binário ./ladder -r https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml
3. Abra o navegador (padrão: http://localhost:8080)

Docker

docker run -p 8080:8080 -d --env RULESET=https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml --name ladder ghcr.io/everywall/ladder:latest

Docker Compose

curl https://raw.githubusercontent.com/everywall/ladder/main/docker-compose.yaml --output docker-compose.yaml
docker-compose up -d

Helm

Consulte README.md no subdiretório helm-chart para obter mais informações.

Uso

Navegador

1. Abra o navegador (padrão: http://localhost:8080)
2. Digite a URL
3. Pressione Enter

Ou acesse diretamente acrescentando a URL ao final da URL do proxy: http://localhost:8080/https://www.example.com

Ou crie um favorito com a seguinte URL:

javascript:window.location.href="http://localhost:8080/"+location.href

API

curl -X GET "http://localhost:8080/api/https://www.example.com"

RAW

http://localhost:8080/raw/https://www.example.com

Executando o Ruleset

http://localhost:8080/ruleset

Configuração

Variáveis de Ambiente

ALLOWED_DOMAINS e ALLOWED_DOMAINS_RULESET são combinados. Se ambos estiverem vazios, nenhuma limitação será aplicada. | BASE_PATH | Caminho base para o proxy, útil se você quiser executar o proxy em um subcaminho (por exemplo, http://localhost:8080/proxy/) | `` |

Ruleset

É possível aplicar regras personalizadas para modificar a resposta ou a URL solicitada. Isso pode ser usado para remover elementos indesejados ou modificar elementos da página. O ruleset é um arquivo YAML, um diretório com arquivos YAML ou uma URL para um arquivo YAML que contém uma lista de regras para cada domínio. Essas regras são carregadas na inicialização.

Há um ruleset básico disponível em um repositório separado ruleset.yaml. Sinta-se à vontade para adicionar suas próprias regras e criar um pull request.

- domain: example.com          # Includes all subdomains
  domains:                     # Additional domains to apply the rule
    - www.example.de
    - www.beispiel.de
  headers:
    x-forwarded-for: none      # override X-Forwarded-For header or delete with none
    referer: none              # override Referer header or delete with none
    user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
    content-security-policy: script-src 'self'; # override response header
    cookie: privacy=1
  regexRules:
    - match: <script\s+([^>]*\s+)?src="(/)([^"]*)"
      replace: <script $1 script="/https://www.example.com/$3"
  injections:
    - position: head # Position where to inject the code
      append: |      # possible keys: append, prepend, replace
        <script>
          window.localStorage.clear();
          console.log("test");
          alert("Hello!");
        </script>
- domain: www.anotherdomain.com # Domain where the rule applies
  useFlareSolverr: false        # Use FlareSolverr for Cloudflare bypass (optional, default: false)
  paths:                        # Paths where the rule applies
    - /article
  googleCache: false            # Use Google Cache to fetch the content
  regexRules:                   # Regex rules to apply
    - match: <script\s+([^>]*\s+)?src="(/)([^"]*)"
      replace: <script $1 script="/https://www.example.com/$3"
  injections:
    - position: .left-content article .post-title # Position where to inject the code into DOM
      replace: | 
        <h1>My Custom Title</h1>
    - position: .left-content article # Position where to inject the code into DOM
      prepend: | 
        <h2>Subtitle</h2>
- domain: demo.com
  headers:
    content-security-policy: script-src 'self';
    user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
  urlMods:              # Modify the URL
    query:              
      - key: amp        # (this will append ?amp=1 to the URL)
        value: 1 
    domain:             
      - match: www      # regex to match part of domain
        replace: amp    # (this would modify the domain from www.demo.de to amp.demo.de)
    path:               
      - match: ^        # regex to match part of path
        replace: /amp/  # (modify the url from https://www.demo.com/article/ to https://www.demo.de/amp/article/)

Integração com FlareSolverr

O Ladder agora oferece suporte à integração com o FlareSolverr para contornar a proteção do Cloudflare e outros desafios anti-bot. Isso é particularmente útil para sites que empregam mecanismos sofisticados de detecção de bots.

Configurando o FlareSolverr

1. Usando Docker Compose (recomendado):

   root@kitploit:~

   # docker-compose.yaml
   services:
     ladder:
       image: ghcr.io/everywall/ladder:latest
       ports:
         - "8080:8080"
       environment:
         - RULESET=https://raw.githubusercontent.com/everywall/ladder-rules/main/ruleset.yaml
         # - FLARESOLVERR_HOST=http://flaresolverr:8191
       depends_on:
         - flaresolverr
     
     flaresolverr:
       image: ghcr.io/flaresolverr/flaresolverr:latest
       ports:
         - "8191:8191"
       environment:
         - LOG_LEVEL=info
   

2. Executando o FlareSolverr separadamente:

   root@kitploit:~

   docker run -d \
     --name flaresolverr \
     -p 8191:8191 \
     ghcr.io/flaresolverr/flaresolverr:latest
   

   Em seguida, inicie o Ladder com a URL do FlareSolverr:

   root@kitploit:~

   FLARESOLVERR_HOST=http://localhost:8191 ./ladder
   

Configurando regras para o FlareSolverr

Para usar o FlareSolverr em domínios específicos, adicione a flag useFlareSolverr: true ao seu ruleset:

# Example ruleset with FlareSolverr
- domain: cloudflare-protected-site.com
  useFlareSolverr: true  # Enable FlareSolverr for this domain
  headers:
    user-agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"

# Regular site without FlareSolverr
- domain: regular-site.com
  headers:
    user-agent: "Custom User Agent 1.0"

Casos de uso

A integração com o FlareSolverr é particularmente útil para:

• Sites protegidos por Cloudflare: Sites que usam os desafios anti-bot do Cloudflare
• Sites com desafios JavaScript: Páginas que exigem a execução de JavaScript para acessar o conteúdo
• Carregamento dinâmico de conteúdo: Sites que carregam conteúdo dinamicamente por meio de JavaScript
• Detecção avançada de bots: Sites que usam técnicas sofisticadas de fingerprinting e detecção de bots

Notas importantes

• O FlareSolverr adiciona latência adicional às requisições, pois precisa resolver desafios
• Ative useFlareSolverr apenas para domínios que realmente precisem, para manter a performance
• O FlareSolverr exige mais recursos, pois executa um navegador headless
• Certifique-se de que o FlareSolverr esteja em execução e acessível antes de ativá-lo no seu ruleset

Desenvolvimento

Para executar um servidor de desenvolvimento em http://localhost:8080:

echo "dev" > handlers/VERSION
RULESET="./ruleset.yaml" go run cmd/main.go

Opcional: servidor de desenvolvimento com recarga automática usando cosmtrek/air

Instale o air de acordo com as instruções de instalação.

Execute um servidor de desenvolvimento em http://localhost:8080:

air # or the path to air if you haven't added a path alias to your .bashrc or .zshrc

Este projeto usa pnpm para compilar uma folha de estilos com as classes do Tailwind CSS. Para desenvolvimento local, se você modificar estilos em form.html, execute pnpm build para gerar uma nova folha de estilos.