ossf/allstarAplicación de GitHub para establecer y aplicar políticas de seguridad
[!IMPORTANT] La GitHub App de Allstar alojada por OpenSSF ha sido retirada. Allstar, el subproyecto de OpenSSF Scorecard, continúa manteniéndose: ahora debes ejecutarlo tú mismo, ya sea como una GitHub Action o como un daemon de servicio.
Consulta ossf/allstar#881 para más detalles.
Si tu organización dependía de la app alojada, consulta Migración desde la app alojada.
Allstar es una GitHub App que supervisa continuamente organizaciones o repositorios de GitHub para verificar el cumplimiento de las mejores prácticas de seguridad. Si Allstar detecta una violación de una política de seguridad, crea un problema para alertar al propietario del repositorio o de la organización. Para algunas políticas de seguridad, Allstar también puede cambiar automáticamente la configuración del proyecto que causó la violación, restaurándola al estado esperado.
El objetivo de Allstar es darte un control fino sobre los archivos y configuraciones que afectan la seguridad de tus proyectos. Puedes elegir qué políticas de seguridad supervisar tanto a nivel de organización como de repositorio, y cómo manejar las violaciones de políticas. También puedes desarrollar o contribuir con nuevas políticas.
Allstar se desarrolla como parte del proyecto OpenSSF Scorecard.
Si Allstar está creando problemas no deseados, sigue estas instrucciones para optar por no participar.
Allstar es altamente configurable. Hay tres niveles principales de controles:
Estas configuraciones se realizan en el repositorio .allstar de la organización.
Nivel de repositorio: Los mantenedores de repositorios en una organización que usa
Allstar pueden optar por incluir o excluir su repositorio de las aplicaciones
a nivel de organización. Nota: estos controles a nivel de repositorio solo funcionan cuando se permite
la "anulación de repositorio" en la configuración a nivel de organización. Estas configuraciones se
realizan en el directorio .allstar del repositorio.
Nivel de política: Los administradores o mantenedores pueden elegir qué políticas
están habilitadas en repositorios específicos y qué acciones toma Allstar cuando se
viola una política. Estas configuraciones se realizan en un archivo yaml de política en
el repositorio .allstar de la organización (administradores) o en el
directorio .allstar del repositorio (mantenedores).
Antes de instalar Allstar a nivel de organización, debes decidir aproximadamente en cuántos repositorios quieres que Allstar se ejecute. Esto te ayudará a elegir entre las estrategias de Opt-In y Opt-Out.
La estrategia Opt In te permite agregar manualmente los repositorios en los que deseas que Allstar se ejecute. Si no especificas ningún repositorio, Allstar no se ejecutará a pesar de estar instalado. Elige la estrategia Opt In si deseas aplicar políticas solo en un número reducido de tus repositorios totales, o si quieres probar Allstar en un solo repositorio antes de habilitarlo en más. Desde la versión v4.3, se admiten globs para agregar fácilmente múltiples repositorios con un nombre similar.
La estrategia Opt Out (recomendada) habilita Allstar en todos los repositorios y te permite seleccionar manualmente los repositorios que optarán por no participar en las aplicaciones de Allstar. También puedes optar por excluir todos los repositorios públicos, o todos los repositorios privados. Elige esta opción si deseas ejecutar Allstar en todos los repositorios de una organización, o si deseas excluir solo un número reducido de repositorios o un tipo específico (es decir, público vs. privado) de repositorio. Desde la versión v4.3, se admiten globs para agregar fácilmente múltiples repositorios con un nombre similar.
| Opt Out (Recomendado) optOutStrategy = true | Opt In optOutStrategy = false | |
|---|---|---|
| Comportamiento predeterminado | Todos los repositorios están habilitados | Ningún repositorio está habilitado |
| Agregar repositorios manualmente | Agregar repositorios manualmente deshabilita Allstar en esos repositorios | Agregar repositorios manualmente habilita Allstar en esos repositorios |
| Configuraciones adicionales | optOutRepos: Allstar se deshabilitará en los repositorios listados optOutPrivateRepos: si es true, Allstar se deshabilitará en todos los repositorios privados optOutPublicRepos: si es true, Allstar se deshabilitará en todos los repositorios públicos (optInRepos: esta configuración se ignorará) | optInRepos: Allstar se habilitará en los repositorios listados (optOutRepos: esta configuración se ignorará) |
| Anulación de repositorio | Si es true: Los repositorios pueden optar por no participar en las aplicaciones de Allstar de su organización
usando la configuración en su propio archivo de repositorio. La configuración de opt-in a nivel de organización que
se aplica a ese repositorio se ignora. Si es false: los repositorios no pueden optar por no participar en las aplicaciones de Allstar configuradas a nivel de organización. | Si es true: Los repositorios pueden optar por participar en las aplicaciones de Allstar de su organización incluso
si no están configurados para el repositorio a nivel de organización. La configuración de opt-out a nivel de organización
que se aplica a ese repositorio se ignora. Si es false: Los repositorios no pueden optar por participar en las aplicaciones de Allstar si no están configurados a nivel de organización. |
Allstar actúa en tu organización como una GitHub App: tú creas la app y tú ejecutas el proceso que se autentica como ella. La configuración consta de dos pasos comunes a todas las implementaciones: crear la app y crear el repositorio de control — y luego una elección sobre cómo ejecutarla:
| GitHub Action | Daemon de servicio | |
|---|---|---|
| Cómo se ejecuta | Trabajo programado en tu repositorio .allstar | Proceso persistente que tú alojas |
| Tú proporcionas | Nada más allá de GitHub | Un servidor u orquestador de contenedores |
| Cadencia | Lo que configures en el cron | Continua, con resultados en 5-10 minutos |
| Esfuerzo de configuración | Moderado | Alto |
| Mejor cuando | Quieres la opción de menor infraestructura | Quieres el mayor control, o ya ejecutas servicios |
La Action es la opción de menor sobrecarga de las dos y es donde la mayoría de las organizaciones deberían comenzar; puedes pasar a un daemon más tarde sin cambiar ninguna configuración de políticas.
Una App es una identidad similar a un usuario con un conjunto de permisos en tu organización.
Allstar necesita acceso de lectura a la mayoría de las configuraciones y contenidos de archivos para detectar
el cumplimiento, y acceso de escritura a problemas y comprobaciones para crear problemas y
soportar la acción block.
Sigue las Instrucciones del operador - Crear una GitHub App y registra el ID de la App y la clave privada. Ambos modos de ejecución los necesitan.
.allstarAllstar lee su configuración de un repositorio llamado .allstar en tu
organización.
La forma más rápida de crear uno es a partir de la muestra:
.allstarEsto habilita todas las políticas actuales de Allstar en todos los repositorios
usando la estrategia Opt Out, con la acción issue. Puedes cambiar cualquier cosa más tarde.
Para un control granular desde el inicio — elegir la estrategia Opt In u Opt Out y escribir archivos de política individuales tú mismo — sigue las instrucciones de instalación manual en su lugar.
Esta opción ejecuta Allstar como un trabajo programado usando GitHub Actions, por lo que no hay infraestructura que operar más allá de GitHub mismo.
Sigue las instrucciones de instalación de GitHub
Actions para configurar una Action recurrente en tu
repositorio .allstar, endurecerla y monitorear sus resultados.
Esta opción ejecuta Allstar como un proceso persistente, que detecta y resuelve violaciones continuamente en lugar de según un horario.
Consulta las Instrucciones del operador para ejecutar el proceso, gestionar secretos, dimensionamiento y las variables de entorno disponibles.
Si tu organización usaba la app alojada por OpenSSF, tu configuración se
transfiere tal cual. El repositorio de control .allstar, allstar.yaml y cada
archivo de política siguen funcionando sin cambios; lo que estás reemplazando es solo el proceso
que los lee.
Para migrar:
.allstar existente exactamente como está.allstar-app de tu organización, si todavía aparece en
Configuración -> GitHub Apps.Los problemas presentados anteriormente por la app alojada permanecen en tus repositorios. Tu propia
instancia identifica sus problemas por la misma etiqueta allstar (o tu
issueLabel configurado), por lo que los adoptará y cerrará a medida que se resuelvan las violaciones,
en lugar de presentar duplicados.
Cada política se puede configurar con una acción que Allstar tomará cuando detecte que un repositorio no cumple.
log: Esta es la acción predeterminada y en realidad se lleva a cabo para todas las
acciones. Todos los resultados y detalles de la ejecución de políticas se registran. Los registros actualmente
solo son visibles para el operador de la app; los planes para exponerlos están en discusión.issue: Esta acción crea un problema de GitHub. Solo se crea un problema por
política, y el texto describe los detalles de la violación de la política. Si el
problema ya está abierto, se le envía un comentario cada 24 horas sin actualizaciones
(actualmente no configurable por el usuario). Si el resultado de la política cambia, se dejará un nuevo comentario
en el problema y se vinculará en el cuerpo del problema. Una vez que se aborda la violación,
Allstar cerrará automáticamente el problema dentro de 5-10 minutos.fix: Esta acción es específica de la política. La política hará los cambios en la
configuración de GitHub para corregir la violación de la política. No todas las políticas podrán
soportar esto (ver más abajo).Acciones propuestas, pero aún no implementadas. Las definiciones se agregarán en el futuro.
block: Allstar puede establecer una Comprobación de estado de
GitHub
y bloquear cualquier PR en el repositorio para que no se fusione si la comprobación falla.email: Allstar enviaría un correo electrónico a los administradores del repositorio.rpc: Allstar enviaría un rpc a algún sistema específico de la organización.Hay dos configuraciones disponibles para configurar la acción de problema:
issueLabel está disponible a nivel de organización y de repositorio. Configurarlo
anulará la etiqueta allstar predeterminada que usa Allstar para identificar sus
problemas.
issueRepo está disponible a nivel de organización. Configurarlo forzará que todos
los problemas creados en la organización se creen en el repositorio especificado.
Similar a la configuración de habilitación de la app Allstar, todas las políticas se habilitan y
configuran con un archivo yaml en el repositorio .allstar de la organización,
o en el directorio .allstar del repositorio. Al igual que con la app, las políticas son opt-in
por defecto; además, la acción log predeterminada no producirá resultados visibles. Una
forma sencilla de habilitar todas las políticas es crear un archivo yaml para cada política con
el contenido:```yaml
optConfig:
optOutStrategy: true
action: issue
Los detalles de cómo funciona la acción `fix` para cada política se detallan a continuación. Si se omite a continuación, la acción `fix` no es aplicable.
### Protección de ramas
El archivo de configuración de esta política se llama `branch_protection.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).
La política de protección de ramas verifica que los [ajustes de protección de ramas](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) de GitHub estén configurados correctamente según la configuración especificada. El texto del issue describirá qué ajuste es incorrecto. Consulta la [documentación de GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) para corregir los ajustes.
La acción `fix` cambiará los ajustes de protección de ramas para que cumplan con la configuración de política especificada.
### Artefactos binarios
El archivo de configuración de esta política se llama `binary_artifacts.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).
Esta política incorpora la [verificación de scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Elimina el artefacto binario del repositorio para lograr el cumplimiento. Como los resultados de scorecard pueden ser extensos, es posible que necesites ejecutar [scorecard en sí](https://github.com/ossf/scorecard) para ver toda la información detallada.
### CODEOWNERS
El archivo de configuración de esta política se llama `codeowners.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).
Esta política verifica la presencia de un [archivo `CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) en tus repositorios.
### Colaboradores externos
El archivo de configuración de esta política se llama `outside.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).
Esta política verifica si algún [Colaborador externo](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) tiene acceso de administrador (por defecto) o de push (opcional) al repositorio. Solo los miembros de la organización deberían tener este acceso, ya que de lo contrario miembros no confiables pueden cambiar ajustes a nivel de administrador y enviar código malicioso.
### SECURITY.md
El archivo de configuración de esta política se llama `security.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).
Esta política verifica que el repositorio tenga un archivo de política de seguridad en `SECURITY.md` y que no esté vacío. El issue creado tendrá un enlace a la [pestaña de GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) que te ayuda a enviar una política de seguridad a tu repositorio.
### Workflow peligroso
El archivo de configuración de esta política se llama `dangerous_workflow.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).
Esta política se ejecutará contra **todas** las ramas, consulta la justificación [aquí](https://github.com/ossf/allstar/issues/569).
Esta política verifica los archivos de configuración de los workflows de GitHub Actions (`.github/workflows`) en busca de patrones que coincidan con comportamientos peligrosos conocidos. Consulta la [documentación de OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) para obtener más información sobre esta verificación.
### Verificación genérica de Scorecard
El archivo de configuración de esta política se llama `scorecard.yaml`, y las [definiciones de configuración están aquí](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).
Esta política ejecuta cualquier verificación de scorecard listada en la configuración `checks`. Todas las verificaciones ejecutadas deben tener una puntuación igual o superior al ajuste `threshold`. Consulta la [documentación de OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md) para obtener más información sobre cada verificación.
#### Carga de SARIF
La política de Scorecard puede opcionalmente cargar los resultados como [SARIF](https://sarifweb.azurewebsites.net/) en la pestaña **Security > Code Scanning** de cada repositorio. Esto brinda a los administradores de la organización visibilidad sobre los hallazgos de Scorecard junto con otras herramientas de seguridad (CodeQL, Dependabot, etc.) sin requerir la configuración de workflows por repositorio.
Para habilitar la carga de SARIF, añade el campo `upload` a tu `scorecard.yaml`:```yaml
optConfig:
optOutStrategy: true
action: issue
checks:
- Binary-Artifacts
- Signed-Releases
threshold: 8
upload:
sarif: true
Requisitos:
security_events). Este
no se encuentra entre los permisos que Allstar necesita de otro modo, así que
agrégalo a tu app antes de habilitar la carga de SARIF.La carga de SARIF funciona con ambas formas de ejecutar Allstar: como un daemon de servicio o como una GitHub Action.
El archivo de configuración de esta política se llama actions.yaml, y las
definiciones de configuración están
aquí.
Esta política comprueba los archivos de configuración de flujos de trabajo de
GitHub Actions (.github/workflows) (y las ejecuciones de flujos de trabajo en
algunos casos) en cada repositorio para asegurarse de que están en línea con las
reglas (p. ej., requerir, denegar) definidas en la configuración a nivel de
organización para la política.
El archivo de configuración de esta política se llama admin.yaml, y las
definiciones de configuración están
aquí.
Esta política comprueba que, por defecto, todos los repositorios deben tener un usuario o grupo asignado como Administrador. Te permite configurar opcionalmente si se permite que los usuarios sean administradores (en lugar de equipos).
Consulta este repositorio como ejemplo del uso de la configuración de Allstar. Como administrador de la organización, considera un README.md con información sobre cómo se está usando Allstar en tu organización.
Por defecto, se espera que los archivos de configuración a nivel de
organización, como el archivo allstar.yaml anterior, estén en un repositorio
.allstar. Si este repositorio no existe, entonces se usa el directorio
allstar del repositorio .github como ubicación secundaria. Para aclararlo,
para allstar.yaml:
| Precedencia | Repositorio | Ruta |
|---|---|---|
| Primaria | .allstar | allstar.yaml |
| Secundaria | .github | allstar/allstar.yaml |
Esto también es válido para los archivos de configuración a nivel de organización de las políticas individuales, como se describe a continuación.
Allstar también buscará configuraciones de políticas a nivel de repositorio en
el repositorio .allstar de la organización, bajo el directorio con el mismo
nombre que el repositorio. Esta configuración se usa independientemente de si la
"anulación de repositorio" está deshabilitada.
Por ejemplo, Allstar buscará la configuración de política para un repositorio
dado myapp en el siguiente orden:
| Repositorio | Ruta | Condición |
|---|---|---|
myapp | .allstar/branch_protection.yaml | Cuando la "anulación de repositorio" está permitida. |
.allstar | myapp/branch_protection.yaml | En todo momento. |
.allstar | branch_protection.yaml | En todo momento. |
.github | allstar/myapp/branch_protection.yaml | Si el repositorio .allstar no existe. |
.github | allstar/branch_protection.yaml | Si el repositorio .allstar no existe. |
Para los archivos de configuración de Allstar y de políticas a nivel de
organización, puedes especificar el campo baseConfig para indicar otro
repositorio que contenga la configuración base de Allstar. Esto se explica mejor
con un ejemplo.
Supongamos que tienes múltiples organizaciones de GitHub, pero quieres mantener
una única configuración de Allstar. Tu organización principal es "acme", y el
repositorio acme/.allstar contiene allstar.yaml:```yaml
optConfig:
optOutStrategy: true
issueLabel: allstar-acme
issueFooter: Issue created by Acme security team.
También tienes una organización satélite de GitHub llamada "acme-sat". Quieres
reutilizar la configuración principal, pero aplicar algunos cambios por encima deshabilitando Allstar en
ciertos repositorios. El repositorio `acme-sat/.allstar` contiene
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
optOutRepos:
- acmesat-one
- acmesat-two
Esto utilizará toda la configuración de acme/.allstar como configuración base, pero luego
aplicará cualquier cambio en el archivo actual sobre la configuración base. El
método con el que se aplica esto se describe como un JSON Merge
Patch. El baseConfig debe ser
un <org>/<repositorio> de GitHub.
Consulta CONTRIBUTING.md