CertInventory

Centralized Digital Certificate Inventory for Corporate Environments

O CertInventory é uma plataforma leve para coleta, centralização, consulta e auditoria de certificados digitais instalados em computadores corporativos.

Desenvolvido com Python, FastAPI e SQLite, o sistema foi projetado para ambientes de TI que precisam de uma visão centralizada dos certificados utilizados por usuários e estações de trabalho Windows.

A coleta pode ser realizada por scripts PowerShell distribuídos através de ferramentas como Active Directory / Group Policy, enquanto o CertInventory centraliza os dados recebidos em uma interface web protegida.

Visão geral

Em ambientes corporativos, certificados digitais podem estar distribuídos por centenas de computadores e diferentes perfis de usuário. Sem uma solução centralizada, identificar:

onde um certificado está instalado;
qual usuário está utilizando determinado certificado;
quando um certificado irá expirar;
quais computadores possuem o mesmo certificado;
quais certificados já estão vencidos;

pode exigir verificações manuais e pouco escaláveis.

O CertInventory busca resolver esse problema centralizando essas informações em uma única aplicação.

Fluxo de funcionamento

┌──────────────────────────┐
│     Windows Endpoint     │
│                          │
│       PowerShell         │
│  certutil / Certificate  │
│         Store            │
└────────────┬─────────────┘
             │
             │ HTTPS
             │ API Key
             ▼
┌──────────────────────────┐
│      CertInventory       │
│                          │
│        FastAPI           │
│      REST API + Web      │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│          SQLite          │
│                          │
│        WAL enabled       │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│        Dashboard         │
│                          │
│ Login JWT • Filters      │
│ Reports • Audit          │
└──────────────────────────┘

Principais recursos

Coleta centralizada

Recebe informações de certificados coletadas remotamente em computadores Windows através de scripts PowerShell.

Segurança e autenticação Web

A interface web (Dashboard) é protegida por formulário de login utilizando JWT (JSON Web Tokens) e cookies HTTP-only, garantindo que somente usuários autenticados possam acessar os dados corporativos.

API protegida

Os endpoints responsáveis pelo recebimento dos dados coletados pelos scripts são protegidos através de API Key, configurada por variável de ambiente.

A chave é enviada através do cabeçalho:

X-API-Key: SUA_API_KEY

Pesquisa e filtros cruzados

Permite combinar diferentes critérios para localizar certificados específicos:

Empresa
Computador
Usuário
Status
- Válido
- Vencido
- Próximo do vencimento
Número de série

Agrupamento inteligente de certificados

Certificados com o mesmo número de série são automaticamente identificados e agrupados.

Por exemplo, um mesmo certificado de e-CNPJ instalado em cinco computadores diferentes poderá ser identificado como uma única entidade, permitindo visualizar sua distribuição no ambiente:

Certificado: ACME LTDA
Serial: 123456789ABC

├── PC-FINANCEIRO-01
│   └── usuario01
│
├── PC-FINANCEIRO-02
│   └── usuario02
│
├── PC-DIRETORIA-01
│   └── usuario03
│
├── PC-CONTABILIDADE-01
│   └── usuario04
│
└── PC-CONTABILIDADE-02
    └── usuario05

Relatórios e exportação

Os dados filtrados podem ser exportados diretamente pelo Dashboard para:

PDF
Excel
Impressão

Os filtros aplicados na interface são considerados durante a geração dos relatórios.

Containerização

O projeto possui uma imagem Docker publicada no Docker Hub, permitindo realizar o deploy sem a necessidade de baixar ou compilar o código-fonte no servidor de produção.

Stack tecnológica

Componente	Tecnologia
Backend	Python 3.13
API	FastAPI
ASGI Server	Uvicorn
ORM	SQLAlchemy
Database	SQLite (WAL)
Frontend	HTML5 / JavaScript
UI Framework	Bootstrap 5
Data Grid	DataTables
Testes	Pytest / HTTPX
Segurança	PyJWT
Containers	Docker / Docker Compose

Configuração

O CertInventory utiliza variáveis de ambiente para armazenar credenciais e chaves criptográficas.

Crie um arquivo .env na raiz do projeto ou na mesma pasta do docker-compose.yml em produção.

# Chave de autorização utilizada pelos scripts PowerShell
API_KEY=CHANGE_ME_TO_A_STRONG_RANDOM_KEY

# Credenciais de acesso ao Dashboard
ADMIN_USER=admin
ADMIN_PASS=CHANGE_ME_TO_A_STRONG_PASSWORD

# Chave criptográfica utilizada para assinatura dos tokens JWT
SECRET_KEY=CHANGE_ME_TO_A_LONG_RANDOM_STRING

Importante: o arquivo .env contém informações sensíveis e não deve ser versionado no Git.

Adicione ao .gitignore:

.env
venv/
__pycache__/
*.pyc
data/

Gerando chaves seguras

Para gerar uma chave aleatória utilizando Python:

python -c "import secrets; print(secrets.token_urlsafe(32))"

O comando pode ser utilizado para gerar tanto a API_KEY quanto a SECRET_KEY.

Exemplo:

API_KEY=7nX...chave-gerada...
SECRET_KEY=K8s...chave-gerada...

Deploy com Docker

O método recomendado para ambientes de produção é utilizar a imagem oficial publicada no Docker Hub.

Dessa forma, o servidor não precisa possuir o código-fonte nem instalar as dependências Python localmente.

1. Preparar o ambiente

Crie uma pasta para o projeto:

mkdir certinventory
cd certinventory

2. Criar o arquivo `.env`

Crie o arquivo:

nano .env

Adicione as variáveis:

API_KEY=CHANGE_ME_TO_A_STRONG_RANDOM_KEY
ADMIN_USER=admin
ADMIN_PASS=CHANGE_ME_TO_A_STRONG_PASSWORD
SECRET_KEY=CHANGE_ME_TO_A_LONG_RANDOM_STRING

3. Criar o `docker-compose.yml`

Crie o arquivo:

nano docker-compose.yml

Utilize:

services:
  web:
    image: yodao/certinventory:latest
    container_name: certinventory_api

    ports:
      - "5000:5000"

    env_file:
      - .env

    environment:
      TZ: America/Sao_Paulo

    volumes:
      - ./data:/app/data

    restart: unless-stopped

Persistência

O volume:

- ./data:/app/data

garante que o banco de dados seja armazenado no servidor host e não dentro do container.

Assim, a atualização ou recriação do container não deverá remover os dados armazenados no banco.

4. Iniciar a aplicação

Execute:

docker compose up -d

O Docker fará o download da imagem e iniciará o container automaticamente.

Verifique o status:

docker compose ps

Acompanhe os logs:

docker compose logs -f

5. Acessar a aplicação

A aplicação estará disponível em:

http://SERVER_IP:5000

Exemplo:

http://192.168.1.100:5000

Atualização

Quando uma nova versão da imagem estiver disponível no Docker Hub:

docker compose pull

Depois:

docker compose up -d

Para acompanhar a inicialização:

docker compose logs -f

Como o banco de dados está armazenado no volume:

./data

os dados existentes permanecem separados da imagem do container.

Operação do container

Verificar status

docker compose ps

Visualizar logs

docker compose logs -f

Reiniciar

docker compose restart

Parar

docker compose down

Iniciar

docker compose up -d

Atualizar

docker compose pull
docker compose up -d

Instalação local

A instalação local é destinada principalmente ao desenvolvimento e manutenção do projeto.

1. Clonar o repositório

git clone https://github.com/VilanovaPassos/certinventory.git
cd certinventory

2. Criar o ambiente virtual

Windows

python -m venv venv

Ative o ambiente:

venv\Scripts\activate

Linux

python3 -m venv venv
source venv/bin/activate

3. Instalar dependências

pip install -r requirements.txt

4. Configurar o `.env`

Crie:

.env

Exemplo:

API_KEY=CHANGE_ME_TO_A_STRONG_RANDOM_KEY
ADMIN_USER=admin
ADMIN_PASS=CHANGE_ME_TO_A_STRONG_PASSWORD
SECRET_KEY=CHANGE_ME_TO_A_LONG_RANDOM_STRING

5. Iniciar o servidor

uvicorn app:app --host 0.0.0.0 --port 5000 --reload

A aplicação estará disponível em:

http://localhost:5000

A documentação automática da API pode ser acessada em:

http://localhost:5000/docs

O parâmetro --reload é recomendado somente para desenvolvimento.

Geração de dados de teste

O projeto possui um script para geração de dados sintéticos.

Ele permite testar o Dashboard sem a necessidade de utilizar certificados reais ou realizar a coleta em computadores da rede.

Execute:

python popular_banco.py

O script limpará o banco atual e criará aproximadamente:

5 Empresas
100 Computadores
100 Usuários
1000 Certificados

Os certificados são distribuídos a partir de um pool de certificados, simulando situações em que o mesmo certificado está instalado em várias máquinas.

O conjunto de dados também contempla diferentes estados:

certificados válidos;
certificados vencidos;
certificados próximos do vencimento;
certificados distribuídos entre diferentes computadores;
certificados associados a diferentes usuários.

Atenção: o script de povoamento limpa os dados existentes. Utilize-o somente em ambientes de desenvolvimento ou teste.

Coleta em endpoints Windows

A coleta dos certificados é realizada através de um script PowerShell.

Em ambientes Active Directory, o script pode ser distribuído utilizando:

Group Policy;
tarefas agendadas;
scripts de logon;
ferramentas de gerenciamento de endpoints.

Também é possível utilizar Item-Level Targeting para determinar quais computadores pertencem a determinada empresa ou grupo.

Consulta do Certificate Store

O comando nativo utilizado como base para a coleta é:

certutil -user -store My

Outra alternativa utilizando o Certificate Provider do PowerShell:

Get-ChildItem Cert:\CurrentUser\My

Esses comandos permitem consultar os certificados armazenados no repositório:

Current User
└── Personal
    └── Certificates

Envio para a API

O agente de coleta consolida os dados obtidos e envia um pacote JSON para a API do CertInventory.

A autenticação é realizada através do cabeçalho:

X-API-Key: SUA_API_KEY

Fluxo:

┌──────────────────────┐
│ Windows Endpoint     │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ PowerShell Collector │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ Certificate Store    │
│ CurrentUser\My       │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│ JSON Payload         │
└──────────┬───────────┘
           │
           │ X-API-Key
           ▼
┌──────────────────────┐
│ CertInventory API    │
└──────────────────────┘

Em ambientes de produção, recomenda-se utilizar HTTPS para proteger os dados durante o transporte.

API

A API é responsável pelo recebimento das informações coletadas nos endpoints Windows.

A autenticação dos agentes é realizada utilizando API Key.

Exemplo conceitual:

POST /api/...
X-API-Key: SUA_API_KEY
Content-Type: application/json

O payload contém as informações necessárias para identificar:

empresa;
computador;
usuário;
certificado;
número de série;
datas de emissão e validade;
informações relevantes para auditoria.

A documentação completa dos endpoints disponíveis pode ser consultada através do Swagger:

http://SERVER_IP:5000/docs

Segurança

O CertInventory possui duas camadas principais de autenticação.

Dashboard

O acesso à interface web utiliza:

usuário;
senha;
JWT;
cookies HTTP-only.

Fluxo:

Usuário
   │
   │ Login
   ▼
Dashboard
   │
   ▼
Autenticação
   │
   ▼
JWT
   │
   ▼
Cookie HTTP-only

API

Os endpoints utilizados pelos agentes de coleta são protegidos por API Key.

PowerShell Agent
       │
       │ X-API-Key
       ▼
   FastAPI
       │
       ├── API Key válida
       │       │
       │       ▼
       │    Processa
       │
       └── API Key inválida
               │
               ▼
            Rejeita

Recomendações para produção

Para ambientes corporativos, recomenda-se:

utilizar HTTPS;
utilizar API Keys longas e aleatórias;
utilizar uma SECRET_KEY forte;
não versionar o .env;
restringir o acesso à porta da aplicação através de firewall;
realizar backups periódicos;
manter o Docker atualizado;
evitar utilizar credenciais padrão;
separar credenciais de desenvolvimento e produção.

Testes automatizados

O projeto utiliza Pytest e HTTPX para testes automatizados.

O banco utilizado durante os testes é isolado em memória utilizando StaticPool, evitando alterações no banco de desenvolvimento ou produção.

A suíte cobre, entre outros pontos:

validação de rotas HTTP protegidas;
autenticação da API REST;
geração de tokens JWT;
redirecionamento de usuários não autenticados;
cookies de autenticação;
expiração de autenticação;
comportamento das rotas protegidas.

Execute:

pytest test_app.py -v

Ou, para executar toda a suíte disponível:

pytest -v

Estrutura do projeto

A estrutura pode variar conforme a evolução do projeto, mas uma instalação típica possui:

certinventory/
│
├── app.py
├── popular_banco.py
├── test_app.py
├── requirements.txt
│
├── Dockerfile
├── docker-compose.yml
├── .env
├── .gitignore
│
├── data/
│   └── database.db
│
├── templates/
│   └── index.html
│
└── static/
    ├── css/
    └── js/

Banco de dados

O CertInventory utiliza SQLite com Write-Ahead Logging (WAL).

O WAL permite que operações de leitura e escrita tenham um comportamento mais adequado em cenários com múltiplos acessos simultâneos.

A utilização do SQLite mantém a arquitetura simples e reduz a necessidade de infraestrutura adicional.

Para ambientes de maior escala, o projeto poderá utilizar PostgreSQL futuramente.

Evolução prevista

Atual
─────────────────────────────

FastAPI
   │
   ▼
SQLite + WAL


Futuro
─────────────────────────────

FastAPI
   │
   ▼
PostgreSQL

Monitoramento e operação

Em ambientes de produção, recomenda-se monitorar:

disponibilidade da aplicação;
utilização de CPU;
utilização de memória;
espaço disponível em disco;
tamanho do banco;
quantidade de requisições;
códigos HTTP de erro;
logs da aplicação;
falhas de autenticação;
integridade dos backups.

Integrações futuras podem incluir:

Prometheus;
Grafana;
Zabbix;
sistemas centralizados de logs.

Roadmap

O projeto está em evolução contínua.

Autenticação e segurança

Autenticação de usuários no Dashboard
Autenticação da API por API Key
JWT para sessão Web
Controle de acesso baseado em funções (RBAC)
Auditoria de alterações

Certificados

Agrupamento inteligente de certificados idênticos
Histórico de certificados removidos
Alertas automáticos de expiração
Histórico de alterações dos certificados

Notificações

Notificações por e-mail
Integração com Microsoft Teams

Dashboard

Infraestrutura

Automação

Agente Windows dedicado
Distribuição automatizada via GPO
Registro automático de computadores
Atualização automática do agente

Autor

Mateus Vilanova dos Passos

Projeto desenvolvido com foco em:

infraestrutura;
segurança;
automação;
gerenciamento de certificados;
administração de ambientes corporativos de TI.

CertInventory

Centralized certificate visibility for corporate infrastructure.

Name		Name	Last commit message	Last commit date
static		static
templates		templates
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
app.py		app.py
database.py		database.py
docker-compose.yml		docker-compose.yml
lista_certificados.ps1		lista_certificados.ps1
models.py		models.py
popular_banco.py		popular_banco.py
requirements.txt		requirements.txt
test_app.py		test_app.py

Latest commit

History

Folders and files

Repository files navigation

CertInventory

Visão geral

Fluxo de funcionamento

Principais recursos

Coleta centralizada

Segurança e autenticação Web

API protegida

Pesquisa e filtros cruzados

Agrupamento inteligente de certificados

Relatórios e exportação

Containerização

Stack tecnológica

Configuração

Gerando chaves seguras

Deploy com Docker

1. Preparar o ambiente

2. Criar o arquivo .env

3. Criar o docker-compose.yml

Persistência

4. Iniciar a aplicação

5. Acessar a aplicação

Atualização

Operação do container

Verificar status

Visualizar logs

Reiniciar

Parar

Iniciar

Atualizar

Instalação local

1. Clonar o repositório

2. Criar o ambiente virtual

Windows

Linux

3. Instalar dependências

4. Configurar o .env

5. Iniciar o servidor

Geração de dados de teste

Coleta em endpoints Windows

Consulta do Certificate Store

Envio para a API

API

Segurança

Dashboard

API

Recomendações para produção

Testes automatizados

Estrutura do projeto

Banco de dados

Evolução prevista

Monitoramento e operação

Roadmap

Autenticação e segurança

Certificados

Notificações

Dashboard

Infraestrutura

Automação

Autor

CertInventory

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

2. Criar o arquivo `.env`

3. Criar o `docker-compose.yml`

4. Configurar o `.env`