Feat: AIAC Phase 1 — functional agent, UC-1 service onboarding + integration tests

.github/workflows/security-scans.yaml

@@ -40,6 +40,11 @@ jobs:
           fail-on-severity: moderate
           deny-licenses: GPL-3.0, AGPL-3.0
           comment-summary-in-pr: never
+          # CVE-2026-45829 / GHSA-f4j7-r4q5-qw2c (chromadb, transitive via crewai): no patched
+          # version exists (affected <= 1.5.9, crewai pins chromadb < 1.2). The vulnerability
+          # requires running a chromadb HTTP server with trust_remote_code=true, which the
+          # github_agent demo does not do. See demo/agents/github_agent/pyproject.toml.
+          allow-ghsas: GHSA-f4j7-r4q5-qw2c
 
   shellcheck:
     name: Shell Script Lint

aiac/.gitignore

@@ -0,0 +1,12 @@
+# AIAC working artefacts (regenerated; not source of truth)
+docs/issues/
+docs/handoffs/
+docs/gh-issues/
+
+# PDP policy writer integration-test scratch output (test/pdp/policy/generate_rego.py)
+test/pdp/policy/rego_out/
+
+# policy-pipeline integration-test generated Rego (test/integration/test_policy_pipeline.py);
+# regenerated per run, left on disk for eyeballing — not source of truth. probe.rego is a
+# committed fixture and is not under rego_out/, so it stays tracked.
+test/integration/rego_out/

aiac/CLAUDE.md

@@ -0,0 +1,180 @@
+# AIAC Codebase Guide
+
+All paths below are relative to `kagenti-extensions/aiac/`.
+
+## Requirements / PRD docs
+
+`docs/specs/PRD.md` — master PRD.
+`docs/specs/components/` — per-component specs.
+
+For current file list, `ls docs/specs/` and `ls docs/specs/components/`.
+
+## Requirements directory — link-following policy
+
+When a document under `docs/specs/` contains a markdown link to another file, use the AskUserQuestion tool to ask before reading it — present "Yes" and "No" as clickable options. If the user picks Yes, read the file normally. If No, treat the link as a label and continue without reading it.
+
+## Issue tracking
+
+Issues are tracked as local markdown files under `docs/issues/`, not on GitHub.
+Never use `gh` commands to create, update, or list issues — always read/write the local files directly.
+
+`docs/issues/implementation-plan.md` — overall implementation plan.
+For current issue list, `ls` the subdirectories under `docs/issues/`.
+
+## Issue tracking — codebase inspection policy
+
+When working on an issue would benefit from inspecting the relevant source code, use the AskUserQuestion tool to ask before doing so — present "Yes" and "No" as clickable options. If the user picks Yes, inspect the codebase normally. If No, work from the issue description and existing context only.
+
+## Handoffs
+
+Per-task handoff documents live under `docs/handoffs/` — one markdown file per task, numeric-prefixed (e.g. `01-update-issues.md`, `02-update-source-and-tests.md`). When asked to generate a handoff, write it here (not a scratch/temp path). Each handoff must be self-contained — background, task, exact files, and acceptance criteria — so a fresh session can execute it without the originating conversation.
+
+## Source code
+
+`src/aiac/` — Python package root (`__init__.py` is empty).
+
+Key stable structure:
+- `idp/` — IdP configuration service and models
+- `pdp/` — PDP policy writer service and library
+- `agent/` — the AIAC Agent layer (rebuilt on the SPM/APM model):
+  - `agent/controller/` — FastAPI Controller (`routes.py` + Dockerfile); `/apply/*` routes dispatch to the UC sub-agents and make the single `compute_and_apply` (PCE) call
+  - `agent/uc/` — use-case sub-agents: `onboarding/` (provision + policy_builder + orchestrator), `policy_update/` (build/rebuild), `role_update/`
+  - `agent/policy_rules_builder/` — PRB: `build_role_rules` / `build_scope_rules` emit `list[PolicyRule]`
+  - `agent/shared/` — shared helpers (`roles.py`, e.g. `flatten_role`)
+  - `agent/onboarding.old/` — archived prior implementation (built on the superseded `ProposedDiff` model); not part of the active build
+- `policy/` — the two-layer policy stack (all implemented):
+  - `policy/model/` — `PolicyRule`, `ServicePolicyModel` (SPM), `AgentPolicyModel` (APM), `PolicyModel`
+  - `policy/store/` — Policy Store service + library (SPM CRUD)
+  - `policy/computation/` — Policy Computation Engine (`compute_and_apply`, SPM-based)
+
+For current file list, `ls` or `find` under `src/aiac/`.
+
+## Tests
+
+`test/` — mirrors `src/aiac/` structure. For current file list, `ls` under `test/`.
+
+**Unit test command:**
+
+```bash
+.venv/bin/pytest test/ -m "not integration"
+```
+
+The whole `test/` tree (including `test/policy/`) collects and runs green. The Policy
+Computation Engine (`aiac.policy.computation.engine`) was migrated to the SPM store surface in
+**Wave 3 / Handoff 05**, so the earlier PCE-chain collection failures (which required ignoring
+`test/policy/computation`, `test/agent/controller/test_routes.py`, and
+`test/integration/test_policy_pipeline.py`) are resolved — no `--ignore` flags are needed.
+
+Use `ls test/` to discover current test directories.
+
+**Integration tests** (`-m integration`) need live config — Keycloak + admin creds + an LLM
+endpoint (`opa` on PATH for the policy-pipeline suite). Those variables live in
+`test/integration/.env` (gitignored): `LLM_BASE_URL`, `LLM_API_KEY`, `LLM_MODEL`, `KEYCLOAK_URL`,
+`KEYCLOAK_ADMIN_USERNAME`, `KEYCLOAK_ADMIN_PASSWORD`. Source it before running:
+
+```bash
+set -a; . test/integration/.env; set +a
+.venv/bin/pytest test/integration/ -m integration
+```
+
+**Smoke test** (requires live service at `AIAC_PDP_CONFIG_URL`, default `http://127.0.0.1:7071`):
+
+```bash
+.venv/bin/python test/idp/configuration/show_keycloak_data.py
+```
+
+Exercises all `Configuration` methods — run `ls test/idp/configuration/` to see current coverage.
+
+## Python environment
+
+Virtual environment: `kagenti-extensions/aiac/.venv`
+
+Activate: `source kagenti-extensions/aiac/.venv/bin/activate`
+Run directly: `kagenti-extensions/aiac/.venv/bin/python` / `kagenti-extensions/aiac/.venv/bin/pytest`
+
+Always use this venv for any Python execution, test runs, or dependency checks.
+
+## Kubernetes & builds
+
+Config: `k8s/`, `pyproject.toml`, `pyrightconfig.json`
+
+Docker images:
+
+| Image | Dockerfile location |
+|-------|-------------------|
+| `aiac-agent` | `src/aiac/agent/controller/Dockerfile` (build context `src/`) |
+| `aiac-pdp-config` | `src/aiac/idp/service/configuration/keycloak/Dockerfile` |
+| `aiac-pdp-policy-opa` | `src/aiac/pdp/service/policy/opa/Dockerfile` |
+| `aiac-policy-store` | `src/aiac/policy/store/service/Dockerfile` |
+| `aiac-rag-ingest` | `rag-ingest/` (separate directory) |
+
+### Non-root container / volume-ownership pattern
+
+All AIAC service images run as **non-root UID 10001**. Each service Dockerfile
+adds the user before `CMD`, matching the `authbridge/sparc-service` pattern:
+
+```dockerfile
+# Drop privileges.
+RUN useradd --no-create-home --uid 10001 aiac
+USER 10001
+```
+
+A Dockerfile `chown` of a directory is **masked once a volume is mounted over
+it** (the mounted volume, not the image layer, is what the container sees), and
+the kubelet leaves emptyDir/PVC volumes root-owned by default. So any service
+that writes to a mounted volume also needs pod-level `securityContext` in its
+k8s manifest so the kubelet chowns the volume to the non-root user:
+
+```yaml
+spec:
+  securityContext:
+    runAsUser: 10001
+    runAsGroup: 10001
+    fsGroup: 10001   # makes the mounted volume group-writable by UID 10001
+```
+
+Services requiring this today:
+- **Policy store** — PVC at `/data` (SQLite backend), `policy-store-statefulset.yaml`
+- **PDP policy OPA writer** — emptyDir at `/rego` (`REGO_OUTPUT_DIR`), `pdp-interface-deployment.yaml`
+
+Services that mount no volumes still need the Dockerfile `USER` directive; the
+pod-level `fsGroup`/volume-chown block above is only required for those that
+write to a mounted volume.
+
+### Pod-security hardening baseline
+
+Beyond non-root, every workload in `k8s/` and the demo manifests carries a
+hardened `securityContext`. Pod level (omitted on the demo `github-agent`, whose
+injected AuthBridge sidecar runs as UID 1337 — hardening there is set per
+container instead so a pod-level `runAsUser` can't clobber the sidecar):
+
+```yaml
+spec:
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 10001        # 1001 for the demo github-agent
+    seccompProfile:
+      type: RuntimeDefault
+```
+
+Container level, on each app container:
+
+```yaml
+securityContext:
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop: ["ALL"]
+```
+
+With `readOnlyRootFilesystem: true` the container gets a writable `/tmp`
+`emptyDir` (and its real data mount — `/data`, `/rego`) so runtime temp writes
+have somewhere to land. The demo `github-agent` **omits** `readOnlyRootFilesystem`
+because its runtime (`uv` / `litellm` / `crewai`) writes caches under `HOME=/app`.
+All core workloads also carry both readiness **and** liveness probes (`httpGet
+/health` where the service exposes one; `tcpSocket` for the Controller and the
+demo workloads, which don't) and CPU/memory requests + limits.
+
+## External references
+
+- [Kagenti Developer Guide](https://github.com/kagenti/kagenti/blob/main/docs/dev-guide.md) — upstream Kagenti dev guide: per-persona workflows (agent, tool, extensions developers, MCP gateway operators), Git/PR process, pre-commit hooks, feature flags, local Kagenti UI v2 development (React frontend + FastAPI backend, building/deploying images to Kubernetes), and HyperShift-based testing on ephemeral OpenShift clusters (cluster lifecycle, cost management, troubleshooting).

aiac/demo/agents/github_agent/.dockerignore

@@ -0,0 +1,7 @@
+.venv
+
+# Secrets — never bake into the image
+.env
+
+# `expect` scripts
+test_startup.exp

aiac/demo/agents/github_agent/.env.template

@@ -0,0 +1,28 @@
+# Github Agent - configuration template
+# Copy to .env and fill in your values.
+
+# LLM configuration
+TASK_MODEL_ID=ollama/ibm/granite4:latest
+LLM_API_BASE=http://host.docker.internal:11434
+LLM_API_KEY=my_api_key
+MODEL_TEMPERATURE=0
+
+# MCP Tool endpoint
+MCP_URL=http://github-tool-mcp:9090/mcp
+
+# Agent service
+PORT=8000
+LOG_LEVEL=INFO
+
+# Optional: static GitHub PAT passed to MCP as Bearer token.
+# If unset, the inbound Authorization header (AuthBridge path) is forwarded instead.
+GITHUB_TOKEN=
+
+# Optional: override the URL advertised in the agent card
+AGENT_ENDPOINT=
+
+# Optional: override the curated tool allow-list (comma-separated tool names)
+ENABLED_TOOLS=
+
+# Optional: expected issuer of inbound JWTs (informational)
+ISSUER=

aiac/demo/agents/github_agent/Dockerfile

@@ -0,0 +1,15 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+ARG RELEASE_VERSION="main"
+
+WORKDIR /app
+COPY . .
+RUN uv sync --no-cache --locked --link-mode copy
+
+ENV PRODUCTION_MODE=True \
+    HOME=/app \
+    RELEASE_VERSION=${RELEASE_VERSION}
+
+RUN chown -R 1001:1001 /app
+USER 1001
+
+CMD ["uv", "run", "--no-sync", "server"]

aiac/demo/agents/github_agent/README.md

@@ -0,0 +1,113 @@
+# github-agent
+
+An autonomous A2A agent that acts on a user's behalf against GitHub **source repositories** and an **issue/PR tracker**, using the [`github-tool-mcp`](https://github.com/kagenti/kagenti-extensions) MCP server.
+
+This agent implements the canonical `github-agent` used by the AIAC policy-pipeline integration test — the two skills match the policy scenario's `source_operations` and `issue_operations` roles.
+
+## Skills
+
+| Skill id | Name | Description |
+|---|---|---|
+| `source_operations` | Source repository operations | Browse and search code; read, create, and modify repository file contents, branches, and commits. |
+| `issue_operations` | Issue & PR tracker operations | Read, search, create, and update issues, comments, sub-issues, and pull requests. |
+
+## Prerequisite: `github-tool-mcp` (production tool)
+
+This agent connects to **`github-tool-mcp:9090/mcp`** — the production 44-tool MCP server — at `MCP_URL`.
+Deploy it before starting the agent:
+
+```
+authbridge/demos/github-issue/k8s/github-tool-deployment.yaml
+```
+
+> **Not the same as `demo/tools/github_tool/`.**
+> `demo/tools/github_tool/` is a simplified 4-tool stub (`source-read`, `source-write`, `issues-read`,
+> `issues-write`) deployed as Service `github-tool` for **UC-1 onboarding discovery** only.
+> The agent never connects to it — it connects to the production `github-tool-mcp` server which
+> exposes the 44-tool GitHub API federation.
+
+## Configuration
+
+All settings are read from environment variables (or a `.env` file). Copy one of the presets:
+
+| Preset | Description |
+|---|---|
+| `.env.ollama` | Default — local Ollama (ibm/granite4) |
+| `.env.openai` | OpenAI gpt-4o-mini |
+| `.env.claude` | Anthropic Claude Sonnet |
+| `.env.template` | Documented placeholder for all vars |
+
+### Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `TASK_MODEL_ID` | litellm model id | `ollama/ibm/granite4:latest` |
+| `LLM_API_BASE` | OpenAI-compatible base URL | `http://host.docker.internal:11434` |
+| `LLM_API_KEY` | LLM API key | `my_api_key` |
+| `MODEL_TEMPERATURE` | Sampling temperature | `0` |
+| `EXTRA_HEADERS` | Extra LLM headers (JSON) | `{}` |
+| `MCP_URL` | MCP tool endpoint | `http://github-tool-mcp:9090/mcp` |
+| `MCP_TIMEOUT` | MCP connect timeout (s) | `600` |
+| `ENABLED_TOOLS` | Override the curated tool allow-list (comma-separated) | (unset → default set) |
+| `PORT` | A2A listen port | `8000` |
+| `LOG_LEVEL` | Log level | `INFO` |
+| `GITHUB_TOKEN` | Static Bearer to MCP (else inbound passthrough) | (unset) |
+| `ISSUER` | Expected `iss` of inbound JWTs (informational) | (unset) |
+| `AGENT_ENDPOINT` | Override the URL advertised in the card | (unset) |
+
+## Running locally
+
+```bash
+cd aiac/demo/agents/github_agent
+cp .env.ollama .env          # or another preset
+uv sync
+uv run server
+# In another terminal:
+curl -s localhost:8000/.well-known/agent-card.json | python3 -m json.tool
+```
+
+Optionally, run `expect -f test_startup.exp` instead to check startup automatically.
+
+## Deploying to Kagenti (Kind cluster)
+
+Prerequisites: a running Kagenti cluster (Keycloak realm `kagenti`, namespace `team1`) with `github-tool-mcp` already deployed.
+
+1. **Build the image:**
+   ```bash
+   cd aiac/demo/agents/github_agent
+   podman build -t github-agent:latest .
+   # or: docker build -t github-agent:latest .
+   ```
+
+2. **Load into the Kind cluster:**
+   ```bash
+   kind load docker-image github-agent:latest --name kagenti
+   ```
+
+3. **Apply manifests:**
+   ```bash
+   kubectl apply -f k8s/configmaps.yaml
+   kubectl apply -f k8s/github-agent-deployment.yaml
+   ```
+
+4. **Confirm AuthBridge injection:**
+   ```bash
+   kubectl get pod -n team1 -l app.kubernetes.io/name=github-agent -o jsonpath='{.items[0].spec.containers[*].name}'
+   ```
+   You should see the `authbridge-proxy` (or `envoy-proxy`) sidecar alongside `agent`.
+
+5. **Port-forward and send a message:**
+   ```bash
+   kubectl port-forward svc/github-agent 8080:8080 -n team1 &
+   # Send an A2A message/send request:
+   curl -s http://localhost:8080/.well-known/agent-card.json | python3 -m json.tool
+   ```
+
+## Architecture
+
+```
+A2A client ──(JSON-RPC /)──► github-agent (:8000)
+                                 │  CrewAI: prereq extract → researcher
+                                 └──(streamable-http, MCP_URL)──► github-tool-mcp:9090/mcp ──► GitHub
+      (AuthBridge sidecar: inbound JWT validation; outbound RFC-8693 token exchange for MCP_URL host)
+```