Entendendo APIs: REST

 

Orquestração, automação e resposta de segurança (SOAR) As plataformas dependem fortemente de APIs (interfaces de programação de aplicativos) para orquestrar ferramentas (produtos) de segurança distintas e invocar as respostas desejadas na forma de ações. Além dos produtos SOAR, as APIs são comuns em quase todos os serviços, ferramentas e produtos usados por profissionais de TI.

Embora as APIs sejam extremamente comuns, você pode não ter experiência em usá-las ou sequer saber que um serviço possui uma ao interagir com ele. Por exemplo, o Facebook usa uma estrutura de API chamada API Graph.

“A API Graph é a principal forma de os aplicativos lerem e gravarem dados no gráfico social do Facebook.”

As APIs podem assumir muitas formas diferentes, mas independentemente da estrutura de API usada para um serviço, elas permitem que profissionais técnicos interajam com um sistema ou serviço. As APIs nos permitem desenvolver e conectar rapidamente um sistema a outro, seja isso estritamente interno a uma única aplicação ou em uma escala maior, como no caso do Swimlane.

O uso de APIs proporciona a indivíduos (e organizações) em todo o mundo uma maneira de compartilhar e interagir com informações de forma rápida, segura (se implementada corretamente, é claro) e em um formato definido (descrito). Sem APIs, a automação não existiria como a conhecemos hoje.

Na primeira parte desta série de duas partes, vou apresentar uma visão geral das APIs REST (Representable State Transfer), bem como os pontos-chave para ajudar você a começar a entender as APIs.

Autenticação

APIs REST geralmente exigem algum mecanismo de autenticação para interagir com a API. Isso é padrão ao interagir com um produto ou serviço pago, mas não necessariamente com ferramentas de inteligência de código aberto (OSINT) ou outros serviços gratuitos na internet.

Existem diversos métodos de autenticação padrão e personalizados que as APIs utilizam. É impossível listá-los todos, mas você encontrará com frequência alguns destes tipos de métodos de autenticação:

Tipo	Exemplo	Descrição
Sem autenticação	Consultando a API do ThreatMiner e pesquisando o domínio google.com	Uma API que não exige que você adicione nenhuma informação adicional ao solicitar dados de uma API.
Nome de usuário e senha	Consultando a API local do Microsoft Exchange	Uma API que requer autenticação básica usando seu nome de usuário e senha.
Token	Consultando haveibeenpwned.com, é necessário criar uma conta gratuita e obter um token de API.	Uma API que exige um token exclusivo para usar o serviço. Normalmente, esse token deve ser fornecido no cabeçalho da sua solicitação.
Delegação	Utilizando a API Microsoft Graph, que requer autenticação OAuth2.	Uma API que funciona em conjunto com um serviço de autenticação que fornece tokens temporários para usar a API.

Esses são apenas alguns exemplos dos diferentes mecanismos de autenticação que um serviço pode usar. Dependendo do produto e da empresa, eles podem escolher um padrão como os acima ou optar por usar um mecanismo próprio.

O principal objetivo desses mecanismos de autenticação é garantir que você tenha os direitos de acesso corretos para o serviço e também assegurar que você esteja respeitando os limites de uso prescritos para o serviço.

Se você estiver interessado em um estudo aprofundado sobre a implementação do OAuth2 pela Microsoft, confira esta série de três partes que escrevi, que explica mais sobre esse mecanismo de autenticação específico: Parte 1, Parte 2, e Parte 3.

Versões

Doravante, usarei um serviço fictício chamado Serviço de Inteligência de Ameaças de Josh e o URL para este serviço é: https://joshsthreatintel.example.

Você pode visitar um site como este e interagir com ele como faria normalmente com qualquer outro site, mas por trás dele existe uma API que permite acessar informações programaticamente para automatizar processos.

Uma boa API terá uma documentação muito boa que detalha como autenticar e usar o serviço. Um padrão comum usado é Arrogância, Mas não precisamos entender o que é Swagger (é um padrão que permite o desenvolvimento mais rápido de APIs e a padronização da documentação das mesmas).

No https://joshsthreatintel.example Nossa API é versionada e pode ser acessada adicionando /v1 para o nosso URL. Se você acessar esta pasta em nosso site, ela poderá estar em branco, você poderá receber uma notificação de que não está autenticado ou poderá ser uma página que exibe a documentação da API. De qualquer forma, a raiz da nossa API será acessada usando este URL: https://joshsthreatintel.example/v1/.

Cada API que você encontrar pode ter uma ou mais versões. Por exemplo, o site havibeenpwned.com possui três:

1. https://haveibeenpwned.com/API/v1
2. https://haveibeenpwned.com/API/v3

Métodos

APIs baseadas em REST são projetadas para interação por meio de métodos específicos definidos em seu código-fonte. Esses métodos respondem de maneira diferente dependendo do tipo de dado utilizado e dos dados enviados à API. Os métodos típicos que você encontrará ao interagir com uma API estão listados na tabela abaixo:

Método	Descrição do termo	Descrição
PEGAR	Recuperar ou ler	Os métodos GET são usados para recuperar informações de uma API.
PUBLICAR	Criar, adicionar ou invocar	Os métodos POST são usados para criar ou adicionar dados, ou para invocar uma ação.
COLOCAR	Correção ou atualização	Os métodos PUT são usados para atualizar ou modificar dados de alguma forma.
EXCLUIR	Destruir ou remover	Os métodos DELETE são usados para remover dados ou interromper uma ação.

Os métodos mais comuns que você encontrará são GET e POST. Dependendo do tipo de API (REST ou SOAP) e do serviço, você poderá precisar fornecer informações adicionais nos cabeçalhos da sua requisição ao fazer uma solicitação à API.

Normalmente, em uma solicitação GET, você enviará uma solicitação HTTP para um endpoint (caminho em uma URL) para recuperar informações específicas da API. Por exemplo, imagine que nosso serviço fictício de inteligência de ameaças tenha um endpoint chamado IP e exige que você forneça um endereço IP para este endpoint. Este endpoint pode ter a seguinte aparência: /ip/123.123.123.123, que acrescentamos ao nosso URL raiz: https://joshsthreatintel.example/v1/ip/123.123.123.123.

Como parte da nossa solicitação, especificamos na chamada para este endpoint que estamos realizando uma PEGAR Solicitamos informações sobre o endereço IP 123.123.123.123.

Aqui estão dois exemplos de como fazer isso em Python e PowerShell Core:

• Python:
  • solicitações de importação
  • resposta = requests.get('https://joshsthreatintel.example/v1/ip/123.123.123.123')
• PowerShell:

   

  • $response = Invoke-RestMethod -Uri '‘https://joshsthreatintel.example/v1/ip/123.123.123.123’'-Método GET

Pode haver um ponto de extremidade diferente disponível que permita a você PUBLICAR um URL específico para o nosso serviço fictício (Serviço de Inteligência de Ameaças do Josh) para que possa ser verificado em busca de atividades maliciosas. Este ponto de extremidade é chamado de URL e seria anexado ao nosso URL raiz: https://joshsthreatintel.example/v1/url.

Além da requisição HTTP normal, ao enviar dados para este serviço falso para escanear uma URL, devemos fornecer o seguinte: corpo da nossa solicitação, a URL que queremos Serviço de Inteligência de Ameaças de Josh para digitalizar. Um exemplo disso em Python é:

import requests body = { 'url': 'http://some.malicious.website.com' } response = requests.post('https://joshsthreatintel.example/v1/url', data=body}

Você verá que o exemplo acima é comum e preferido pela maioria das APIs, mas este endpoint também pode permitir que você... PEGAR Uma URL que utiliza parâmetros de consulta.

Um parâmetro de consulta, em sua essência, é uma forma de filtrar ou selecionar informações de uma API. Parâmetros de consulta são comuns quando um serviço permite que o usuário influencie os resultados retornados por uma chamada de API, mas também podem ser usados para invocar uma ação, como analisar uma URL em vez de fornecer atributos no corpo de uma requisição HTTP.

Os parâmetros de consulta geralmente são concatenados, o que, na minha opinião, reduz a legibilidade. Aqui está um exemplo que você pode encontrar ao usar parâmetros de consulta com APIs:

https://joshsthreatintel.example/v1/url?url=some.malicious.website.com {caminho do site para a API}/{endpoint}?{param=value}

Como você pode ver no exemplo acima, temos o caminho raiz da nossa API e, em seguida, o endpoint; que é o URL Neste caso. Depois do URL No endpoint, podemos ver nosso parâmetro de consulta. Nosso parâmetro de consulta começa com um ? Em seguida, é apresentado o nome do parâmetro e o valor que estamos usando para esse parâmetro.

Um endpoint de API pode permitir que você especifique vários parâmetros de consulta. Por exemplo, aqui está a sintaxe da URL para recuperar informações da API REST da RIPE (Réseaux IP Européens) para um endereço IP específico:

https://rest.db.ripe.net/search?source=ripe&query-string={querystring} {caminho do site para a API}/{endpoint}?{param=value}&{param=value}

Você deve ter notado a adição de um E, O que indica a existência de outro parâmetro de consulta. Este também contém um nome de parâmetro e um valor que estamos usando para esse parâmetro. Uma API pode permitir que vários desses parâmetros sejam concatenados. Você precisará consultar a documentação da API para verificar o que é permitido para um endpoint específico.

Você perceberá que as APIs da vida real optam por usar parâmetros de consulta ou exigem que você forneça um par de chave-valor no corpo da solicitação.

Cabeçalhos

Ao usar APIs, você pode precisar adicionar informações adicionais a um PEGAR ou PUBLICAR ou outro método para o cabeçalhos de uma requisição HTTP. Isso pode ser um token de autenticação, especificar o tipo de conteúdo ou fornecer outras informações.

Em termos básicos, um cabeçalho O valor são metadados usados para estabelecer uma conexão com uma API. Esses metadados são usados pela API para autenticar ou definir o ambiente para o tipo de ação/solicitação a ser executada.

É extremamente comum que APIs que exigem autenticação solicitem um token nos cabeçalhos da requisição HTTP. Esse token pode ser permanente ou, no caso de um esquema de autenticação baseado em delegação (como o OAuth2), um token temporário que precisa ser renovado após um período. De qualquer forma, fornecer essa autenticação é uma prática comum em APIs.

Você também pode precisar especificar Aceitar ou Tipo de conteúdo cabeçalhos juntamente com um Autorização Cabeçalho. Em termos mais simples, um cabeçalho geralmente tem o formato de um par chave-valor. Aqui está um exemplo em Python de como esses dois cabeçalhos podem ser:

custom_headers = { 'Accept': 'application/json', 'Authorization': 'Bearer {SOME_AUTHENTICATION_TOKEN}' }

Esses cabeçalhos são então enviados juntamente com nossa solicitação HTTP para o servidor. Os cabeçalhos podem ou não ser necessários ao usar uma API e, se forem necessários, geralmente serão necessários para todos os métodos usados em suas solicitações HTTP.

Espero que isso ajude a entender os conceitos básicos de APIs REST. No próximo post, vou explicar as APIs SOAP (Simple Object Access Protocol), que são muito mais complexas do que as APIs REST.