From e96df8d237df564818a3e6a3ae8a0e7d80fb8e3f Mon Sep 17 00:00:00 2001 From: Vegar Sechmann Molvig Date: Fri, 8 Dec 2023 12:47:56 +0100 Subject: [PATCH] remove wrong things from readme, flesh out components section --- README.md | 92 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 68 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index b456ad4e..6b86745c 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ naisdevice is a mechanism enabling NAVs developers to connect to internal resources in a secure and friendly manner. -Each resource is protected by a gateway, and the developer is only granted access to the gateway if all of the following requirements are met: -- Has a valid nav.no account +Each resource is _protected_ by a gateway, and the developer is only granted access to the gateway if all of the following requirements are met: +- Has a valid account - Has accepted naisdevice [terms and conditions](https://naisdevice-approval.external.prod-gcp.nav.cloud.nais.io/) - Device is [healthy](#what-is-a-healthy-device) -- Is member of the AAD access group for the gateway (e.g. to connect to team A's DB, you must be member of team A's AAD-group) +- Is member of the AAD access group for the gateway (e.g. to connect to team A's DB (via gateway), you must be member of team A's AAD-group) ## Deploying client changes Executing `make release-frontend` is required for deploy of new naisdevice client to be released and made available for download/install/update. @@ -14,40 +14,84 @@ Executing `make release-frontend` is required for deploy of new naisdevice clien ## key attributes - minimal attack surface -- frequent key rotation - instantly reacting to relevant security events -- improved auditlogs: who connected when and to what, as well as other relevant user events +- improved auditlogs: who connected when and to what - moving away from traditional device management enables building a strong security culture through educating our users on client security instead of automatically configuring their computers -## architecture +### components -todo: simple visual describing: -- apiserver coordinates configuration -- device + gateway fetches config on a timer -- [naisdevice-health-checker](https://github.com/nais/naisdevice-health-checker) informs apiserver of device health from Kolide -- additionally: enroller used first time user connects/enrolls into the system +## apiserver -### components +The `apiserver` component serves as the gRPC API server, responsible for handling various configurations and managing communication with other agents. Its primary functionalities include: + +- Serving the gRPC API. +- Distributing configurations to the following agents: + - [device-agent](#device-agent) + - [gateway-agent](#gateway-agent) + - [prometheus-agent](#prometheus-agent) +- Retrieving device health status from the `nais/kolide-event-handler`. + +## gateway-agent + +The `gateway-agent` runs on virtual machines (VMs) and interacts with the `apiserver` to receive and apply configurations. Key features of the `gateway-agent` include: + +- Streaming configurations from the `apiserver`. +- Dynamic setup of: + - WireGuard for communication from devices. + - iptables for forwarding traffic. + +## auth-server + +The `auth-server` operates in a cloud run environment and plays a crucial role in user authentication. Its functionalities include: + +- Authenticating users. +- Issuing tokens to devices for secure communication. + +## enroller + +The `enroller` is deployed on Cloud Run and is responsible for managing the enrollment process for both gateways and devices. -#### apiserver -The naisdevice apiserver main responsibility is to serve the [device-agents](#device-agent) and [gateway-agents](#gateway-agent) with configuration through a set of APIs. +- Handling the enrollment of gateways and devices securely. -It's database is master for all peers (devices and gateways) operating in the environment, as well as keeping track of and allocating IPs in the VPN's address space. +## device-helper -It calculates the appropriate configuration for the peers primarily based on two factors: -1. Is the device owner authorized to use the gateway? -2. Is the device in a healthy state? +The `device-helper` serves as the gRPC API for the `device-agent` and performs essential setup tasks for devices. Key functionalities include: -If both is true, the device-agent and gateway-agent is informed with the necessary information in order for them to communicate. +- Providing a gRPC API for the `device-agent`. +- Reading device serial information. +- Configuring network interfaces, routes, and WireGuard for secure communication. -### device-agent -### gateway-agent +## device-agent -## [Kolide](https://www.kolide.com/) +The `device-agent` is a crucial component responsible for managing device configurations and facilitating communication with the `apiserver`. Its main features include: -## [WireGuard](https://www.wireguard.com) +- Streaming configurations from the `apiserver`. +- Delegating configuration tasks to the `device-helper` via its gRPC API. +- Serving status updates through its gRPC API to the CLI/systray. +- Executing the authentication flow to obtain user tokens. + +## systray + +The `systray` component acts as a graphical user interface (GUI) for the `agent`, utilizing its gRPC API. It provides a convenient way for users to interact with and monitor the agent's status. + +## controlplane-cli + +The `controlplane-cli` serves as an administrative command-line interface (CLI) interacting with the `apiserver` through its gRPC API. This CLI is designed for administrative tasks and configurations. + +## prometheus-agent + +The `prometheus-agent` component connects to all gateways over WireGuard and configures Prometheus (deployed on the same VM) to scrape relevant metrics. + +- Establishing connections to gateways using WireGuard. +- Configuring Prometheus to scrape metrics from connected gateways. ## FAQ -### What is a healthy device? + ### How to install + See https://doc.nais.io/device + +## Stuff we use +[Kolide](https://www.kolide.com/) + +[WireGuard](https://www.wireguard.com)