trailofbits/open-sourcing

Cómo hacer open source de un repositorio

Prepare un repositorio para su publicación pública, de modo que un externo sin contexto previo pueda compilarlo, usarlo y contribuir a él, y que nada sensible se publique con él. Siga los pasos en orden; la auditoría de secretos es lo primero porque su resultado (mantener o recrear el repositorio) afecta todo lo demás.

Cuándo usarlo

• Hacer público un repositorio privado
• Auditar un repositorio público existente para asegurar su calidad de publicación ("hacerlo oficial")
• Elegir una licencia para un proyecto
• Configurar empaquetado, versionado o automatización de lanzamientos antes de un lanzamiento público

Cuándo NO usarlo

• Desarrollo rutinario en un proyecto ya publicado (sin evento de lanzamiento)
• Auditar código de terceros en busca de vulnerabilidades (use una habilidad de revisión de seguridad)
• Publicar un paquete desde un repositorio que permanecerá privado; solo aplican los pasos de gestión de lanzamientos; omita el resto

Flujo de trabajo

Paso 1: Detectar el perfil de la organización

bash {baseDir}/scripts/detect_org.sh

El script inspecciona los remotos de git y los correos electrónicos de los committers recientes, e imprime un nombre de perfil. Si imprime trailofbits, lea references/trailofbits.md ahora y aplique su política de licencias, cuentas de publicación y notas de proceso en los pasos restantes. Si imprime generic, continúe solo con la guía genérica. Si el usuario dice que la detección es incorrecta, confíe en el usuario.

Paso 2: Auditar secretos — antes que nada

Un repositorio que alguna vez haya contenido secretos (claves API, credenciales, datos de clientes) no debe hacerse público. Reescribir el historial es propenso a errores y no alcanza forks, cachés ni artefactos de CI. La solución confiable es un repositorio nuevo: copie el árbol actual, haga commit y archive el repositorio antiguo de forma privada.

1. Pregunte si el proyecto alguna vez manejó secretos o material confidencial de clientes. Para herramientas de una consultoría de seguridad, pregunte también si los fixtures de prueba o los datos de ejemplo provinieron de compromisos con clientes.
2. Escanee todo el historial con una herramienta dedicada si está disponible — gitleaks git . o trufflehog git file://. — en lugar de hacerlo a ojo.
3. Revise más allá del árbol de git: registros y artefactos de GitHub Actions, lanzamientos antiguos, historial de issues y PRs, y la wiki del repositorio; todo se vuelve público con el repositorio.
4. Después de hacerse público, active el escaneo de secretos de GitHub y la protección contra push en la configuración del repositorio.

Rechace estas racionalizaciones — este es el único paso que no se puede corregir después de la publicación:

• "La clave fue revocada, así que el historial está bien." Las credenciales revocadas siguen filtrando nombres de infraestructura, URLs internas y patrones que los atacantes usan para apuntar.
• "Reescribiremos el historial con git-filter-repo." Las reescrituras no alcanzan forks, clones, cachés ni artefactos de CI; el enfoque de repositorio nuevo sí lo hace.
• "Son solo datos de prueba." Los fixtures derivados de compromisos con clientes o sistemas de producción son confidenciales independientemente de cómo se etiqueten.

Paso 3: Ejecutar la verificación de preparación

bash {baseDir}/scripts/check_readiness.sh

El script imprime una lista de verificación de indicadores de presencia (README, LICENSE, CONTRIBUTING, SECURITY.md, CI, pruebas, etiquetas semver, ...) y advierte sobre archivos rastreados que comúnmente contienen secretos. Trate los elementos no marcados como indicaciones para discutir, no como fallos graves — un prototipo de investigación no necesita todo lo que necesita una biblioteca insignia. Revise las brechas con el usuario y corrija las que importen para este proyecto.

Paso 4: Documentación

El README es la puerta de entrada del proyecto. Confirme que explica:

• Qué es el proyecto y qué problema resuelve (primer párrafo)
• Cómo instalarlo — gestor de paquetes, imagen de contenedor o compilar desde fuente; una compilación de un clon nuevo debe funcionar usando solo lo que está en el repositorio
• Cómo usarlo — al menos un ejemplo concreto y copiable
• Cómo contribuir — en línea o mediante CONTRIBUTING.md
• La licencia — una sección corta que la nombre

También agregue:

• SECURITY.md con instrucciones para reportar vulnerabilidades (una dirección de contacto o reporte privado de vulnerabilidades de GitHub). Para herramientas de seguridad, esto es requisito básico.
• Documentación de API, compilada y alojada (GitHub Pages mediante CI es la ruta habitual), enlazada desde el README y el campo de sitio web del repositorio. Consulte las referencias de lenguaje a continuación para las herramientas de documentación por ecosistema.
• Un código de conducta si el proyecto espera contribuyentes externos.

Paso 5: Licencia

Sin licencia no significa open source, independientemente de la visibilidad. Lea references/licensing.md para conocer los criterios de selección y los mecanismos. La versión corta:

1. Aplique la política de la organización si se detectó una en el Paso 1.
2. De lo contrario: Apache 2.0 como opción permisiva predeterminada, AGPLv3 cuando la modificación privada por parte de competidores sea una preocupación real, Creative Commons para artefactos que no sean código.
3. Agregue el archivo LICENSE, establezca los identificadores SPDX en los metadatos del paquete, indique la licencia en el README y verifique que los tres coincidan.

Paso 6: Pruebas y CI

• Confirme que el conjunto de pruebas exista y pase; un repositorio público con una rama predeterminada que falla indica abandono.
• Asegúrese de que CI ejecute las pruebas en cada PR, en la matriz de versiones de lenguaje y plataformas compatibles.
• Aplique formato y linting en CI (herramientas específicas del lenguaje en las referencias a continuación), para que los debates de estilo nunca lleguen a la revisión.
• Respete las herramientas existentes. No reemplace un formateador, linter o verificador de tipos que funcione como parte de la publicación como open source. Si está rezagado con respecto a la generación actual (las referencias de lenguaje nombran las herramientas actuales), advierta al mantenedor y deje que decida; solo cuando falte una categoría por completo — sin verificador de tipos, sin formateador — agregue el valor predeterminado actual.
• Considere un umbral de cobertura que haga fallar CI cuando la cobertura disminuya.
• Refuerce los propios flujos de trabajo antes de que se conviertan en superficie de ataque pública:
  • Fije las acciones de terceros a SHAs de commit completos; active Dependabot para github-actions para que los fijados se mantengan actualizados.
  • Establezca bloques permissions: de menor privilegio (comience desde permissions: {}).
  • Audite con zizmor .github/workflows/ y aplique linting con actionlint.

Paso 7: Configuración del repositorio

• Protección de rama en la rama predeterminada: sin fuerza de push, PRs requeridos. Prefiera conjuntos de reglas para repositorios nuevos; la protección de rama clásica sigue siendo compatible.
• Protección de fusión: verificaciones de estado requeridas para que los PRs no puedan fusionarse con pruebas fallidas.
• Dependabot o Renovate para actualizaciones de dependencias y Actions. Agrupe las actualizaciones para reducir el ruido de PRs y establezca una ventana de enfriamiento (por ejemplo, 7 días) para que las versiones recién publicadas — y ocasionalmente secuestradas — envejezcan antes de su adopción.
• .editorconfig para que los editores de los contribuyentes coincidan en los conceptos básicos de espacios en blanco.
• Etiquetas: créelas tan pronto como más de un issue o PR necesite una; los prefijos para facetas escalan bien (C: componente, P: plataforma). Vea las etiquetas de blight para un ejemplo práctico.

Paso 8: Lanzamientos y versionado

• Etiquete cada lanzamiento vX.Y.Z, siguiendo semver; use los sufijos -rc.N / -pre.N para candidatos de lanzamiento y prelanzamientos.
• Haga que los lanzamientos sean impulsados por CI: enviar una etiqueta (o publicar un GitHub Release) activa la compilación, el empaquetado y la carga sin pasos manuales. Un lanzamiento debería ser git tag vX.Y.Z && git push origin vX.Y.Z.
• Publique los paquetes bajo una cuenta propiedad de la organización, no una personal, y use publicación confiable (OIDC) en lugar de tokens de larga duración siempre que el índice lo admita.

Paso 9: Prácticas específicas del lenguaje

Identifique los lenguajes del proyecto a partir de sus archivos marcadores y lea la referencia correspondiente para empaquetado, publicación y herramientas de calidad:

Archivo marcador	Referencia
pyproject.toml, setup.py	references/python.md — delega en la habilidad de python moderno para herramientas
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 otros ecosistemas, aplique los principios transversales: compilaciones reproducibles desde un clon nuevo, lanzamientos impulsados por CI, publicación confiable o cuentas propiedad de la organización, y metadatos de licencia en el manifiesto del paquete.

Revisión final

Antes de cambiar la visibilidad, verifique desde la perspectiva de un externo:

1. Clone en un directorio limpio y siga las instrucciones de compilación del README al pie de la letra — ¿funcionan sin conocimiento tribal?
2. Vuelva a ejecutar {baseDir}/scripts/check_readiness.sh y confirme que las brechas restantes son decisiones deliberadas, comunicadas al usuario.
3. Confirme que la auditoría de secretos (Paso 2) realmente ocurrió; es el único paso que no se puede corregir después de la publicación.

Hacer público el repositorio es entonces un cambio en la configuración del repositorio. Acompañe el lanzamiento con un anuncio donde la organización tenga un proceso para ello.

Recursos adicionales

Archivos de referencia

• references/licensing.md — criterios de selección de licencia, metadatos SPDX, forks y relicenciamiento
• references/trailofbits.md — superposición de políticas de Trail of Bits (cargado solo cuando se detecta en el Paso 1)
• references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md — empaquetado, publicación y herramientas de calidad por lenguaje

Scripts

• scripts/detect_org.sh — imprime el perfil de la organización (trailofbits o generic) a partir de los remotos de git y los correos electrónicos de los committers
• scripts/check_readiness.sh — imprime indicadores de presencia para archivos de preparación para lanzamientos y señala archivos rastreados que comúnmente contienen secretos