> For the complete documentation index, see [llms.txt](https://docs.konvu.com/konvu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.konvu.com/konvu/get-started/connect-your-environment/source-code/self-hosted-analysis/architecture-overview.md).

# Architecture Overview

Konvu's Self-Hosted Analysis consists of two core components that work together to provide secure vulnerability analysis within your infrastructure:

## Components

### Controller

The **Controller** orchestrates security analysis jobs within your Kubernetes cluster. It:

* Receives analysis commands from Konvu's backend via heartbeat polling
* Creates and manages Kubernetes Jobs for vulnerability analysis
* Enforces concurrency limits to prevent resource exhaustion
* Manages credential resolution through a three-tier system
* Reports job status and results back to the backend

**Use Cases**:

* AI-powered vulnerability triage (`qualification`)
* Full repository security scanning (`cartography`)
* Container image vulnerability triage (`container_qualification`)
* Deep exploitability investigation (`investigation`)
* Automated dependency remediation (`autofix`)

### Broker

The **Broker** enables secure discovery and access to your private code repositories. It:

* Discovers repositories from your GitHub installations
* Fetches Dependabot alerts from GitHub so Konvu can triage vulnerabilities detected by GitHub's SCA
* Writes back alert dismissals to GitHub when you dismiss vulnerabilities as false positives in Konvu
* Generates short-lived Git access tokens (1-hour JWT tokens)
* Tracks commit activity for risk assessment
* Never exposes long-lived credentials to the cloud

{% hint style="info" %}
To fetch and sync Dependabot alerts, your GitHub App needs `vulnerability_alerts` permissions. See [Connecting GitHub](/konvu/get-started/connect-your-environment/source-code/self-hosted-analysis/connecting-github.md) for details.
{% endhint %}

**Use Cases**:

* Private GitHub Enterprise repositories
* Private GitHub.com repositories via GitHub Apps
* Organizations requiring air-gapped token generation

## How They Work Together

```
┌─────────────────────────────────────────┐
│      Konvu Backend (Cloud)              │
│   sensors.konvu.com / api.konvu.com     │
└───────┬─────────────────┬───────────────┘
        │                 │
   ┌────▼──────┐    ┌────▼──────────┐
   │  Broker   │    │  Controller   │
   │  Session  │    │   Session     │
   └────┬──────┘    └────┬──────────┘
        │                │
        │    Customer Kubernetes Cluster
┌───────┼────────────────┼───────────────┐
│       │                │               │
│  ┌────▼─────┐     ┌───▼──────────┐     │
│  │  Broker  │     │  Controller  │     │
│  │   Pod    │     │     Pod      │     │
│  └────┬─────┘     └───┬──────────┘     │
│       │               │                │
│       │               ▼                │
│       │      ┌────────────────┐        │
│       │      │ Analysis Pods  │        │
│       │      │  (konvu-sca)   │        │
│       │      └────────────────┘        │
│       ▼                                │
│  ┌──────────────┐                      │
│  │    GitHub    │                      │
│  └──────────────┘                      │
└────────────────────────────────────────┘
```

**Workflow**:

1. **Discovery** (Broker): Syncs repository metadata and Dependabot alerts from your GitHub organization
2. **Token Generation** (Broker): Creates encrypted, short-lived tokens when needed
3. **Analysis Execution** (Controller): Runs security scans using credentials
4. **Results**: Analysis pods report directly to Konvu backend

**Key Security Features**:

* **End-to-End Encryption**: Repository tokens encrypted with RSA-OAEP
* **Short-Lived Credentials**: 1-hour JWT tokens minimize exposure
* **No Code Transmission**: Your code never leaves your infrastructure
* **Independent Sessions**: Broker and controller maintain separate connections

## Deployment Options

Both components can be deployed on:

* **Any Kubernetes cluster**: AWS EKS, Google GKE, Azure AKS, OpenShift, on-premises, etc. (v1.28+)
* **Together or separately**: Single cluster (recommended) or different clusters for isolation
* **With or without cloud services**: Direct Helm deployment or integrated with cloud-native tools (AWS Secrets Manager, IRSA, etc.)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.konvu.com/konvu/get-started/connect-your-environment/source-code/self-hosted-analysis/architecture-overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.