Código de Exemplo da IBM

Este repositório contém código Python para gerenciar os IBM Security Appliances usando suas respectivas APIs REST. O appliance ISAM possui o código mais maduro.

O código para o appliance ISDS está em desenvolvimento.

O código para o appliance ISVG é totalmente novo (testado apenas com 10.0.1.0 e superiores).

Requisitos

É necessário Python v3.9 ou superior para este pacote.

Os seguintes pacotes Python são obrigatórios:

1. requests - para fazer chamadas REST API
2. PyYAML - para o código de exemplo funcionar
3. jmespath - é necessário para o código de exemplo

Os seguintes pacotes Python são opcionais:

1. cryptography - para executar ações em certificados (usado para idempotência em management_ssl_certificate)
2. python-dateutil - utilitários de data (usado para idempotência em management_ssl_certificate)

Os appliances precisam ter um endereço IP definido para sua LMI. Isso pode significar que os appliances já tiveram sua configuração inicial concluída com aceitação da licença.

Verificação TLS habilitada (v2024.4.5)

Estas alterações são compatíveis com versões anteriores. Por padrão, não verificamos, mas sempre exibimos um aviso:

Certificate verification has been disabled. Python is NOT verifying the SSL
certificate of the host appliance and InsecureRequestWarning messages are

being suppressed for the following host:

https://{0}:{1}

To use certificate verification:

1. When the certificate is trusted by your Python environment:
   Instantiate all instances of ISAMAppliance with verify=True or set
   the environment variable IBMSECLIB_VERIFY_CONNECTION=True.
2. When the certificate is not already trusted in your Python environment:
   Instantiate all instances of ISAMAppliance with the verify parameter
   set to the fully qualified path to a CA bundle.

See the following URL for more details:
https://requests.readthedocs.io/en/latest/user/advanced/#ssl-cert-verification

Para corrigir este aviso de validação de certificado, considere as instruções abaixo:

Uso correto:

Se você tiver o certificado em disco em algum lugar, instancie o ISAMAppliance com:

ISAMAppliance(…, verify=<path to cert>)

Você pode recuperá-lo do appliance usando um comando como:

openssl s_client -connect ${HOSTNAME}:${PORT} </dev/null 2>/dev/null | openssl x509 -outform pem >  isamAppliance.pem

Se o certificado já for confiável no seu ambiente Python, instancie o ISAMAppliance com:

ISAMAppliance(…, verify=True)

ou defina a variável de ambiente: IBMSECLIB_VERIFY_CONNECTION=true

Se você receber erros sobre o nome do host não corresponder ao certificado:

Isso pode ser semelhante a:

<stack trace>

…

    raise CertificateError("hostname %r doesn't match %r" % (hostname, dnsnames[0]))

urllib3.util.ssl_match_hostname.CertificateError: hostname '192.168.42.111' doesn't match 'appliance.ibm.com'

Garanta que o nome do host usado ao instanciar seu ISAMAppliance corresponda ao Subject Alternative Name do certificado.

Verifique com:

openssl x509 -in <cert-pem-file> -text

Exemplo:

$ openssl x509 -in /path/to/appliance.pem -text

Certificate:

Data:
    Version: 3 (0x2)
    …
        X509v3 Subject Alternative Name:
            DNS:appliance.ibm.com

…

O seguinte gerará erros:

ISAMAppliance(host=”192.168.42.111”, lmi_port=443, verify=/path/to/appliance.pem)

pois o host não corresponde ao Subject Alternative Name. Em vez disso, use:

ISAMAppliance(host=”appliance.ibm.com”, lmi_port=443, verify=/path/to/appliance.pem)

Versionamento

Este pacote usa uma data para versionamento. Por exemplo: "2017.03.18.0"

É a data em que o pacote é lançado, com um número de sequência no final para lidar com os casos em que há vários lançamentos no mesmo dia (espera-se que seja incomum).

Recursos

Este pacote Python oferece os seguintes recursos:

1. Fácil de usar - os detalhes de fazer uma chamada REST são tratados dentro de uma classe de appliance
2. Layout intuitivo do pacote de código e nomes que mapeiam para a interface gráfica do appliance
3. Idempotência - funções que fazem atualizações consultam o appliance para comparar os dados fornecidos e verificar se uma alteração é necessária antes de efetuar a mudança.
4. As etapas de Commit e Deploy são fornecidas separadamente para permitir flexibilidade na sua execução
5. Logging padrão incluído - com a capacidade de definir níveis de logging.
6. Os parâmetros das funções usarão valores padrão sempre que possível.
7. Uma opção force é fornecida para sobrepor a idempotência.
8. Funções de comparação são fornecidas - recebem a saída JSON e fornecem uma comparação significativa.

Formato de Retorno de Dados da Função

{
    rc:       <0 for success, higher for errors>
    changed:  <True or False>
    warnings: <List of strings with warnings - e.g. incompatible version>
    data:     <JSON data returned by appliance REST API that the function called>
}

Nota: é preferível retornar avisos em vez de enviar um rc diferente de zero.

Organização do código

Classes de Appliance

Uma classe abstrata ibmappliance é estendida para criar uma classe para cada appliance suportado aqui. Atualmente, isso inclui os appliances ISAM e ISDS.

Classes de Usuário

Uma classe abstrata User é estendida para cada tipo de usuário necessário. Para ISAM, há um usuário para acesso ao appliance e outro para autenticação no Web Runtime (Policy Server).

Layout dos pacotes ISAM

Existem quatro pacotes ISAM principais - base, web, aac e fed. web contém todos os componentes necessários para configurar a funcionalidade web, incluindo LDAP embutido, runtime e recursos que são ativados como parte do módulo wga. aac contém recursos ativados como parte do módulo mga, e fed os da federation. base contém todo o resto - incluindo aac, fed, runtime e Audit Configuration (estes são comuns a e e, portanto, ficam em ).

Nomes de Pacotes e Arquivos

Os nomes de pacotes e arquivos foram criados com a seguinte intenção:

1. Manter nomes que correspondam ao que está na interface gráfica (LMI para o appliance ISAM).
2. Cada arquivo deve conter apenas um de cada tipo de função (ver lista abaixo) - ou seja, apenas um add().
3. Agrupar funções relacionadas - uma de cada tipo - em um arquivo.
4. O URI para as chamadas REST API em um arquivo será o mesmo e gerencia uma "funcionalidade" do appliance.

Utilitários

Contém funções diversas que são genéricas e independentes de qualquer IBM Appliance, por exemplo, json_compare().

Tipos de Função

get_all()

Esta função normalmente retorna todos os objetos relacionados a essa funcionalidade.

get()

Esta função retorna os detalhes de um objeto específico.

set()

Esta função determina se o objeto a ser manipulado existe; se não existir, chama add(); caso contrário, chama update(). Nos casos em que não há update(), ela compara para ver se há diferença entre o valor existente no appliance e o valor que está sendo definido pela função - se forem diferentes, ela executa delete() no objeto antes de chamar add().

add()

Verifica se o objeto já existe - se existir, pula; caso contrário, adiciona.

update()

Verifica se o objeto já existe - se existir, verifica se uma atualização é necessária antes de fazer a alteração; caso contrário, não faz nada.

delete()

Verifica se o objeto já existe - se existir, exclui; caso contrário, não faz nada.

import_<>()

"import" é uma palavra reservada, portanto há um sufixo para indicar o que importar (por exemplo, arquivo ou chave). Esta função verifica se o objeto existe antes de importá-lo.

export_<>()

A exportação verifica se o objeto existe antes de exportá-lo - ao exportar para um arquivo, e o arquivo já existir, não exportará novamente. Exportação

compare()

Compare recebe a saída JSON das funções get_all() e a compara. Ela remove do JSON os dados que são exclusivos de cada appliance (por exemplo, valores UUID). O valor deleted_keys retornado lista as chaves JSON que foram removidas antes da comparação.

Parâmetros de Função

Objeto do appliance

Crie um objeto do appliance e passe-o para a função. O appliance e o objeto User necessários são classes que permitem extensões futuras, como autenticação por certificado em vez de nome de usuário/senha.

check_mode

O padrão é False; passe True para retornar e não fazer alterações. O sinalizador "changed" será definido como True se alterações forem detectadas.

force

O padrão é False; passe True para sobrepor a lógica de idempotência.

Outros Parâmetros

Os outros parâmetros correspondem exatamente à documentação da REST API. A intenção era fazer referência à documentação da REST API e não ter que repeti-la. Consulte a documentação da REST API para obter detalhes.

Como Adicionar e Fazer Alterações

Abra uma issue no GitHub quando um bug for descoberto ou quando houver REST APIs não cobertas por este pacote. Forneça notas detalhadas junto com os logs de trace ao relatar um bug.

Licença

O conteúdo deste repositório é open-source sob a licença Apache 2.0.

Copyright 2017 International Business Machines

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.