Criação do endpoint '/health'

[Maxwbh]

Criado /health
Para Retornar que o serviço esta ativo e no ar;

[mbcosta]

Valeu @Maxwbh obrigado pelo PR, como o @rvalyi disse seria melhor se pudesse dividir o PR, de forma geral em qualquer projeto é recomendado fazer um PR com o menor número de alterações possíveis e dentro de um escopo ou assunto específico, isso é importante porque pode reduzir o tempo de Revisão e permite ter um foco melhor nas discussões sobre cada alteração por poderem ser vistas em separado e de forma independente, por exemplo dividindo esse PR em:

• Arquivos "ignore"
• Cliente Python
• LOG Completo
• Alterações Dockerfile
• Alterações Gemfile
• Alterações no Puma
• Check Health
• Uso do campo documento_numero
• Testes
• Documentações
• Serviço Render
• ...
• Devidos Créditos por Autoria

Isso já seria bem melhor para o processo de Revisão.

OBS.: Na atualização que você fez nesse PR em 06/01/2026, um force-push, parece que acabou criando um problema todos os commits do repositório foram incluídos nesse PR, o que está gerando esses conflitos de arquivos, isso pode ter acontecido por algum comando errado, talvez um rebase, você precisa corrigir essa questão para dar continuidade ao processo de Revisão e Merge, para corrigir você pode tentar baixar o projeto atual, incluir o seu e em seguida fazer cherry-picking dos seus commits resolvendo eventuais conflitos, e como comentado acima será melhor se você considerar separar esse PR. Eu já estava buscando fazer a Revisão antes disso então por favor avise caso algo que está na Revisão abaixo esteja desatualizado.

Sobre o seu PR tem coisas interessantes como o Cliente Python e a estrutura de documentação, mas a principal questão não é técnica e sim saber qual é o seu objetivo em relação a:

Você quer trabalhar e colaborar com esse projeto da API mantido pela Akretion e o BRCobranca mantido pelo Kivanio, os projetos originais, ou você quer fazer um Fork desses dois projetos?

É preciso você responder a essa questão inicial porque não faz muito sentido alguém fazer um Fork e criar um PR no repositório original mudando as referencias sobre quem são os Autores, Mantenedores e links dos Projetos Originais para um Fork, já que são outras pessoas e endereços:

https://github.com/Maxwbh/boleto_cnab_api/blob/master/Dockerfile#L27

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/development/brcobranca-fork.md

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/api/troubleshooting.md

https://github.com/Maxwbh/boleto_cnab_api/blob/master/SECURITY.md

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/ARCHITECTURE.md

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/TODO_INTEGRACAO.md

Sobre fazer um Fork

O que posso dizer é que de uma forma geral é uma atitude considerada extrema que ocorre na maioria dos casos quando os Desenvolvedores do projeto tem alguma forte divergência ou alguém pretende redefinir a direção do projeto ou o projeto ficou abandonado "órfão", na maioria dos casos os Desenvolvedores que trabalham em projetos de Código Aberto e Publico buscam sempre que possível colaborar com os projetos originais, inclusive buscando contornar divergências, basicamente porque é a união de diversos desenvolvedores que torna o projeto forte e que também acaba reduzindo os custos de manutenções, atualizações e melhorias para todos os envolvidos.

Se todo desenvolvedor que encontrar um projeto de Código Aberto Publico decidir fazer um Fork ao invés de buscar colaborar com o Projeto Original é quase certo que todos esses Projetos, incluindo os Forks, vão "morrer".

Se o objetivo de qualquer projeto é ter o melhor código possível, e nesses casos os projetos são de Código Aberto e Públicos, o que é melhor somar ou dividir forças?

Como esse parece ser o seu primeiro contato público com esse projeto, será importante saber se você tem ou visualiza alguma divergência incontornável com o projeto ou com os Desenvolvedores originais e o que levou você a optar em querer fazer um Fork, teria alguma divergência? Qual? Ou teria algum outro motivo? Ou você não está familiarizado em colaborar com Projetos Públicos de Código Aberto e precisa de ajuda sobre qual a forma de abordar e colaborar com esse tipo de projeto?

Em favor de você optar por colaborar com o projeto ao invés de fazer um Fork

A Akretion criou, financiou e mantém esse projeto desde 16/06/2017

https://github.com/akretion/boleto_cnab_api/commits/master/?after=825aaab4ee50183d0a3aaef8d712d328530e0c64+69

Em 14/07/2017 foi inciado o processo para integrar essa API ao Projeto que Localiza o Odoo no Brasil

https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_account_payment_order

O repositório do BRCobranca desde 08/12/2017 faz referencia a esse projeto da API

https://github.com/kivanio/brcobranca

https://github.com/kivanio/brcobranca/commits/master/README.md

kivanio/brcobranca@9eb15ed

Desde 29/01/2018 nós já sabemos que a implementação da API estava funcional

https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_account_payment_brcobranca

A partir de 2021 é possível ver que foram feitos diversos PRs nos quais é usada essa API porém por Desenvolvedores de outras Empresas https://github.com/OCA/l10n-brazil/pulls?page=5&q=is%3Apr+is%3Aclosed+brcobranca , portanto sem uma ligação direta com a Akretion, o que demonstra o uso real e efetivo da implementação por terceiros, uma validação de pares.

Desde de 13/09/2024 o projeto que Localiza o Odoo no Brasil passou a fazer testes reais e automáticos a cada novo PR usando essa API, desde a criação da Imagem baseada nesse repositório a testes que geram Boletos, Arquivos de Remessa e o Processamento do Arquivo de Retorno usando a API

• [14.0][CI] l10n_br_account_payment_brcobranca: Github CI with live API OCA/l10n-brazil#3361

Veja a configuração

https://github.com/OCA/l10n-brazil/blob/16.0/.github/workflows/test.yml#L52

Devido a natureza dos projetos existe muito mais chance de surgir pelo menos um novo PR uma vez ao mês no Projeto da Localização do que aqui, até por isso desde 07/10/2024 a API usa a imagem Alpine Latest e não uma versão Fixa como é recomendado por muitos Guias de Segurança de Imagens

https://docs.docker.com/build/building/best-practices/

• [UPD] Atualizando OS Alpine 3.20.2, README com informações sobre o Alpine e padronização do Dockerfile #36

Porque com isso nós sabemos que se ocorrer alguma falha causada pela atualização isso vai aparecer nos Testes da Localização, por exemplo em um PR qualquer é possível ver a criação de uma nova imagem baseada nesse repositório

https://github.com/OCA/l10n-brazil/actions/runs/20492789978/job/58887819466?pr=4299#step:2:247

Os testes que são realizados estão no arquivo https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_brcobranca/tests/test_brcobranca.py , são gerados os Boletos e Arquivos de Remessa dos seguintes casos

https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_account_payment_order

Os testes de Processamento de Arquivos de Retorno são feitos apenas para os casos UNICRED/400, AILOS/240 e Nordeste/400, parece ser suficiente mas outros testes podem ser adicionados.

O LOG dos testes com os resultados confirmando que houve a criação de Boletos, Arquivos de Remessa e o Processamento de um Arquivo de Retorno podem ser visto no mesmo PR do exemplo acima

https://github.com/OCA/l10n-brazil/actions/runs/20492789978/job/58887819466?pr=4299#step:9:4181

Outros testes são feitos na sequencia até a linha https://github.com/OCA/l10n-brazil/actions/runs/20492789978/job/58887819466?pr=4299#step:9:4243

A Akretion trabalha desde de 2009 em projetos de Código Aberto e Públicos, veja https://akretion.com/pt-BR/empresa e https://github.com/akretion , com foco principal no Odoo e no Brasil no Projeto que Localiza o Odoo consequentemente isso levou a empresa a criar ou colaborar em outros projetos relacionados ao uso de um ERP no Brasil por exemplo:

• https://github.com/erpbrasil
• https://github.com/akretion/nfelib
• etc https://github.com/akretion

Então quem participa de um desses projetos pode acabar a vir participar de outros diversos projetos, dessa forma criando ou se integrando a uma rede de desenvolvedores que tem o interesse em comum de trabalhar em projetos que viabilizam a implementação de ERPs, E-commerce, outros tipos de negócios, Programas de Gestão de Empresas Públicas, Instituições e Organizações Sem Fins Lucrativos, etc usando Código Aberto.

Também é importante ver o Histórico de Contribuições dos projetos para deixar claro o compromisso e empenho ao longo de anos de diversas pessoas e empresas que buscaram e buscam contribuir com esses projetos.

O BRCobranca é um projeto que existe desde de 28/03/2009 portanto em 28/03/2026 vai completar 17 anos

https://github.com/kivanio/brcobranca/stargazers

https://github.com/kivanio/brcobranca/watchers

O projeto da API existe desde 10/06/2017

https://github.com/akretion/boleto_cnab_api/graphs/contributors

OBS.: Na primeira imagem dessa seção, a tela do Histórico de Commits mostra a data de 16/06/2027 mas na tela com o gráfico do Contributors aparece 10/06/20217, uma diferença de 6 dias, qual deve ser considerada como a Data de Criação? E por que existe essa diferença? Por enquanto acredito que a data de 10/06/2027 é referente a criação do Projeto no github e de 16/06/2017 é referente ao primeiro commit efetivo, então a data a ser considerada seria a de 16/06/2017.

https://github.com/akretion/boleto_cnab_api/stargazers

https://github.com/akretion/boleto_cnab_api/watchers

Em 10/06/2027 ou 16/06/2027, daqui cerca de um ano e meio, esse projeto da API vai completar 10 Anos, uma marca para qualquer projeto, desde casos complexos como Kernel, Sistemas Operacionais, Interfaces Gráficas ou mesmo simples Bibliotecas ou simples API como está, que como vem sendo usada pelo projeto que Localiza o Odoo no Brasil acredito que tem grandes chances de alcançar essa marca, o futuro vai depender mais do que vai acontecer ao CNAB nos próximos anos, se a modernização do sistema bancário vai tornar-lo obsoleto e consequentemente esses projetos também ou se vamos adapta-los com o tempo, a ver, bom mas cabe a você avaliar o que é melhor para o seu proposito e se vai querer colaborar com os projetos originais ou fazer um fork.

Sobre formas de implementação, segurança e infra-estrutura em geral

Como vi alguns comentários na sua Documentação que parecem terem sido feitos em relação a implementação, segurança e a infra-estrutura em geral vou colocar alguns pontos inciais sobre isso, podemos debater ouvindo você sobre outros casos de uso e formas diferentes de implementação e assim poder avaliar os motivos das inclusões e alterações.

Hoje pelo o que vejo, e conheço, uma das melhores formas de implementar uma Aplicação X é com o Docker Compose, digo isso porque ao poder separar as imagens em Aplicação, Banco de Dados, Boleto CNAB API, Outras N Imagens de APIs usadas pela Aplicação isso acaba resolvendo vários problemas em relação a infra-estrutura e aplicações, desde:

Reprodução simples de ambientes complexos

Um exemplo simples relacionado a essa API pode ser visto no PR

• [UPD+WIP] Odoo v16 Debian Trixie, Python 3.12.12 e PostgresSQL 18.1-trixie docky-odoo-brasil#20

Com simples comandos

$ git clone -b UPD-v16_debian_trixie_python_3_12_12 https://github.com/akretion/docky-odoo-brasil/ odoo-brasil-16-debian
$ cd odoo-brasil-16-debian
$ docker --debug compose build
$ docker compose run --rm --service-ports --use-aliases -e NOGOSU=True odoo gosu odoo bash
odoo@dev-odoo-brasil-16:~$

É possível ter um ambiente de testes, que demonstra esse conceito, nesse exemplo a Aplicação é o Odoo, o Banco de Dados é PostgreSQL e o Boleto CNAB API também é implementado, com isso é possível testar a criação de Boletos, Arquivos CNAB e Processar Arquivos de Retorno usando o Odoo que por ter o Código Aberto permite uma Auditoria Real já que sendo publico todo o código pode ser visto e assim pode ser estudado e usado como referencia.

Então em qualquer Sistema Operacional onde seja possível instalar o Docker e o Docker Compose vai ser possível testar esse ambiente de exemplo, e além disso é possível ver que dessa forma diversos desenvolvedores podem trabalhar em um mesmo projeto complexo sem se preocupar com os detalhes das diversas bibliotecas instaladas e após uma atualização todos conseguem re-criar a Imagem e testar o mesmo ambiente em diferentes SO, isso há alguns anos atrás era um grande problema e mesmo hoje ainda é um problema em outros tipos de implementação que não usam o Docker ou algo semelhante.

Controle do Ambiente onde Aplicação roda

Tanto o Sistema Operacional quanto os pacotes instalados podem ser definidos em uma versão especifica e se necessário com patchs, com isso é possível atender os mais diversos cenários, mas também reduzindo riscos de falhas causadas por programas desnecessários, as atualizações e manutenções, ou mesmo se necessário um rollback, são mais tranquilos por poderem ser feitos testes e simulações, além de existir um Histórico de alterações dessa infra-estrutura porque é usado o GIT.

Segurança

O uso de Contêineres em si já é algo visando a Segurança, por isolar/encapsular em diferentes partes/Imagens o que for necessário para rodar uma determinada Aplicação, no exemplo acima é possível ver que o Banco de Dados/PostgreSQL está em uma Imagem diferente da Imagem da Aplicação/Odoo, o que em muitas outras formas de implementação isso não aconteceria, mas que dessa forma traz o beneficio de ter em cada Imagem apenas as Bibliotecas minimas o que reduz a possibilidade de falhas, facilita manutenções, correções e melhorias e também cria uma "barreira" de segurança entre as Imagens porque se uma imagem for comprometida por um acesso indevido o acesso a outra Imagem pode não ser tão simples em relação a se o Banco de Dados de Aplicação estivessem juntas em uma mesma Imagem ou SO, outro exemplo de um caso hipotético em muitas implementações o computador ou a Imagem que está em contato com a Internet provavelmente só tem essa função, ela não roda a Aplicação e nem o Banco da Dados e em caso de algum problema grave o SO que roda o Docker pode simplesmente desligar ou reiniciar o contêiner. Mas tem outros aspectos sobre a Segurança que são importantes ter consciência:

• Como em todos os Sistemas Operacionais Linux qualquer Serviço/Aplicação que não é essencial roda com um Usuário especifico e Restrito, muitas Aplicações até mostram um Alerta ou mesmo bloqueiam a execução de um Serviço usando o Usuário Root, que é o Administrador no caso do Linux, isso significa que qualquer Comando ou Script Maliciosos que venham a ser de alguma forma executados por um contêiner configurado com o Usuário Restrito as Permissões de Acesso irão simplesmente negar/bloquear essa ação, que é o caso dessa API

https://github.com/akretion/boleto_cnab_api/blob/master/Dockerfile#L6

https://github.com/akretion/boleto_cnab_api/blob/master/Dockerfile#L30

• As configurações de Rede são fundamentais para a Segurança da API, usando como exemplo o PR do Odoo, o Docker Compose permite por exemplo definir as Portas Expostas nesse caso a do PostgreSQL e da Boleto CNAB API apenas para a rede interna

https://github.com/akretion/docky-odoo-brasil/blob/UPD-v16_debian_trixie_python_3_12_12/dev.docker-compose.yml#L19

  boleto_cnab_api:
    image: ghcr.io/akretion/boleto_cnab_api:latest
    networks:
      - local

Isso acaba diminuindo a "Superfície de Ataque", em outras palavras quanto mais fechada a sua rede e as portas que você precisa expor na internet melhor, como esse micro-serviço foi pensado para ser usado por uma Aplicação X, já que não armazena nada, provavelmente em qualquer implementação a porta que deverá ser exposta na internet é a de um Firewall que pode acabar redirecionando ou para um Servidor de Páginas Apache, Nginx, etc e em seguida para Aplicação X ou mesmo diretamente para a Aplicação X, mas não a porta da API.

Ou você tem um caso de uso, uma implementação, em que se justifica expor a porta do serviço na internet?

Então no caso desse projeto a Segurança tem dois aspectos importantes:

1) O que depende e é responsabilidade da API e do Projeto

A Pesquisa e Desenvolvimento buscando atualizar e manter os arquivos de configuração e implementação da API dentro dos melhores padrões de segurança, por exemplo o arquivo Dockerfile ou definindo para usar um Usuário Restrito para rodar a Aplicação (o que em si já bloqueia inúmeras ameaças já que nenhum comando que possa afetar o SO de forma irreversível vai conseguir ser executado), manter o SO e as Bibliotecas atualizadas, o que é feito usando a última versão do Alpine, definindo no Gemfile as versões mais atualizadas possíveis e o uso de "robôs" no github que monitoram as versões das bibliotecas e criam automaticamente PRs de Atualização, testes constantes que nesse caso são feitos usando o Projeto da Localização Brasileira e orientações e recomendações sobre a infra-estrutura ideal de rede para ter a melhor segurança possível.

2) O que não depende e não é responsabilidade da API e do Projeto

A infra-estrutura onde a API vai ser implementada e a Segurança da Aplicação X que vai usar a API, porque podem ser muitas e variadas, nós podemos apenas recomendar que por segurança a API esteja dentro de uma sub-rede acessada apenas pela Aplicação X e consequentemente que a API não seja exposta na Internet, ou se for necessário trafegar pela Internet que seja via VPN, mas isso é apenas uma RECOMENDAÇÃO porque esse Projeto não tem como se responsabilizar sobre como é a Infra-Estrutura onde a API é implementada ou mesmo o nível de Segurança da Aplicação X que vai usar a API por serem muitas formas e em alguns casos desconhecidas.

Se a recomendação desse segundo ponto for seguida vai acabar reduzindo drasticamente a possibilidade de alguma falha grave de segurança causada pela API.

Dentro desse contexto seguem algumas questões relacionadas:

Por que você acredita ser necessário recomendar que não sejam criados Issues sobre Falhas de Segurança no projeto?

https://github.com/Maxwbh/boleto_cnab_api/blob/master/SECURITY.md

Eu até entendo essa recomendação em grandes e complexos projetos, mas como coloquei acima a segurança nesse projeto está na arquitetura ou como a API é incluída dentro de uma infra-estrutura, então nesse caso eu acredito que é muito melhor ter orientações e recomendações claras sobre a infra-estrutura ideal e quais são ou não as responsabilidades do projeto do que buscar algum tipo de confidencialidade, porque isso é resolvido de forma muito mais efetiva ao configurar a infra-estrutura de forma correta que é não expor a API a ambientes e situações de risco desnecessários, apenas a Aplicação X precisa ter acesso a API e isso pode ser controlado através de sub-rede ou mesmo VPN, e se alguém não se atenta a esse fato não acredito que vai ser não abrindo Issues Públicas que o problema vai ser resolvido, veja o exemplo que você colocou

Primeiro ponto esse código pode até ser executado mas NÃO VAI CAUSAR NENHUM PROBLEMA por um motivo simples o Serviço é executado por um Usuário Restrito, o APP, e não pelo Root, dessa forma o comando vai ser simplesmente negado/bloqueado, isso pode ser testado usando o exemplo com o Odoo, ao iniciar a Aplicação com docker compose é possível entrar no contêiner da API e executar o comando

/usr/src/app $ rm -rf /
rm: can't remove '/lib/sysctl.d': Permission denied
rm: can't remove '/lib/apk/db/lock': Permission denied
rm: can't remove '/lib/apk/db/scripts.tar': Permission denied
rm: can't remove '/lib/apk/db/installed': Permission denied
rm: can't remove '/lib/apk/db/triggers': Permission denied
rm: can't remove '/lib/apk/exec': Permission denied
rm: can't remove '/lib/libc.musl-x86_64.so.1': Permission denied

... Se necessário posso ver de colocar o LOG completo, são 47418 Linhas no Total

rm: can't remove '/var/spool/mail': Permission denied
rm: can't remove '/var/spool/cron/crontabs': Permission denied
rm: can't remove '/var/log': Permission denied
rm: can't remove '/var/mail': Permission denied
rm: can't remove '/var/opt': Permission denied
rm: can't remove '/var/run': Permission denied
rm: can't remove '/var/local': Permission denied
rm: can't remove '/var/tmp': Permission denied
rm: can't remove '/var/empty': Permission denied
rm: can't remove '/.dockerenv': Permission denied
/usr/src/app $

Em seguida para confirmar se isso afetou o comportamento da API eu rodei no contêiner da Aplicação, nesse caso o Odoo, os testes do módulo que implementa o BRCobranca:

odoo@dev-odoo-brasil-16:~$ odoo -d test -u l10n_br_account_payment_brcobranca --workers 0 --stop-after-init --test-enable
....


2026-01-06 21:46:25,844 13 INFO test odoo.addons.l10n_br_account_payment_brcobranca.models.account_move: Connecting to http://boleto_cnab_api:9292/api/boleto/multi to get Boleto of invoice INV/2026/00001 
2026-01-06 21:46:29,878 13 INFO test odoo.addons.l10n_br_account_payment_brcobranca.models.account_payment_order: Connecting to http://boleto_cnab_api:9292/api/remessa to generate CNAB-REMESSA file for Payment Order PAY0105 
2026-01-06 21:46:33,549 13 INFO test odoo.addons.base.models.ir_attachment: filestore gc 48 checked, 48 removed 
2026-01-06 21:46:33,551 13 INFO test odoo.service.server: 16 post-tests in 353.92s, 24404 queries 
2026-01-06 21:46:33,552 13 INFO test odoo.tests.stats: l10n_br_account_payment_brcobranca: 18 tests 353.89s 24404 queries 
2026-01-06 21:46:33,553 13 INFO test odoo.tests.result: 0 failed, 0 error(s) of 16 tests when loading database 'test' 
2026-01-06 21:46:33,553 13 INFO test odoo.service.server: Initiating shutdown 
2026-01-06 21:46:33,554 13 INFO test odoo.service.server: Hit CTRL-C again or send a second signal to force the shutdown. 
2026-01-06 21:46:33,676 13 INFO test odoo.sql_db: ConnectionPool(used=0/count=0/max=64): Closed 1 connections  
odoo@dev-odoo-brasil-16:~$

Não ocorreu erro, busquei fazer a alteração descrita no seu exemplo mandando o valor do campo nosso_numero com "; rm -rf /" alterando o valor no arquivo https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_order/models/account_payment_line.py#L263 o resultado foi uma mensagem de erro

  File "l10n_br_account_payment_brcobranca/models/account_payment_order.py", line 209, in _get_brcobranca_remessa
    raise ValidationError(res.text)
odoo.exceptions.ValidationError: Puma caught this error: Número inválido (ArgumentError)

Testei colocar esse "; rm -rf /" nos outros campos que são enviados para API para ver se teria algum resultado diferente dependendo do tipo do Campo

Campo valor tipo Float

  File "l10n_br_account_payment_brcobranca/models/account_payment_order.py", line 209, in _get_brcobranca_remessa
    raise ValidationError(res.text)
odoo.exceptions.ValidationError: Puma caught this error: Brcobranca::Remessa::Pagamento#valor: Deve ser um Float (Brcobranca::ValorInvalido)

Campo data_vencimento tipo Data

  File "l10n_br_account_payment_brcobranca/models/account_payment_order.py", line 209, in _get_brcobranca_remessa
    raise ValidationError(res.text)
odoo.exceptions.ValidationError: Puma caught this error: invalid date (Date::Error)

Campo nome_sacado tipo String

Não gerou erro, faltou algum tipo de tratamento?

Parece que não, já que hoje não parece ser possível em determinados campos diferenciar um código malicioso como esse de um valor válido, mas não parece ter efeito algum, porque depois desses testes eu voltei o código para enviar os valores corretos, rodei novamente os testes e não tive erros, então esse comando não alterou o funcionamento da API, talvez você tenha colocado apenas como um exemplo porém acredito que é importante deixar claro a real possibilidade desse exemplo acontecer que é nula.

Ou você consegue demonstrar a execução desse código usando esse repositório atual? Ou é algo que pode acontecer com as alterações do seu PR?

Acredito que o Projeto pode buscar fazer algum tipo de varredura no código ou incluir algum tipo de teste para buscar reduzir possíveis vulnerabilidades de segurança, em uma pesquisa rápida é possível ver algumas ferramentas que fazem uma varredura:

• https://github.com/cerberauth/vulnapi
• https://vulnissimo.io/
• https://pentest-tools.com/website-vulnerability-scanning/api-scanner
• https://nordicapis.com/api-vulnerability-scanners/

Mas nesses links é possível notar que as ferramentas fazem uma varredura em APIs que estão expostas na internet, então a principal questão sobre isso, que é a mesma que fiz um pouco acima, é:

Esse Projeto de API deve considerar uma implementação que vai expor a porta do serviço na internet?

Hoje eu acredito que não, e parece ser algo desnecessário, e você acredita que sim? Se sim você pode justificar?

Segundo ponto, considerando que a API está configurada dentro de uma sub-rede acessada apenas pela Aplicação X e não exposta na internet, então esse código malicioso só pode vir dessa Aplicação X e isso significa que a Segurança da Aplicação X foi comprometida o que é muito mais grave e preocupante porque é onde estão os Dados da Empresa, e se alguém mal intencionado já tem acesso ao servidor onde a principal Aplicação está rodando não vai ser uma simples recomendação "NÃO abra uma Issue Pública" que vai resolver o problema, isso pode ser ilustrado com algumas perguntas:

Nesse exemplo onde está a responsabilidade dos Desenvolvedores da Aplicação X sobre os valores dos campos que vão ser enviados para a API? Ou você acredita que a Aplicação X que vai usar a API não tem nenhuma responsabilidade tanto de tratar os valores dos campos que são enviados para a API quanto da Segurança dessa Aplicação?

A API foi idealizada para ser possível que diversas Aplicações diferentes possam usa-la mas o Projeto da API não pode, e não tem como, se responsabilizar pela Segurança da Aplicação X que vai usar a API, isso está relacionado a ideia do uso de Contêineres porque cada contêiner acaba tendo determinadas funções e responsabilidades mas restritas dentro de um escopo definido, nós podemos melhorar o tratamento dos Valores recebidos (mas acredito que configurar corretamente as Permissões de Acesso é mais efetivo, ou não?) e podemos orientar a implementar a API dentro de uma rede local, ou mesmo uma sub-rede de servidores ou se necessário em uma VPN e não expor a API na Internet, mas isso é apenas uma orientação nós não temos como controlar e consequentemente se responsabilizar pela forma como outros Desenvolvedores decidiram implementar a API ou mesmo se eles tem conhecimento para entender sobre isso, mas se você acredita que existem razões que justificam incluir isso no projeto será importante para nós ouvi-las.

OBS.: O Odoo também usa o Python e existe uma orientação de segurança sobre como tratar os valores String de forma ideal e com menos riscos, caso tenha interesse:

• [18.0][REF] l10n_br_base: Usando o método do tools para validar Chaves PIX tipo CNPJ OCA/l10n-brazil#4031

https://github.com/OCA/odoo-community.org/blob/master/website/Contribution/CONTRIBUTING.rst#33idioms

https://github.com/Maxwbh/boleto_cnab_api/blob/master/SECURITY.md

Acredito que a melhor orientação sobre a Segurança da Aplicação X e que podemos fazer recomendações minimas mas que é um assunto muito vasto que foge do escopo do projeto, por poderem ser feitas diversas combinações e com isso a segurança da Aplicação X que vai usar a API não é e não tem como ser responsabilidade desse Projeto, já que dependendo do tamanho da implementação pode ser algo complexo e recomendar não usar HTTPS e não expor a porta da API na internet é o minimo, para avaliar a segurança real de uma implementação de uma Aplicação X é preciso ver diversos aspectos desde Hardware, SO, rede, firewall, Disponibilidade, Redundância, Backup, Disaster Recovery, VPN, linguagens usada, bibliotecas, banco de dados, criptografia, configurações e permissões de segurança, etc tem muito mais coisas a serem vistas além do que apenas cinco itens.

O arquivo .env basta configurar nos arquivos ignore, sobre o LOG parece ser algo que você está implementando e eu não vejo justificativa para isso porque se for necessário saber o valor de uma variável basta "imprimir" no LOG essa variável ou do lado da Aplicação X, se for python com um print ou se for do lado da API com um puts o README atual mostra isso

https://github.com/akretion/boleto_cnab_api

E isso só vai ser necessário em uma implementação, manutenção ou correção, até porque hoje se faltar algum campo ou o valor de algum campo estiver errado o LOG já mostra uma mensagem sobre isso e também porque dependendo do tamanho do projeto e dos níveis de acesso de cada camada de Suporte não é interessante que seja possível ativar com facilidade um LOG que mostra todos os valores e assim alguém do primeiro nível de Suporte pode acabar vendo diversos dados sensíveis tanto da Empresa quantos dos Clientes dessa Empresa, mas se você acredita que é válido fique a vontade de argumentar em favor.

Nessa parte você parece orientar corretamente sobre a implementação e por isso será importante para nós ouvir de você a respeito desse assunto.

Se não tem SQL por que incluir isso? Não seria melhor remover?

Se não tem XSS por que incluir isso? Não seria melhor remover?

Você está orientando para mostrar todos os erros da API apenas no LOG e não mostrar na tela para o Usuário, é isso?

Se for isso

Não, isso de acordo com os casos de uso conhecidos hoje não é Bom, as mensagens de erro precisam ser mostradas ao Usuário, não completas mas a parte inicial porque ali ele é informado do problema que em alguns casos o próprio Usuário vai resolver e mesmo que o Usuário não compreenda a mensagem, o suporte pode ser feito pelo Primeiro Nível, quer dizer sem a necessidade de alguém com acesso restrito ao servidores ter que olhar o LOG da API por uma falha de Configuração de um CNAB especifico, já que sabemos que implementação por parte da API está funcional a maior probabilidade de erros são por Falta de Campo ou Campo com o Tipo ou Tamanho errados

Como a API dentro de uma rede local, atrás de um Firewall, pode ser atacada por DoS? Ou você está considerando um ataque de DoS vindo da rede interna?

Nós podemos ver de configurar ou limitar determinadas funcionalidades para evitar uma "sobre-carga" tanto de rede quanto de algum processo, mas veja que é difícil imaginar como a API pode ser atacada com DoS sem estar exposta na internet, e por que a API estaria exposta na internet? Ou você tem um exemplo que demonstra que isso pode acontecer? Além do que é função do Firewall tratar ou barrar ataques do tipo DoS, ou na sua opinião seria da API? E se o ataque parte da rede interna significa que a Segurança da Aplicação X foi comprometida o que é muito mais grave e preocupante porque é onde estão os Dados da Empresa e a Segurança da Aplicação X e a infra-estrutura não é, e nem tem como ser devido as muitas possibilidades de implementações, responsabilidade desse Projeto.

Por que ter um LOG completo, com os casos de sucesso, na API?

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/api/troubleshooting.md

Isso é algo como um "Modo Debug" que pode ser ativado e desativado, e ainda é possível deixar configurado para ter o mesmo comportamento que hoje, mostrando apenas os LOGs de erros?

O LOG principal hoje idealmente deveria estar na Aplicação X que usa a API e não na API o motivo é simples esse LOG é usado para mostrar ao Usuário dentro da Aplicação X a Mensagem de Erro, por exemplo:

E mesmo que o Usuário não compreenda a mensagem, o suporte pode ser feito pelo Primeiro Nível, quer dizer sem a necessidade de alguém com acesso restrito ao servidores ter que olhar o LOG da API por uma falha de Configuração de um CNAB especifico, já que sabemos que implementação por parte da API está funcional a maior probabilidade de erros são por Falta de Campo ou Campo com o Tipo ou Tamanho errados, o que não parece justificar a API ficar criando LOGs que não serão nem armazenados.

Isso parece ser algo a ser usado por exemplo no momento de uma atualização ou durante alguma implementação que passou a dar um erro inesperado mas não parece ser necessário no uso do dia a dia, ou você acredita ter uma justificativa? A única que imagino é que a sua Aplicação não permite você incluir ou mesmo ver o LOG dessa Aplicação então você precisa ver os erros e os casos de sucesso no LOG da API, é isso? Se for você pode informar qual é Aplicação que você está usando em conjunto com a API?

Por que você acredita ser necessário criar um apelido/alias dentro da API para o campo documento_numero?

https://github.com/Maxwbh/boleto_cnab_api/tree/master/docs/fields

Até entendo que você queira e acredita que esse campo ao invés de ser chamado de documento_numero deveria ser numero_documento mas nesse caso o ideal é fazer um PR com essa alteração no BRCobranca ou no seu Fork e não na API, por uma questão de arquitetura, a API disponibiliza uma forma TRANSPARENTE de comunicação com o BRCobranca como ele é hoje, a API não é, e acredito que não deve ser, uma segunda camada de implementação da Biblioteca, isso também é importante para manutenção e identificação e resolução de erros/Troubleshotting porque sabendo por outros casos de Banco/CNAB que a API funciona e principalmente por ser transparente que a maior probabilidade de erros que acontecem são referentes a um caso especifico de um Banco/CNAB, então ou a Aplicação X está mandando campos com problemas ou faltando ou o BRCobranca tem algum erro ou está desatualizado em relação a esse caso especifico de Banco/CNAB.

Com essa alteração você acaba incluindo a API como uma terceira camada de analise para depurar um problema, porque o erro pode estar na API já que ela reimplementa isso, veja que isso acaba incluindo a API em um problema que eu acredito que não deveria estar e hoje parece não estar, e você mesmo faz referencias a isso em outras partes da sua Documentação

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/api/troubleshooting.md

Por que você acredita ser necessário incluir informações e configurações sobre uma instalação local?

https://github.com/Maxwbh/boleto_cnab_api/blob/master/CONTRIBUTING.md

https://github.com/Maxwbh/boleto_cnab_api/blob/master/start.sh#L38

O uso de máquinas e ambientes virtuais e mais recentemente de contêineres não é sem motivo, isso resolve um dos piores problemas em projetos de TI que é a reprodução de ambiente que leva a uma famosa frase que é "No meu ambiente isso funciona ou não funciona" e que pode levar a horas, dias e até meses para entender um problema e isso ocorre justamente em ambientes locais porque os outros Desenvolvedores não tem acesso ao ambiente local portanto nós não sabemos qual é o Sistema Operacional, se está atualizado ou não, quais a Bibliotecas estão instaladas ou não, em quais versões, ou mesmo se houveram alterações em arquivos, por isso em caso de algum erro fica difícil saber o motivo ou responder porque um determinado erro está acontecendo, já com o Docker nós sabemos o que está instalado e a reprodução de ambiente pode ser feita por todos os desenvolvedores envolvidos de forma simples.

Então qual seria a sua justificativa sobre por que, quando e em quais situações você acredita ser valido e necessário fazer uma instalação local? Já que isso hoje parece ser voltar para um passado e para um problema que foi superado pelo uso desses ambientes virtuais como o Docker.

OBS.: A versão do Python 3.7 já é obsoleta desde o segundo semestre de 2023 e não deve ser usada em ambientes profissionais, se não houver alguma restrição, por motivos de segurança as versões Python que devem ser usadas são 3.10, 3.11 e a 3.12, veja:

https://devguide.python.org/versions/

Por que você quer incluir na Documentação da API detalhes específicos sobre os campos de determinados Banco/CNAB?

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/development/brcobranca-fork.md

https://github.com/Maxwbh/boleto_cnab_api/tree/master/docs/fields

Entendo que essas informações são importantes mas não seria melhor se isso estivesse na Documentação do BRCobranca? Parece ser o lugar mais adequado, ou não?

Então parece que o ideal é que isso seja incluído em um PR na Documentação no BRCobranca ou no seu Fork e não na API, acredito que o escopo da Documentação da API deve ser sobre a comunicação tanto entre a Aplicação X com a API quanto da API com o BRCobranca e outros aspectos referentes por exemplo a segurança, agora a respeito dos campos e os detalhes de cada Banco/CNAB parece que o melhor lugar é na Documentação do BRCobranca, se você discorda será importante justificar.

Apenas para confirmar, essa recomendação de enviar todos os campos e "Não filtrar por Banco" e para o caso SICOOB ou para todos os casos?

Em outra parte da Documentação parece indicar ser uma orientação geral

https://github.com/Maxwbh/boleto_cnab_api/tree/master/docs/fields

Mas mesmo que seja apenas para o SICOOB acredito que essa orientação está equivocada, porque

https://github.com/OCA/l10n-brazil/tree/16.0/l10n_br_account_payment_order

Não parece fazer sentido a Aplicação X mandar por exemplo os campos byte_idt e posto em todos os casos, quando esses campos só existem e são usados pelo SICOOB e SICREDI, então porque você acha que deveria?

Você também pode usar como referencia a implementação feita no projeto Odoo, porque é possível ver as particularidades de cada caso mapeado até agora, nos campos informados é usada a mesma nomenclatura do BRCobranca, veja:

• Boleto https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_brcobranca/models/account_move_line.py
• Arquivos Remessa https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_brcobranca/models/account_payment_line.py
• Processamento do Arquivo de Retorno https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_brcobranca/parser/cnab_file_parser.py

Nesses arquivos é possível ver essa diferença em um mesmo Banco, apenas um exemplo o caso Santander 240 é diferente do 400 https://github.com/OCA/l10n-brazil/blob/16.0/l10n_br_account_payment_brcobranca/models/account_payment_line.py#L84 no 240 existe o codigo_baixa mas isso não existe no 400, então usando esse caso como exemplo a sua recomendação é que na Aplicação X todos os Bancos/CNAB enviem esse campo codigo_baixa? Mesmo que esse campo só exista no Santander 240, é isso mesmo?

Por que incluir testes de Banco/CNAB específicos na API?

https://github.com/Maxwbh/boleto_cnab_api/blob/master/spec/all_banks_spec.rb

Hoje parece que é suficiente que os testes da API sejam apenas Gerar um Boleto, um Arquivo de Remessa e Processar um Arquivo de Retorno de um caso genérico qualquer, porque os testes específicos de cada Banco/CNAB são feitos nos testes do BRCobranca e da Localização, que representa a Aplicação X, já que cada uma das possíveis Aplicações que usa ou irá usar API deverá avaliar o que precisa ser feito para implementar e se vai ou não incluir testes porque é onde se vai fazer necessário verificar a necessidade de criação ou não dos campos específicos a serem enviados, isso não é feito na API, esses testes específicos podem ser incluídos no BRCobranca, mas hoje eu não vejo sentido em ter testes específicos na API, na sua visão qual seria o motivo para incluir?

Qual a versão do Docker e do Docker Compose que você usou ou está usando?

Na sua Documentação e no arquivo de "Implementação Automática" está sendo usado o comando docker-compose com traço

https://github.com/Maxwbh/boleto_cnab_api/blob/master/CONTRIBUTING.md#commits-e-versionamento

https://github.com/Maxwbh/boleto_cnab_api/blob/master/start.sh#L26

Mas esse comando com o traço é referente a Versão 1 do Docker Compose que é em Python onde a versão final é de 10/05/2021 a partir dessa data essa versão não recebe Atualizações de Segurança e desde de Julho de 2023 já é considerada obsoleta e não recomendada para uso profissional porque desde de 2020 já existe a Versão 2 do Docker Compose em GO que vem sendo testada ao longo desses anos e hoje é a recomendada para uso profissional onde o traço foi substituído pelo espaço, por exemplo:

$ docker compose version
Docker Compose version 2.40.3
$ docker version
Client:
 Version:           28.5.2
 API version:       1.51
 Go version:        go1.25.4
 Git commit:        89c5e8fd66634b6128fc4c0e6f1236e2540e46e0
 Built:             Fri Dec  5 17:46:26 2025
 OS/Arch:           linux/amd64
 Context:           default

Qual o retorno desses comandos no seu ambiente?

No seu caso o docker deve ser o mesmo comando porém se o Docker Compose usado é a Versão 1 deverá ser

$ docker-compose --version

Veja os links abaixo para mais detalhes

Docker Compose V1 is deprecated

https://github.com/docker/compose

Warning

The final Compose V1 release, version 1.29.2, was May 10, 2021. These packages haven't received any security updates since then. Use at your own risk.

https://docs.docker.com/compose/migrate/

From July 2023 Compose V1 stopped receiving updates. It’s also no longer available in new releases of Docker Desktop.

Compose V2, which was first released in 2020, is included with all currently supported versions of Docker Desktop. It offers an improved CLI experience, improved build performance with BuildKit, and continued new-feature development.

Você teve algum problema ou erro usando a Biblioteca RGhost na Versão 0.9.9 ?

Veja nós sabemos sobre a questão do BRCobranca não estar usando essa versão

• RGhost 0.9.9 kivanio/brcobranca#269

Aqui tem um ponto importante sobre colaborar em Projetos Públicos de Código Aberto, em muitos casos falta ajuda mesmo para questões minimas como Testar e Validar alguma alteração, o objetivo de usar essa versão é para que assim a comunidade da Localização Brasileira e quem mais usar a API acabe testando e validando a correção feita na versão 0.9.9, que é até algo simples e resolvido em 08/03/2024 mas que por algum motivo que nós não sabemos não é publicada no rubygems

Então será importante saber se você teve erros e por isso decidiu usar essa outra versão ou por qual motivo você acredita ser melhor usar essa versão.

Por que você quer incluir uma Propaganda de um Serviço de um Terceiro no projeto? Você tem alguma relação comercial com a empresa https://render.com/ ? Ou ganha algum tipo de comissão?

Desde que iniciei essa Revisão houveram mudanças no texto antes a propaganda do serviço estava mais explicita e parecia direcionar para o uso de um Serviço Grátis mas que depois apontava as limitações do serviço e orientava e recomendava o uso do Serviço Pago, vou deixar as imagens com o objetivo de tentar entender do porque você quer incluir as informações sobre Preços do Serviço dessa Empresa no projeto

Antes de 23/01/2026

https://github.com/Maxwbh/boleto_cnab_api/blob/master/DEPLOY.md

Você começa dizendo que é algo simples, 5 minutos e gratuito

Mas em seguida você aponta as limitações do Serviço Grátis e orienta a usar o Serviço Pago, informando o Preço, Benefícios e Como Fazer, o que claramente caracteriza uma Propaganda

E também está sendo incluído um arquivo de configuração

https://github.com/Maxwbh/boleto_cnab_api/blob/master/render.yaml

Em 23/01/2026

https://github.com/Maxwbh/boleto_cnab_api/blob/master/docs/DEPLOY.md

Como a arquitetura API permite várias formas de implementação, em geral como um micro-serviço dentro de um Docker Compose ou apenas subindo com o Docker, não é comum na Documentação ser incluída uma Propaganda de um Serviço de uma Empresa Especifica, a não ser que essa empresa patrocine o projeto, acredito que é até possível incluir uma referencia a um serviço de terceiro no qual a API já está pré-configurada mas incluir Valores referentes aos Preços praticados pela Empresa parece fora do escopo do projeto, basta refletir sobre qual o sentido no futuro de alguém criar um PR aqui no projeto sobre:

"[UPD] Atualizar a Tabela de Preços do https://render.com/ "

Ou alguém criar um Issue sobre

"Os Preços do serviço https://render.com/ estão desatualizados"

Portando por que esse projeto que é sobre uma API que permite usar o BRCobranca deveria informar e manter informações sobre o Preços praticados por essa empresa https://render.com/ ? Você tem alguma justificativa? Ou então você pode esclarecer essa questão a respeito da sua relação com essa empresa? Por que é importante o projeto referenciar esse serviço especifico?

Algumas questões mais técnicas para tentar entender porque você usou esse serviço especifico, em muitas implementações em que essa API será usada já existe uma determinada infra-estrutura e orçamento definidos para a Aplicação X que vai usar a API, como a API é um micro-serviço com a imagem tendo cerca de 550 MB normalmente se considera que tanto a infra-estrutura como o orçamento da Aplicação X já devem ser, na maioria dos casos, o suficiente para permitir incluir a API nessa mesma estrutura, ou de forma mais clara a API vai rodar ou próxima ou dentro da infra-estrutura da Aplicação X, o que não parece justificar a ideia de rodar a API de forma isolada em um Serviço na Internet, ou estou errado sobre a forma que essa implementação é feita com o render.com? Então seguem algumas perguntas:

O que justifica o uso do serviço dessa empresa ao invés de adicionar a API na infra-estrutura da Aplicação X? Ou o que levou você ao uso desse serviço? Alguma requisição do projeto? Tem alguma restrição de segurança do seu caso de uso? Ou esse serviço tem alguma funcionalidade que torna a implementação melhor?

Você usou como base alguma documentação de outro projeto ou algum programa de IA para gerar a Documentação? Se sim qual?

Essa pergunta é necessária porque na Documentação que você está incluindo tem orientações bem claras sobre como fazer um Issue ou um PR ideal:

https://github.com/Maxwbh/boleto_cnab_api/blob/master/CONTRIBUTING.md

Tanto esse PR quanto o que foi fechado no BRCobranca, que eu vi que foram feitos por você, não parecem seguir essas orientações:

• O PR no BRCobranca Merge kivanio/brcobranca#270 não tem um Título Descritivo e no corpo do PR parece não ter uma seção Resumo apenas as Mudanças

Foi encerrado sem justificativa, você poderia informar por que fechou o PR?

Mas nesse PR provavelmente surgiria a mesma questão inicial que eu fiz, sobre se você quer colaborar com os projetos originais ou fazer um Fork.

• Nesse PR aqui Criação do endpoint '/health' #42 o Título também não é Descritivo, já que como essa própria Revisão mostra o health é apenas uma parte, dentro do corpo do PR a Descrição não é completa e não tem nem Resumo e nem Mudanças

Portanto esse PR não parece estar de acordo com as próprias orientações que estão sendo incluídas, então é importante para nós tentarmos entender o por que você não seguiu as suas próprias orientações, se porque a Documentação foi baseada em uma Documentação de outro Projeto ou foi gerada por algum programa de "inteligencia artificial" ou algum outro motivo, qual?

Faltou a orientação sobre o quanto é importante separar tantos Issues quanto PRs dentro do menor escopo possível, isso é fundamental para um melhor processo de Revisão, por exemplo com a divisão sugerida no incio desse comentário.

Conclusão

Procurei fazer uma Revisão inicial, faltou testar e olhar com profundidade o Cliente Python, mas devido o tamanho do PR e consequentemente da Revisão e o fato de que a principal pergunta nesse PR não é técnica e sim sobre se você quer colaborar com o projeto ou fazer um fork acredito que é melhor já orientar e mostrar a importância de dividir esse PR para melhor Revisão e comentar sobre alguns outros pontos que vi, se tiver dúvidas estou a disposição para tentar esclarecer.