Solicitar Demonstração

Primeiros Passos — CLI

Bem-vindo à Interface de Linha de Comando do PKIGuardian! Este guia irá ajudá-lo a instalar e usar a ferramenta CLI.

Índice

Instalação

Pré-requisitos

  • SDK ou Runtime .NET 10
  • Acesso de rede à API do PKIGuardian

Instalar a partir de Binário

Faça o download da versão mais recente para sua plataforma:

Windows:

# Baixar da página de releases
Invoke-WebRequest -Uri "https://github.com/mtpanissa/PKIGuardian/releases/latest/download/pkiguardian-win-x64.zip" -OutFile pkiguardian.zip
Expand-Archive pkiguardian.zip -DestinationPath "C:\Program Files\PKIGuardian"
# Adicionar ao PATH
$env:PATH += ";C:\Program Files\PKIGuardian"

Linux:

# Baixar e extrair
curl -L https://github.com/mtpanissa/PKIGuardian/releases/latest/download/pkiguardian-linux-x64.tar.gz | tar xz
sudo mv pkiguardian /usr/local/bin/
sudo chmod +x /usr/local/bin/pkiguardian

macOS:

# Usando Homebrew
brew tap mtpanissa/pkiguardian
brew install pkiguardian

# Ou baixar manualmente
curl -L https://github.com/mtpanissa/PKIGuardian/releases/latest/download/pkiguardian-osx-x64.tar.gz | tar xz
sudo mv pkiguardian /usr/local/bin/
sudo chmod +x /usr/local/bin/pkiguardian

Compilar a partir do Código-Fonte

# Clonar o repositório
git clone https://github.com/mtpanissa/PKIGuardian.git
cd PKIGuardian

# Compilar a CLI
cd src/PKIGuardian.CLI
dotnet build -c Release

# Executar a CLI
dotnet run -- --help

# Ou publicar como binário autocontido
dotnet publish -c Release -r linux-x64 --self-contained
# Binário estará em bin/Release/net10.0/linux-x64/publish/

Verificar a Instalação

pkiguardian --version
# Saída: PKIGuardian CLI v1.0.0 (Phase 12)

Configuração

Configuração Inicial

Execute o assistente de configuração:

pkiguardian config setup

Você será solicitado a fornecer:

  • URL da API: Seu endpoint da API do PKIGuardian (ex.: https://api.pkiguardian.com)
  • Método de Autenticação: Chave de API, Token JWT ou mTLS
  • Formato de Saída Padrão: table, json ou csv

Arquivo de Configuração

A CLI armazena a configuração em ~/.pkiguardian/config.json:

{
  "current_profile": "default",
  "profiles": {
    "default": {
      "api_url": "https://api.pkiguardian.com",
      "auth_method": "api_key",
      "output_format": "table",
      "verify_ssl": true,
      "timeout": 30
    }
  }
}

Variáveis de Ambiente

Substitua a configuração com variáveis de ambiente:

export PKIGUARDIAN_API_URL="https://api.pkiguardian.com"
export PKIGUARDIAN_API_KEY="sua-chave-de-api"
export PKIGUARDIAN_OUTPUT_FORMAT="json"

Uso Básico

Estrutura de Comandos

pkiguardian <recurso> <ação> [opções] [flags]

Exemplos:

pkiguardian certificate list
pkiguardian iot device get <id-dispositivo>
pkiguardian approval approve <id>

Obter Ajuda

# Ajuda geral
pkiguardian --help

# Ajuda do recurso
pkiguardian certificate --help

# Ajuda do comando
pkiguardian certificate list --help

Flags Globais

Disponíveis em todos os comandos:

Flag Descrição Exemplo
--format Formato de saída (table, json, csv) --format json
--profile Usar perfil específico --profile production
--verbose Saída detalhada --verbose
--debug Modo de depuração --debug
--no-color Desabilitar saída colorida --no-color
--output Salvar saída em arquivo --output resultado.json

Comandos Comuns

Gerenciamento de Certificados

Listar certificados:

# Todos os certificados
pkiguardian certificate list

# Filtrar por status
pkiguardian certificate list --status expiring --days 30

# Filtrar por ambiente
pkiguardian certificate list --environment production

# Combinar filtros
pkiguardian certificate list --status active --type web-server --format json

Obter detalhes de um certificado:

# Por ID
pkiguardian certificate get <id-certificado>

# Obter em formato PEM
pkiguardian certificate get <id-certificado> --format pem --output cert.pem

Solicitar novo certificado:

# Usando um modelo
pkiguardian certificate request \
  --template web-server \
  --hostname api.example.com \
  --sans "www.example.com,example.com"

# Parâmetros personalizados
pkiguardian certificate request \
  --common-name "api.example.com" \
  --organization "Empresa S.A." \
  --key-algorithm RSA-4096 \
  --validity 365

Renovar um certificado:

# Renovar automaticamente com os mesmos parâmetros
pkiguardian certificate renew <id-certificado>

# Renovar com aprovação automática
pkiguardian certificate renew <id-certificado> --auto-approve

Revogar um certificado:

pkiguardian certificate revoke <id-certificado> \
  --reason key-compromise \
  --comment "Suspeita de exposição da chave privada"

Fluxo de Aprovação

Listar aprovações pendentes:

pkiguardian approval list --pending

Aprovar uma solicitação:

pkiguardian approval approve <id-aprovacao> \
  --comment "Verificado e aprovado"

Rejeitar uma solicitação:

pkiguardian approval reject <id-aprovacao> \
  --reason "Documentação obrigatória não apresentada"

Gerenciamento de Dispositivos IoT

Listar dispositivos:

# Todos os dispositivos
pkiguardian iot device list

# Filtrar por tipo
pkiguardian iot device list --type lorawan

# Filtrar por status
pkiguardian iot device list --status active

Obter detalhes de um dispositivo:

pkiguardian iot device get <id-dispositivo>

Cadastrar um dispositivo:

pkiguardian iot device enroll <id-dispositivo> \
  --type lorawan \
  --profile perfil-dispositivo.json

Gerar QR code para Provisionamento Zero-Touch:

pkiguardian iot zerotouch generate-qr <id-dispositivo> \
  --output qr-cadastro.png

Verificar atestação TPM:

pkiguardian iot attestation verify <id-dispositivo>

Análises

Obter previsões ML:

# Previsões para os próximos 30 dias
pkiguardian analytics predictions --days 30

# Apenas previsões de alto risco
pkiguardian analytics predictions --min-score 0.8 --format json

Recomendações de otimização de custos:

# Ver recomendações
pkiguardian analytics costs optimize

# Aplicar uma recomendação
pkiguardian analytics costs optimize --apply --id <id-recomendacao>

Análise de uso:

pkiguardian analytics usage \
  --start 2026-01-01 \
  --end 2026-02-01 \
  --format csv \
  --output relatorio-uso.csv

Previsão de capacidade:

pkiguardian analytics forecast --months 12

Calculadora TCO:

pkiguardian analytics tco \
  --certificates 10000 \
  --automation-level high \
  --format json

Descoberta e Segurança

Varrer endpoints:

# Varrer um domínio
pkiguardian discovery scan --target example.com

# Varrer portas específicas
pkiguardian discovery scan \
  --target example.com \
  --ports 443,8443,9443

Varredura de segredos:

# Varrer um repositório
pkiguardian discovery secrets \
  --repo /caminho/para/repo \
  --recursive \
  --format json

Verificar exposição externa:

pkiguardian discovery exposure \
  --source shodan \
  --export relatorio-exposicao.json

Detectar certificados não autorizados:

pkiguardian discovery rogue --domain example.com

Análise de cifras:

pkiguardian discovery ciphers --target api.example.com:443

Protocolos Avançados

Gerenciamento de workloads SPIFFE:

# Listar workloads
pkiguardian spiffe workload list

# Registrar workload
pkiguardian spiffe workload register \
  --spiffe-id spiffe://example.com/web \
  --selector k8s:pod-label:app:web

Assinatura de certificados SSH:

# Assinar chave de host
pkiguardian ssh hostkey sign \
  --hostname servidor.example.com \
  --principals servidor.example.com,192.168.1.1

# Assinar chave de usuário
pkiguardian ssh userkey sign \
  --username alice \
  --principals alice,admin

Cadastro S/MIME:

pkiguardian smime enroll --email alice@example.com

Assinatura de documentos:

pkiguardian signing sign-document \
  --file documento.pdf \
  --cert-id <id> \
  --output documento-assinado.pdf

Assinatura de código:

pkiguardian signing sign-code \
  --artifact app.exe \
  --cert-id <id> \
  --output app-assinado.exe

Ferramentas DevOps

Certificado-como-Código:

# Validar YAML
pkiguardian devops cert-as-code validate --file certificados.yaml

# Aplicar configuração
pkiguardian devops cert-as-code apply --file certificados.yaml

ChatOps:

# Testar mensagem
pkiguardian devops chatops test-message \
  --channel #seguranca \
  --message "Notificação de teste"

Certificados de desenvolvimento local:

pkiguardian devops local-cert generate \
  --hostname localhost \
  --output ./certs/

Gerenciamento de plugins:

# Listar plugins
pkiguardian devops plugin list

# Instalar plugin
pkiguardian devops plugin install <nome-do-plugin>

Auditoria e Relatórios

Ver logs de auditoria:

pkiguardian audit log \
  --start 2026-01-01 \
  --end 2026-02-01 \
  --user alice \
  --format json

Gerar relatório:

pkiguardian report generate \
  --template expiring-certs \
  --output relatorio.pdf

Formatos de Saída

Formato Tabela (Padrão)

Saída em tabela legível por humanos:

pkiguardian certificate list --format table

Saída:

ID       Nome Comum           Expiração   Status    Tipo
-------- -------------------- ----------- --------- -----------
cert-001 api.example.com      2026-12-31  Ativo     Servidor Web
cert-002 mail.example.com     2026-06-15  Expirando E-mail
cert-003 vpn.example.com      2026-03-20  Ativo     VPN

Formato JSON

JSON legível por máquinas:

pkiguardian certificate list --format json

Saída:

{
  "certificates": [
    {
      "id": "cert-001",
      "subjectCN": "api.example.com",
      "expiry": "2026-12-31T23:59:59Z",
      "status": "Active",
      "type": "WebServer"
    }
  ],
  "total": 1
}

Formato CSV

CSV compatível com planilhas:

pkiguardian certificate list --format csv --output certs.csv

Saída:

ID,Nome Comum,Expiração,Status,Tipo
cert-001,api.example.com,2026-12-31,Ativo,Servidor Web
cert-002,mail.example.com,2026-06-15,Expirando,E-mail

Perfis

Os perfis permitem gerenciar múltiplos ambientes.

Criar Perfil

pkiguardian config profile add production \
  --api-url https://prod-api.pkiguardian.com \
  --auth-method api-key

Listar Perfis

pkiguardian config profile list

Saída:

NOME        URL DA API                              ATIVO
default     https://api.pkiguardian.com             Sim
production  https://prod-api.pkiguardian.com        Não
staging     https://staging-api.pkiguardian.com     Não

Alternar Perfil

pkiguardian config profile use production

Usar Perfil para um Único Comando

pkiguardian certificate list --profile production

Autenticação

Autenticação por Chave de API

  1. Gere a chave de API na Interface Web (Configurações > Chaves de API)
  2. Configure:
pkiguardian config set api-key <sua-chave-de-api>

Ou use variável de ambiente:

export PKIGUARDIAN_API_KEY="sua-chave-de-api"

Autenticação por Token JWT

# Login
pkiguardian auth login --username alice --password <senha>

# O token é armazenado na configuração
# Renovar token
pkiguardian auth refresh

Autenticação por mTLS

pkiguardian config set auth-method mtls
pkiguardian config set client-cert ./client-cert.pem
pkiguardian config set client-key ./client-key.pem

Uso Avançado

Pipes e Scripts

# Obter IDs de certificados expirando em breve
pkiguardian certificate list --status expiring --days 30 --format json | \
  jq -r '.certificates[].id'

# Renovar todos os certificados expirando
pkiguardian certificate list --status expiring --days 30 --format json | \
  jq -r '.certificates[].id' | \
  xargs -I {} pkiguardian certificate renew {}

# Exportar todos os certificados
pkiguardian certificate list --format json | \
  jq -r '.certificates[] | "\(.id),\(.subjectCN),\(.expiry)"' > certs.csv

Operações em Lote

# Revogar múltiplos certificados
cat ids-certificados.txt | while read cert_id; do
  pkiguardian certificate revoke $cert_id --reason superseded
done

Scripts Personalizados

Exemplo: Monitorar certificados expirando

#!/bin/bash
# verificar-expirando.sh

DIAS=30
SAIDA=$(pkiguardian certificate list --status expiring --days $DIAS --format json)
TOTAL=$(echo $SAIDA | jq '.total')

if [ $TOTAL -gt 0 ]; then
  echo "Atenção: $TOTAL certificados expirando em $DIAS dias"
  echo $SAIDA | jq -r '.certificates[] | "\(.subjectCN) - \(.expiry)"'
  exit 1
else
  echo "Todos os certificados estão válidos"
  exit 0
fi

Integração com CI/CD

GitHub Actions:

- name: Verificar Status dos Certificados
  run: |
    pkiguardian certificate list --status expiring --days 30 --format json
    COUNT=$(pkiguardian certificate list --status expiring --days 30 --format json | jq '.total')
    if [ $COUNT -gt 0 ]; then exit 1; fi
  env:
    PKIGUARDIAN_API_KEY: ${{ secrets.PKIGUARDIAN_API_KEY }}

GitLab CI:

verificar_certificados:
  script:
    - pkiguardian certificate list --status expiring --days 30
  only:
    - schedules

Solução de Problemas

Problemas de Conexão

# Testar conexão
pkiguardian config test

# Modo detalhado para depuração
pkiguardian certificate list --verbose --debug

Erros de Autenticação

# Verificar chave de API
pkiguardian config get api-key

# Fazer login novamente
pkiguardian auth login

# Verificar perfil
pkiguardian config profile list

Comando Não Encontrado

# Verificar instalação
which pkiguardian

# Verificar PATH
echo $PATH

# Usar caminho completo
/usr/local/bin/pkiguardian --version

Próximos Passos

Suporte

Última Atualização: Maio de 2026 | Versão: Phase 12

Relacionados

Primeiros Passos — Interface Web

Bem-vindo à Interface Web do PKIGuardian! Este guia irá ajudá-lo a começar a usar a interface web.

Ler mais

Primeiros Passos — Aplicativo Móvel MAUI

Bem-vindo ao PKIGuardian MAUI! Este guia irá ajudá-lo a instalar e usar o aplicativo móvel para iOS

Ler mais

Manual do Usuário — PKIGuardian

Bem-vindo ao Manual do Usuário do PKIGuardian. Este manual oferece orientações completas para todos os usuários da

Ler mais