Siga la salida de la instalación del chart de Helm sobre cómo hacer port-forward al dashboard de Krane.

### Ejecutar con Docker

Se asume que tiene [docker](https://docs.docker.com/get-docker/) ejecutándose en su máquina local. Instale [docker-compose](https://docs.docker.com/compose/install/#install-compose) si aún no lo ha hecho.

Krane depende de RedisGraph. El stack de `docker-compose` define todo lo necesario para construir y ejecutar el servicio _Krane_ localmente. También se encargará de su dependencia [RedisGraph](https://oss.redislabs.com/redisgraph/).```
docker-compose up -d

Una vez dentro del contenedor, puedes comenzar a usar comandos `krane`. Prueba `krane -help`.```sh
krane -h

Para detener _Krane_ y sus servicios dependientes:```
docker-compose down

krane

Kubernetes RBAC static analysis & visualisation tool

dashboard Start K8s RBAC dashboard server
help      Display global or [command] help documentation
report    Run K8s RBAC report

-h, --help
    Display help documentation

-v, --version
    Display version information

-t, --trace
    Display backtrace when an error occurs

Marcin Ciszak <[email protected]> - Appvia Ltd <appvia.io>

### Generar informe RBAC

#### Con contexto local de `kubectl`

Para ejecutar un informe contra un clúster en ejecución, debes proporcionar un contexto _kubectl_```
krane report -k <context>

NOTA: _Krane_ espera que los siguientes archivos (en formato YAML o JSON) estén presentes en la ruta de directorio especificada:
  - psp
  - roles
  - clusterroles
  - rolebindings
  - clusterrolebindings

Si Pod Security Policies no están en uso, puede omitir la expectativa anterior creando un archivo `psp` manualmente con el siguiente contenido:```json
{
  "items": []
}

NOTA: La cuenta de servicio utilizada por _Krane_ requerirá acceso a los recursos de RBAC. Consulte [Requisitos previos](https://github.com/appvia/krane/blob/HEAD/k8s/one-time/prerequisites.yaml) para obtener detalles.

#### En el pipeline de CI/CD

Para validar la definición de RBAC como un paso en el pipeline de CI/CD```
krane report --ci -d </path/to/rbac-directory>

La bandera de clúster `-c <cluster-name>` se puede pasar si desea ejecutar el panel contra un nombre de clúster específico. El panel buscará datos relacionados con el nombre de clúster especificado que están almacenados en caché en el sistema de archivos.

El comando anterior iniciará un servidor web local en el puerto predeterminado `8000` y mostrará el enlace del panel.

## Arquitectura

### Datos RBAC indexados en una base de datos de grafos local

_Krane_ indexa entidades RBAC en RedisGraph. Esto nos permite consultar la red de dependencias de manera eficiente y simple utilizando un subconjunto de [CypherQL](https://oss.redislabs.com/redisgraph/cypher_support/) soportado por [RedisGraph](https://oss.redislabs.com/redisgraph/).

#### Schema

![Grafo de entidades de Krane](https://raw.githubusercontent.com/appvia/krane/HEAD/doc/images/krane-graph-diagram.svg "Grafo de entidades de Krane")

#### Nodes

Los siguientes nodos se crean en el Grafo para los objetos RBAC relevantes:

* `Psp`       - Un nodo PSP que contiene atributos relacionados con la política de seguridad del pod. Solo aplicable al trabajar con K8s < 1.25.
* `Rule`      - El nodo Rule representa una regla de control de acceso sobre recursos de Kubernetes.
* `Role`      - El nodo Role representa un Role o ClusterRole dado. El atributo `kind` define el tipo de rol.
* `Subject`   - Subject representa todos los posibles actores en el clúster (`kind`: User, Group y ServiceAccount)
* `Namespace` - Nodo de Namespace de Kubernetes.

#### Aristas

* `:SECURITY`  - Define un enlace entre nodos Rule y Psp. Solo aplicable al trabajar con K8s < 1.25.
* `:GRANT`     - Define un enlace entre un Role y una Rule asociada a ese rol.
* `:ASSIGN`    - Define un enlace entre un Actor (Subject) y un Role/ClusterRole dado (nodo Role).
* `:RELATION`  - Define un enlace entre dos nodos Actor (Subject) diferentes.
* `:SCOPE`     - Define un enlace entre nodos Role y Namespace.
* `:ACCESS`    - Define un enlace entre nodos Subject y Namespace.
* `:AGGREGATE` - Define un enlace entre ClusterRoles (un ClusterRole agrega a otro) `A-(aggregates)->B`
* `:COMPOSITE` - Define un enlace entre ClusterRoles (un ClusterRole puede ser agregado en otro) `A<-(is a composite of)-B`

Todas las aristas son bidireccionales, lo que significa que el grafo se puede consultar en cualquier dirección. Las únicas excepciones son las relaciones `:AGGREGATE` y `:COMPOSITE` que son unidireccionales, aunque se refieren a los mismos nodos de arista.

#### Consultar el Grafo

Para consultar el grafo directamente, puede ejecutar comandos dentro de un contenedor `redisgraph` en ejecución, iniciar `redis-cli` y ejecutar sus consultas arbitrarias. Siga las [instrucciones](https://oss.redislabs.com/redisgraph/) oficiales para ver ejemplos de [comandos](https://oss.redislabs.com/redisgraph/commands/).

También puede consultar el Grafo desde la consola de _Krane_. Primero, acceda mediante exec al contenedor _Krane_ en ejecución, luego```ruby
# Start Krane console - this will open interactive ruby shell with Krane code preloaded

console

# Instantiate Graph client

graph = Krane::Clients::RedisGraph.client cluster: 'default'

# Run arbitrary CypherQL query against indexed RBAC Graph

res = graph.query(%Q(
  MATCH (r:Rule {resource: "configmaps", verb: "update"})<-[:GRANT]-(ro:Role)<-[:ASSIGN]-(s:Subject)
  RETURN s.kind as subject_kind, s.name as subject_name, ro.kind as role_kind, ro.name as role_name))

# Print the results

res.print_resultset

Nota: La consulta de ejemplo anterior seleccionará todos los Sujetos con Roles/ClusterRoles asignados que otorguen acceso a `update configmaps`.

## Configuración

### Reglas de Riesgo RBAC

Las reglas de riesgo RBAC se definen en el archivo [Rules](https://github.com/appvia/krane/blob/HEAD/config/rules.yaml). La estructura de cada regla es en gran medida autoexplicativa.
El conjunto integrado puede ampliarse/sobrescribirse añadiendo reglas personalizadas adicionales al archivo [Cutom Rules](https://github.com/appvia/krane/blob/HEAD/config/custom-rules.yaml).

#### Macros de Reglas de Riesgo

Las macros son "contenedores" de un conjunto de atributos comunes/compartidos y son referenciadas por una o más reglas de riesgo. Si decides usar una macro en una regla de riesgo determinada, debes referenciarla por nombre, p.ej. `macro: <macro-name>`. Ten en cuenta que los atributos definidos en la `macro` referenciada tendrán prioridad sobre los mismos atributos definidos a nivel de regla.

Una macro puede contener cualquiera de los siguientes atributos:

- `query`   - [Consulta RedisGraph](#querying-the-graph). Tiene prioridad sobre `template`. Requiere que `writer` esté definido.
- `writer`  - Writer es una expresión Ruby utilizada para formatear el conjunto de resultados de `query`. Writer tiene prioridad sobre `template`.
- `template` - Nombre de plantilla de consulta/escritor incorporada. Si no se especifican `query` y `writer`, se utilizará el generador de consultas seleccionado junto con el escritor correspondiente.

#### Atributos de las Reglas de Riesgo

Una regla puede contener cualquiera de los siguientes atributos:

- `id`           [Requerido] El id de la regla es un identificador único de la misma.
- `group_title`  [Requerido] Título que se aplica a todos los elementos que caen bajo esta comprobación de riesgo.
- `severity`     [Requerido] Severidad, como uno de :danger, :warning, :info.
- `info`         [Requerido] Información textual sobre la comprobación y sugerencias sobre cómo mitigar el riesgo.
- `query`        [Condicional] [Consulta RedisGraph](#querying-the-graph).
  - Tiene prioridad sobre `template`. Requiere que `writer` esté definido.
- `writer`       [Condicional] Writer es una expresión Ruby utilizada para formatear el conjunto de resultados de la consulta.
  - Writer tiene prioridad sobre `template`. Requiere que `query` esté definido.
- `template`     [Condicional] Nombre de plantilla de consulta/escritor incorporada. Si no se especifican `query` y `writer`, se utilizará el generador de consultas seleccionado junto con el escritor correspondiente.
  - Algunas plantillas incorporadas requieren que se especifique el atributo `match_rules` a nivel de regla individual para construir la consulta correcta. Plantillas que actualmente lo requieren:

    - **_risky-role_** - Construye una consulta de grafo de múltiples coincidencias basada en las reglas de acceso especificadas por `match_rules`. La consulta de grafo generada devuelve las siguientes columnas:
      - role_name
      - role_kind
      - namespace_name (se devuelve un _array_ si se devuelven múltiples elementos)

- `match_rules`  [Condicional] Requerido cuando `template` depende de reglas de coincidencia para construir una consulta.
  - Ejemplo:
    ```yaml
     match_rules:
     - resources: ['cronjobs']
       verbs: ['update']
    ```
     Los atributos y valores siguen la [especificación de roles RBAC de Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-examples).

- `custom_params` [Opcional] Lista de pares clave-valor personalizados que se evaluarán y reemplazarán en la representación de `query` y `writer` de una regla.
  - Ejemplo:
    ```yaml
    custom_params:
    - attrA: valueA
    - attrB: valueB
    ```
    Los marcadores de posición de plantilla para las claves anteriores `{{attrA}}` y `{{attrB}}` se reemplazarán con `valueA` y `valueB` respectivamente.

- `threshold`  [Opcional] Valor numérico. Cuando está definido, estará disponible como marcador de posición de plantilla `{{threshold}}` en la expresión `writer`.
- `macro`      [Opcional] Referencia a parámetros comunes definidos en una macro con nombre.
- `disabled`   [Opcional] Cuando se establece en `true`, deshabilitará la regla dada y la excluirá de la evaluación.
                Por defecto, todas las reglas están habilitadas.

#### Ejemplos de Reglas de Riesgo

##### Consulta explícita y expresión de escritor```yaml
- id: verbose-rule-example
  group_title: Example rule
  severity:    :danger
  info:        Risk description and instructions on how to mitigate it goes here
  query: |
    MATCH
      (s:Subject)-[:ACCESS]->(ns:Namespace)
    WHERE
      NOT s.name IN {{whitelist_subject_names}}
    RETURN
      s.kind as subject_kind,
      s.name as subject_name,
      COLLECT(ns.name) as namespace_names
    ORDER BY
      subject_kind,
      subject_name,
      namespace_names DESC
  threshold: 2
  writer: |
    if result.namespace_names.count > {{threshold}}
      "#{result.subject_kind} #{result.subject_name} can access namespaces: #{result.namespace_names.join(', ')}"
    end
  disabled: true

El ejemplo anterior muestra una de las reglas incorporadas. Hace referencia a la plantilla `risky-role` que, al procesarse, expandirá la regla inyectando expresiones `query` y `writer` antes de que se activen las evaluaciones de reglas. `match_rules` se usará para construir la consulta de coincidencia adecuada.

### Lista blanca de riesgos RBAC

La lista blanca opcional contiene un conjunto de nombres de atributos definidos personalizados y sus respectivos valores (incluidos en la lista blanca).

#### Atributos de la lista blanca

Los nombres de los atributos y sus valores son arbitrarios. Se definen en el archivo [Whitelist](https://github.com/appvia/krane/blob/HEAD/config/whitelist.yaml) y se dividen en tres secciones separadas:
  - `global` - Ámbito de nivel superior. Los atributos personalizados definidos aquí se aplicarán a todas las Reglas de Riesgo independientemente del nombre del clúster.
  - `common` - Los atributos personalizados se limitarán al `id` de una Regla de Riesgo específica, independientemente del nombre del clúster.
  - `cluster` (con lista anidada de nombres de clúster) - Los atributos personalizados se aplicarán al `id` de una Regla de Riesgo específica para un nombre de clúster determinado.

Cada [Regla de Riesgo](#rbac-risk-rules), al evaluarse, intentará interpolar todos los marcadores de posición de parámetros utilizados en la `query`, por ejemplo, `{{your_whitelist_attribute_name}}`. Si un nombre de parámetro marcador de posición (es decir, un nombre entre llaves dobles) coincide con alguno de los nombres de atributos incluidos en la lista blanca para esa Regla de Riesgo `id`, se reemplazará con su valor calculado.
Si no se encuentran valores para un marcador de posición dado, se sustituirá por `['']`.

#### Ejemplos de lista blanca

El siguiente ejemplo de lista blanca produce la siguiente asignación `placeholder-key => value` para una [Regla de Riesgo](#rbac-risk-rules) con un valor de atributo `id` que coincide con _"some-risk-rule-id"_```
{{whitelist_role_names}}    => ['acp:prometheus:operator']
{{whitelist_subject_names}} => ['privileged-psp-user', 'another-user']

## Despliegue en Kubernetes

_Krane_ puede desplegarse fácilmente en clústeres de Kubernetes locales o remotos.

### Requisitos previos de K8s

El namespace de Kubernetes, la cuenta de servicio y el RBAC adecuado deben estar presentes en el clúster. Consulte los [Requisitos previos](https://github.com/appvia/krane/blob/HEAD/k8s/one-time/prerequisites.yaml) como referencia.

El punto de entrada predeterminado de _Krane_ ejecuta [bin/in-cluster-run](https://github.com/appvia/krane/blob/HEAD/bin/in-cluster-run) que espera a que la instancia de RedisGraph esté disponible antes de iniciar el bucle de _report_ de RBAC y el servidor web _dashboard_.

Puede controlar ciertos aspectos de la ejecución en el clúster con las siguientes variables de entorno:

* `KRANE_REPORT_INTERVAL` - Define el intervalo en segundos para la ejecución del informe de análisis estático de RBAC. Valor predeterminado: `300` (en segundos, es decir, 5 minutos).
* `KRANE_REPORT_OUTPUT` - Define el formato de salida del informe de riesgos de RBAC. Valores posibles `:json`, `:yaml`, `:none`. Valor predeterminado: `:json`.

### Clúster K8s local o remoto

#### Chart de Helm

Antes de comenzar, necesitará las siguientes herramientas:
* [CLI de Helm](https://helm.sh/docs/intro/install/)

Instalar el chart de Helm:```sh
$ helm repo add appvia https://appvia.github.io/krane
$ helm repo update
$ helm install krane appvia/krane --namespace krane --create-namespace

Ten en cuenta que el servicio del panel de control de _Krane_ no está expuesto por defecto!```sh
kubectl port-forward svc/krane 8000 \
  --context=<docker-desktop> \
  --namespace=krane

# Open Krane dashboard at http://localhost:8000

Nota: Asegúrate de que tu contexto kube actual esté configurado correctamente antes de ejecutar el comando anterior!

La pila de aplicaciones ahora debería estar desplegada en un clúster de Kubernetes y todos los servicios listos y expuestos. Ten en cuenta que _Krane_ iniciará automáticamente su bucle de informes y servidor de panel.```sh
docker stack services --orchestrator kubernetes --namespace krane krane

Verifique la postura de seguridad RBAC de su clúster de Kubernetes visitando http://localhost:8000.

Tenga en cuenta que para despliegues de clúster remotos probablemente necesitará hacer port-forward del servicio _Krane_ primero```sh
kubectl --context=my-remote-cluster --namespace=krane port-forward svc/krane 8000

## Notificaciones

Krane te notificará sobre anomalías detectadas de severidad media y alta a través de su integración con Slack.

Para habilitar notificaciones, especifica Slack `webhook_url` y `channel` en el archivo [config/config.yaml](https://github.com/appvia/krane/blob/HEAD/config/config.yaml), o alternativamente establece las variables de entorno `SLACK_WEBHOOK_URL` y `SLACK_CHANNEL`. Las variables de entorno tendrán prioridad sobre los valores del archivo de configuración.

## Desarrollo Local

Esta sección describe los pasos para habilitar el desarrollo local.

### Configuración

Instala las dependencias de código de _Krane_ con```sh
./bin/setup

Para inspeccionar que el servicio RedisGraph esté activo:```sh
docker-compose ps

### Desarrollo

En este punto deberías poder modificar el código base de _Krane_ y probar resultados invocando comandos en el shell local.```sh
$ ./bin/krane --help                    # to get help
$ ./bin/krane report -k docker-desktop  # to generate your first report for
                                        # local docker-desktop k8s cluster
...

Esto iniciará automáticamente el servidor del Dashboard, abrirá el navegador predeterminado y vigilará los cambios en los archivos fuente.

_Krane_ viene preconfigurado para mejorar la experiencia del desarrollador con [Skaffold](https://skaffold.dev/). Iterar sobre el proyecto y validar la aplicación ejecutando toda la pila en un clúster de Kubernetes local o remoto se ha vuelto más fácil.
La recarga en caliente de código permite que los cambios locales se propaguen automáticamente al contenedor en ejecución para un ciclo de desarrollo más rápido.```sh
skaffold dev --kube-context docker-desktop --namespace krane --port-forward

## Contribuir a Krane

¡Damos la bienvenida a cualquier contribución de la comunidad! Eche un vistazo a nuestra guía de [contribución](https://github.com/appvia/krane/blob/HEAD/CONTRIBUTING.md) para obtener más información sobre cómo empezar. Si usas _Krane_, te resulta útil o estás interesado en la seguridad de Kubernetes, por favor háznoslo saber **marcando con estrella** y **siguiendo** este repositorio. ¡Gracias!

## Participa

Únete a la discusión en nuestro [canal de la comunidad](https://www.appvia.io/join-the-appvia-community).

Krane es un proyecto comunitario y agradecemos tus contribuciones. Para reportar un error, sugerir una mejora o solicitar una nueva función, abre un issue en GitHub. Consulta nuestra guía de [contribución](https://github.com/appvia/krane/blob/HEAD/CONTRIBUTING.md) para obtener más información sobre cómo puedes ayudar.

## Hoja de ruta

Consulta nuestra [hoja de ruta](https://github.com/appvia/krane/projects/1) para conocer detalles sobre nuestros planes para el proyecto.


## Licencia

Autor:  Marcin Ciszak <[email protected]>

Copyright (c) 2019-2020 [Appvia Ltd](https://appvia.io)

Este proyecto se distribuye bajo la [Licencia Apache, Versión 2.0](https://github.com/appvia/krane/blob/HEAD/LICENSE).