Allstar

[!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.

Resumen

• ¿Qué es Allstar?

Novedades de Allstar

• whats-new.md

Deshabilitar problemas no deseados

• ¡Ayuda! Allstar está creando problemas que no quiero. ¡No los quiero!

Primeros pasos

• Antecedentes
• Opciones a nivel de organización
• Opciones de instalación
  • Crea tu GitHub App
  • Crea tu repositorio de control .allstar
  • Ejecutar Allstar como una GitHub Action
  • Ejecutar Allstar como un daemon de servicio
• Migración desde la app alojada

Políticas y acciones

• Acciones
• Políticas

Avanzado

• Definiciones de configuración
• Ejemplos de configuración
• Ejecuta tu propia instancia de Allstar

Contribuir

• Contribuciones

Resumen

¿Qué es Allstar?

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.

Novedades de Allstar

Deshabilitar problemas no deseados

Si Allstar está creando problemas no deseados, sigue estas instrucciones para optar por no participar.

Primeros pasos

Antecedentes

Allstar es altamente configurable. Hay tres niveles principales de controles:

• Nivel de organización: Los administradores de la organización pueden elegir habilitar Allstar en:
  • todos los repositorios de la organización;
  • la mayoría de los repositorios, excepto algunos que optaron por no participar;
  • solo unos pocos repositorios que optaron por participar.

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).

Opciones a nivel de organización

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.

Opciones de instalació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:

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.

Crea tu GitHub App

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.

Crea tu repositorio de control .allstar

Allstar 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:

1. Abre el repositorio de muestra y haz clic en el botón "Use this template"
2. En el campo de Nombre del Repositorio, escribe .allstar
3. Haz clic en "Create repository from template"

Esto 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.

Ejecutar Allstar como una GitHub Action

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.

Ejecutar Allstar como un daemon de servicio

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.

Migración desde la app alojada

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:

1. Crea tu propia GitHub App e instálala en tu organización con el mismo acceso a repositorios que tenía la app alojada.
2. Mantén tu repositorio .allstar existente exactamente como está.
3. Ejecuta Allstar como una Action o como un daemon.
4. Desinstala 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.

Políticas y acciones

Acciones

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.

Configuración de acciones

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.

Políticas

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:

• La GitHub App de Allstar debe tener el permiso de repositorio Code scanning alerts configurado en Read & write (alcance de API: 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 no es bloqueante: si la carga falla (p. ej., debido a permisos faltantes), la comprobación de la política continúa con normalidad.
• La detección de cambios compara el SHA del commit HEAD del repositorio y omite el escaneo y la carga cuando no se ha hecho push al repositorio desde la última carga.

La carga de SARIF funciona con ambas formas de ejecutar Allstar: como un daemon de servicio o como una GitHub Action.

GitHub Actions

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.

Administradores de Repositorio

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).

Políticas Futuras

• Asegurarse de que dependabot esté habilitado.
• Comprobar que las dependencias estén fijadas/congeladas.

Ejemplo de Repositorio de Configuración

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.

Avanzado

Definiciones de Configuración

• Configuración de habilitación a nivel de organización
• Configuración de habilitación de anulación de repositorio

Ubicación secundaria de configuración a nivel de 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:

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.

Configuraciones de políticas de repositorio en el repositorio de la organizació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:

Ubicación de la configuración base y de fusión a nivel de organización

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.

Contribuciones

Consulta CONTRIBUTING.md