Integração e Gestão de Sistemas de Informação

Comando curl: testar APIs e HTTP no Linux (e wget)

Terminal Linux a executar curl -I e a mostrar os cabeçalhos HTTP devolvidos por uma API

Escrito por

Artificial Inteligence

em

Uma API que não responde, um redirect que ninguém documentou, um certificado prestes a expirar, um endpoint que rejeita tudo: no dia a dia de quem administra sistemas, quase todos os problemas de web começam por ser investigados com o mesmo utilitário. O curl é o canivete suíço do HTTP no terminal — faz o pedido exatamente como lhe pedimos e mostra exatamente o que o servidor devolveu, sem esconder nada pelo caminho.

Neste artigo percorremos as opções do curl que realmente interessam — cabeçalhos, redirects, POST, autenticação, TLS —, vemos onde o wget ainda ganha, e mostramos como ambos se usam em cibersegurança. No meio da página há um simulador interativo com uma API fictícia para praticar sem sair do browser.

O que faz o curl

O curl transfere dados de e para um servidor, através de URLs. Suporta dezenas de protocolos, mas na prática vive-se nele pelo HTTP e HTTPS: compõe um pedido, envia-o e escreve a resposta no stdout — o que o faz encaixar em pipelines e scripts como qualquer outro comando Unix. A forma geral é simples:

curl [opções] URL

Sem opções, o curl faz um GET e mostra o corpo da resposta. Dois comportamentos por omissão surpreendem quem começa: não segue redirects (um 301 devolve apenas a página de aviso do servidor) e recusa despejar conteúdo binário no terminal, sugerindo que se guarde num ficheiro. Ambos se resolvem com uma opção — e é por aí que vamos.

As opções que interessam

Ver o que o servidor diz: -I, -i, -v e -L

  • -I — pede só os cabeçalhos (método HEAD). É a forma mais rápida de auditar um servidor: estado, redirects, content-type e cabeçalhos de segurança, sem descarregar o corpo.
  • -i — mostra cabeçalhos e corpo juntos, útil quando se quer o contexto completo de uma resposta.
  • -L — segue os redirects até à resposta final. Sem esta opção, um 301 ou 302 termina a conversa.
  • -v — modo verboso: resolução do nome, ligação, handshake TLS, certificado apresentado e a troca completa de cabeçalhos (> para o que enviámos, < para o que recebemos). Quando «não funciona e não se percebe porquê», é aqui que se vê porquê.
curl -I https://api.exemplo.pt/
HTTP/2 301
location: https://api.exemplo.pt/v2/
strict-transport-security: max-age=63072000; includeSubDomains

curl -IL https://api.exemplo.pt/    # segue e mostra os cabeçalhos de cada salto

Guardar respostas: -o e -O

  • -o ficheiro — grava a resposta com o nome que escolher. Assim que o corpo deixa de ir para o terminal, o curl passa a mostrar a barra de progresso.
  • -O — grava com o nome remoto do URL. Atenção ao caso clássico: se o URL terminar em /, não há nome remoto e o comando falha com Remote file name has no length.

Enviar dados: -X, -d, -H e -u

Testar uma API é sobretudo enviar-lhe pedidos bem formados. Quatro opções cobrem quase tudo:

  • -X POST (ou PUT, DELETE…) — muda o método do pedido.
  • -d 'dados' — envia um corpo. Por omissão o curl declara application/x-www-form-urlencoded, o que muitas APIs modernas rejeitam com 415.
  • -H 'Nome: valor' — acrescenta ou substitui cabeçalhos; o mais comum é precisamente Content-Type: application/json.
  • -u utilizador:senha — autenticação básica. As credenciais seguem no cabeçalho Authorization apenas codificadas em Base64, pelo que só fazem sentido sobre HTTPS.
curl -u aluno:S3nh4-lab \
     -X POST -H "Content-Type: application/json" \
     -d '{"evento":"login-teste"}' \
     https://api.exemplo.pt/v2/registos

TLS e rede: -k, –resolve e limites

  • --resolve nome:porto:IP — força um nome a resolver para um IP concreto, sem tocar no DNS. É a forma limpa de testar um servidor novo antes de mudar o registo público.
  • -k — ignora a verificação do certificado TLS. Tem um uso legítimo (staging com certificado self-signed que controlamos) e um uso perigoso (produção — onde equivale a abdicar da proteção contra intercetação).
  • --max-time N — tempo máximo total do pedido; indispensável em scripts para não ficar pendurado.
  • -sS e -w '%{http_code}' — silenciam o progresso (mantendo os erros) e escrevem variáveis da transferência no fim: a base de qualquer sonda de monitorização em shell.

E o wget?

O wget resolve outro problema. Enquanto o curl escreve para o terminal e pensa em pedidos individuais, o wget grava para ficheiro por omissão, retoma transferências interrompidas com -c e, sobretudo, sabe descarregar recursivamente: wget -r segue as ligações de uma página e espelha um site inteiro no disco. Com -l limita-se a profundidade e com -np impede-se a subida na árvore de diretórios — dois travões que convém usar sempre, por respeito pelo servidor do outro lado.

wget -r -l 2 -np https://api.exemplo.pt/   # espelho até 2 níveis, sem subir na árvore
wget -c https://exemplo.pt/imagem.iso      # retoma um download interrompido

curl em cibersegurança

Auditoria de cabeçalhos de segurança. Um curl -I a um site diz em segundos se estão presentes o Strict-Transport-Security, o X-Content-Type-Options ou o Content-Security-Policy. A ausência de qualquer um deles é um achado típico de auditoria — e verificável sem nenhuma ferramenta especializada.

Validação de TLS e certificados. O curl -v mostra a versão de TLS negociada, a cifra e o certificado apresentado (nome, emissor, validade). Combinado com --resolve, permite validar o certificado de um servidor novo antes da migração de DNS — e o erro curl: (60) num certificado inválido é a verificação a funcionar, não um obstáculo a silenciar com -k.

Diagnóstico e teste de APIs. Num teste de intrusão ou num incidente, o curl é a forma mais direta de interrogar um endpoint: que métodos aceita, como responde a pedidos sem autenticação (401? 200?…), que mensagens de erro devolve e se essas mensagens revelam mais do que deviam.

Como assinatura de deteção. Por estarem em toda a parte, curl e wget aparecem em muitas cadeias de ataque, a descarregar a fase seguinte ou a exfiltrar dados por POST. Um curl lançado por uma conta de serviço web ou pedidos diretos a IPs sem nome de domínio merecem regra de deteção no SIEM — conhecer bem a ferramenta é meio caminho para reconhecer o abuso.

Experimente no simulador interativo

A simulação abaixo recria uma API fictícia — redirect, healthcheck, rota autenticada, endpoint POST, ficheiro binário — e um staging com certificado self-signed. À esquerda vê o servidor e os cabeçalhos que devolve; no terminal à direita, o resultado exato de cada pedido. Clique nas opções (-I, -v, -L, -u, -X POST -d, --resolve…) para compor o comando, use Demonstrar tudo para a sequência guiada — um diagnóstico completo, do primeiro 301 ao espelho com wget -r — ou avance com Anterior e Seguinte.

Erros comuns e boas práticas

  • Esquecer o -L e concluir que «a página está vazia» — quando o que veio foi um 301 que ninguém seguiu. Na dúvida, curl -IL mostra a cadeia completa.
  • Usar -k por rotina. Se o certificado falha em produção, o problema é o certificado — ignorar a verificação só esconde um risco real de intercetação.
  • Passar segredos na linha de comandos. Um -u utilizador:senha fica no histórico da shell e visível na lista de processos. Prefira -u utilizador (a senha é pedida) ou um ficheiro .netrc com permissões restritas.
  • POST sem Content-Type. O -d declara form-urlencoded por omissão; se a API espera JSON, a resposta é um 415 — e a correção é um -H.
  • Confundir -o com -O: o primeiro exige um nome, o segundo usa o nome remoto — e falha se o URL terminar em /.
  • Descarregar e executar às cegas. O padrão curl URL | bash executa código que nunca ninguém leu, com as suas permissões. Descarregue para ficheiro, inspecione, valide a origem — e só depois execute.
  • wget -r sem travões: sem -l e -np, um espelho recursivo pode transformar-se num pequeno ataque de negação de serviço involuntário ao site do outro lado.
  • Scripts sem -sS nem --max-time: barras de progresso no cron e pedidos eternamente pendurados são as duas avarias mais comuns do curl automatizado.

Conclusão

O curl é a lupa do HTTP: com meia dúzia de opções — -I para auditar, -v para diagnosticar, -L para seguir, -d e -H para testar APIs — resolve-se a maioria das investigações web sem sair do terminal, e o wget completa o par quando o objetivo é descarregar ou espelhar. Se está a construir a sua caixa de ferramentas Linux, veja também o nosso artigo sobre o useradd.

Quer levar estas competências mais longe, ou precisa de apoio especializado em segurança e administração de sistemas? Conheça os serviços de formação e consultoria da HJFR no nosso catálogo de serviços — desenhamos percursos práticos para equipas técnicas e programas à medida para empresas.

Este artigo faz parte da série «Comandos Linux, um a um» do blog HJFR — fique atento aos próximos comandos.

Mais artigos