IaC Scan Runner

Servicio que escanea tu Infraestructura como Código en busca de vulnerabilidades comunes.

Índice

• Descripción
• Ejecución
  • Ejecutar con Docker
  • Ejecutar desde CLI
  • Ejecutar desde el código fuente
• Licencia
• Contacto
• Agradecimientos

Propósito y descripción

El IaC Scan Runner es un servicio de API REST utilizado para escanear paquetes de IaC (Infraestructura como Código) y realizar diversas comprobaciones de código para encontrar posibles vulnerabilidades y mejoras. Explora los docs para más información.

Ejecución

Esta sección explica cómo ejecutar la API REST.

Ejecutar con Docker

Puedes ejecutar la API REST usando la imagen pública de Docker xscanner/runner de la siguiente manera:

# run IaC Scan Runner REST API in a Docker container and 
# navigate to localhost:8080/swagger or localhost:8080/redoc
$ docker run --name iac-scan-runner -p 8080:80 xscanner/runner

O puedes construir la imagen localmente y ejecutarla así:

# build Docker container (it will take some time) 
$ docker build -t iac-scan-runner .
# run IaC Scan Runner REST API in a Docker container and 
# navigate to localhost:8080/swagger or localhost:8080/redoc
$ docker run --name iac-scan-runner -p 8080:80 iac-scan-runner

Ejecutar desde CLI

Para ejecutar usando la CLI de IaC Scan Runner:

# install the CLI
$ python3 -m venv .venv && . .venv/bin/activate
(.venv) $ pip install iac-scan-runner
# print OpenAPI specification
(.venv) $ iac-scan-runner openapi
# install prerequisites
(.venv) $ iac-scan-runner install
# run IaC Scan Runner REST API
(.venv) $ iac-scan-runner run

Ejecutar desde el código fuente

Para ejecutar localmente desde el código fuente:

# Export env variables 
export MONGODB_CONNECTION_STRING=mongodb://localhost:27017
export SCAN_PERSISTENCE=enabled
export USER_MANAGEMENT=enabled

# Setup MongoDB
$ docker run --name mongodb -p 27017:27017 mongo

# install prerequisites
$ python3 -m venv .venv && . .venv/bin/activate
(.venv) $ pip install -r requirements.txt
(.venv) $ ./install-checks.sh
# run IaC Scan Runner REST API (add --reload flag to apply code changes on the way)
(.venv) $ uvicorn src.iac_scan_runner.api:app

Uso y ejemplos

Esta parte mostrará uno de los posibles despliegues y ejemplos breves sobre cómo usar las llamadas a la API.

Primero clonaremos el repositorio iac scan runner y ejecutaremos la API.

$ git clone https://github.com/xlab-si/iac-scan-runner.git
$ docker compose up

Después de esto, puedes usar diferentes endpoints de la API llamando a localhost:8000. También puedes navegar a localhost:8000/swagger o localhost:8000/redoc y probar todos los endpoints de la API allí. En este ejemplo, usaremos curl para llamar a los endpoints de la API.

1. Creamos un proyecto llamado test.

curl -X 'POST' \
  'http://0.0.0.0/project?creator_id=test' \
  -H 'accept: application/json' \
  -d ''

Se nos devolverá el id del proyecto. Para este ejemplo, el id del proyecto es 1e7b2a91-2896-40fd-8d53-83db56088026.

2. Por ejemplo, digamos que queremos iniciar todas las comprobaciones excepto ansible-lint. Desactivémoslo.

curl -X 'PUT' \
  'http://0.0.0.0:8000/projects/1e7b2a91-2896-40fd-8d53-83db56088026/checks/ansible-lint/disable' \
  -H 'accept: application/json'

3. Ahora, cuando el proyecto está configurado, podemos simplemente elegir los archivos que queremos escanear y comprimirlos. Para que IaC-Scan-Runner funcione, se espera que los archivos sean archivos comprimidos (normalmente archivos zip). En este caso, el tipo de respuesta será json, pero es posible cambiarlo a html. Por favor, cambie YOUR.zip por la ruta de su archivo.

curl -X 'POST' \
  'http://0.0.0.0:8000/projects/1e7b2a91-2896-40fd-8d53-83db56088026/scan?scan_response_type=json' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F '[email protected];type=application/zip'

Eso es todo.

Ampliación del flujo de trabajo de escaneo con nuevas herramientas de comprobación

En cierto punto, podría ser necesario incluir nuevas herramientas de comprobación dentro del flujo de trabajo de escaneo, con el objetivo de proporcionar una cobertura más amplia de los estándares de IaC y tipos de proyectos. Por lo tanto, en esta subsección se identifica y describe una secuencia de pasos necesarios para ese propósito. Sin embargo, los pasos deben realizarse manualmente como se describirá, pero está previsto automatizar este procedimiento en el futuro a través de la API y proporcionar una interfaz amigable que ayude al usuario al importar nuevas herramientas que pasen a formar parte del catálogo disponible que compone el flujo de trabajo de escaneo. La Figura 16 describe los pasos necesarios que deben tomarse para ampliar el flujo de trabajo de escaneo con una nueva herramienta.

Paso 1 – Añadir clase específica de herramienta al directorio de comprobaciones Primero, es necesario añadir una nueva clase Python específica de la herramienta al directorio de comprobaciones dentro del código fuente de IaC Scan Runner: iac-scan-runner/src/iac_scan_runner/checks/new_tool.py
La clase de una nueva herramienta hereda de la clase Check existente, que proporciona una generalización de las herramientas del flujo de trabajo de escaneo. Además, es necesario proporcionar la implementación de los siguientes métodos:

1. def configure(self, config_filename: Optional[str], secret: Optional[SecretStr])
2. def run(self, directory: str) Mientras que el primero tiene como objetivo proporcionar los parámetros específicos de la herramienta necesarios para configurarla (como contraseñas, ids de cliente y tokens), el otro especifica cómo se invoca la herramienta misma a través de API o CLI y se devuelve su salida sin procesar.

Paso 2 – Añadir la instancia de la clase de la herramienta de comprobación dentro del constructor de ScanRunner Una vez que la nueva clase derivada de Check se ha añadido al código fuente de IaC Scan Runner, también es necesario modificar el código fuente de su clase principal, llamada ScanRunner. En cuanto a las modificaciones de esta clase, primero se requiere importar la clase específica de la herramienta, crear una nueva instancia de la clase de la herramienta de comprobación y añadirla al diccionario de comprobaciones de IaC dentro de def init_checks(self). A) Importar la clase de la herramienta de comprobación from iac_scan_runner.checks.tfsec import TfsecCheck B) Crear una nueva instancia del objeto de la herramienta de comprobación dentro de init_checks """Initiate predefined check objects""" new_tool = NewToolCheck() C) Añadirla al diccionario self.iac_checks dentro de init_checks

    self.iac_checks = {
        new_tool.name: new_tool,
        …
    }

Paso 3 – Añadir la herramienta de comprobación a la matriz de compatibilidad dentro de la clase Compatibility Por otro lado, dentro del archivo src/iac_scan_runner/compatibility.py, también se debe ampliar el diccionario que representa la matriz de compatibilidad. Hay dos casos posibles: a) se debe añadir un nuevo tipo de archivo como clave, junto con la lista de herramientas relevantes como valor b) se debe añadir la nueva herramienta a la lista de compatibilidad para el tipo de archivo existente.

    compatibility_matrix = {
        "new_type": ["new_tool_1", "new_tool_2"],
        …
        "old_typeK": ["tool_1", …  "tool_N", "new_tool_3"]
    }

Paso 4 – Proporcionar soporte para la síntesis de resultados Finalmente, el último paso en la secuencia de modificaciones necesarias para la ampliación del flujo de trabajo de escaneo es modificar la clase ResultsSummary (src/iac_scan_runner/results_summary.py). Precisamente, se requiere añadir una parte del código a su método summarize_outcome que buscará cadenas específicas propias de la herramienta y que pueden usarse para identificar si la comprobación pasó o falló. Dentro del bucle que recorre las comprobaciones compatibles, para cada nueva herramienta se debe incluir la siguiente estructura if-else:

        if check == "new_tool":
            if outcome.find("Check pass string") > -1:
                self.outcomes[check]["status"] = "Passed"
                return "Passed"
            else:
                self.outcomes[check]["status"] = "Problems"
                return "Problems"

Licencia

Este trabajo está licenciado bajo la Apache License 2.0.

Contacto

Puedes contactar al equipo de xOpera enviando un correo electrónico a [email protected].

Agradecimientos

Este proyecto ha recibido financiación del programa de investigación e innovación Horizonte 2020 de la Unión Europea bajo el Acuerdo de Subvención No. 101000162 (PIACERE).