API

Tela: API e contas de integração (1/2)



Tela: API e contas de integração (2/2)

Tudo o que você vê e faz no Hive está disponível na API REST (OpenAPI 3.1, /api/v1 ). Outras plataformas usam uma conta de integração com um token enviado como Authorization: Bearer <token> . As contas ficam em Integrações › Central de integrações › API e contas de integração (pede permissão para administrar a API); a documentação de todas as rotas está em Documentação da API (Swagger).

Criar uma conta de integração por plataforma, escolhendo os domínios de dados, o modo, a validade do token, IPs permitidos, mTLS e um limite de chamadas.

Trocar (rotacionar) ou revogar um token.

Ligar o Webhook de CI de uma conta, pausá-lo, trocar o segredo e reenviar entregas.

Navegar e experimentar todas as rotas na Documentação da API e baixar o openapi.json .

Clique em Nova conta de integração.

Dê à conta um nome com letras minúsculas, números e hífens, como cmdb-servicenow , e diga para que serve. O nome aparece na trilha de auditoria de cada chamada.

Escolha os Domínios de dados que a conta pode usar: Ativos e detalhes, Software e uso, Relacionamentos e mapas, Rede, Nuvem/virtualização/Kubernetes, Contratos e licenças, Vulnerabilidades e insights, Alertas e eventos, Chamados e mudanças, Relatórios, Trilha de auditoria, Pessoas e identidade, Sinal de confiança do dispositivo, Telemetria (OpenTelemetry) e Plano de controle do provedor. Escolha o Modo: Somente leitura (recomendado) ou Leitura e envio (necessário para importar ativos, mudar alertas ou enviar chamados e mudanças). Se quiser, escolha o Modelo de CMDB das respostas (modelo do Hive, ServiceNow CSDM ou DMTF CIM) e um Webhook para avisos de mudança (https).

Escolha a Validade do token (90, 180 ou 365 dias) e, se quiser, os IPs permitidos (faixas como 198.51.100.0/24), Exigir certificado do cliente (mTLS) e o Limite de chamadas por minuto (padrão 600; acima dele a API responde 429 com Retry-After).

Clique em Criar conta e gerar token. Copie o token agora: ele aparece uma única vez, e o Hive guarda só uma impressão digital dele. Testar o token agora confere; Exemplo de chamada mostra uma requisição pronta.

Colunas: Conta de integração, Pode acessar, Modo, Token (vencimento; aviso 15 dias antes),Último uso e Webhook de CI (ligado, configurar ou pausado).

Trocar token cria um token novo (válido por 365 dias); o antigo continua funcionando por 7 dias para a outra plataforma se atualizar e depois vence sozinho. Nesse período a linha mostra "Dois tokens valendo durante a troca (7 dias)."

Revogar para todas as chamadas na hora e não pode ser desfeito; para conectar de novo, crie uma conta nova.

Webhook de CI: Endereço que recebe, Ligar webhook, Pausar/Retomar, Trocar segredo, Enviar teste e as entregas com Enviar de novo. Valide X-Hive-Signature : HMAC-SHA256 de "timestamp.corpo" com o segredo mostrado uma vez.

A mesma aba tem Popular a CMDB da sua plataforma, as Rotas de entrada (POST) e o Proxy de leitura (opcional), um pequeno programa na DMZ que serve só rotas GET.

Documentação da API (Swagger) abre a documentação de todas as rotas, agrupadas por área, com parâmetros, corpos e respostas (pede permissão de leitura de integrações ou de administração da API).

Use a caixa de filtro para achar uma área (tag).

Try it out chama a API com a sua sessão, com as suas permissões. Por padrão só dá para experimentar GET; marque Permitir experimentar POST, PUT, PATCH e DELETE e confirme para rodar requisições de escrita de verdade (elas vão para a auditoria).

Baixar openapi.json salva o contrato para importar no Postman ou no Bruno.

Exemplo prático: conta somente leitura para o CMDB do ServiceNow



Exemplo prático: achar e experimentar uma rota na documentação

Remaining e RateLimit-Reset .

Uma conta revogada não pode ser restaurada.

Criar, trocar e revogar pedem permissão para administrar a API.

Pelo proxy de leitura só funcionam contas somente leitura.

O endereço do webhook precisa ser https público; endereços privados são recusados.

Não há OAuth para contas de integração.

Popule seu CMDB em 3 passos

Integrar com o GRCS

Grafana e Power BI

Chamados de ITSM, CMDB e mudanças aprovadas

Qualquer plataforma pode manter seu CMDB igual ao Hive sem conector dedicado: uma carga inicial, depois só o que mudou, depois avisos de mudança. Tudo usa uma conta de integração criada em Integrações › Central de integrações › API e contas de integração, com o escopo Ativos e detalhes (e Software e uso para incluir o software instalado).

Exportar todos os itens de configuração (ICs) de uma vez, no modelo do Hive, ServiceNow CSDM ou DMTF CIM.





Ler só o que mudou desde a última leitura, incluindo os itens removidos.

Receber um POST assinado para cada IC criado, alterado ou removido.

GET /api/v1/cis/export?model=hive|csdm|cim&include=software devolve todos os ICs ativos em NDJSON (um IC por linha), no arquivo hive-cis.ndjson .

Ou leia em páginas: GET /api/v1/cis?limit=500 e depois GET /api/v1/cis?cursor=<nextCursor> até hasMore ser false. limit vai até 2000.

Cada item tem id , class , removed , updatedAt , attributes e, quando pedido, relationships . O modelo vem da conta (Modelo de CMDB das respostas) ou de model= .

A última página de uma leitura traz o syncToken . Guarde.

Na próxima vez chame GET /api/v1/cis?changed_since=<syncToken> : vêm só os ICs novos e alterados, e os aposentados com removed: true . Pagine com cursor como antes e guarde o novo syncToken .

changed_since=0 (ou sem o parâmetro) é uma leitura completa.

Em vez de consultar, ligue o Webhook de CI da conta (coluna Webhook de CI › Configurar, ou Webhook para avisos de mudança no assistente). O Hive faz POST de ci.created , ci.updated e ci.removed com o corpo {type, occurredAt, ci} e os cabeçalhos X-Hive-Event , X-Hive-Delivery , X-Hive-Timestamp e X-Hive-Signature: sha256=<HMAC-SHA256 de "timestamp.corpo"> . Falhas são tentadas de novo de 30 s até 12 h. As mudanças também podem ir para um barramento de eventos (Kafka, RabbitMQ, Service Bus, SNS, Pub/Sub).

Baixe o contrato com Baixar openapi.json (ou abra Documentação da API (Swagger)) e importe no Postman ou no Bruno para ter a coleção completa. Toda chamada usa Authorization: Bearer <token> .



aposentado no CMDB e guarda o novo token.

Um sync token inválido devolve 422 ( invalid-sync-token ); recomece com uma leitura completa.

A exportação não é retomável; para bases muito grandes, leia em páginas com cursor .

Os eventos do webhook vão só para contas com o escopo de ativos, a partir do momento em que ele é ligado (sem histórico anterior), e só para os ativos assinados quando a conta tem uma lista.

O endereço do webhook precisa ser https público.

O contrato ( /api/openapi.json ) pede login, a não ser que o administrador tenha deixado a documentação da API pública.

API e contas de integração

Integrar com o GRCS

Chamados de ITSM, CMDB e mudanças aprovadas

O GRCS traz do Hive só os ativos que têm um risco ativo ou uma não conformidade aberta: o cadastro do ativo, as vulnerabilidades abertas, os alertas abertos, os serviços de negócio e a avaliação dos controles com evidência. Ele usa uma conta de integração e a API REST; o cartão GRCS em Integrações › Central de integrações › Catálogo (categoria GRC e risco) abre o assistente da conta com os escopos certos.

Criar a conta de integração do GRCS com webhook e limite de chamadas.

Vincular cada alvo do GRCS a um ativo do Hive pelos identificadores.

Assinar a conta nos ativos que importam, por id ou tag.

Ler ativos, achados, alertas, serviços de negócio e conformidade em lotes, e receber eventos.

Em Central de integrações › API e contas de integração, clique em Nova conta de integração (ou Conectar no cartão do GRCS). Escolha os Domínios de dados Ativos e detalhes, Vulnerabilidades e insights, Alertas e eventos e Relatórios; Modo Somente leitura (escolha Leitura e envio só se o GRCS gravar a referência dele de volta). Preencha Webhook para avisos de mudança (opcional) e o Limite de chamadas por minuto. O token aparece uma vez.





POST /api/v1/assets/lookup com até 500 identificadores ( id , externalRef , hwUuid , serial , fqdn , hostname , ip , ou sem tipo para tentar nesta ordem). Cada resposta diz found , none ou ambiguous (com candidatos) e qual identificador casou. O IP é o último recurso: um casamento ambíguo nunca vincula.

Opcional: grave a referência do GRCS com PUT /api/v1/assets/import (fonte grcs , externalId = id do alvo; precisa de Leitura e envio). Depois, GET /api/v1/assets?externalRef=grcs:<id> o encontra.

PUT , PATCH ou DELETE /api/v1/api-accounts//assets com ids de ativos ou tags (por exemplo a tag grcs ). A própria conta pode manter sua lista com o próprio token. Com uma lista, o webhook e os eventos cobrem só os ativos assinados; sem lista, tudo o que os escopos permitem. Até 5.000 ativos e 100 tags por chamada, 50.000 entradas por conta.

GET /api/v1/assets//full — o ativo com hardware, software, serviços, bancos de dados e relacionamentos.

GET /api/v1/vulnerabilities/findings?asset=a,b,c e GET /api/v1/alerts?asset=a,b,c — até 200 ativos por chamada; com changedSince (24h, 7d ou uma data ISO) a lista vem em ordem de mudança e a próxima página está no cabeçalho Hive-Next-Cursor .

GET /api/v1/business-services?asset=a,b — os serviços de que cada ativo faz parte, o papel (componente ou dependência) e se é ponto único de falha.

GET /api/v1/assets//compliance ou POST /api/v1/compliance/assets (até 200 ativos) — cada controle da ISO 27001, PCI DSS, LGPD/GDPR, HIPAA e CIS v8 que se aplica ao ativo: atendido , parcial , nao_atendido ou na , percentual e a evidência medida com a data.

O webhook recebe vulnerability.opened , vulnerability.closed , vulnerability.risk_changed (mudou a severidade, o KEV ou a faixa do EPSS) e compliance.changed , com subject = id do ativo e a assinatura HMAC em X-Hive-Signature , além dos eventos ci.* . Os mesmos eventos podem ir para um barramento de eventos filtrado por uma tag de ativo.

Acima do limite da conta a API responde 429 com Retry-After ; toda resposta traz RateLimit-Limit , RateLimit-Remaining e RateLimit-Reset . O limite vale por nó do núcleo. Aqui o parâmetro é changedSince ; a rota de ICs usa changed_since .

API e contas de integração

Popule seu CMDB em 3 passos

Conformidade e hardening

Vulnerabilidades

Tela: Grafana e Power BI

O Hive serve conjuntos de dados prontos para ferramentas de BI em /api/v1/bi , só leitura: JSON simples para o Grafana e um feed OData v4 para o Power BI. Os dois usam o token de uma conta de integração ( Authorization: Bearer <token> ), e cada conjunto confere a permissão de leitura do seu domínio, então uma conta vê só o que os escopos dela permitem. Os cartões Grafana e Power BI em Integrações › Central de integrações › Catálogo (categoria BI) criam essa conta para você.

Criar com um clique, pelo catálogo, uma conta somente leitura para o Grafana ou o Power BI.

Listar os conjuntos disponíveis para a conta e lê-los em JSON ou OData.

Montar painéis do Grafana com séries no tempo ( from / to do painel) e relatórios do Power BI que se atualizam pelo feed.

Todo conjunto respeita o escopo de ativos do perfil (sites, tags, grupos) de quem chama.

GET /api/v1/bi lista os conjuntos com título, colunas, a permissão, se está disponível para quem chama e os caminhos.

GET /api/v1/bi/<conjunto> devolve uma lista JSON de linhas.

from e to : milissegundos do Grafana ( $ , $ ) ou ISO 8601; padrão os últimos 7 dias.

interval : 5m, 15m, 1h, 6h ou 1d; sem ele, até 2 dias → 15m, até 31 dias → 1h, mais → 1d (no máximo 5000 pontos).

limit (padrão 1000, até 10000) e offset ; a próxima página está no cabeçalho Link: <…>; rel="next" .

Documento de serviço: GET /api/v1/bi/odata ; metadados: GET /api/v1/bi/odata/$metadata ; dados: GET /api/v1/bi/odata/<EntitySet> .



Opções de consulta: $select , $top , $skip , $count e $format . O servidor pagina de 1000 linhas por vez com @odata.nextLink . $filter e $orderby são recusados ("Filtre e ordene no Power Query depois de carregar os dados").

Conjuntos que a conta não pode ler ficam fora do documento de serviço e do $metadata .

[Implementation="2.0"]) `` 3. O navegador lista Assets, AssetsByType, AlertsBySeverity, OpenAlertsOverTime, VulnerabilitiesBySeverity, PatchCompliance e LicenseUsage. Carregue LicenseUsage e PatchCompliance.

Só o token Bearer é aceito: sem usuário e senha (Basic) e sem token no endereço.

Um conjunto sem a permissão responde 403 ("This account cannot read this dataset."); sem token, 401.

O limite de chamadas da conta vale (padrão 600 por minuto); painéis grandes do Grafana contam cada painel.

As rotas de BI também podem ser servidas pelo proxy de leitura na DMZ, com uma conta somente leitura.

As telas do Power BI e do Grafana não fazem parte do Hive; os nomes dos menus delas podem mudar entre versões.



API e contas de integração

Relatórios e painéis

Central de integrações