Merge pull request #209 from Obmondo/docs/security-exporter-readmes

docs(kubeaid-security-exporter): add chart README, refresh the agent one

Author: ashish1099

argocd-helm-charts/kubeaid-agent/README.md

@@ -18,7 +18,9 @@ on the `kubeaid` Argo CD project, stored in the `argocd-project-role-kubeaid-age
 - `argocd-project-role-kubeaid-agent` Secret in the `argocd` namespace, holding the Argo CD auth token under the
   `token` key (created automatically by `kubeaid-cli`). Name overridable via
   `appConfig.argocd.authTokenSecretName`.
-- kube-prometheus, if `serviceMonitor` / `prometheusRule` stay enabled (both default to `true`).
+- `kubeaid-security-exporter` in the cluster, if `appConfig.securityPosture.enabled` stays `true`. The agent
+  forwards that exporter's snapshots; it collects no posture data itself.
+- kube-prometheus, if `serviceMonitor` stays enabled (defaults to `true`).
 
 ## Key values / KubeAid-specific configuration
 
@@ -30,20 +32,19 @@ on the `kubeaid` Argo CD project, stored in the `argocd-project-role-kubeaid-age
 | `appConfig.obmondoAPI.url` | `https://api.obmondo.com/api` | Obmondo API endpoint (mTLS). |
 | `appConfig.kubeaidUpdate.enabled` | `false` | Opt-in: schedule the service-window Argo CD sync cron job. |
 | `appConfig.kubeaidUpdate.checkInterval` | `15m` | Poll cadence for an active KubeAid update service window. |
-| `appConfig.securityPosture.enabled` | `true` | Collect vulnerabilities (trivy-operator reports), least-privilege findings, network-policy and runtime-detection posture, and submit them to the Obmondo API. Also gates the matching RBAC and the PrometheusRule. |
-| `appConfig.securityPosture.interval` | `12h` | Full posture collection cadence (Trivy refreshes reports every 24h). |
+| `appConfig.securityPosture.enabled` | `true` | Poll `kubeaid-security-exporter` and forward its snapshots to the Obmondo API. The agent collects nothing itself. |
+| `appConfig.securityPosture.exporterURL` | `http://kubeaid-security-exporter` | In-cluster URL of the exporter. A bare Service name resolves in the agent's own namespace; qualify it if the two charts deploy to different namespaces. |
+| `appConfig.securityPosture.pollInterval` | `1h` | Poll cadence. The submit is skipped when `collectedAt` has not advanced, so end-to-end freshness is bounded by the exporter's collection interval, not by this. |
 | `obmondoAPITLSSecretName` | `obmondo-clientcert` | Secret with the mTLS keypair. |
 | `extraSecretReaderNamespaces` | `[]` | Extra namespaces where a secrets-read Role/RoleBinding is created for the agent. |
-| `prometheusRule.upgradableThreshold` | `20` | `ImageOutdatedAndVulnerable` fires when more images than this have both a fixable Critical/High CVE and a newer tag (for `upgradableFor`, default 24h). |
 
 ## Operational notes
 
 - RBAC is least-privilege by construction: a purpose-built ClusterRole grants exactly the verbs the agent's code
-  calls (no `watch`, no blanket `view`). Secrets access stays on namespaced Roles. The security-posture rules
-  (trivy-operator, Cilium/Tetragon, KubeArmor resources) are gated by the same `securityPosture.enabled` flag the
-  agent reads, so RBAC and behaviour cannot disagree.
-- `securityPosture.enabled: true` is safe on clusters without a scanner — the collector detects missing APIs via
-  discovery and does nothing. Set it to `false` only where vulnerability detail must not leave the cluster.
+  calls (no `watch`, no blanket `view`). Secrets access stays on namespaced Roles. The agent holds no CRD access
+  at all — reading Trivy, Cilium, Tetragon and KubeArmor resources belongs to `kubeaid-security-exporter`.
+- `securityPosture.enabled: true` is safe where the exporter is not installed — the poll fails, a metric records
+  it, and nothing is submitted. Set it to `false` only where vulnerability detail must not leave the cluster.
 - Runs unprivileged: non-root, all capabilities dropped, `RuntimeDefault` seccomp.
 
 ## Docs links

argocd-helm-charts/kubeaid-security-exporter/README.md

@@ -0,0 +1,71 @@
+# kubeaid-security-exporter
+
+Deploys the [KubeAid Security Exporter](https://gitea.obmondo.com/EnableIT/kubeaid-security-exporter) — a
+Kubernetes-native exporter that reads a cluster's security posture and reports it as Prometheus metrics and
+a JSON API. It only ever reads: no Kubernetes object is created, mutated, or deleted.
+
+What it collects, where the relevant operator is installed:
+
+- **Vulnerabilities and least-privilege findings** from Trivy Operator's report CRs — full CVE detail
+  (CVSS score, installed and fixed version, advisory link), rather than the lossy Prometheus projection.
+- **Upgrade availability**, by joining those findings against version-checker on canonical image
+  references resolved in Go. Rebuilding image references in PromQL fails silently.
+- **Network enforcement** from Cilium — whether policy is actually realised on an app's pods, which is a
+  different question from whether the app ships a policy.
+- **Runtime detection posture** from Tetragon and KubeArmor — which engines are armed, and whether they
+  observe or enforce.
+
+None of those are required. Each source is detected through API discovery, and an absent operator is
+reported as absent rather than as a failure or as a clean result.
+
+## Relationship to kubeaid-agent
+
+The exporter collects; it never talks to the Obmondo API. `kubeaid-agent` GETs `/api/v1/security-posture`
+from this Service and forwards the snapshot, so reporting posture off-cluster is the agent's concern and
+cluster read access is this chart's. That split is why the agent holds no CRD access at all.
+
+Deploying this chart without the agent is fine — the metrics and the JSON API work standalone.
+
+## Prerequisites
+
+- **trivy-operator**, for vulnerability and least-privilege data. Without it the exporter reports no
+  findings, and says so rather than reporting a clean cluster.
+- **version-checker**, for upgrade availability. Without it findings still ship, with upgrade availability
+  unknown rather than "up to date".
+- kube-prometheus, if `serviceMonitor` / `prometheusRule` stay enabled (both default to `true`).
+
+Cilium, Tetragon and KubeArmor are read when present and skipped when not.
+
+## Key values
+
+| Value | Default | Meaning |
+|---|---|---|
+| `exporter.interval` | `12h` | Collection cadence. Trivy refreshes its reports on a 24h TTL, so polling faster re-reads identical data. |
+| `exporter.port` | `8080` | Serves `/healthz`, `/readyz`, `/metrics` and `/api/v1/security-posture`. |
+| `prometheusRule.upgradableThreshold` | `20` | `ImageOutdatedAndVulnerable` fires above this many images having both a fixable Critical/High CVE and a newer tag available. |
+| `prometheusRule.upgradableFor` | `24h` | How long the count must hold before the alert fires. |
+
+## Alerting
+
+One alert, `ImageOutdatedAndVulnerable`. It is a count, so it fires once per cluster rather than once per
+image, and the threshold is deliberately high — every real cluster carries a few of these at any moment, so
+a low threshold fires everywhere on day one and gets ignored. The signal worth acting on is a pile of easy
+upgrades, not the existence of one.
+
+Collection status is exported as `security_exporter_collection` (1 ok, 0 failed, -1 not installed) but is
+deliberately not alerted on: a collection failure is a debugging signal, not something worth paging for.
+
+## Operational notes
+
+- RBAC is least-privilege by construction — a purpose-built ClusterRole granting exactly the verbs the code
+  calls, with no `watch` anywhere since the exporter builds no informers. Every rule is consumed through a
+  dynamic client, so none of those resource names appear in Go source; removing a rule fails silently and
+  renders the cluster as clean rather than erroring.
+- Runs unprivileged: non-root, read-only root filesystem, all capabilities dropped, `RuntimeDefault` seccomp.
+- A collection pass holds every VulnerabilityReport in memory at once, so the memory ceiling scales with
+  image count rather than with request rate.
+
+## Docs links
+
+- Chart source: `templates/` and [values.yaml](./values.yaml) in this directory (documented inline).
+- Obmondo: <https://obmondo.com>