From 1bc4eca5385be8ef8240bf84c821259a279d0d44 Mon Sep 17 00:00:00 2001 From: Crypt-Guard Date: Sat, 20 Jun 2026 09:59:31 -0300 Subject: [PATCH] chore: professionalize repository documentation and GitHub metadata --- .editorconfig | 21 ++++++++++ .gitattributes | 20 +++++++++ .../ISSUE_TEMPLATE/bug_report.yml | 0 {github => .github}/ISSUE_TEMPLATE/config.yml | 0 .../ISSUE_TEMPLATE/feature_request.yml | 0 .../ISSUE_TEMPLATE/security_hardening.yml | 0 {github => .github}/PULL_REQUEST_TEMPLATE.md | 2 +- {github => .github}/dependabot.yml | 0 {github => .github}/workflows/docs.yml | 3 ++ .../workflows/python-static.yml | 0 .../workflows/security-scan.yml | 0 GOVERNANCE.md | 2 +- README.md | 41 +++++++++++-------- SECURITY.md | 5 +++ docs/ARCHITECTURE.md | 8 +++- more_info/CONTRIBUTING.md | 3 +- more_info/ROADMAP.md | 5 ++- more_info/requirements.txt | 2 + 18 files changed, 91 insertions(+), 21 deletions(-) create mode 100644 .editorconfig create mode 100644 .gitattributes rename {github => .github}/ISSUE_TEMPLATE/bug_report.yml (100%) rename {github => .github}/ISSUE_TEMPLATE/config.yml (100%) rename {github => .github}/ISSUE_TEMPLATE/feature_request.yml (100%) rename {github => .github}/ISSUE_TEMPLATE/security_hardening.yml (100%) rename {github => .github}/PULL_REQUEST_TEMPLATE.md (93%) rename {github => .github}/dependabot.yml (100%) rename {github => .github}/workflows/docs.yml (95%) rename {github => .github}/workflows/python-static.yml (100%) rename {github => .github}/workflows/security-scan.yml (100%) diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..260ed30 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,21 @@ +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.py] +indent_style = space +indent_size = 4 + +[{*.yml,*.yaml,*.json,*.md}] +indent_style = space +indent_size = 2 + +[*.md] +trim_trailing_whitespace = false + +[Makefile] +indent_style = tab diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..fa47a92 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,20 @@ +* text=auto eol=lf + +*.py text eol=lf linguist-language=Python +*.md text eol=lf +*.txt text eol=lf +*.json text eol=lf +*.yml text eol=lf +*.yaml text eol=lf + +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.zip binary +*.exe binary +*.dll binary +*.so binary +*.dylib binary +*.pdf binary diff --git a/github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml similarity index 100% rename from github/ISSUE_TEMPLATE/bug_report.yml rename to .github/ISSUE_TEMPLATE/bug_report.yml diff --git a/github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml similarity index 100% rename from github/ISSUE_TEMPLATE/config.yml rename to .github/ISSUE_TEMPLATE/config.yml diff --git a/github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml similarity index 100% rename from github/ISSUE_TEMPLATE/feature_request.yml rename to .github/ISSUE_TEMPLATE/feature_request.yml diff --git a/github/ISSUE_TEMPLATE/security_hardening.yml b/.github/ISSUE_TEMPLATE/security_hardening.yml similarity index 100% rename from github/ISSUE_TEMPLATE/security_hardening.yml rename to .github/ISSUE_TEMPLATE/security_hardening.yml diff --git a/github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md similarity index 93% rename from github/PULL_REQUEST_TEMPLATE.md rename to .github/PULL_REQUEST_TEMPLATE.md index c3d30ff..562db32 100644 --- a/github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,7 +16,7 @@ Descreva o problema e a solução proposta. Explique por que esta mudança perte Descreva ameaças afetadas, novos riscos, dados sensíveis envolvidos e mitigações. Se não houver impacto, justifique brevemente. -Se o PR mudar criptografia, formato de arquivo, KDF, Vault, KeyGuard, containers ou controles de segurança, explique obrigatoriamente: +Se o PR mudar criptografia, formato de arquivo, KDF, Vault, KeyGuard, containers, autenticação, secure delete, logs ou controles de segurança, explique obrigatoriamente: - compatibilidade de leitura e escrita; - migração ou rollback; diff --git a/github/dependabot.yml b/.github/dependabot.yml similarity index 100% rename from github/dependabot.yml rename to .github/dependabot.yml diff --git a/github/workflows/docs.yml b/.github/workflows/docs.yml similarity index 95% rename from github/workflows/docs.yml rename to .github/workflows/docs.yml index e605406..cd88b29 100644 --- a/github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,6 +34,9 @@ jobs: SECURITY.md CHANGELOG.md CODE_OF_CONDUCT.md + SUPPORT.md + GOVERNANCE.md + NOTICE more_info/CONTRIBUTING.md more_info/ROADMAP.md docs/ARCHITECTURE.md diff --git a/github/workflows/python-static.yml b/.github/workflows/python-static.yml similarity index 100% rename from github/workflows/python-static.yml rename to .github/workflows/python-static.yml diff --git a/github/workflows/security-scan.yml b/.github/workflows/security-scan.yml similarity index 100% rename from github/workflows/security-scan.yml rename to .github/workflows/security-scan.yml diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 4d24d90..d61daac 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -27,4 +27,4 @@ Somente mantenedores autorizados podem publicar releases. O processo futuro deve ## Alterações desta governança -Mudanças neste documento devem ser propostas por pull request, com justificativa e período razoável para revisão comunitária. +Mudanças neste documento devem ser propostas por pull request, com justificativa e período razoável para revisão comunitária. A governança poderá evoluir conforme o projeto, a comunidade e o grupo de mantenedores crescerem. diff --git a/README.md b/README.md index 74fac95..4ee722d 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,24 @@ # CryptGuard -CryptGuard é uma aplicação para criptografia autenticada de arquivos, com interface gráfica em PySide6 e ferramentas de linha de comando para operações auxiliares. +[![Documentação](https://github.com/Crypt-Guard/CryptGuard/actions/workflows/docs.yml/badge.svg)](https://github.com/Crypt-Guard/CryptGuard/actions/workflows/docs.yml) +[![Checks Python](https://github.com/Crypt-Guard/CryptGuard/actions/workflows/python-static.yml/badge.svg)](https://github.com/Crypt-Guard/CryptGuard/actions/workflows/python-static.yml) +[![Licença Apache-2.0](https://img.shields.io/badge/licen%C3%A7a-Apache--2.0-blue.svg)](LICENSE) + +CryptGuard é uma aplicação de criptografia autenticada de arquivos com interface gráfica em PySide6, CLI, Vault, KeyGuard e containers seguros. > [!IMPORTANT] -> O projeto está em desenvolvimento e aberto à auditoria comunitária. Ele ainda não passou por auditoria criptográfica externa independente. Avalie o código e o modelo de ameaça antes de proteger dados críticos. +> O projeto utiliza primitivas criptográficas consolidadas e práticas defensivas, mas nenhum software oferece segurança absoluta. Ele está em desenvolvimento, ainda precisa de testes automatizados mais amplos e não passou por auditoria criptográfica externa independente. Avalie o código e o modelo de ameaça antes de proteger dados críticos. ## Principais recursos -- Criptografia autenticada de arquivos e verificação de integridade. +- Criptografia autenticada de arquivos. +- Verificação de integridade. - Vault para organização de arquivos já criptografados. - KeyGuard para geração e gerenciamento local de senhas. - Containers seguros `.vault` para transporte e backup de itens selecionados. -- CLIs para containers e higiene de arquivos. +- CLI para containers e higiene de arquivos. - Hardening *best-effort* de memória, processo, arquivos temporários e logs. +- Secure delete *best-effort*, sujeito às limitações da mídia e do sistema de arquivos. ## Estado atual @@ -20,25 +26,26 @@ A aplicação principal está em [`CryptGuardv2/`](CryptGuardv2/). A série 3.x Não há, neste repositório, uma release binária oficial ou uma garantia de estabilidade de formato e API. O uso atual deve ser feito a partir do código-fonte. Consulte o [changelog](CHANGELOG.md) e o [roadmap](more_info/ROADMAP.md) para distinguir o estado documentado das metas futuras. +A documentação externa, a governança e a automação do repositório estão organizadas fora da aplicação. A profissionalização do código interno de `CryptGuardv2/` será realizada separadamente, com testes e revisão próprios. + ## Instalação pelo código-fonte Use Python 3.11 ou mais recente. Python 3.13 é a versão usada para gerar o arquivo de dependências travadas atualmente disponível no projeto. ```bash git clone https://github.com/Crypt-Guard/CryptGuard.git -cd CryptGuard -cd CryptGuardv2 +cd CryptGuard/CryptGuardv2 python -m venv .venv ``` Ative o ambiente virtual: ```bash +# Windows +.venv\Scripts\activate + # Linux/macOS source .venv/bin/activate - -# Windows (PowerShell) -.venv\Scripts\Activate.ps1 ``` Instale e execute: @@ -56,15 +63,15 @@ Na interface gráfica, selecione um arquivo e use **Encrypt**, **Decrypt** ou ** Para conhecer os comandos auxiliares e as práticas recomendadas, consulte o [guia de uso](docs/USAGE.md). -## Security Model +## Modelo de segurança O CryptGuard busca oferecer confidencialidade e detecção de adulteração para dados armazenados, desde que a senha seja adequada e o ambiente de execução seja confiável. O formato v5 usa criptografia autenticada em streaming; parâmetros de derivação e metadados relevantes são vinculados à autenticação. Vaults e containers reduzem a exposição operacional, mas não substituem controle de acesso do sistema, criptografia de disco ou backups. As proteções de memória, processo e exclusão segura são *best-effort*. -Leia o [modelo de segurança completo](docs/SECURITY_MODEL.md) antes de usar o projeto com dados sensíveis. +Leia a [Política de Segurança](SECURITY.md) e o [modelo de segurança completo](docs/SECURITY_MODEL.md) antes de usar o projeto com dados sensíveis. -## Limitations (Limitações) +## Limitações - Uma máquina comprometida, malware, keylogger ou acesso root/administrador pode capturar senhas e dados em texto claro. - Exclusão segura não pode ser garantida em SSDs, NVMe, sistemas com *copy-on-write*, snapshots ou backups. @@ -73,7 +80,7 @@ Leia o [modelo de segurança completo](docs/SECURITY_MODEL.md) antes de usar o p - Não há promessa de segurança absoluta, inviolabilidade ou adequação automática a requisitos regulatórios. - Compatibilidade legada deve ser validada com cópias de teste antes de qualquer migração importante. -## Documentation (Documentação) +## Documentação - [Arquitetura](docs/ARCHITECTURE.md) - [Modelo de segurança](docs/SECURITY_MODEL.md) @@ -81,19 +88,21 @@ Leia o [modelo de segurança completo](docs/SECURITY_MODEL.md) antes de usar o p - [Uso](docs/USAGE.md) - [Dependências](docs/DEPENDENCIES.md) - [Processo de release](docs/RELEASE_PROCESS.md) +- [Política de segurança](SECURITY.md) +- [Guia de contribuição](more_info/CONTRIBUTING.md) - [Roadmap](more_info/ROADMAP.md) - [Changelog](CHANGELOG.md) - [Suporte](SUPPORT.md) - [Governança](GOVERNANCE.md) -## Contributing (Contribuindo) +## Contribuindo Issues e pull requests são bem-vindos. Antes de contribuir, leia o [guia de contribuição](more_info/CONTRIBUTING.md) e o [Código de Conduta](CODE_OF_CONDUCT.md). Mudanças em criptografia, formato de arquivo, KDF, Vault ou controles de segurança devem explicar impacto, riscos e compatibilidade. -## Security Policy (Política de Segurança) +## Política de segurança Não publique vulnerabilidades exploráveis em issues. Siga o processo de divulgação responsável descrito em [SECURITY.md](SECURITY.md). -## License (Licença) +## Licença CryptGuard é distribuído sob a [Apache License 2.0](LICENSE). Dependências de terceiros mantêm suas próprias licenças; consulte também o arquivo [NOTICE](NOTICE). diff --git a/SECURITY.md b/SECURITY.md index bf1547d..517ba3e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,6 +2,8 @@ O CryptGuard fornece mecanismos de criptografia autenticada, mas nenhum software oferece segurança absoluta. Esta política descreve versões cobertas, modelo de ameaça, limitações e o processo de divulgação responsável. +Para detalhes técnicos e premissas, consulte o [Modelo de Segurança](docs/SECURITY_MODEL.md). + ## Versões suportadas | Linha | Suporte de segurança | @@ -44,6 +46,7 @@ As seguintes condições não são neutralizadas pelo CryptGuard: - captura de texto claro por swap, hibernação, crash dump ou periféricos; - snapshots, backups, sincronizadores ou históricos do sistema que preservem arquivos ou texto claro; - senhas fracas, reutilizadas, compartilhadas de forma insegura ou perdidas; +- engenharia social, coerção ou divulgação voluntária de credenciais; - exposição causada por aplicações externas após a descriptografia; - ataques físicos e forenses contra um equipamento ligado e desbloqueado. @@ -88,3 +91,5 @@ A sobrescrita e remoção de arquivos é apenas *best-effort*. SSDs e NVMe usam ## Conformidade de exportação Software criptográfico pode estar sujeito a regras locais de uso, importação e exportação. Distribuidores e usuários são responsáveis por avaliar as normas aplicáveis à sua jurisdição. Este texto não constitui aconselhamento jurídico nem uma classificação formal de exportação. + +Consulte também o [Modelo de Segurança detalhado](docs/SECURITY_MODEL.md). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bad2da5..a7bbe80 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Visão geral -O CryptGuard é uma aplicação Python com interface gráfica, serviços de criptografia e utilitários de linha de comando. A raiz do repositório contém documentação, governança e automação; a aplicação executável está integralmente em `CryptGuardv2/`. +O CryptGuard é uma aplicação Python com interface gráfica, serviços de criptografia e utilitários de linha de comando. A raiz do repositório contém documentação, governança e automação; a aplicação executável está integralmente em [`CryptGuardv2/`](../CryptGuardv2/). Este documento é uma descrição de alto nível baseada na árvore, nos nomes dos módulos e na documentação existente. Ele não substitui revisão de código nem declara estabilidade das interfaces internas. @@ -48,6 +48,10 @@ Faz a ponte entre subsistemas, especialmente containers e Vaults. Essa camada re Isola caminhos, ambiente Linux e efeitos específicos de Windows. Proteções dependentes de plataforma devem falhar de modo controlado quando indisponíveis. +### `i18n` + +Reúne recursos e documentação de internacionalização. A expansão bilíngue deve manter textos, codificação e fallback consistentes entre interface e documentação. + ## Fluxo conceitual ```text @@ -69,3 +73,5 @@ Dados não devem ser considerados íntegros antes da validação criptográfica. - Compatibilidade legada amplia a superfície de ataque e deve permanecer explicitamente testada. Qualquer refatoração interna de `CryptGuardv2/` será realizada em uma etapa separada. A profissionalização documental deste repositório não altera a arquitetura executável atual. + +Consulte também o [README](../README.md) e o [Modelo de Segurança](SECURITY_MODEL.md). diff --git a/more_info/CONTRIBUTING.md b/more_info/CONTRIBUTING.md index 62e36bb..d2d37a6 100644 --- a/more_info/CONTRIBUTING.md +++ b/more_info/CONTRIBUTING.md @@ -79,7 +79,7 @@ No PowerShell, defina `$env:PYTHONPYCACHEPREFIX = ".cache/pycache"` antes do `co 4. Preencha integralmente o [template de pull request](../.github/PULL_REQUEST_TEMPLATE.md). 5. Explique limitações conhecidas, migração e compatibilidade. -Mudanças em criptografia, formato de arquivo, KDF, Vault, KeyGuard, containers ou segurança devem incluir uma explicação explícita do impacto de segurança, ameaças afetadas, riscos de regressão, compatibilidade e vetores de teste. Não apresente um algoritmo próprio como seguro sem análise pública e evidências adequadas. +Mudanças em criptografia, formato de arquivo, KDF, Vault, KeyGuard, containers, autenticação, logs, secure delete ou gerenciamento de segredos devem incluir uma explicação explícita do impacto de segurança, ameaças afetadas, riscos de regressão, compatibilidade e vetores de teste. Não apresente um algoritmo próprio como seguro sem análise pública e evidências adequadas. ## Documentando mudanças de segurança @@ -88,6 +88,7 @@ Mudanças em criptografia, formato de arquivo, KDF, Vault, KeyGuard, containers - Documente alterações de formato e caminhos de migração. - Use dados sintéticos em testes e exemplos. - Mantenha detalhes exploráveis em canal privado até a correção coordenada. +- Registre limitações conhecidas e atualize o roadmap quando a entrega depender de trabalho futuro. ## Licença diff --git a/more_info/ROADMAP.md b/more_info/ROADMAP.md index 6f66a1d..739e13a 100644 --- a/more_info/ROADMAP.md +++ b/more_info/ROADMAP.md @@ -8,19 +8,22 @@ Este documento apresenta intenções de evolução, não promessas de entrega. P - Writer documentado no formato v5 com SecretStream e Argon2id. - GUI em PySide6, Vault, KeyGuard, containers `.vault` e CLIs auxiliares. - Documentação, templates comunitários e CI inicial para existência de documentos, compilação Python e análises não bloqueantes. +- Dependabot configurado para acompanhar GitHub Actions e dependências Python sem alterar automaticamente o código. - Projeto em desenvolvimento, sem auditoria criptográfica externa independente confirmada. ## Curto prazo - Construir uma suíte automatizada reproduzível para criptografia, autenticação, corrupção, senhas incorretas e compatibilidade. - Estabelecer testes de integração para Vault, KeyGuard, containers e CLIs. -- Corrigir gradualmente achados de Ruff e Bandit até tornar esses checks bloqueantes. +- Corrigir gradualmente achados de Ruff, Bandit e mypy; torná-los bloqueantes somente quando o código estiver preparado. - Definir ambientes suportados de Python e sistemas operacionais com evidências de CI. - Revisar e documentar formatos persistentes e estratégias de migração. +- Manter atualizações semanais de dependências sob revisão humana. ## Médio prazo - Separar dependências de runtime, GUI, testes e qualidade. +- Refatorar gradualmente arquivos grandes, preservando comportamento e compatibilidade com testes de regressão. - Unificar a estratégia entre `requirements.txt` e `requirements.lock.txt` sem perder reprodutibilidade. - Criar empacotamento reproduzível e validar instaladores em ambientes isolados. - Formalizar CI/CD para artefatos, matrizes de plataforma e testes de regressão. diff --git a/more_info/requirements.txt b/more_info/requirements.txt index af6d2b4..ee4e515 100644 --- a/more_info/requirements.txt +++ b/more_info/requirements.txt @@ -1,6 +1,8 @@ # AVISO: este arquivo é um resumo histórico/auxiliar e não deve ser usado para # instalar a aplicação. A lista operacional principal está em # ../CryptGuardv2/requirements.txt, e o lock correspondente fica na mesma pasta. +# A separação entre dependências de runtime e desenvolvimento será feita em uma +# etapa própria de profissionalização do código principal. cryptography>=44.0.1 argon2-cffi>=23.1.0