From afecb6a681540ea1b89c805c99ecadf296ea82bc Mon Sep 17 00:00:00 2001 From: Dave O'Connor Date: Thu, 18 Dec 2025 16:15:45 -0500 Subject: [PATCH] docs: Add AI agent documentation with progressive disclosure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation files for AI coding assistants (Claude Code, Gemini CLI) following progressive disclosure principles: - CLAUDE.md: Entry point for Claude Code - GEMINI.md: Entry point for Gemini CLI - AGENTS.md: Concise project overview with quick reference - agent_docs/: Detailed topic-specific documentation - architecture.md: Component details, CRD structure, configuration - development.md: Building, testing, code generation - deployment.md: OLM deployment, container builds 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- AGENTS.md | 42 +++++++++++++++++ CLAUDE.md | 3 ++ GEMINI.md | 3 ++ agent_docs/architecture.md | 62 +++++++++++++++++++++++++ agent_docs/deployment.md | 92 ++++++++++++++++++++++++++++++++++++++ agent_docs/development.md | 86 +++++++++++++++++++++++++++++++++++ 6 files changed, 288 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md create mode 100644 agent_docs/architecture.md create mode 100644 agent_docs/deployment.md create mode 100644 agent_docs/development.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..34285dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Container Security Operator + +Kubernetes operator that brings Quay/Clair security metadata to clusters. Watches pods, queries registries for vulnerabilities, exposes findings via `ImageManifestVuln` CRDs. + +## Quick Reference + +| Task | Command | +|------|---------| +| Build | `make build` | +| Run locally | `make run` | +| Install CRDs | `make installcrds` | +| Run tests | `go test -v ./...` | +| Regenerate code | `make codegen` | + +## Project Structure + +``` +cmd/security-labeller/ # Entrypoint +labeller/ # Core controller (informers, reconciliation) +secscan/ # Registry client for vulnerability data +image/ # Container image ID parsing +apis/secscan/v1alpha1/ # CRD types +generated/ # Auto-generated clients (do not edit) +bundle/ # OLM deployment manifests +``` + +## Key Flow + +1. Labeller watches Pod events via informers +2. Parses container image IDs from running pods +3. Queries registry's `.well-known/app-capabilities` endpoint +4. Fetches vulnerability data from Clair via manifest-security API +5. Creates/updates `ImageManifestVuln` resources +6. Garbage collects orphaned manifests on pod deletion + +## Detailed Documentation + +For specific topics, see: + +- @agent_docs/architecture.md - Component details, CRD structure, configuration +- @agent_docs/development.md - Building, testing, code generation +- @agent_docs/deployment.md - OLM deployment, container builds diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..910a2d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# CLAUDE + +@AGENTS.md diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..c77fbdc --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,3 @@ +# GEMINI + +Please follow instructions from @./AGENTS.md diff --git a/agent_docs/architecture.md b/agent_docs/architecture.md new file mode 100644 index 0000000..946d2c2 --- /dev/null +++ b/agent_docs/architecture.md @@ -0,0 +1,62 @@ +# Architecture + +## Components + +### cmd/security-labeller/main.go +Entrypoint that: +- Parses CLI flags and config file +- Handles TLS certificate configuration +- Creates and runs the Labeller controller + +### labeller/ +Core controller implementation: +- `labeller.go`: Main controller with informers for Pods and ImageManifestVulns, work queue, reconciliation logic +- `manifest.go`: ImageManifestVuln creation/update, garbage collection, affected pod tracking +- `config.go`: Configuration struct and YAML loading +- `multinamespacelistwatcher.go`: Watches resources across multiple namespaces + +### secscan/ +Registry client for vulnerability scanning: +- `client.go`: Main client interface implementation +- `wellknown.go`: Fetches `.well-known/app-capabilities` from registries +- `types.go`: Response types from Clair (Layer, Feature, Vulnerability) +- `quay/`: Quay-specific implementations +- `rest/`: HTTP REST client utilities + +### image/ +Container image parsing: +- `image.go`: Parses image IDs from various formats (Docker Hub, private registries, with/without digests) +- Handles pull secret parsing from Kubernetes secrets + +### apis/secscan/v1alpha1/ +CRD type definitions: +- `types.go`: ImageManifestVuln, Feature, Vulnerability structs +- `register.go`: Scheme registration + +## ImageManifestVuln CRD + +### Spec (immutable scanner data) +- `image`: Image name +- `manifest`: Manifest digest +- `features`: List of features with vulnerabilities + +### Status (dynamic cluster state) +- `affectedPods`: Map of pod paths to container IDs +- Severity counts: `unknownCount`, `lowCount`, `mediumCount`, `highCount`, `criticalCount`, `defcon1Count` +- `fixableCount`: Vulnerabilities with available fixes +- `lastUpdate`: Timestamp of last resync + +## Configuration + +Via CLI flags or `example/example-config.yaml`: + +| Option | Default | Description | +|--------|---------|-------------| +| `namespaces` | (all) | Namespaces to watch | +| `interval` | 30m | Controller resync interval | +| `resyncThreshold` | 1h | Min time before refreshing vuln data | +| `labelPrefix` | secscan | Label prefix for resources | +| `wellknownEndpoint` | .well-known/app-capabilities | Registry endpoint | +| `promAddr` | :8081 | Prometheus metrics address | +| `insecure` | false | Skip TLS verification | +| `extraCerts` | | Directory with extra CA certificates | diff --git a/agent_docs/deployment.md b/agent_docs/deployment.md new file mode 100644 index 0000000..0748e75 --- /dev/null +++ b/agent_docs/deployment.md @@ -0,0 +1,92 @@ +# Deployment + +## Container Image Build + +```bash +# Build operator image +docker build -t quay.io//container-security-operator . + +# Push to registry +docker push quay.io//container-security-operator +``` + +The Dockerfile uses multi-stage build: +1. Go builder stage compiles the binary +2. Alpine runtime stage with ca-certificates + +## Quick Deploy (Development) + +```bash +# Build and push operator image +./hack/build.sh + +# Deploy to cluster +./hack/deploy.sh + +# Tear down +./hack/teardown.sh +``` + +## OLM Deployment (Production) + +The operator is deployed via Operator Lifecycle Manager. + +### Bundle Contents + +``` +bundle/ +├── imagemanifestvuln.crd.yaml # CRD definition +├── manifests/ +│ └── container-security-operator.v*.clusterserviceversion.yaml +├── metadata/ +├── cso.catalogsource.yaml # CatalogSource +├── cso.operatorgroup.yaml # OperatorGroup +├── cso.subscription.yaml # Subscription +└── Dockerfile # Catalog image build +``` + +### Deploy Steps + +1. Update image reference in ClusterServiceVersion: + ```yaml + # bundle/manifests/container-security-operator.v1.0.0.clusterserviceversion.yaml + image: quay.io//container-security-operator + ``` + +2. Build and push catalog image: + ```bash + cd bundle/ + docker build -t quay.io//cso-catalog . + docker push quay.io//cso-catalog + ``` + +3. Update CatalogSource image: + ```yaml + # bundle/cso.catalogsource.yaml + image: quay.io//cso-catalog + ``` + +4. Create CatalogSource: + ```bash + # Upstream Kubernetes + kubectl create -n olm -f bundle/cso.catalogsource.yaml + + # OpenShift + kubectl create -n openshift-marketplace -f bundle/cso.catalogsource.yaml + ``` + +5. Verify package is available: + ```bash + kubectl get packagemanifest container-security-operator + ``` + +6. Create OperatorGroup and Subscription: + ```bash + kubectl create -n -f bundle/cso.operatorgroup.yaml + kubectl create -n -f bundle/cso.subscription.yaml + ``` + +## Public Availability + +- **Kubernetes**: [operatorhub.io/operator/container-security-operator](https://operatorhub.io/operator/container-security-operator) +- **OpenShift**: Available via OperatorHub in the console diff --git a/agent_docs/development.md b/agent_docs/development.md new file mode 100644 index 0000000..bd306ab --- /dev/null +++ b/agent_docs/development.md @@ -0,0 +1,86 @@ +# Development + +## Prerequisites + +- Go 1.23+ +- kubectl with cluster access +- Docker or Podman (for container builds) + +## Building + +```bash +# Build the operator binary +make build +# Output: bin/security-labeller + +# Update vendored dependencies +make vendor +``` + +## Running Locally + +```bash +# Install the CRD first +make installcrds + +# Run with local kubeconfig +make run +# Uses: ~/.kube/config and example/example-config.yaml + +# Or run directly with flags +./bin/security-labeller \ + -kubeconfig ~/.kube/config \ + -namespaces default,test \ + -resyncInterval 15m \ + -promAddr :8081 +``` + +## Testing + +```bash +# Run all tests +go test -v ./... + +# Run specific package tests +go test -v ./labeller/... +go test -v ./image/... +go test -v ./secscan/... +go test -v ./k8sutils/... + +# Run with coverage +go test -v -cover ./... +``` + +## Code Generation + +The `generated/` directory contains auto-generated Kubernetes clients. To regenerate after modifying `apis/secscan/v1alpha1/types.go`: + +```bash +# Clone code-generator (one-time setup) +make get-code-generator + +# Regenerate clientsets, informers, listers +make codegen +``` + +This updates: +- `generated/clientset/` - Typed client for ImageManifestVuln +- `generated/informers/` - Shared informer factories +- `generated/listers/` - Indexer-backed listers +- `apis/secscan/v1alpha1/zz_generated.deepcopy.go` - DeepCopy methods + +## Development Environment Setup + +```bash +# Install CRD and apply example manifests +make devenv +# Runs: kubectl create -f bundle/imagemanifestvuln.crd.yaml +# kubectl apply -f bundle/examples/ +``` + +## CI Checks + +The GitHub Actions CI runs: +1. `go mod tidy` - Verify go.mod is clean +2. `make build` - Build compiles successfully +3. `go test -v ./...` - All tests pass