DeviceLifecycle-API

Problema

O DeviceLifecycle gera evidências operacionais relevantes: o inventário CSV mais recente, os resultados do ciclo de vida e os logs de execução. Dashboards internos, serviços de monitoramento, ferramentas de inventário e rotinas de auditoria podem precisar desses dados, mas conceder acesso direto ao sistema de arquivos do servidor ampliaria desnecessariamente o limite de confiança.

Expor comandos do ciclo de vida por uma API seria ainda mais arriscado. Uma integração de relatórios não deve receber autoridade para colocar dispositivos em quarentena, restaurá-los ou excluir identidades.

Solução

DeviceLifecycle-API é uma extensão HTTP separada e somente leitura. Ela lê os artefatos já produzidos pelo DeviceLifecycle e os disponibiliza por endpoints autenticados.

A relação é intencionalmente unidirecional:

• DeviceLifecycle permanece como produtor autoritativo de relatórios, logs, estado e decisões administrativas;
• DeviceLifecycle-API autentica consumidores e retorna dados existentes;
• os consumidores formatam ou monitoram as respostas conforme suas próprias necessidades.

Interromper ou desinstalar a API não afeta o motor do ciclo de vida. O DeviceLifecycle não depende da extensão para inventariar, colocar em quarentena, recuperar ou remover dispositivos.

Contrato da API

O serviço expõe uma superfície pequena e versionada em /api/v1:

• /health informa a disponibilidade do serviço e dos arquivos de origem;
• /metadata retorna metadados do relatório e do log atuais;
• /report.csv entrega o CSV original sem transformação;
• /report converte o CSV atual para JSON;
• /log?lines=N retorna uma quantidade limitada das linhas mais recentes;
• /log/file entrega o log atual completo.

Não existem endpoints de escrita nem caminhos de arquivos controlados pelo cliente. A API não acessa Active Directory, Entra ID, Intune ou Microsoft Graph.

Arquitetura de segurança

A API foi projetada para infraestrutura interna, mas não assume que a rede interna seja inerentemente confiável.

Os controles incluem:

• autenticação pelo cabeçalho X-API-Key;
• chaves hexadecimais aleatórias de 64 caracteres geradas durante a instalação;
• comparação da chave em tempo constante;
• segredos e configuração de runtime armazenados fora do repositório;
• allowlist de endereços aprovados no Windows Firewall;
• autenticação configurável para o endpoint de saúde;
• Swagger UI, ReDoc e schema OpenAPI desabilitados em runtime;
• rejeição de caminhos absolutos e de navegação para diretórios superiores;
• leituras estáveis que comparam tamanho e timestamp de modificação;
• limites para solicitações de linhas do log;
• respostas com Cache-Control: no-store e X-Content-Type-Options: nosniff;
• logs rotativos de requisições que nunca registram a chave da API.

HTTP sem TLS é destinado somente a segmentos locais ou internos confiáveis. Acesso roteado ou não confiável deve passar por um proxy reverso HTTPS.

Instalação e operação

Um instalador em PowerShell prepara todo o ambiente do serviço no Windows:

1. valida as fontes de relatório e log do DeviceLifecycle;
2. valida Python 3.10 ou mais recente;
3. cria os diretórios de instalação e runtime;
4. cria um ambiente virtual Python;
5. instala FastAPI e Uvicorn;
6. gera a chave da API fora do controle de versão;
7. registra uma tarefa de inicialização como SYSTEM;
8. cria uma regra restrita de firewall quando endereços consumidores são configurados;
9. inicia e valida o serviço.

O projeto também fornece rotação de chave, validação de configuração, atualização, exemplos de consulta e scripts de desinstalação completa.

Comportamento em falhas

O serviço verifica se os arquivos de origem permanecem estáveis antes de retorná-los. Quando um relatório ou log muda durante a leitura, a requisição falha em vez de entregar um artefato parcialmente atualizado.

Relatório indisponível, CSV inválido, log ausente, chave incorreta, quantidade excessiva de linhas ou caminho configurado de forma insegura produzem erros explícitos sem modificar os arquivos do produtor.

Isso mantém a extensão estritamente observacional: ela pode falhar ao servir dados, mas não pode alterar o estado do ciclo de vida.

Estado atual

O repositório contém a aplicação FastAPI, configuração e módulo auxiliar em PowerShell, scripts de instalação e inicialização, validação, rotação de chave, desinstalação, exemplo de consumidor, política de segurança, changelog, referência HTTP e documentação bilíngue de arquitetura.

A implementação pública foi sanitizada. Endereços organizacionais, chaves, dados de tenant, credenciais, certificados e topologia interna permanecem fora do controle de versão.

O que o projeto demonstra

DeviceLifecycle-API demonstra separação de capacidades em ferramentas de infraestrutura. Sistemas de relatórios e monitoramento recebem somente a interface mínima necessária, enquanto a autoridade privilegiada de gerenciamento de dispositivos permanece isolada na automação principal. O projeto combina um contrato HTTP deliberadamente reduzido com autenticação, allowlist de rede, acesso seguro a arquivos, isolamento de segredos e ferramentas operacionais de instalação.