trailofbits/open-sourcing

Abrindo um Repositório para Open Source

Prepare um repositório para lançamento público, de modo que uma pessoa externa, sem contexto prévio, possa construir, usar e contribuir com ele — e para que nada sensível seja incluído. Siga as etapas em ordem; a auditoria de segredos vem primeiro porque seu resultado (manter vs. recriar o repositório) afeta tudo o que vem depois.

Quando Usar

• Tornar um repositório privado público
• Auditar um repositório público existente quanto à qualidade de lançamento ("torná-lo oficial")
• Escolher uma licença para um projeto
• Configurar empacotamento, versionamento ou automação de release antes de um lançamento público

Quando NÃO Usar

• Desenvolvimento rotineiro em um projeto já lançado (sem evento de release)
• Auditar código de terceiros em busca de vulnerabilidades (use uma habilidade de revisão de segurança)
• Publicar um pacote a partir de um repositório que permanecerá privado — apenas as etapas de gerenciamento de release se aplicam; pule o restante

Fluxo de Trabalho

Etapa 1: Detectar o perfil da organização

bash {baseDir}/scripts/detect_org.sh

O script inspeciona os remotes git e os e-mails dos commiters recentes e imprime um nome de perfil. Se imprimir trailofbits, leia references/trailofbits.md agora e aplique sua política de licenciamento, contas de publicação e notas de processo ao longo das etapas restantes. Se imprimir generic, prossiga apenas com as orientações genéricas. Se o usuário disser que a detecção está errada, confie no usuário.

Etapa 2: Auditar segredos — antes de qualquer outra coisa

Um repositório que já conteve segredos (chaves de API, credenciais, dados de clientes) não deve ser tornado público. Reescrever o histórico é propenso a erros e não atinge forks, caches ou artefatos de CI. A correção confiável é um repositório novo: copie a árvore atual, faça commit e arquive o repositório antigo de forma privada.

1. Pergunte se o projeto já lidou com segredos ou material confidencial de clientes. Para ferramentas de consultoria de segurança, pergunte também se dados de teste ou exemplos vieram de compromissos com clientes.
2. Escaneie o histórico completo com uma ferramenta dedicada, se disponível — gitleaks git . ou trufflehog git file://. — em vez de inspecionar manualmente.
3. Verifique além da árvore git: logs e artefatos do GitHub Actions, releases antigos, histórico de issues e PRs, e o wiki do repositório — tudo se torna público com o repositório.
4. Após tornar público, ative a varredura de segredos do GitHub e a proteção contra push nas configurações do repositório.

Rejeite estas racionalizações — esta é a única etapa que não pode ser corrigida após a publicação:

• "A chave foi revogada, então o histórico está limpo." Credenciais revogadas ainda vazam nomes de infraestrutura, URLs internos e padrões que atacantes usam para Mira.
• "Vamos reescrever o histórico com git-filter-repo." Reescrever perde forks, clones, caches e artefatos de CI; a abordagem de repositório novo não.
• "São apenas dados de teste." Dados de teste derivados de compromissos com clientes ou sistemas de produção são confidenciais, independentemente de como são rotulados.

Etapa 3: Executar a verificação de prontidão

bash {baseDir}/scripts/check_readiness.sh

O script imprime uma lista de verificação de indicadores de presença (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, testes, tags semver, ...) e avisa sobre arquivos rastreados que comumente contêm segredos. Trate itens não marcados como sugestões de discussão, não como falhas críticas — um protótipo de pesquisa não precisa de tudo que uma biblioteca de ponta precisa. Percorra as lacunas com o usuário e corrija as que importam para este projeto.

Etapa 4: Documentação

O README é a porta de entrada do projeto. Confirme que ele explica:

• O que é o projeto e qual problema ele resolve (primeiro parágrafo)
• Como instalá-lo — gerenciador de pacotes, imagem de contêiner ou compilação a partir do código-fonte; a compilação a partir de um clone novo deve funcionar usando apenas o que está no repositório
• Como usá-lo — pelo menos um exemplo concreto e copiável
• Como contribuir — inline ou via CONTRIBUTING.md
• A licença — uma seção curta nomeando-a

Adicione também:

• SECURITY.md com instruções para relatar vulnerabilidades (um endereço de contato ou relatório privado de vulnerabilidade do GitHub). Para ferramentas de segurança, isso é requisito básico.
• Documentação da API, construída e hospedada (GitHub Pages via CI é o caminho usual), vinculada a partir do README e do campo de site do repositório. Veja as referências de linguagem abaixo para ferramentas de documentação por ecossistema.
• Um código de conduta se o projeto espera contribuidores externos.

Etapa 5: Licenciamento

Sem licença não é open source, independentemente da visibilidade. Leia references/licensing.md para critérios de seleção e mecânica. A versão resumida:

1. Aplique a política da organização, se uma foi detectada na Etapa 1.
2. Caso contrário: Apache 2.0 como padrão permissivo, AGPLv3 quando a modificação privada por concorrentes for uma preocupação real, Creative Commons para artefatos não relacionados a código.
3. Adicione o arquivo LICENSE, defina identificadores SPDX nos metadados do pacote, declare a licença no README e verifique se todos os três concordam.

Etapa 6: Testes e CI

• Confirme que a suíte de testes existe e passa; um repositório público com uma branch padrão com falha sinaliza abandono.
• Garanta que o CI execute os testes em cada PR, em toda a matriz de versões de linguagem e plataformas suportadas.
• Imponha formatação e linting no CI (ferramentas por linguagem nas referências abaixo), para que debates de estilo nunca cheguem à revisão.
• Respeite as ferramentas existentes. Não substitua um formatador, linter ou verificador de tipos funcional como parte da abertura do código. Se ele estiver desatualizado em relação à geração atual (as referências de linguagem nomeiam as ferramentas atuais), avise o mantenedor e deixe-o decidir; apenas quando uma categoria estiver completamente ausente — sem verificador de tipos, sem formatador — adicione o padrão atual.
• Considere um gate de cobertura que falhe o CI quando a cobertura cair.
• Reforce os próprios workflows antes que se tornem superfície de ataque pública:
  • Fixe ações de terceiros a SHAs completos de commit; habilite Dependabot para github-actions para que os pinnings permaneçam atualizados.
  • Defina blocos permissions: com privilégio mínimo (comece com permissions: {}).
  • Audite com zizmor .github/workflows/ e faça lint com actionlint.

Etapa 7: Configurações do repositório

• Proteção de branch na branch padrão: sem force push, PRs obrigatórios. Prefira conjuntos de regras para repositórios novos; a proteção clássica de branch continua suportada.
• Proteção de merge: verificações de status obrigatórias para que PRs não possam ser mesclados com testes falhando.
• Dependabot ou Renovate para atualizações de dependências e Actions. Agrupe atualizações para reduzir o ruído de PRs e defina uma janela de espera (ex.: 7 dias) para que versões recém-publicadas — e ocasionalmente sequestradas — envelheçam antes da adoção.
• .editorconfig para que os editores dos contribuidores concordem com o básico de espaçamento.
• Labels: crie-os assim que mais de uma issue ou PR precisar de um; prefixos para facetas escalam bem (C: componente, P: plataforma). Veja as labels do blight para um exemplo prático.

Etapa 8: Releases e versionamento

• Marque cada release com vX.Y.Z, seguindo semver; use sufixos -rc.N / -pre.N para release candidates e pré-lançamentos.
• Torne os releases orientados por CI: enviar uma tag (ou publicar um GitHub Release) aciona compilação, empacotamento e upload sem etapas manuais. Um release deve ser git tag vX.Y.Z && git push origin vX.Y.Z.
• Publique pacotes sob uma conta de propriedade da organização, não pessoal, e use publicação confiável (OIDC) em vez de tokens de longa duração sempre que o índice suportar.

Etapa 9: Práticas específicas por linguagem

Identifique as linguagens do projeto a partir de seus arquivos de marcação e leia a referência correspondente para empacotamento, publicação e ferramentas de qualidade:

Arquivo de marcação	Referência
pyproject.toml, setup.py	references/python.md — delega à habilidade de python moderno para ferramentas
CMakeLists.txt, Makefile (C/C++)	references/c-cpp.md
Cargo.toml	references/rust.md
go.mod	references/go.md
package.json	references/javascript.md
Gemfile, *.gemspec	references/ruby.md

Para outros ecossistemas, aplique os princípios transversais: compilações reproduzíveis a partir de um clone novo, releases orientados por CI, publicação confiável ou contas de propriedade da organização, e metadados de licença no manifesto do pacote.

Revisão Final

Antes de virar a chave de visibilidade, verifique da perspectiva de um externo:

1. Clone em um diretório limpo e siga as instruções de compilação do README ao pé da letra — elas funcionam sem conhecimento tácito?
2. Execute novamente {baseDir}/scripts/check_readiness.sh e confirme que as lacunas restantes são escolhas deliberadas, declaradas ao usuário.
3. Confirme que a auditoria de segredos (Etapa 2) realmente aconteceu; é a única etapa que não pode ser corrigida após a publicação.

Tornar o repositório público é então uma alteração nas configurações do repositório. Acompanhe o release com um anúncio onde a organização tem um processo para isso.

Recursos Adicionais

Arquivos de Referência

• references/licensing.md — critérios de seleção de licença, metadados SPDX, forks e relicenciamento
• references/trailofbits.md — política da Trail of Bits (carregada apenas quando detectada na Etapa 1)
• references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md — empacotamento, publicação e ferramentas de qualidade por linguagem

Scripts

• scripts/detect_org.sh — imprime o perfil da organização (trailofbits ou generic) a partir de remotes git e e-mails de commiters
• scripts/check_readiness.sh — imprime indicadores de presença para arquivos de prontidão de release e sinaliza arquivos rastreados que comumente contêm segredos